PAD test build (do not merge)

.claude/skills/openpocket-flash/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: openpocket-flash
+description: Build, dry-run and flash an OpenPocket package to a connected Donner Pocket X or M-VAVE BlackBox from the command line (node tools/op.mjs flash, over USB MIDI, no browser). Use to check that a built package fits the connected pedal, or, only when the captain explicitly instructs it, to write it. Covers the safety rules and the SD-card recovery.
+---
+
+# Flash a pedal from the command line
+
+`node tools/op.mjs flash` (or `make flash ARGS="..."`) runs the same update protocol as the browser installer
+(`docs/index.html`): the code is `docs/pxota.js` and `docs/pxpkg.js`, shared with the page; `tools/flash.mjs` only adds the
+command line. Run everything from the repository root. The command runs on the host, not in the container: the pedal is a USB
+device.
+
+## Safety rules (read first)
+
+1. **Never flash without the captain's explicit instruction** for this pedal and this package. A task that says "build" or
+   "test" is not that instruction. Without it, stop after the dry run and report.
+2. **Always dry-run first**, and read its output: pedal, model and package must be the ones intended.
+3. Never put `--confirm-flash` in a script, alias or default. It is typed for one flash, on the captain's say-so.
+4. Keep the pedal plugged in and powered until the command prints `done`. Close the browser installer and any other MIDI
+   program first; they hold the port.
+5. Only one pedal on the bus. The command refuses when none or several answer.
+6. A failure prints the recovery pointer. Do not retry in a loop: report the output to the captain.
+
+## 1. Set up once
+
+```
+node tools/op.mjs doctor          # Node 18+ (Docker only for building)
+npm ci --prefix tools             # the one dependency, @julusian/midi (prebuilt RtMidi), into tools/node_modules
+```
+
+On Linux the MIDI library needs ALSA (`libasound2`); the pedal's USB MIDI port must be visible to your user.
+
+## 2. Build the package
+
+```
+node tools/op.mjs package         # docs/firmware/PocketX_9NN.fwsc, BlackBox_9NN.fwsc, manifest.json, build/SHA256SUMS
+```
+
+Details and failures: the `openpocket-toolchain` skill. To flash a package built elsewhere (for example a test image from
+another branch), keep its `.fwsc` next to the `manifest.json` that was built with it and pass both.
+
+## 3. Dry run (writes nothing)
+
+```
+node tools/op.mjs flash --dry-run
+node tools/op.mjs flash --dry-run --package build-x/PocketX_925.fwsc --manifest build-x/manifest.json
+```
+
+It checks the package against the manifest (size, SHA-256, identity, UFW and CRC structure), finds the pedal by asking each
+MIDI input for its identity (a read-only query), and refuses a package for the other model. The pedal's flash is not touched.
+Success ends with `dry run ok: would update PocketX_923 -> PocketX_924`.
+
+Refusals (exit 2, nothing sent to the pedal): no `--confirm-flash` and no `--dry-run`; package not listed in the manifest;
+SHA-256, size or identity differs from the manifest; wrong model; no pedal; several pedals; pedal already in update mode
+(power-cycle it).
+
+## 4. Flash (only on the captain's explicit instruction)
+
+```
+node tools/op.mjs flash --confirm-flash [--package FILE] [--manifest FILE]
+```
+
+Same checks as the dry run, then: the pedal stages its update loader (step 1), the loader writes the app area (step 2), the
+pedal restarts, and the command reads the version it reports. `done: the pedal reports PocketX_924.` is success (exit 0); a
+version that differs from the package is a failure. It takes about a minute. Report the full output to the captain.
+
+## 4b. A pedal that restarts in a loop (only on the captain's explicit instruction)
+
+```
+node tools/op.mjs flash --rescue --confirm-flash [--package FILE] [--manifest FILE] [--timeout SECONDS]
+make flash-rescue ARGS="--confirm-flash"
+```
+
+The installer page's rescue mode, on the command line. Start it first, then plug the pedal in or let it restart. It polls every
+MIDI port every 100 ms; the moment the pedal answers its identity query it sends the upgrade command (which stops the sound
+processing, so the restarts stop) and installs the package of the pedal's model. `--package` pins one package: a pedal of
+the other model is refused before anything is sent. Without `--package` the manifest's package for the pedal's model is used.
+It waits `--timeout` seconds (default 180); an install already running is never cut short. A pedal that vanishes before the
+update finished has had nothing written: it is waited for again. `--rescue --dry-run` waits for the pedal and checks the model,
+writing nothing. Reached states: the running firmware's MIDI port, and an OpenPocket update loader left half-done (finished only with `--package`: a loader does not report its model; a foreign loader is refused). Not reached
+(same as the page): a firmware that crashes before it answers, and the chip's mask-ROM loader `WL80UBOOT` (USB 4C4A:8057, no
+MIDI); both need the SD-card recovery. Timeout is exit 1 with the recovery text. One pedal on the bus: the first to answer is used.
+
+## 5. Recovery
+
+A failure (exit 1) prints `FAILED: ...` and the recovery text. In order:
+
+1. Unplug USB, power-cycle the pedal, run `--dry-run` again to see what it reports. A pedal in update mode (`ota-...`) is
+   finished by the browser installer's resume button, or by this command after a power-cycle.
+2. If it stays dead, the SD-card recovery in the README (`flash/`: fm1buddy on an ESP32-S3; the image comes from your factory
+   backup with `make appimage DUMP=fm1-1.bin` or `makeimage.bat`). Only the captain does this.
+
+Never publish or commit a pedal backup (`fm1-1.bin`, `fm1-300.bin`): they hold the official firmware.
+
+## Tests
+
+`node tests/test_flash.mjs` (part of `node tools/op.mjs test`) drives the real command against the simulated pedal that runs
+the pedal's own `ota.c` and loader code: update, dry run writes nothing, wrong model, damaged package, missing confirmation,
+no pedal, two pedals, failure with the recovery text, and `--rescue` against a pedal that restarts in a loop (answers on the
+Nth restart, never answers, vanishes mid-transfer, wrong model, missing confirmation). Real hardware is not covered by any test.

.claude/skills/openpocket-rescue/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: openpocket-rescue
+description: Rescue a Donner Pocket X / M-VAVE BlackBox that restarts in a loop or no longer boots, from a Mac with no extra hardware (make rescue, tools/uboot_rescue.py, over the chip's USB UBOOT boot state). Use when the installer's rescue mode cannot finish, the pedal loops after a bad image, or a flash left the app area broken. Covers when to use it, the safety rules, who runs the sudo write, and how to read the result.
+---
+
+# Rescue a looping or bricked pedal
+
+The pedal's mask ROM always enters the USB boot state ("UBOOT": USB `4C4A:8057`, shown as `WL80UBOOT1.00`) when the app is bad,
+and it cannot be damaged. `tools/uboot_rescue.py` waits for that state, loads JieLi's RAM loader and rewrites the app area from
+the official package. Full walkthrough and the record of the first real run: `docs/RESCUE.md`.
+
+## When to use it
+
+- The pedal restarts in a loop and the installer page's rescue mode (or `node tools/op.mjs flash`) cannot finish. Try those first:
+  they need no root.
+- The pedal stays in the boot state (no loop, no sound) after an interrupted flash: the rescue finishes the job.
+- Not for Bluetooth or firmware behaviour questions, and not on a pedal that works.
+
+## Rules (read first)
+
+1. **Read-only first.** `make rescue` writes nothing to the flash (the loader goes to RAM only) and saves a backup of the whole flash
+   to `~/OpenPocket-rescue`. Read its output before anything else.
+2. **The captain runs the write.** `make rescue-write` and every `sudo` command need the captain's password and instruction. An
+   agent runs neither: prepare the exact command and give it with the `!` prefix.
+3. The write range is only whole 4 KiB sectors in `[0x4000, end of the package)`, `[0x4000, 0xA3000)` for BlackBox. Never write
+   the head `[0, 0x4000)` or anything above the package. The tool refuses; do not work around it.
+4. Never chip erase (`FB02`) and never burn a key (`FC12`). The tool cannot send them; do not add them.
+5. Stop on any `REFUSED` (wrong device, chip key not `0x980F`, flash not 1 MiB, head differs from the package). Nothing was written;
+   report the message.
+6. Keep the first backup. Never commit or publish a backup or a package: they hold the official firmware.
+7. After a restore, do not reinstall the Bluetooth test image until the cause of the loop is known.
+
+## How
+
+```
+brew install libusb          # once
+make doctor                  # rescue lines: libusb, official package, loader, root
+make rescue                  # read-only: INQUIRY, loader to RAM, key, flash id, backup, head check, sectors that differ
+make rescue-write            # only on the captain's instruction, after the read-only run passed
+```
+
+Options go after `ARGS=` (`make rescue ARGS="--package FILE.fwsc"`; `--image flash.bin`, `--loader FILE`, `--backup-dir DIR`,
+`--attempts N`). Plug the pedal straight into the Mac (no hub). Start the command first; it waits for the pedal and starts by
+itself the moment it appears (the pedal is in UBOOT about 44 s of every 70 s while it loops). Needs the official BlackBox package
+(default `~/Documents/BlackBox (2).fwsc`) and Python 3.
+
+## Reading the result
+
+| Output | Meaning |
+| --- | --- |
+| `INQUIRY: WL82 UBOOT1.00 1.00` | the right device |
+| `loader running: chip key 0x980f, flash id ...  (1024 KiB)` | the checks passed; record the flash id |
+| `backup saved: ...dump.bin` | the rollback copy is complete on disk |
+| `head [0, 0x4000) matches the image` | the package fits this pedal |
+| `N of 160 sectors ... differ` | what a write would do; a rerun after a partial write shows fewer |
+| `Read-only run finished, nothing was written` | exit 0, the read-only run is done |
+| `Done: N sectors written and verified` | exit 0 after `--write`; power-cycle the pedal |
+| `the pedal went away ... waiting for it again` | the window closed; it resumes by itself |
+| exit 1 `ERROR` | setup: libusb, `sudo`, missing package; the message names the fix |
+| exit 2 `REFUSED` | a safety check stopped it, nothing written |
+| `LIBUSB_ERROR_ACCESS` | run with `sudo` (`make rescue` does); if it persists as root, report it |
+
+Save the output of a real run (`make rescue 2>&1 | tee rescue.log`) and add its numbers to `docs/RESCUE.md`.
+
+## Tests
+
+`make rescue-check` runs the tool against a simulated UBOOT pedal (protocol, guards, resume, no hardware); it is part of
+`make test`. Hardware behaviour is not covered by any test.

.claude/skills/openpocket-simulator/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: openpocket-simulator
+description: Start and drive the hosted OpenPocket simulated pedal (node tools/op.mjs sim, make sim): the firmware's real screen, editor protocol and preset store running natively behind a local HTTP API, with a code-drawn front panel of the pedal as its page. Use to press or hold footswitches and buttons, turn the knobs, read the screen as a PNG, read the pedal state, send SysEx, dump or reset the flash, or to use the installer and editor pages against a simulated pedal in a browser. Use for verifying UI, editor-protocol or preset-store changes without a pedal, and for trying a preset or a screen. Use to hear a preset through bundled guitar loops, a file or a computer input. Not for USB or Bluetooth (not simulated).
+---
+
+# OpenPocket simulator
+
+The pedal's own `ui.h`, `px_editor.h` and `px_store.h` run natively (`tests/edsim.c`) behind HTTP. Full reference:
+`docs/SIMULATOR.md` (every endpoint, the state fields, what is not simulated). Run from the repository root. Needs Node 18+
+and a C compiler (`node tools/op.mjs doctor` says whether `cc` is there); no Docker.
+
+## Start
+
+```
+node tools/op.mjs sim --port 0 --reset &      # prints: OpenPocket simulator (pedal) listening on http://127.0.0.1:PORT/
+```
+
+`--port 0` picks a free port: read the URL from the first line of output. Without `--port` it is 8766. The flash lives in
+`build/sim/flash.bin` (`--flash FILE`); without `--reset` a session continues where it stopped. The first start compiles
+the simulator (a few seconds). Stop it with Ctrl-C or by killing the process **you** started.
+
+## Drive (with `U=http://127.0.0.1:PORT`)
+
+| Do | Request |
+| --- | --- |
+| A footswitch or button | `curl -X POST $U/api/press/NAME`: `fs_up` `fs_dn` `fx` `home` `push` `mod` `amp` `cab` `dly` `rev`; `push_long` (SAVE), `dpush` (MOVE), `home_long` (tuner) |
+| Hold a button | `curl -X POST $U/api/down/NAME`, later `$U/api/up/NAME`: the same ten names, timed as the firmware does (HOME 0.7 s, PUSH 0.8 s, double click 350 ms) |
+| Turn the knob | `curl -X POST $U/api/knob/3` (negative: other way; `?fast` for steps of 5) |
+| Volume, battery, tuner pitch | `POST $U/api/volume/55`, `/api/battery/3640[/USB_MV]`, `/api/tuner/110` |
+| Bypass, load in the status text | `POST $U/api/bypass/1`, `/api/load/17` |
+| Read the state | `curl -s $U/api/state` (slot, name, mode, focused block, the whole sound, `frame`, `held`, `knob`) |
+| Read the screen | `curl -s "$U/api/screen.png?scale=2" -o screen.png`, then look at it; `screen.rgb565` is the raw pixels |
+| SysEx | `curl -s -X POST $U/api/sysex -d 'f0 7d 4f 50 01 f7'` returns `{"reply":"hex"}` (`docs/EDITOR-PROTOCOL.md`) |
+| Dump / reset the flash | `curl -s $U/api/flash -o flash.bin`; `curl -X POST $U/api/reset` |
+
+Every request is applied before it is answered. The pedal's pages: `chain` (PLAY) -> `block` -> `edit`; `push_long` opens
+`save` (knob picks the slot, `push` saves); `home_long` opens the tuner, any control leaves it. A worked path to change a
+setting: `press/amp`, `knob/2`, `press/push`, `knob/8`, then `state` shows `preset.p[5][0]` up by 8 and `dirty: 1`.
+Prove a screen claim by reading `screen.png`, not only the state.
+
+## Browser
+
+`$U/` is the pedal's front panel (`tools/sim/pedal.html`) with the live screen in its LCD: press and hold the buttons and
+footswitches, drag or wheel the knobs, click PARA for PUSH, or use the keys listed on the page. Scripts on the page have
+`window.pedal` (`down`, `up`, `tap`, `turn`, `master`, `state`); a control is `[data-control=NAME]`, `#master` or `#para`.
+`$U/plain` is the plain page with the screen, every control as a button, the battery, the tuner pitch and the state.
+`$U/site/index.html` (installer) and `$U/site/editor.html`
+(editor) are `docs/` with a virtual Web MIDI injected, so Connect finds the simulated pedal in any browser; drive them with
+`chrome-devtools-axi` or Playwright. For the installer use the update flow instead of the pedal:
+`node tools/op.mjs sim --update FLASH.bin` (an image such as `flash_old.bin` from `python3 tests/fixtures.py DIR`).
+
+## Sound
+
+The skin's Sound section runs the real engine (`engine/px_dsp.c`, built to `tools/sim/px_engine.wasm`) in an AudioWorklet:
+pick a bundled loop (`assets/loops/`), a dropped file or a device, press Play (the first click starts the audio; a device
+starts muted), and the preset on the screen is what you hear. `window.pedal.audio()` reports it (`running`, `heard`,
+`muted`, ...), and `#in-meter`, `#out-meter` carry `data-db`. Without a browser, `node tools/sim/render.mjs OUTDIR [preset]`
+renders the loops to WAV. After any change to `engine/`, run `node tools/op.mjs wasm` (Docker) and commit the new binary:
+`tests/test_audio.mjs` fails otherwise. `docs/SIMULATOR.md` ("The sound") has the reasons and limits.
+
+## Limits (say so when verifying)
+
+No LEDs or bypass footswitch (the firmware has none: the skin's backlights are
+its own reading of the state), no USB or Bluetooth. `press/NAME` has no timing, `down` and `up` do. The panel's TUNER line
+is the stock firmware's: in OpenPocket both footswitches are two presses, and the tuner is a long press of HOME.
+`press()` and the `button_*` functions in `tests/edsim.c` mirror the control dispatch of `firmware/openpocket.c`: if that
+loop changes, change them too. The proof is the firmware's real code on a PC, not the pedal.
+
+## Tests
+
+`node tests/test_sim.mjs` (also in `node tools/op.mjs test`) covers the API, the flash file and the shim.
+`node tests/test_pedal_input.mjs` covers the skin's input mapping, and `node tests/test_pedal_page.mjs OUTDIR` drives the skin
+in Chromium and saves screenshots (needs Playwright). `node tests/test_audio.mjs` covers the engine and the loops, and
+`node tests/test_audio_page.mjs OUTDIR` the Sound section in Chromium with a fake audio input (needs Playwright).

.claude/skills/openpocket-toolchain/SKILL.md

@@ -24,8 +24,10 @@ Run commands from the repository root.
 | Build the firmware, the update loader and the installer packages | `node tools/op.mjs build` |
 | Build, then write `build/SHA256SUMS` | `node tools/op.mjs package` |
 | Host tests (engine, preset store, screen, simulated pedal, installer, editor) | `node tools/op.mjs test` |
+| The simulated pedal on a local port (host `cc`, no Docker; skill `openpocket-simulator`) | `node tools/op.mjs sim` |
 | Remove every build output (needs no Docker) | `node tools/op.mjs clean` |
 | A shell in the container | `node tools/op.mjs shell` |
+| Dry-run or flash a built package to a connected pedal (host, USB MIDI) | `node tools/op.mjs flash`: see the `openpocket-flash` skill |
 
 Outputs: `firmware/openpocket.bin`, `docs/firmware/PocketX_9NN.fwsc`, `BlackBox_9NN.fwsc`, `manifest.json`. All of them
 are gitignored. Two clean builds give identical bytes; a changed checksum means the source or a pin changed.
@@ -50,8 +52,9 @@ Follow `references/updating-pins.md`. Never bypass the checksum check.
 
 ## Safety rules of this repository
 
-- **Never flash a device from an agent.** No `flash`, no WebUSB or MIDI write to a real pedal. Only the captain installs,
-  from the browser installer, by hand. Hardware checks are in `docs/MIDI-TEST.md` when present.
+- **Never flash a device unless the captain explicitly instructs it.** `node tools/op.mjs flash --dry-run` is allowed; `--confirm-flash`
+  and any other write to a real pedal only on the captain's say-so, following the `openpocket-flash` skill. Builds and tests never
+  touch a pedal. Hardware checks are in `docs/MIDI-TEST.md` when present.
 - **Never publish an unreviewed package as the installer default.** A test package is a separate, labelled file and is
   not listed in the default `docs/firmware/manifest.json`. `PUBLISH-*.bat` is the maintainer's tool: do not run it.
 - **Keep the official-firmware analysis out of the repository.** Facts about the vendor's firmware (offsets, tables,