romdevtools 0.13.0 → 0.15.0

package/AGENTS.md

@@ -4,7 +4,7 @@ You are reading this because romdev is connected. This is the orientation. Read
 
 ## What this server does
 
-Drives the full homebrew ROM dev loop for 14 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace which ROM offset a Genesis graphic was DMA'd from (`dmaTrace({precision:'sampled'})`), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
+Drives the full homebrew ROM dev loop for 14 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace which ROM offset a Genesis graphic was DMA'd from (`watch({on:'dma', precision:'sampled'})`), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
 
 You drive the work. The human is a director — they may want a game, a ROM disassembly, a tool-assisted reverse-engineering session, or anything else this server can do.
 
@@ -54,7 +54,7 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 - `input` — drive controllers, look up hardware bit layouts. `navigate` walks menus by advancing on SCREEN CHANGE (not fixed frames) and reports whether each press was consumed — the fast, reliable way to script a UI.
 - `state` — savestates and forensic state inspection (`state({op:'save'})`, `state({op:'load'})`, `state({op:'export'})` a slot to disk without touching the live host, `state({op:'list'})`, `state({op:'dump'})`)
 - `memory` — read/write VRAM/OAM/CGRAM/ARAM and other regions (all 14 platforms). `memory({op:'read'})` takes `offsets:[…]` to batch scattered reads in one call. **`memory({op:'search'})`/`memory({op:'searchNext'})`** = the Cheat-Engine value-search loop ("find the address of X, narrow as X changes"). **`memory({op:'readCart'})`** reads the loaded cart image to confirm a patch is live. **`memory({op:'classify'})`** says whether bytes look like ASCII/code/tile-data (kills the "found table that's really a string" trap). `memory({op:'snapshot'})` + `memory({op:'diff'})` answer "which bytes changed across this event?" (diff defaults to a clustered summary with stride detection); `state({op:'diff'})` is the coarse whole-machine version.
-- `debug` — `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14), **`dmaTrace({precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
+- `debug` — `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14), **`watch({on:'dma', precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
 - `assets` — convert PNGs to tiles (`encodeArt`/`importArt`), WAVs to BRR, identify ROMs (`cart({op:'identify'})`), plus the hacking toolkit (`romPatch({op})` — write/writeMany/spliceCHR/relocate/makeStored/findFree/findPointer/diff, `assembleSnippet`, `cart({op:'extract'})`, `cart({op:'wrap'})`)
 - `project` — starter snippets per platform
 - `show` — `playtest({op})`: `op:'open'` opens the live SDL window for a human, `op:'stop'` closes it, `op:'status'` reports liveness, `op:'framebuffer'` captures exactly what the human's window shows
@@ -242,14 +242,21 @@ your project dir, it lands at `./read_joystick.asm` (alongside
 `main.asm`), NOT under `./include/` or `./lib/`. Every platform
 follows the same flat layout.
 
-Because the layout is flat, **`build({output:'project', path, platform})` rebuilds the
-whole directory in one call — no per-iteration file manifest.** It finds `main.c`
-(C / SGDK Genesis / GBA / cc65-C / SDCC-C) or `main.s` / `main.asm` (asm), links every
-`.c`/`.s` in the dir, treats `.h`/`.inc` as includes, and folds binary assets
-(`.bin/.chr/.pcm/.brr/.vgm/...`) in as `binaryIncludes`. So iterating an on-disk project is
-just `build({output:'project', path:'/my/proj', platform})` every time — you don't re-send
-`sources`/`includes` each build. (Use `build({output:'rom'})` with explicit `sources` when
-the files aren't on disk, e.g. generated in-context.)
+Because the layout is flat, **the simplest loop is `build({output:'run', path, platform})`
+(build + load + run + screenshot in one call) or `build({output:'project', path, platform})`
+(build the dir to a ROM) — no per-iteration file manifest, on EVERY platform.** Point it at
+a scaffolded directory and it does the right per-platform thing automatically: finds the
+entry (`main.c` for C / SGDK Genesis / GBA / cc65-C / SDCC-C, or `main.s` / `main.asm` for
+asm), routes the platform's crt0 correctly (e.g. GB/GBC `gb_crt0.s` via the cart-header path,
+not as a plain source — so no `gsinit` collision), applies the right linker preset
+(e.g. NES `chr-ram-runtime`, which supplies the OAM/CHARS segments), skips SDK intermediates
+(e.g. Genesis `sega.preprocessed.s`, the SNES SPC700 driver, any `*.upstream.*`), wires the
+runtime (GBA libtonc/libgba/maxmod by what the source includes), routes `#include`d C/asm
+siblings as includes, treats `.h`/`.inc` as includes, and folds binary assets
+(`.bin/.chr/.pcm/.brr/.vgm/.xgc/...`) in as `binaryIncludes`. So iterating an on-disk project
+is just `build({output:'run', path:'/my/proj', platform})` every time — you do **not** need to
+enumerate `sources`/`includes`/`crt0Path`/`linkerConfig` by hand. (Use `build({output:'rom'})`
+with explicit `sources` only when the files aren't on disk, e.g. generated in-context.)
 
 ## Supported platforms
 
@@ -297,7 +304,7 @@ Different platforms have different levels of MCP-exposed debugging — different
 > lookup/apply/create), `cpu({op:'read'})`, `memory({op:'search'})`/`memory({op:'searchNext'})`/`memory({op:'readCart'})`/`memory({op:'classify'})`,
 > `memory({op:'snapshot'})`/`memory({op:'diff'})`/`state({op:'diff'})`, `watch({on:'mem'})`/`breakpoint({on:'write',precision:'sampled'})`.
 > `audioDebug({op:'inspect'})` covers the 12 systems with a sound chip (all but Atari 2600/7800).
-> **`dmaTrace({precision:'exact'})`** (which DMA wrote a VRAM tile, and from where) is **Genesis-only**
+> **`watch({on:'dma', precision:'exact'})`** (which DMA wrote a VRAM tile, and from where) is **Genesis-only**
 > (VDP DMA) — elsewhere use `breakpoint({on:'write'})`/`watch({on:'range'})`. All other RE tools above
 > work on every platform that has the register-write/watch core hooks (all 14).
 > `disasm({target:'rom'})` + `disasm({target:'references'})` + `disasm({target:'project'})` cover **all 14** — every
@@ -881,7 +888,7 @@ OAM format: bytes per sprite are `[y, tileIndex, attributes, x]`.
 
 Three shapes, pick the one that matches what you're doing:
 
-- **`scaffold({op:'project', platform, name, path, template?})`** — writes a starter directory: `main.{c,asm,s}` (from `examples/<platform>/templates/`) + every runtime file the template depends on (headers, crt0, linker .cfg) + README + `.gitignore`. Self-contained: take it elsewhere and rebuild with stock cc65/sdcc, no romdev install needed. Defaults to `template:"default"` (smallest visible-and-runnable program); most tier-1 platforms also have `hello_sprite` + `tile_engine` + the 5 genre templates.
+- **`scaffold({op:'project', platform, name, path, template?})`** — writes a starter directory: `main.{c,asm,s}` (from `examples/<platform>/templates/`) + every runtime file the template depends on (headers, crt0, linker .cfg) + README + `.gitignore`. Self-contained: take it elsewhere and rebuild with stock cc65/sdcc, no romdev install needed. Defaults to `template:"default"` (smallest visible-and-runnable program); most tier-1 platforms also have `hello_sprite` + `tile_engine` + the 5 genre templates. **Then build it in ONE call: `build({output:'run', path:<that dir>, platform})`** — the dir build applies the platform's recipe (crt0/linker-preset/runtime/intermediate-skip) automatically, so you never hand-wire `crt0Path`/`codeLoc`/`linkerConfig`. This scaffold→build path is verified to build + render on every platform/template.
 
 - **`scaffold({op:'project', ..., withSnippets: true})`** — same as above, **plus** drops every vetted starter snippet for the platform alongside main.c. Use when you want "main.c + every helper file ready to edit" in one shot, without picking a genre. Snippets that overlap with the template's runtime are skipped (no double-writes). Response includes `snippetsCopied: string[]`.
 
@@ -1044,10 +1051,10 @@ A few platform-tool quirks worth knowing up front:
 - **asar bank-border-crossed** can happen if your `org` + `dw` runs past $00FFFF. Native vectors are at $FFE4-$FFEE; emulation vectors at $FFF4-$FFFF. Use `scaffold({op:'snippets', platform: "snes", mode: "get", name: "lorom_header.asm"})` for the layout.
 - **cc65 (NES, C64, etc.) zero page** starts at $02. cc65 reserves $00-$01 for its runtime. Your first `.res 1` lands at $02, not $00. Use `symbols({op:'map'})` after `build({output:'romWithDebug'})` to confirm.
 - **NES pattern table cap = 256 tiles per nametable**. The tilemap index is 8-bit, so per-frame BG can use at most 256 unique tiles per pattern table. Auto-converting a busy illustration usually overflows. `encodeArt({stage:'tilemap'})` warns; the only workaround is mid-frame CHR bank switching (MMC3-class mapper).
-- **NES + GB/GBC turnkey** (R9/R10 self-contained + sound, 2026-05-25): use `scaffold({op:'project', platform, template, name, path})` to scaffold a project. The pipeline copies every file the template depends on — `{nes,gb}_runtime.{h,c}`, `gb_hardware.h`, custom `crt0.s`, linker `.cfg`, `patch-header.js` (GB) — into the project directory alongside `main.c`. **No auto-injection at build time.** The build pipeline compiles exactly what you tell it via `sources` / `sourcesPaths` / `includes` / `includePaths` / `crt0` / `crt0Path` / `linkerConfig` / `codeLoc`. Take the project elsewhere with stock cc65/sdcc and it builds the same way. The runtime APIs include sprites, BG, input, AND **sound** — `sound_init` / `sound_play_tone(channel, period, vol, length)` / `sound_play_noise` / `sound_off`. NES drives pulse1+pulse2+triangle+noise via $4000-$400F + $4015; GB drives the 4-channel APU via NR10-NR52. SFX-grade, fire-and-forget — for full music tracks, drop in famitone2 (NES) or your own driver. Templates: `default` (palette cycle), `hello_sprite` (sprite + d-pad + **beep on A press**), `tile_engine` (multi-room tile map). Docs: [`src/platforms/nes/MENTAL_MODEL.md`](src/platforms/nes/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/nes/TROUBLESHOOTING.md); [`src/platforms/gb/MENTAL_MODEL.md`](src/platforms/gb/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/gb/TROUBLESHOOTING.md). **Game-loop order matters on NES:** stage `oam_clear`+`oam_spr` BEFORE `ppu_wait_nmi`, not after — the NMI handler DMA's whatever shadow_oam contains at vblank-start. **GB ROM header:** both asm and C builds now auto-run `rgbfix` inside `build({output:'rom'})`, so the Nintendo logo + checksums + CGB flag are correct out of the box — no manual `patchGbHeader` step needed.
+- **NES + GB/GBC turnkey** (R9/R10 self-contained + sound, 2026-05-25): use `scaffold({op:'project', platform, template, name, path})` to scaffold a project. The pipeline copies every file the template depends on — `{nes,gb}_runtime.{h,c}`, `gb_hardware.h`, custom `crt0.s`, linker `.cfg`, `patch-header.js` (GB) — into the project directory alongside `main.c`. **No auto-injection at build time.** Iterate the whole dir in one call with `build({output:'run', path, platform})` (or supply `sources` / `sourcesPaths` / `includes` / `includePaths` / `crt0` / `crt0Path` / `linkerConfig` / `codeLoc` explicitly when the files aren't on disk). Take the project elsewhere with stock cc65/sdcc and it builds the same way. The runtime APIs include sprites, BG, input, AND **sound** — `sound_init` / `sound_play_tone(channel, period, vol, length)` / `sound_play_noise` / `sound_off`. NES drives pulse1+pulse2+triangle+noise via $4000-$400F + $4015; GB drives the 4-channel APU via NR10-NR52. SFX-grade, fire-and-forget — for full music tracks, drop in famitone2 (NES) or your own driver. Templates: `default` (palette cycle), `hello_sprite` (sprite + d-pad + **beep on A press**), `tile_engine` (multi-room tile map). Docs: [`src/platforms/nes/MENTAL_MODEL.md`](src/platforms/nes/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/nes/TROUBLESHOOTING.md); [`src/platforms/gb/MENTAL_MODEL.md`](src/platforms/gb/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/gb/TROUBLESHOOTING.md). **NES sprite staging:** the bundled `nes_runtime` now handles the OAM-DMA race for you (oam_clear just resets the index; ppu_wait_nmi hides unused slots after you stage), so the old "must stage before ppu_wait_nmi" flicker trap is gone — the standard `oam_clear → oam_spr → ppu_wait_nmi` loop renders cleanly. **GB ROM header:** both asm and C builds auto-run `rgbfix` inside `build({output:'rom'/'run'})`, so the Nintendo logo + checksums + CGB flag are correct out of the box — no manual header-patch step needed (use `romPatch({op:'gbHeader'})` only to fix up an external ROM).
 - **Game Boy / GBC silent-failure footguns** (R54 cleanup, full detail in `platform({op:'doc', platform:"gb"|"gbc", name:"mental_model"})`):
   - **The bundled `gb_crt0.s` is now actually linked.** Pre-r54 a fundamental bug in `buildZ80C` was shipping the raw .s text to sdld as if pre-assembled — sdld silently rejected it and fell back to SDCC's stock sm83 crt0 (no GB cart boot, no IRQ vectors). Map showed no `init` symbol, $0000 was $FF, $0100 was $FF. Every GB ROM ran on stock crt0 invisibly. Fixed by auto-detecting .s source vs .rel object and running it through sdasgb first. Post-fix: `init` at $0150, entry $0100 = `00 c3 50 01` (nop; jp $0150), reset vector $0000 = $C9. **This was the root cause for #14 audio AND part of why every previous "runtime should work OOTB" round still felt friction-heavy.**
-  - **GB/GBC C builds now auto-fix the header at build time** (rgbfix runs inside `build({output:'rom'})`): Nintendo logo at $0104, header checksum at $014D, global checksum, and the CGB flag at $0143 ($00 for `.gb`, $C0 for `.gbc`). You no longer need to call `patchGbHeader` manually — the ROM `build({output:'rom'})` hands back boots on real hardware as-is. `patchGbHeader({path})` still exists if you want to override title / cart type / RAM size / etc. on an existing file.
+  - **GB/GBC C builds now auto-fix the header at build time** (rgbfix runs inside `build({output:'rom'})`): Nintendo logo at $0104, header checksum at $014D, global checksum, and the CGB flag at $0143 ($00 for `.gb`, $C0 for `.gbc`). You no longer need to patch the header manually — the ROM `build({output:'rom'})` hands back boots on real hardware as-is. `romPatch({op:'gbHeader', path})` still exists if you want to override title / cart type / RAM size / etc. on an existing file.
   - **`shadow_oam` is pinned at $C100** in the bundled `gb_runtime.c` via `__at(0xC100)`. OAM DMA reads ONLY the high byte and copies 160 bytes from `$XX00` — a plain `uint8_t my_oam[160]` may land at $C017 and DMA garbage. If you roll your own OAM buffer, pick an address with `0x00` low byte (e.g. $C200) and pass it directly to `oam_dma_copy`.
   - **Call `enable_vblank_irq()` once at boot.** Without it, `wait_vblank()` busy-polls `LY` which updates only at WASM `frame({op:'step'})` quantum boundaries → game loop runs at ~1/30 intended speed on the emulator. After enable, `wait_vblank()` compiles to `HALT` + vblank IRQ wake (~10 cycles per frame).
   - **Use `memcpy_vram(dst, src, n)` for VRAM bulk writes**, NOT raw `(uint8_t*)0x8000` casts — SDCC sm83 may elide the latter as dead code. The bundled `gb_hardware.h` declares every $FFxx register as `volatile`-typed so direct writes like `BGP = 0xE4;` are fine; the hazard is only on cast-through-pointer block copies.

package/CHANGELOG.md

@@ -4,6 +4,130 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.15.0
+
+**Scaffold audit: every scaffold on every platform now builds AND renders.** Two
+independent multi-agent audits found the documented "scaffold then build the dir"
+happy path was broken on most platforms, and that many scaffolds built but
+rendered blank. Both are fixed — verified 115/115 templates build via the dir
+path, and every genre game renders recognizable content. This matters most for
+weaker agents: the first build now succeeds, so they build on a working example
+instead of assuming the server is broken and installing their own tools.
+
+### Fixed — project-directory build (the linchpin)
+- **`build({output:'run'|'project', path})` now works on EVERY platform.** It was
+  0/8 on GB/GBC/NES/Genesis and 0/5 on Atari 2600 via the natural path. The
+  dir-builder used to glob every file as a source; it now applies a per-platform
+  recipe that matches a hand-written build: routes the crt0 correctly (GB/GBC
+  `gb_crt0.s` via the cart-header path — no more `Multiple definition of gsinit`),
+  applies the linker preset (NES `chr-ram-runtime` — no more `Missing memory area
+  'OAM'`), skips SDK intermediates (Genesis `sega.preprocessed.s`, the SNES SPC700
+  driver, any `*.upstream.*`), wires the GBA runtime (libtonc/libgba/maxmod by
+  what the source includes), routes `#include`d C/asm siblings as includes, and
+  bundles every incbin asset (`.xgc`/`.vgz`/…). `output:'run'` accepts `path` too
+  (build+load+run+screenshot a dir in one call). One shared code path so the two
+  build routes can't drift. Locked in by `scaffold-build-happypath.test.js`.
+- **SNES multi-`.c` builds** (genre scaffolds ship `main.c` + `snes_sfx.c`) — the
+  stale single-`.c` guard in `buildSnesC` is removed (the link path already
+  handled multiple TUs).
+
+### Fixed — scaffolds rendered blank/wrong (now show content)
+- **SMS/GG**: `vdp_init` R6 default 0xFB→0xFF — sprite tiles now read from $2000
+  where scaffolds upload them (were reading the empty $0000 bank → invisible). GG
+  also: 64-byte GG palette format (scaffolds shipped 32) + visible-window coords.
+- **Genesis**: genre scaffolds now call `VDP_linkSprites` (the SAT link bytes were
+  0 = end-of-list → only slot 0 drew); shmup enemies spread across the field.
+- **SNES**: `sports`/`racing` `oamSet` now uses byte offsets (`slot<<2`); a real
+  4bpp console font is embedded (the stub made all text black) + the BG-base /
+  text-offset / `consoleVblank` wiring fixed → c_hello/puzzle/platformer show text.
+- **Lynx**: `platformer`/`puzzle`/`sports`/`racing` use the `while(tgi_busy()){}` +
+  full-screen `tgi_bar` clear (were black via bare `tgi_clear()`).
+- **C64**: genre sprite data moved $0800→$2000 (it collided with the $0801 `.prg`
+  load → `sports` crashed to BASIC, sprites corrupt).
+- **NES**: the bundled runtime no longer races the OAM-DMA — `oam_clear` resets the
+  index and `ppu_wait_nmi` hides unused slots after staging, so sprite-light
+  scaffolds no longer flicker to black; `default` backdrop no longer cycles to black.
+- **PCE**: `pce_video.c` now programs the VDC display timing (NTSC 256×224) — fixes
+  the vertically-doubled picture.
+- **GBA**: per-frame `tte_printf("%05d")` (broken in the bundled libtonc — garbles +
+  wedges the loop) replaced with a hand-built score string + `tte_write`.
+- **Atari 2600**: `paddle` kernel rebuilt to a 2-line kernel (the per-line work
+  overflowed a 76-cycle scanline → ~250 lines, no vsync lock); now stable at 210.
+
+### Changed
+- **Doc-drift swept**: every agent-facing `runSource`/`buildSource` → the current
+  `build({output:'run'|'rom'})`, dead tool names (`loadCategory`, `inspectSprites`,
+  …) → the consolidated forms, across the scaffold README emitter, `nextStep`,
+  examples, platform docs, and `.cfg` comments. Emitted scaffold-README `frames`
+  60→240 (60 caught the boot logo on some platforms → false "blank").
+- **Thin genres** given a BG world (Genesis sports court / racing road, NES racing
+  road, SNES sports/racing) so they read as the genre, not objects on black.
+- **Missing-genre error** for msx/pce/atari2600 now names the working project
+  templates instead of a bare "default".
+- The `uint8-loop-bound` preflight lint is scope-aware (no longer false-flags a
+  `uint16_t` loop counter that shares a name with a `uint8_t` in another function).
+
+## 0.14.0
+
+**Two platform-specific top-level tools folded into their domain verbs, a
+device-free cheat search, and skill-surface polish.** Pre-1.0 the surface keeps
+consolidating with no deprecated aliases (call `catalog({op:'whatsNew'})` for the
+live OLD→NEW map), so the tool count drops 34 → 32.
+
+### Changed (breaking — pre-1.0, no aliases)
+- **`patchGbHeader` → `romPatch({op:'gbHeader'})`.** It's a ROM-file patch, same
+  family as romPatch's other ops — not a standalone Game-Boy tool. Same params
+  (path/outputPath/cgb/title/cartType/romSize/ramSize/destination), same output.
+- **`dmaTrace` → `watch({on:'dma'})`.** The Genesis VDP-DMA trace is a log-all
+  trace like `watch`'s on:'mem'/'range'/'pc' — now a fourth `on`. Same
+  `precision:'exact'|'sampled'` + filters.
+- **`cheats({op:'search'})` no longer needs `platform`.** Omit it and the search
+  sweeps EVERY indexed platform; each match reports its own `platform`. You don't
+  have to know the console to find a game's cheats. Pass `platform` only to scope
+  the search to one console.
+
+### Added
+- **`GET /skills/romdev/SKILL.md`** is now the primary skill URL — it mirrors the
+  on-disk path agents save skills to (`~/.claude/skills/romdev/SKILL.md`) exactly.
+  `/romdev/SKILL.md` and the flat `/romdev-skill.md` are kept as aliases.
+- **The `/livestream` observer header now links to `/documentation`** (the live
+  Swagger console), so a human watching can jump to the API docs.
+
+### Fixed (HTTP transport — failures are now unmissable)
+- **A failed tool call returns a non-2xx, never a 200 with the error in the body.**
+  Tools that signal failure by RETURNING a failure-shaped result ({ok:false} /
+  {opened:false} / {applied:false} / a top-level `error`) — not just by throwing —
+  now map to HTTP 400 uniformly for EVERY tool. Before, e.g. `playtest` returning
+  `{opened:false}` came back 200, so an agent driving the REST/skill surface saw
+  "success," never read the body, and reported "window's up!" while no window
+  existed. (Valid "no"/state answers — `notSupported`, `matched:false`,
+  `loaded:false` — correctly stay 200.) A failed `playtest` window-open also now
+  logs to the server console so a human at the terminal sees it regardless.
+- **`x-romdev-session` is now REQUIRED — a missing header returns 401**, instead
+  of the server auto-minting a throwaway one-shot session (which silently dropped
+  the loaded ROM and surfaced as "No ROM loaded" a couple calls later). The 401
+  message tells the agent to pick one stable id and send it every call.
+
+### Fixed (playtest — no more invisible windows)
+- **`playtest({op:'open'})` now FAILS LOUDLY when there's no real display** instead
+  of reporting `opened:true` for a window nothing can see. If the server's SDL
+  comes up on the `offscreen`/`dummy` video driver (no desktop session — server
+  started over SSH, from a tty, before the desktop login, or as a headless agent
+  subprocess), the window would render and play audio but never appear on a
+  screen. We now detect the selected driver via SDL itself
+  (`sdl.info.drivers.video.current`) — ground truth, cross-platform (Linux/macOS/
+  Windows), and it correctly ALLOWS a virtual display like Xvfb (reports `x11`,
+  not `offscreen`). On the offscreen case the open throws (→ 400 / MCP error) with
+  the exact fix: run the server from inside your logged-in desktop session.
+  Headless tools (screenshot/runSource/inspect) are unaffected — offscreen stays
+  fine for everything except opening a window for a human.
+
+### Changed
+- **The skill/HTTP session docs now coach a UNIQUE, task-descriptive
+  `x-romdev-session` id** (e.g. `nes-platformer-build`) — the id is the label a
+  human sees in `/livestream`, and it's how several agents share one server
+  without clobbering each other's emulator host.
+
 ## 0.13.0
 
 **Renamed `romdev-mcp` → `romdevtools` + a plain-HTTP tool surface and an Agent
@@ -34,7 +158,7 @@ duplication). Same Express app, same localhost trust, per-agent dynamic sessions
   via zod→JSON-Schema (the same conversion MCP `tools/list` uses).
 - **`GET /documentation`** — Swagger UI over the spec: a live "try it" console.
 - **`GET /tool/{name}/schema`** — that tool's JSON Schema (a validator on demand).
-- **`GET /romdev-skill.md`** — the Agent Skills open-standard SKILL.md
+- **`GET /skills/romdev/SKILL.md`** — the Agent Skills open-standard SKILL.md
   (frontmatter + workflow guide + generated tool reference). ~100 tokens of
   name+description until invoked vs the always-on MCP tool defs — the on-demand
   context win. Works in Claude Code, opencode, OpenClaw, Hermes, etc. unchanged.

package/README.md

@@ -9,7 +9,7 @@ npx romdevtools
 That's it — one command starts the local romdev **tool server** (no global install, no host compiler/emulator). Point any coding agent at it three ways:
 
 - **Plain HTTP** — `POST http://127.0.0.1:7331/tool/{name}`; browse/try every tool at `/documentation`.
-- **Agent Skill** — `GET /romdev-skill.md` (the [Agent Skills](https://agentskills.io) standard; ~100 tokens until invoked).
+- **Agent Skill** — `GET /skills/romdev/SKILL.md` (the [Agent Skills](https://agentskills.io) standard; save it to your skills dir as `skills/romdev/SKILL.md`; ~100 tokens until invoked).
 - **MCP** — it's also a [Model Context Protocol](https://modelcontextprotocol.io/) server at `/mcp` for clients that want it.
 
 This package contains all the JavaScript — the tool surface, the WASM emulator host, the per-platform scaffolds, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages it depends on, loaded on demand the first time you build or run a given platform.
@@ -19,7 +19,7 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 ## What's in this package
 
 - **`bin`**
-  - `romdevtools` → the tool server (`src/mcp/server.js`). Serves the HTTP tool routes, `/documentation`, `/romdev-skill.md`, and an MCP endpoint on `http://127.0.0.1:7331` by default (`PORT` / `HOST` to override). `romdev-mcp` is kept as an alias of the same command.
+  - `romdevtools` → the tool server (`src/mcp/server.js`). Serves the HTTP tool routes, `/documentation`, `/skills/romdev/SKILL.md`, and an MCP endpoint on `http://127.0.0.1:7331` by default (`PORT` / `HOST` to override). `romdev-mcp` is kept as an alias of the same command.
   - `romdevtools-cli` → a smoke/utility CLI, incl. `romdevtools-cli play <rom>` (SDL window, hot-plug controllers).
 - **`src/`** — the server, MCP tools, WASM host, core/toolchain resolvers, per-platform memory interpretation, and bundled library/runtime source (cc65 libs, PVSnesLib, SGDK, libtonc/libgba, hUGEDriver, …) that scaffolded projects link against.
 - **`examples/`** — per-platform starter projects and genre scaffolds.
@@ -58,12 +58,17 @@ running server:
 - **Plain HTTP:** `POST http://127.0.0.1:7331/tool/{name}` with the args as a JSON
   body; the response is JSON. Browse/try every tool at **`/documentation`**
   (Swagger UI, served locally — no CDN), or get the machine spec at
-  **`/openapi.json`**. For stateful work (load → step → read) the first call
-  returns an `x-romdev-session` header — echo it on later calls to keep the same
-  emulator session. romdev runs **locally** and tool path args (`path`,
-  `outputPath`, …) are **local filesystem paths**, not uploads — pass absolute
-  paths on the same machine.
-- **Agent Skill:** **`GET /romdev-skill.md`** is a portable [Agent
+  **`/openapi.json`**. **The agent picks its own session id** and sends it as the
+  `x-romdev-session` header on every call — it's **required** (no header → `401`;
+  the server won't silently run you in a throwaway session). Make it unique and
+  task-descriptive (e.g. `nes-platformer-build`), since it's also the label shown
+  in the `/livestream` observer. The emulator host is per-session, so the same id
+  keeps your ROM across calls, and several agents can share one server by each
+  using a different id. A call that fails returns a non-2xx (4xx) with the reason
+  in the body — never a 200 that hides an error. romdev runs **locally** and tool
+  path args (`path`, `outputPath`, …) are **local filesystem paths**, not uploads
+  — pass absolute paths on the same machine.
+- **Agent Skill:** **`GET /skills/romdev/SKILL.md`** is a portable [Agent
   Skills](https://agentskills.io) `SKILL.md` (works in Claude Code, opencode,
   OpenClaw, Hermes, …). Drop it in your agent's skills dir; it costs ~100 tokens
   until invoked (vs always-on MCP tool defs), then teaches the workflows + the

package/examples/atari2600/main.asm

@@ -3,7 +3,7 @@
 ; standard NTSC frame timing (3 vsync + 37 vblank + 192 visible + 30
 ; overscan). Read joystick to move the sprite.
 ;
-; Build: buildSource({ platform: "atari2600", source: <this file> })
+; Build: build({ output: "rom",  platform: "atari2600", source: <this file> })
 
   processor 6502
   org $F000

package/examples/atari2600/templates/default.asm

@@ -3,7 +3,7 @@
 ; standard NTSC frame timing (3 vsync + 37 vblank + 192 visible + 30
 ; overscan). Read joystick to move the sprite.
 ;
-; Build: buildSource({ platform: "atari2600", source: <this file> })
+; Build: build({ output: "rom",  platform: "atari2600", source: <this file> })
 
   processor 6502
   org $F000

package/examples/atari2600/templates/paddle.asm

@@ -111,9 +111,14 @@ MAIN:
   STA VSYNC
 
   ; ── VBLANK (37 lines) — game logic ────────────────────────────────
+  ; 34 here + the 3 STA WSYNC in the P0/P1 positioning block below = 37 VBLANK
+  ; lines total. (Bug fix: this loop used to be 37 AND the positioning added 3
+  ; more → 265 scanlines/frame → the TV/emulator can't lock vsync → rolling /
+  ; black picture. Exactly 262 lines = 3 VSYNC + 37 VBLANK + 192 visible + 30
+  ; overscan; the positioning WSYNCs MUST be counted against the 37.)
   LDA #2
   STA VBLANK
-  LDX #37
+  LDX #34
 .vb:
   STA WSYNC
   DEX
@@ -212,93 +217,100 @@ MAIN:
   STA AUDV0
 .sfx_done:
 
-  ; Position P0 horizontally at column 16 (race-the-beam delay)
-  STA WSYNC
-  LDA #1
+  ; ── Position P0 / P1 / HMOVE — exactly 3 WSYNC-bounded lines ───────
+  ; CRITICAL: every RESPx write AND the STA HMOVE must complete inside
+  ; the 76-cycle scanline that began with its STA WSYNC. A DEX/BNE delay
+  ; loop costs 5 cycles/iteration, so the loop count must be small enough
+  ; that RESPx still lands before the line ends. The old code used
+  ; LDX #38 (~189 cycles = 2.5 scanlines!) with no WSYNC before RESP1/
+  ; HMOVE, so it emitted ~2-3 UNCOUNTED scanlines past the 262 budget →
+  ; ~265 lines/frame → vsync never locks (rolling magenta band). HMOVE
+  ; was also issued mid-line; it must follow a fresh WSYNC.
+
+  ; Line 1 of 3: coarse-position P0 (left, ~column 16)
   STA WSYNC
-  LDX #15
+  LDX #5
 .p0d:
   DEX
-  BNE .p0d
+  BNE .p0d           ; ~24 cycles in → P0 lands near the left edge
   STA RESP0
-  ; Position P1 at column 144
+  ; Line 2 of 3: coarse-position P1 (right, ~column 132)
   STA WSYNC
-  LDX #38
+  LDX #13
 .p1d:
   DEX
-  BNE .p1d
+  BNE .p1d           ; ~64 cycles in (< 76) → P1 lands near the right
   STA RESP1
+  ; Line 3 of 3: apply HMOVE on a FRESH line, right after WSYNC
+  STA WSYNC
   STA HMOVE
 
   LDA #0
   STA VBLANK
 
-  ; ── Visible (192 lines) ───────────────────────────────────────────
+  ; ── Visible (192 lines) — TWO-LINE KERNEL ─────────────────────────
+  ; CRITICAL: a single scanline is only 76 CPU cycles. The full per-line
+  ; render here (playfield walls + P0 + P1 + ball, each a SEC/SBC/CMP +
+  ; conditional store) is ~88 cycles — it does NOT fit in one line. In a
+  ; 1-line kernel each WSYNC iteration then spills past the line boundary,
+  ; so 192 iterations stretch to ~232 emitted lines → ~250-line frame →
+  ; vsync never locks (rolling magenta band — THE bug).
+  ;
+  ; The fix is the standard 2600 "2-line kernel": each loop pass renders
+  ; TWO scanlines and splits the work across two WSYNCs, doubling the
+  ; budget to ~152 cycles. 96 passes × 2 lines = 192 visible lines.
+  ; Y counts 192→2 in steps of 2; paddles/ball move in 2px steps (fine
+  ; for Pong). The branchless "LDA #off / CMP / BCS skip / LDA #on" form
+  ; also drops the JMPs the old code paid every line.
   LDY #192
 .draw:
+  ; ---- first line of the pair: playfield walls + left paddle ----
   STA WSYNC
-  TYA
-  ; Top-bottom walls: lines 0..3 and 188..191 draw a full-width PF
-  CMP #4
-  BCS .nottop
-  LDA #$FF
-  STA PF0
-  STA PF1
-  STA PF2
-  JMP .pf_done
-.nottop:
-  CMP #188
-  BCC .notbot
-  LDA #$FF
-  STA PF0
-  STA PF1
-  STA PF2
-  JMP .pf_done
-.notbot:
+  ; Top + bottom walls: full-width PF on the outer rows (Y>=189 / Y<5)
   LDA #0
+  CPY #189
+  BCS .wall
+  CPY #5
+  BCS .nowall
+.wall:
+  LDA #$FF
+.nowall:
   STA PF0
   STA PF1
   STA PF2
-.pf_done:
   ; Left paddle: 8 lines starting at P0_Y
   TYA
   SEC
   SBC P0_Y
   CMP #8
-  BCS .p0blank
-  LDA #$FF
-  STA GRP0
-  JMP .p0done
-.p0blank:
   LDA #0
+  BCS .p0off
+  LDA #$FF
+.p0off:
   STA GRP0
-.p0done:
+  ; ---- second line of the pair: right paddle + ball ----
+  STA WSYNC
   ; Right paddle: 8 lines starting at P1_Y
   TYA
   SEC
   SBC P1_Y
   CMP #8
-  BCS .p1blank
-  LDA #$FF
-  STA GRP1
-  JMP .p1done
-.p1blank:
   LDA #0
+  BCS .p1off
+  LDA #$FF
+.p1off:
   STA GRP1
-.p1done:
   ; Ball: 2 lines starting at BALL_Y
   TYA
   SEC
   SBC BALL_Y
   CMP #2
-  BCS .blblank
-  LDA #2
-  STA ENABL
-  JMP .bldone
-.blblank:
   LDA #0
+  BCS .bloff
+  LDA #2
+.bloff:
   STA ENABL
-.bldone:
+  DEY
   DEY
   BNE .draw
 

package/examples/atari7800/main.c

@@ -1,6 +1,6 @@
 // ── Hello, Atari 7800 — MARIA bring-up + single sprite ──────────────
 //
-// Build: buildSource({ platform: "atari7800", source: <this file>,
+// Build: build({ output: "rom",  platform: "atari7800", source: <this file>,
 //                      language: "c" })
 //
 // Sets up a minimal display list, paints the background blue and renders

package/examples/atari7800/templates/default.c

@@ -34,7 +34,7 @@
  * the 4KB of internal RAM.
  *
  * ── Build ───────────────────────────────────────────────────────
- *   buildSource({ platform: "atari7800", sources: { "main.c": ... } })
+ *   build({ output: "rom",  platform: "atari7800", sources: { "main.c": ... } })
  */
 #include <stdint.h>
 #include "atari7800_sfx.h"

package/examples/atari7800/templates/music_demo.c

@@ -10,7 +10,7 @@
  *
  * The note tables live in atari7800_music.c — they ARE the song.
  *
- * Build: buildSource({ platform: "atari7800", template: "music_demo" })
+ * Build: build({ output: "rom",  platform: "atari7800", template: "music_demo" })
  */
 #include <stdint.h>
 #include "atari7800_music.h"

package/examples/c64/main.c

@@ -4,7 +4,7 @@
 // directly: writes screen codes into screen RAM, sets per-cell colors
 // in color RAM, and cycles the border color in a main loop.
 //
-// Build: buildSource({ platform: "c64", source: <this file>, language: "c" })
+// Build: build({ output: "rom",  platform: "c64", source: <this file>, language: "c" })
 
 #include <stdint.h>
 

package/examples/c64/templates/platformer.c

@@ -80,7 +80,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -131,7 +131,7 @@ void main(void) {
 
   POKE(VIC_SPR_ENA, 0);
   copy_sprite(0, player_sprite);
-  SPRITE_POINTERS[0] = 0x20;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
   POKE(VIC_SPR_COL(0), 0x07);  /* yellow player */
   POKE(VIC_BORDER, 0x06);      /* dark blue */
   POKE(VIC_BG0,    0x06);

package/examples/c64/templates/puzzle.c

@@ -121,7 +121,7 @@ static void lock_piece(void) {
         grid[r][c] = 0;
         grid[r][c+1] = 0;
         grid[r][c+2] = 0;
-        if (score < 65500) score += 30;
+        if (score < 65500u) score += 30;
         sfx_tone(0, 0x80, 0x10, 12);
       }
     }

package/examples/c64/templates/racing.c

@@ -49,7 +49,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -75,8 +75,8 @@ void main(void) {
   uint8_t i, pad;
   POKE(VIC_SPR_ENA, 0);
   copy_sprite(0, car_sprite);
-  SPRITE_POINTERS[0] = 0x20;
-  for (i = 0; i < MAX_OBS; i++) SPRITE_POINTERS[1 + i] = 0x20;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
+  for (i = 0; i < MAX_OBS; i++) SPRITE_POINTERS[1 + i] = 0x80;
   POKE(VIC_SPR_COL(0), 0x07);  /* yellow player */
   for (i = 0; i < MAX_OBS; i++) POKE(VIC_SPR_COL(1 + i), 0x02);  /* red obstacles */
   POKE(VIC_BORDER, 0x00);

package/examples/c64/templates/shmup.c

@@ -20,7 +20,8 @@
 #define PEEK(addr)      (*(volatile uint8_t*)(addr))
 
 #define SPRITE_POINTERS  ((volatile uint8_t*)0x07F8)
-#define SPRITE_DATA_BASE 0x0800  /* sprite N data at $0800 + N*64 */
+#define SPRITE_DATA_BASE 0x2000  /* sprite N data at $2000 + N*64 — NOT $0800,
+                                  * which collides with the $0801 .prg load (C64-1) */
 
 #define JOY_UP    0x01
 #define JOY_DOWN  0x02
@@ -121,9 +122,9 @@ void main(void) {
 
   /* Sprite pointers: slot N points at /64 index into the VIC bank.
    * Default bank = $0000-$3FFF. $0800 / 64 = 32 = $20. */
-  SPRITE_POINTERS[SLOT_PLAYER] = 0x20;
-  for (i = 0; i < MAX_BULLETS; i++) SPRITE_POINTERS[SLOT_BULLET0 + i] = 0x21;
-  for (i = 0; i < MAX_ENEMIES; i++) SPRITE_POINTERS[SLOT_ENEMY0 + i] = 0x22;
+  SPRITE_POINTERS[SLOT_PLAYER] = 0x80;  /* $2000/64 */
+  for (i = 0; i < MAX_BULLETS; i++) SPRITE_POINTERS[SLOT_BULLET0 + i] = 0x81;
+  for (i = 0; i < MAX_ENEMIES; i++) SPRITE_POINTERS[SLOT_ENEMY0 + i] = 0x82;
 
   POKE(VIC_SPR_COL(SLOT_PLAYER), 0x07);  /* yellow */
   for (i = 0; i < MAX_BULLETS; i++) POKE(VIC_SPR_COL(SLOT_BULLET0 + i), 0x01);  /* white */
@@ -175,7 +176,7 @@ void main(void) {
         if (aabb(&bullets[i], &enemies[j])) {
           bullets[i].alive = 0;
           enemies[j].alive = 0;
-          if (score < 65500) score += 10;
+          if (score < 65500u) score += 10;
           sfx_noise(8);
           break;
         }

package/examples/c64/templates/sports.c

@@ -41,7 +41,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -56,9 +56,9 @@ void main(void) {
   copy_sprite(0, paddle_sprite);
   copy_sprite(1, paddle_sprite);
   copy_sprite(2, ball_sprite);
-  SPRITE_POINTERS[0] = 0x20;
-  SPRITE_POINTERS[1] = 0x21;
-  SPRITE_POINTERS[2] = 0x22;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
+  SPRITE_POINTERS[1] = 0x81;
+  SPRITE_POINTERS[2] = 0x82;
   POKE(VIC_SPR_COL(0), 0x01);  /* white */
   POKE(VIC_SPR_COL(1), 0x01);
   POKE(VIC_SPR_COL(2), 0x07);  /* yellow ball */

package/examples/gb/main.asm

@@ -4,7 +4,7 @@
 ; it to the BG map, enables the LCD, then loops reading joypad and
 ; scrolling the BG. Build with:
 ;
-;   buildSource({platform:"gb", source: <this>})
+;   build({ output: "rom", platform:"gb", source: <this>})
 ;
 ; rgbfix gets applied automatically by buildForPlatform so the header
 ; checksum is valid.