romdevtools 0.13.0 → 0.14.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
@@ -297,7 +297,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
@@ -1044,10 +1044,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.** 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 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,67 @@ 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.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 +95,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/cheats/lookup.js

@@ -121,37 +121,58 @@ function baseName(name) {
     .trim();
 }
 
+// The platforms that ship a bundled cheat index — the set searchCheatGames sweeps
+// when no `platform` is given. (Kept in step with cheats.js SUPPORTED; C64 has no
+// source cheats so it has no index.)
+const INDEXED_PLATFORMS = [
+  "nes", "gb", "gbc", "snes", "genesis", "sms", "gg",
+  "atari2600", "atari7800", "lynx", "gba", "pce", "msx",
+];
+
 /**
- * Fuzzy-search a platform's cheat index by game name. Returns the best-matching
- * game names + cheat counts WITHOUT dumping the whole DB — so an agent can find
- * "NBA Jam Tournament" → the real entry without a huge context load.
+ * Fuzzy-search the cheat DB by game NAME. Each match carries the `platform` it
+ * was found on, so the caller never has to know the console up front. By default
+ * this searches EVERY indexed platform (the natural ask: "find a game's cheats"
+ * — you shouldn't have to name the device); pass `platform` only to scope the
+ * search to one console. Returns best-matching game names + cheat counts WITHOUT
+ * dumping the whole DB.
  * @param {object} a
- * @param {string} a.platform
  * @param {string} a.query
+ * @param {string} [a.platform]  optional — restrict to one platform; omit to search all
  * @param {number} [a.limit]
  * @param {number} [a.minScore]
- * @returns {Promise<{platform:string, query:string, matches:Array<{game:string, score:number, cheats:number}>, gameCount:number, note:string}>}
+ * @returns {Promise<{platform:string|null, query:string, matches:Array<{game:string, platform:string, score:number, cheats:number}>, gameCount:number, note:string}>}
  */
 export async function searchCheatGames({ platform, query, limit = 12, minScore = 0.25 }) {
-  const idx = await loadIndex(platform);
-  if (!idx || !idx.games) {
+  const platforms = platform ? [platform] : INDEXED_PLATFORMS;
+  let scored = [];
+  let gameCount = 0;
+  let missing = [];
+  for (const plat of platforms) {
+    const idx = await loadIndex(plat);
+    if (!idx || !idx.games) { missing.push(plat); continue; }
+    gameCount += idx.gameCount ?? Object.keys(idx.games).length;
+    const fuse = await getFuse(plat);
+    if (!fuse) continue;
+    for (const r of fuse.search(baseName(query))) {
+      const score = simFromFuse(r.score);
+      if (score >= minScore) scored.push({ game: r.item.game, platform: plat, score, cheats: r.item.cheats });
+    }
+  }
+  // When scoped to one platform and that platform has no index at all, say so.
+  if (platform && missing.length) {
     return { platform, query, matches: [], gameCount: 0, note: `No bundled cheat index for platform '${platform}'.` };
   }
-  const names = Object.keys(idx.games);
-  const fuse = await getFuse(platform);
-  // Search the tag-stripped query against the tag-stripped baseName index.
-  const results = fuse.search(baseName(query));
-  const matches = results
-    .map((r) => ({ game: r.item.game, score: simFromFuse(r.score), cheats: r.item.cheats }))
-    .filter((m) => m.score >= minScore)
+  const matches = scored
     .sort((a, b) => b.score - a.score || a.game.length - b.game.length)
     .slice(0, limit);
+  const scope = platform ? `the ${platform} cheat DB` : `the cheat DB (all ${platforms.length - missing.length} platforms)`;
   return {
-    platform, query, matches,
-    gameCount: idx.gameCount ?? names.length,
+    platform: platform ?? null,
+    query, matches, gameCount,
     note: matches.length === 0
-      ? `No game in the ${platform} cheat DB (${names.length} games) is close to "${query}". Try fewer/looser words.`
-      : `${matches.length} candidate(s) by fuzzy name match (region/revision tags ignored, typo-tolerant). Pass an exact \`game\` to cheats({op:'lookup'}) (it also fuzzy-matches). Score is name similarity, not a content guarantee — verify a label before patching.`,
+      ? `No game in ${scope} (${gameCount} games) is close to "${query}". Try fewer/looser words.`
+      : `${matches.length} candidate(s) by fuzzy name match across ${platform ? "1 platform" : "all platforms"} (each match shows its \`platform\`; region/revision tags ignored, typo-tolerant). To read a game's cheats, call cheats({op:'lookup', platform, game}) with the match's own platform. Score is name similarity, not a content guarantee — verify a label before patching.`,
   };
 }
 

package/src/http/routes.js

@@ -5,20 +5,22 @@
 //   GET  /tool/:name/schema   that tool's JSON Schema (a validator on demand)
 //   GET  /openapi.json        OpenAPI 3.1 spec for every /tool/:name route
 //   GET  /documentation       Swagger UI over /openapi.json (live "try it" console)
-//   GET  /romdev-skill.md     the SKILL.md (Agent Skills open standard) — channel
-//                             doc that drives the routes, never mentions MCP
+//   GET  /skills/romdev/SKILL.md  the SKILL.md (Agent Skills open standard) — the
+//                             channel doc that drives the routes, never mentions
+//                             MCP. Also at /romdev/SKILL.md and /romdev-skill.md.
 //
-// Sessions: each agent gets its own session dynamically, same isolation as MCP.
-// First call with no x-romdev-session → mint one, return it in the response
-// header; the agent echoes it on later calls (sticky host across load→step→read).
-// A call with no header gets an ephemeral per-request session (fine for pure-file
-// tools; stateful host work should keep the header). No auth — localhost trust,
-// same as /mcp (the app already mounts localhostHostValidation()).
+// Sessions: each agent picks its own stable id and sends it as x-romdev-session
+// on EVERY call (same per-agent host isolation as MCP). The header is REQUIRED —
+// no header → 401 (we don't auto-mint a throwaway session; that silently dropped
+// the loaded ROM and surfaced as "No ROM loaded" later). First use of an id
+// creates the session, reuse keeps the host across load→step→read, different ids
+// isolate different agents. No auth beyond that — localhost trust, same as /mcp
+// (the app already mounts localhostHostValidation()).
 
-import { randomUUID } from "node:crypto";
 import { buildToolRegistry, runTool, toolJsonSchema } from "./tool-registry.js";
 import { skillPreamble, skillToolReference, buildSkillDoc } from "./skill-doc.js";
 import { swaggerHtml, swaggerAsset } from "./swagger.js";
+import { observer } from "../observer/bus.js";
 import { log } from "../mcp/log.js";
 
 const SESSION_HEADER = "x-romdev-session";
@@ -40,12 +42,16 @@ export function mountHttpToolRoutes(app, opts = {}) {
   /** @type {Map<string, {registry: Map<string,any>, lastSeen: number}>} */
   const sessions = new Map();
 
-  function getSession(sessionKey) {
+  function getSession(sessionKey, { sticky = false } = {}) {
     let s = sessions.get(sessionKey);
     if (!s) {
-      s = { registry: buildToolRegistry(sessionKey), lastSeen: Date.now() };
+      s = { registry: buildToolRegistry(sessionKey), lastSeen: Date.now(), sticky };
       sessions.set(sessionKey, s);
       log.debug(`[http] session ${sessionKey.slice(0, 8)} created (${sessions.size} active)`);
+      // Surface sticky sessions in /livestream (like the MCP path does on init).
+      // Ephemeral one-shot sessions are NOT registered (they'd spam connect/
+      // disconnect); their individual `call` events still show in the stream.
+      if (sticky) { try { observer.sessionConnected(sessionKey); } catch {} }
     } else {
       s.lastSeen = Date.now();
     }
@@ -58,6 +64,7 @@ export function mountHttpToolRoutes(app, opts = {}) {
     for (const [key, s] of sessions) {
       if (now - s.lastSeen > idleMs) {
         sessions.delete(key);
+        if (s.sticky) { try { observer.sessionDisconnected(key); } catch {} }
         log.debug(`[http] session ${key.slice(0, 8)} reaped (idle)`);
       }
     }
@@ -71,30 +78,38 @@ export function mountHttpToolRoutes(app, opts = {}) {
   // ── POST /tool/:name ──────────────────────────────────────────────────────
   app.post("/tool/:name", async (req, res) => {
     const name = req.params.name;
-    // session: sticky if header present, ephemeral otherwise.
-    let sessionKey = req.headers[SESSION_HEADER];
-    let ephemeral = false;
+    // Session model: the AGENT picks its own stable, task-descriptive id and
+    // sends it as x-romdev-session on EVERY call — first use creates the session,
+    // reuse keeps the same host/state (load→step→read), and different ids isolate
+    // different agents. NO HEADER → 401: we don't auto-mint a throwaway session
+    // (that silently dropped the loaded ROM and surfaced as "No ROM loaded" two
+    // calls later). Requiring the header up front turns that silent footgun into
+    // a loud, fixable 401.
+    const sessionKey = req.headers[SESSION_HEADER];
     if (typeof sessionKey !== "string" || !sessionKey) {
-      sessionKey = randomUUID();
-      ephemeral = true;
+      res.status(401).json({
+        error: "Missing required `x-romdev-session` header. Pick ONE stable, " +
+          "task-descriptive id for yourself (e.g. 'nes-platformer-build') and send " +
+          "it on EVERY call — it's your per-session emulator key (the ROM you load " +
+          "lives under it; the next call only sees it with the SAME id) and the " +
+          "label shown in the /livestream observer. Several agents share one server " +
+          "by each using a different id.",
+      });
+      return;
     }
-    const { registry } = getSession(sessionKey);
+    const { registry } = getSession(sessionKey, { sticky: true });
     const tool = registry.get(name);
     if (!tool) {
       res.status(404).json({
-        error: `Unknown tool '${name}'. GET /openapi.json or /romdev-skill.md for the list.`,
+        error: `Unknown tool '${name}'. GET /openapi.json or /skills/romdev/SKILL.md for the list.`,
       });
       return;
     }
-    // echo the session id so the agent can reuse it (esp. when we minted one)
+    // echo the session id back (convenience for clients that log it)
     res.setHeader(SESSION_HEADER, sessionKey);
-    const out = await runTool(tool, req.body);
-    if (ephemeral) {
-      // drop the ephemeral session immediately (no sticky host wanted)
-      sessions.delete(sessionKey);
-    }
+    const out = await runTool(tool, req.body, sessionKey);
     if (out.ok) res.json(out.result);
-    else res.status(400).json({ error: out.error });
+    else res.status(400).json(out.result ?? { error: out.error });
   });
 
   // ── GET /tool/:name/schema ────────────────────────────────────────────────
@@ -122,17 +137,26 @@ export function mountHttpToolRoutes(app, opts = {}) {
     res.send(buf);
   });
 
-  // ── GET /romdev-skill.md ──────────────────────────────────────────────────
-  app.get("/romdev-skill.md", (req, res) => {
+  // ── GET /skills/romdev/SKILL.md (primary) + aliases ───────────────────────
+  // Agents store skills on disk as skills/<name>/SKILL.md (a dir named after the
+  // skill, canonical file SKILL.md). We serve the same doc at several paths so
+  // the URL matches wherever the agent saved it:
+  //   /skills/romdev/SKILL.md  — primary: full disk mirror (~/.claude/skills/romdev/SKILL.md)
+  //   /romdev/SKILL.md         — alias: the <name>/SKILL.md tail
+  //   /romdev-skill.md         — alias: flat form (older refs)
+  const serveSkill = (req, res) => {
     const md = buildSkillDoc({
       registry: metaRegistry,
       agentsBody: opts.agentsBody ?? "",
       version,
     });
     res.type("text/markdown").send(md);
-  });
+  };
+  app.get("/skills/romdev/SKILL.md", serveSkill);
+  app.get("/romdev/SKILL.md", serveSkill);
+  app.get("/romdev-skill.md", serveSkill); // alias
 
-  log.debug("[http] tool surface mounted: POST /tool/:name, /openapi.json, /documentation, /romdev-skill.md");
+  log.debug("[http] tool surface mounted: POST /tool/:name, /openapi.json, /documentation, /skills/romdev/SKILL.md");
   return { sessions, stop: () => clearInterval(reaper) };
 }
 
@@ -158,13 +182,14 @@ export function buildOpenApi(registry, version) {
         },
         responses: {
           200: { description: "Tool result (JSON).", content: { "application/json": { schema: { type: "object" } } } },
-          400: { description: "Validation or tool error.", content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } } },
+          400: { description: "Validation or tool error (the action did not succeed).", content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } } },
+          401: { description: "Missing required x-romdev-session header.", content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } } },
           404: { description: "Unknown tool." },
         },
         parameters: [{
-          name: SESSION_HEADER, in: "header", required: false,
+          name: SESSION_HEADER, in: "header", required: true,
           schema: { type: "string" },
-          description: "Per-agent session id. Omit on the first call to get one back in the response header; echo it on later calls to keep a sticky emulator session (load→step→read). Omit entirely for one-shot pure-file tools.",
+          description: "REQUIRED. Per-agent session id — pick one stable, UNIQUE, task-DESCRIPTIVE string (e.g. 'nes-platformer-build', 'zelda-romhack-text') and send it on EVERY call. It's the per-session emulator key (load→step→read state lives under it) AND the label shown in the /livestream observer, so a descriptive id tells a watching human which task each call belongs to. Several agents share one server safely by each using a different id. Missing → 401.",
         }],
       },
     };
@@ -174,7 +199,7 @@ export function buildOpenApi(registry, version) {
     info: {
       title: "romdev HTTP tool API",
       version,
-      description: "Plain-HTTP surface for romdev's retro-game-dev tools — the non-MCP way to drive the same tools. Generated from the tool registry. See /romdev-skill.md for the workflow guide.",
+      description: "Plain-HTTP surface for romdev's retro-game-dev tools — the non-MCP way to drive the same tools. Generated from the tool registry. See /skills/romdev/SKILL.md for the workflow guide.",
     },
     servers: [{ url: "/" }],
     paths,

package/src/http/skill-doc.js

@@ -3,7 +3,7 @@
 // One shared body (AGENTS.md, channel-neutral) is wrapped per delivery channel:
 //   - MCP connection instructions = mcpPreamble + body   (says "call the MCP
 //     tools"; never mentions HTTP routes / skills)
-//   - GET /romdev-skill.md        = skill frontmatter + skillPreamble + body +
+//   - GET /skills/romdev/SKILL.md = skill frontmatter + skillPreamble + body +
 //     generated tool reference     (says "POST /tool/{name}"; never mentions MCP)
 //
 // So neither surface mentions the other: the delivery instructions live in the
@@ -38,8 +38,8 @@ export const skillPreamble = [
   "  • GET  /tool/{name}/schema — that tool's JSON Schema (the exact parameters + types).",
   "  • GET  /openapi.json — the full machine-readable API; GET /documentation — a browsable console.",
   "",
-  "Sessions (for stateful work like load→step→read): your first POST returns an `x-romdev-session` header.",
-  "Echo that header on subsequent calls to keep the SAME emulator session. Omit it for one-shot file tools.",
+  "## Sessions — IMPORTANT for stateful work (load → step → read)",
+  "**Pick ONE session id for yourself and send it as the `x-romdev-session` header on EVERY call.** Make it UNIQUE and DESCRIPTIVE of what you're doing — e.g. `nes-platformer-build`, `zelda-romhack-text`, `gba-sprite-debug` (a slug, optionally with a short random suffix to stay unique). A human may be watching the live observer at /livestream, where your session id is the label for all your activity — a descriptive id tells them at a glance which agent/task each call belongs to; a bare uuid or `default` is opaque. The emulator/host is per-session: the ROM you `loadMedia` lives in YOUR session, and the next `frame`/`memory`/`cpu` call only sees it if it carries the SAME id. Do NOT send a new id each call — that's a fresh empty session every time (your loaded ROM vanishes; \"No ROM loaded\"). Several agents can share one server safely: each just sends a DIFFERENT id, so nobody clobbers another's ROM (another reason to make yours distinctive). The header is REQUIRED on every `/tool/{name}` call — omit it and you get a **401** (the server will NOT silently run you in a throwaway session). Pure file tools (romPatch/cart/encodeAudio) still need the header; just reuse your one id everywhere.",
   "",
   "Each tool is a domain VERB keyed by an operation axis — e.g. POST /tool/memory {\"op\":\"read\",…},",
   "POST /tool/build {\"output\":\"rom\",…}, POST /tool/romPatch {\"op\":\"findPointer\",…}. The full per-tool",
@@ -47,7 +47,7 @@ export const skillPreamble = [
 ].join("\n");
 
 /**
- * Build GET /romdev-skill.md: frontmatter + skill preamble + shared body +
+ * Build GET /skills/romdev/SKILL.md: frontmatter + skill preamble + shared body +
  * generated tool reference.
  * @param {{registry: Map<string,any>, agentsBody: string, version?: string}} args
  * @returns {string}
@@ -68,16 +68,17 @@ export function buildSkillDoc({ registry, agentsBody, version }) {
 
   // Update note — stamped with the running server's version. A saved skill is a
   // static snapshot (it doesn't auto-update), but this doc is GENERATED live from
-  // the running server, so re-fetching always gives you the current version. The
-  // server reports its version at GET /healthz, so an agent can detect staleness.
+  // the running server, so re-fetching always gives the current version. An agent
+  // can check the running version two ways: the tool call POST /tool/catalog
+  // {"op":"status"} → `romdevVersion`, or GET /healthz → `version`.
   const v = version ?? "0.0.0";
   const updateNote = [
     "## Keeping this skill current",
     `This skill was generated by romdev **v${v}** (it's a snapshot — it does not auto-update). ` +
     "romdev generates it live from the running server, so to update: run the latest `npx romdevtools`, " +
-    `then re-fetch \`GET http://localhost:7331/romdev-skill.md\` and overwrite your saved copy. ` +
-    "The running server reports its version at `GET /healthz` (`{\"version\":\"…\"}`) — if it's newer than the " +
-    "`metadata.version` above, your saved skill is stale; re-fetch it.",
+    `then re-fetch \`GET http://localhost:7331/skills/romdev/SKILL.md\` and overwrite your saved copy. ` +
+    "To check whether you're stale, ask the running server its version — `POST /tool/catalog {\"op\":\"status\"}` " +
+    "returns `romdevVersion` (or `GET /healthz` → `version`); if it's newer than the `metadata.version` above, re-fetch.",
   ].join("\n");
 
   return [

package/src/http/swagger.js

@@ -56,7 +56,7 @@ export function swaggerHtml(opts = {}) {
     <p>Loading interactive docs… If this doesn't render, the raw OpenAPI spec is at
        <a href="${specUrl}"><code>${specUrl}</code></a>, every tool is callable via
        <code>POST /tool/{name}</code>, and the workflow guide is at
-       <a href="/romdev-skill.md"><code>/romdev-skill.md</code></a>.</p>
+       <a href="/skills/romdev/SKILL.md"><code>/skills/romdev/SKILL.md</code></a>.</p>
   </div>
   <div id="swagger-ui"></div>
   <script src="${base}/swagger-ui-bundle.js"></script>