# CLAUDE.md

Seedbox: a generative MIDI rhythm and melody machine for the Raspberry Pi Pico 2 W. v0.1 is a browser simulator with a finished engine, and a checked stripboard layout. The next job is the C firmware.

Read first: `README.md`, `docs/concept.md`, `firmware/README.md`, `docs/decisions.md`.

## Ground rules

- **`sim/engine.js` is the musical reference.** The C engine must reproduce `test/vectors/` exactly. Don't "fix" the C to sound better: change the JS, listen, regenerate, commit both.
- **Never regenerate the vectors to make a failing port pass.** `npm run vectors` is only for intended changes to the music. Say so in the commit message.
- **Keep the engine integer-only and deterministic.**
  - No `Math.random`, no floats in decisions, no wall-clock time.
  - Use floor division through `fdiv`/`mod`.
- **`hardware/layout.js` is the only source for the stripboard.**
  - After any change, run `node hardware/check-layout.js`; it must print `layout clean`.
  - Then run `node tools/build-wiring.js`.
  - Don't hand-edit `tools/wiring.html`.
- **Hardware facts that can't be checked here** (lug order on the user's TRS jacks, Nokia BL polarity): flag them; don't guess.
- **RP2350**:
  - Inputs use pull-ups (erratum E9).
  - Set GP0/GP4 drive strength to 8–12 mA.
  - The pin map in `docs/hardware/pinout.md` is fixed by the board that's being built; don't move pins without updating `layout.js` and re-running the checker.

## Commands

```sh
npm test                          # vectors + layout, must pass before every commit
npm run vectors                   # regenerate vectors (intended music changes only)
node hardware/check-layout.js --nets
node tools/build-wiring.js
npx serve .  →  http://localhost:3000/sim/      # simulator (Web MIDI needs localhost/https)
```

No npm dependencies. Node 18+.

## Layout

- `sim/` simulator: `engine.js` (portable; also `require`-able from Node), `app.js` (browser UI, Web MIDI, scheduler, screen renderer), `index.html`.
- `test/` `cases.js` (the case list), `render.js`, `gen-vectors.js`, `check-vectors.js`, `vectors/*.json`.
- `hardware/` `layout.js`, `check-layout.js`.
- `tools/` single-file bench pages: `wiring.html` (built), `bom.html`, `panel.html`; `wiring-src/` holds the parts `wiring.html` is built from.
- `docs/` user-facing docs; `docs/hardware/svg` and the CSVs are exports from the tools.
- `firmware/` empty except the plan. Suggested structure is in its README.

## Conventions

- The user (Gee) builds by hand: stripboard, hookup wire, panel-mount parts. Write instructions as strip letter + hole number, with colour roles from `docs/hardware/wiring.md`.
- Docs are plain and short. Tables over prose for anything you'd look up.
- Commit vectors and engine changes together. Commit layout and rebuilt wiring together.