[PC | ESP | STM HW] Build CrossPad for the given platform. • platform='pc' → CMake + Ninja host simulator. PREFER THIS over cmake --build build (picks right MSVC env on Windows, parses errors/warnings, streams progress). • platform='idf' → idf.py build for ESP32-S3 firmware. PREFER THIS over raw idf.py build (sources IDF env, auto-fullcleans when new apps detected, parses errors/warnings). • platform='stm' → CMake + Ninja + arm-none-eabi for STM32G0 firmware (CrossPad r20). Uses CMakePresets (Debug/Release); output is build//CrossPad_STM32_r20.elf. Mode×platform compatibility: • incremental → all (default) • clean → all (wipes build dir, then builds) • reconfigure → PC & STM (re-runs cmake without wiping cache) • fullclean → IDF only (runs idf.py fullclean, then builds)

[PC] Launch the built simulator binary in the background. Returns pid + exe_path. Refuses to spawn a duplicate if one is already responding on the TCP control port (use force=true to override). Fails if binary not built — call crosspad_build first. Currently PC-only (IDF firmware doesn't run on the host).

[PC sim] Stop the running PC simulator. Identifies the process by /proc//exe match against the built binary (Linux) or pgrep -x basename (macOS/Windows), sends SIGTERM, waits up to 3s, then SIGKILL stragglers. Returns killed PIDs and whether anything still answers on the TCP control port. Currently PC-only.

[PC] Health check for a build — detects stale exe, new sources missing from build system, dirty submodules. Use before crosspad_build to decide if rebuild needed. Currently PC-only.

[ESP HW | STM HW] Flash firmware to a connected CrossPad device. target='esp' (default) → ESP32-S3 firmware (requires prior crosspad_build platform=idf): • transport='uart' uses idf.py flash (device must be in bootloader mode). • transport='ota' uses platform-idf/tools/ota_flash.py over USB CDC (no bootloader mode required). Works on both CrossPad generations: rev <2.0 (ESP native USB) and rev 2.0 (port is the STM32 CDC bridge — STM emulates the esptool DTR/RTS auto-reset and forwards the flash to the ESP over LPUART2; rev-2.0 STM must be in passthrough mode, i.e. NOT booted with pad-4 held). target='stm' → STM32G0 firmware via STM32_Programmer_CLI (requires prior crosspad_build platform=stm): • method='swd' flashes over ST-Link (SWD). • method='dfu' flashes the USB DFU bootloader (board in ST system memory — hold pad 1 at boot or trigger boot_request_dfu). Flasher resolved from config (stm_programmer_cli) → $STM32_PROG → PATH.

[PC | ESP HW] Capture logs (consolidated; replaces crosspad_log_pc and crosspad_log_idf in v6). • target='pc' → spawn the built sim binary, capture stdout/stderr, then kill it. Fields used: timeout_seconds (default 5), max_lines (default 200). port and filter MUST be omitted. • target='idf' → read serial from a connected ESP32-S3 via pyserial (no TTY needed). Fields used: port (auto-detected if omitted), timeout_seconds (default 10), max_lines (default 500), filter (substring, case-insensitive).

[ESP HW] List all connected USB serial devices. Identifies CrossPad devices separately and tags each with kind: 'esp-native' (rev <2.0, ESP32-S3 native USB, VID 0x303a/PID 0x3456) or 'stm-bridge' (rev 2.0, STM32 composite CDC+MIDI bridge, VID 0x0483/PID 0x5740 — STM programs the ESP over LPUART2).

[STM HW] Real-time SWD tracer for the STM32G0B1 firmware (ST-Link). Non-halting RAM polling of firmware variables resolved from the Debug ELF (like ST-Studio/CubeMonitor). Pick an action: • doctor → environment precheck → issues[] (run this FIRST; resolve issues, then config_set). • config_set → persist a resolved path/serial to ~/.config/crosspad-mcp/config.json (key,value). • symbols → list/search traceable variables from the ELF (query optional). • start → begin a background trace (signals[], rate_hz). • stop → end the active trace. • add/remove → mutate the live poll set of the active trace (signals[]); returns the current signal set. • status → device_state (running/stop_suspected/exited), sample_count, actual_fs, signals. • read → recent samples downsampled + per-signal stats (cheap; safe for the LLM). • save → export the in-memory buffer to CSV (returns file_path). • device_state → deep low-power/STOP register dump. • ui → returns the localhost dashboard URL. Signal names accept array indexing, e.g. 's_inputs[0]', 's_adc_raw[3]'.

[PC] Build and run the Catch2 test suite for crosspad-pc. PREFER THIS over invoking the test binary directly — configures cmake with BUILD_TESTING=ON, parses Catch2 output into passed/failed counts and errors, supports filter and list_only.

[PC sim] Capture a PNG screenshot from the running PC simulator. Default behavior (return_inline=false): saves to /screenshots/ and returns metadata + file_path (cheap, no token cost). Set return_inline=true ONLY when the LLM needs to actually see the image — that returns base64 inline and burns ~50-150k tokens.

[PC sim] Send one input event to the running PC simulator (consolidated; replaces 7 v5 tools). Pick an action, then supply ONLY the fields it needs — extras are ignored. Required fields per action: • pad_press → pad (velocity optional, default 127) • pad_release → pad • encoder_rotate → delta (positive=CW, negative=CCW) • encoder_press → (none) • encoder_release → (none) • click → x, y • key → keycode (SDL keycode int) Requires the simulator to be running (crosspad_run first).

[PC sim] Send one MIDI event to the running PC simulator (consolidated; replaces 4 v5 tools). Pick a type, then supply ONLY the fields it needs — extras are ignored. Required fields per type: • note_on → note (velocity optional, default 127) • note_off → note (velocity optional, default 0) • cc → cc_num, value ⚠️ NOT YET SUPPORTED BY PC SIM (no midi_cc handler — call fails fast) • program_change → program ⚠️ NOT YET SUPPORTED BY PC SIM (no midi_program_change handler — call fails fast) channel (0-15) defaults to 0 for every type. Only note_on/note_off actually reach the sim today.

[PC sim] Read runtime statistics from the running PC simulator: pad state, capabilities, heap, registered apps, active pad logic.

[PC sim] Read settings from the running simulator.

[PC sim] Write a single setting on the running simulator.

Git status across ALL detected CrossPad repos in one call: branch, HEAD, dirty files, submodule sync state. PREFER THIS over running git status per repo — handles the 5-repo monorepo layout in one shot.

Show submodule drift in a parent repo (crosspad-pc or platform-idf): commits ahead/behind pinned, changed files, uncommitted work. Use to inspect dev-mode work before pinning.

Update a submodule in a parent repo to the latest commit on a tracking branch (git fetch + checkout origin/ + stage). Destructive: discards local commits in the submodule that aren't on the remote branch.

Commit staged changes in a specific CrossPad repo. PREFER THIS over raw git commit — handles repo aliases (idf/pc/arduino/core/gui), refuses on merge conflicts, uses 0600 tempfiles for messages (no shell-quoting issues with quotes/newlines/backticks), and never pushes. Stages files[] first if supplied.

Search for symbol DEFINITIONS (classes, functions, macros, enums, typedefs) across CrossPad repos via git grep. PREFER THIS over raw grep -r or git grep — it filters to definitions only (skips call sites/declarations), classifies kind, and aggregates across all repos automatically. Substring match: 'Foo' matches FooBar, MyFoo. Vendored/generated trees (lvgl, managed_components, thorvg, TFT_eSPI, STM Drivers/Middlewares/CMSIS, build, …) are skipped by default — pass include_vendored=true to scan them.

List all crosspad-core interfaces (I*-prefixed classes in crosspad-core/include/crosspad/).

Find all classes implementing a given interface across CrossPad repos. Returns className, file path, platform. Use crosspad_list_interfaces first if you don't know exact names.

List platform capability flags (Capability enum) and which capabilities each platform sets.

List apps registered via REGISTER_APP() macro by scanning source files. Different from crosspad_apps_list (which reads the package registry).

List apps from the crosspad-apps registry, aggregating installation status across all detected platform repos. Reads JSON; no Python required. Different from crosspad_list_apps_source (which scans REGISTER_APP() in source code).

Install an app from the crosspad-apps registry as a git submodule. Requires gh CLI authenticated. Delegates to /{tools|scripts}/app_manager.py.

Remove an installed app submodule from a platform repo. Delegates to app_manager.py.

Update one or all installed apps on a platform. EXACTLY ONE of these must be supplied: set app_name to update a single app, OR set update_all=true to update every installed app on the platform. Supplying both, or neither, is an error.

Sync a platform's apps.json manifest with existing submodules (rebuild manifest from disk state).