romdevtools 0.22.1 → 0.24.0

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -22,6 +22,32 @@ read that platform's `platform({op:'doc', platform, name:'mental_model'})`.
 The cheat DB is bundled (`romdev_game_codes`). Do **not** scan the user's disk for
 `.cht` files — if it's not in the bundled DB, treat it as absent and RE it.
 
+**Reading a `cheats({op:'lookup'})` hit as a RAM/code map.** Each decoded part carries an
+`address`, a `value`, a `kind` (`ram` = a labeled variable; `code` = a labeled ROM
+patch site, has a `compare`), and a `device` (`game-genie`/`pro-action-replay`/
+`gameshark`/`action-replay`/`raw`). So "which byte holds magic?" → one `lookup` call.
+Filter a long list with `filter:"health"` or `kind:"ram"`. A match is by No-Intro
+**name/filename, NOT a verified CRC** — it's PROBABLE (a different region/revision can
+move addresses), so confirm before patching. The cheapest confirmation is to apply it
+and watch: `cheats({op:'apply', path, desc})` → `frame({op:'screenshot'})`.
+
+`cheats({op:'apply'})` is non-destructive (volatile core state, the RetroArch way — the ROM
+file is never touched; `host({op:'reset'})`/`state({op:'load'})`/`cheats({op:'clear'})` removes it). It takes a
+matched `desc`, a raw `code`, or `loadMedia({cheats:[…]})` to seed codes BEFORE frame 0.
+`appliedAs` reports how it went in (`ram` poke / `rom` read-intercept / `raw` device
+code). DB coverage is 13/14 (every tier-1 system except C64); GBA cheats are
+encrypted, so apply-only (no labeled-address map — see `mapNote`).
+
+**Creating a NEW code — `cheats({op:'make', platform, address, value, compare?})`.** The inverse of
+decoding: turn a byte you found (via §1 or `breakpoint`) into a shareable, verified code,
+for ANY ROM incl. your own homebrew/WIP. A RAM cheat needs just `address`+`value`; a ROM
+patch adds `compare` (the byte currently there). It encodes for the platform's native
+device(s) and labels each (NES/Genesis → Game Genie; SNES → Pro Action Replay **and**
+Game Genie; GB/GBC → Game Genie + GameShark; SMS/GG → Action Replay) plus the raw
+`ADDR:VAL`; each carries `verified:true` (round-trips against the full DB). Systems with no
+letter-code device (Atari 2600/7800, Lynx, GBA, C64, PC Engine, MSX) get a verified raw
+code. Works on all 14. Nothing is ever written to a ROM file.
+
 ---
 
 ## 1. To find the RAM address of a value (score / timer / stat / HP / record-id)
@@ -50,12 +76,20 @@ usually a struct/entity array, each island one record.
 The #1 trap: visible names/labels are often **pre-rendered tile GRAPHICS**, not
 font-rendered from an ASCII string. Patching the ASCII string then does nothing.
 
-1. `text({op:'learn'})` on the on-screen text. If it reports
-   `likelyPreRenderedGraphic:true` (unique sequential tiles, no font reuse),
-   **stop** — the text is a bitmap. Editing it means changing tile pixels, not a
-   string. Do not patch any ASCII string you found; it isn't the source.
-2. If it IS font-rendered, find the string with `text({op:'find'})` /
-   `text({op:'encode'})` and patch that.
+1. `text({op:'learn'})` on the on-screen text — it infers the game's char→tile-ID map
+   (games use their own encoding: Excitebike A=$0A, Mario ASCII-offset, FF sparse). Two
+   modes: ROM mode `knownStrings:[{text, offset}]` when you found the bytes; **LIVE mode
+   `fromScreen:[{text, row, col}]`** reads the tile IDs straight off the live BG map at a
+   tile position (`background({view:'map'})` shows where the text sits) — this breaks the
+   chicken-and-egg of needing the offset you're still hunting. Live mode works on every
+   tilemap platform (NES/SNES/Genesis/GB/GBC/SMS/GG/C64); atari2600/7800, lynx, gba have
+   no text nametable → ROM mode only. If `learn` reports `likelyPreRenderedGraphic:true`
+   (unique sequential tiles, no font reuse), **stop** — the text is a bitmap. Editing it
+   means changing tile pixels, not a string. Do not patch any ASCII string you found.
+2. If it IS font-rendered: `text({op:'find', romPath, text, fontMap})` locates the string
+   (returns `fileOffset`, `prgFileOffset`, and a bank-aware `cpuAddress`+`bank` to feed
+   `disasm({target:'rom'})`; flags a likely length-prefix byte to avoid the overrun trap),
+   then `text({op:'encode', text, fontMap})` → bytes for `romPatch({op:'write'})`.
 3. To find where a graphic/text was sourced from: on **Genesis**, `watch({on:'dma', precision:'sampled'})`
    — drive to the screen that shows the graphic, and it reports the ROM offset(s)
    the tiles were DMA'd from (decoded from the VDP DMA registers). Edit the tile
@@ -103,6 +137,15 @@ from a SOURCE struct rather than written in place. Don't conclude "the address
 is wrong." Find the source: `memory({op:'search'})` the live value to locate the struct
 the copy reads from, then `breakpoint({on:'write'})` on THAT.
 
+**Precision — exact vs sampled.** The default `breakpoint({on:'write'})` is a core-level write
+watchpoint: it returns the EXACT writing instruction's PC, captured inside the CPU write
+path — correct even for NMI/IRQ-driven writes (the common case where a frame-sampled PC
+is just the idle loop). On a banked mapper it reports the `bank` (NES/GB/SMS-GG) so you
+can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
+`breakpoint({on:'write', precision:'sampled'})` (a.k.a. `watch({on:'mem'})`) steps until the byte changes
+and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
+value timeline or when you just want the change history, and cross-check the value trace.
+
 ---
 
 ## 5b. To READ a register at an instruction — execution breakpoints (all 14)
@@ -254,6 +297,101 @@ and `input({op:'set'})` state it too.)
 
 ---
 
+## 7. Authoring & verifying the byte patch
+
+Once you know WHAT to change, the write loop is a handful of calls — no custom scripts:
+
+- **`assembleSnippet({cpu, origin, code})`** — assemble a tiny asm chunk to raw bytes (no
+  header/linker/segments). CPUs: `6502 / 65c02 / 65816 / 68k / z80 / sm83 / gb / gbc /
+  huc6280`. **Z80 gotcha:** the sdas dialect requires `#` on immediates (`ld a,#5`, not
+  `ld a,5`).
+- **`romPatch({op:'write', path, offset, hex, expect})`** — the splicer THE other hack tools
+  compose through. **Always pass `expect`** (the current bytes) — it refuses the write if
+  they don't match, catching a hex/dec slip or a patch authored against region A applied to
+  region B. `allowExpand` for size-changing edits.
+- **`romPatch({op:'diff', platform, a, b})`** — mapper-aware ROM diff: reports CPU addresses
+  (NROM-128 mirrors, SNES LoROM `XX:XXXX`), per-region tallies (PRG vs CHR vs header), and
+  `tile:N` annotations on CHR changes for direct sprite-hack identification. Use it to
+  confirm a patch landed where you meant.
+- **`disasm({target:'references', path, platform, address})`** — find every instruction that
+  references a target address, classified `call/jump/branch/read/write/use/ref` (walks the
+  vector table too). The fast "who touches this?" for a STATIC image. Limitation: direct
+  addressing only — indirect/computed jumps aren't detected (use the runtime `watch`/
+  `breakpoint` tools in §5/§5d for those).
+- **`cart({op:'extract', path, outputDir})`** — split a ROM into standard parts (NES header/
+  prg/chr; SNES copier_header+rom+internal header; Genesis vectors/header/body; GB boot/
+  header/body) + a `manifest.json` (mapper, mirroring…). **`cart({op:'wrap'})`** is the inverse:
+  emits `wrapperSource` + `linkerConfig` ready for `build({output:'rom'})`.
+
+Verify-before-patch: `memory({op:'write', region:'system_ram', offset, hex})` on the LIVE emulator and
+watch the screen react — cheaper than shipping a wrong ROM patch.
+
+## 7b. Whole-ROM rebuildable disassembly — `disasm({target:'project'})`
+
+For a STRUCTURAL hack (new logic, not a byte poke), turn the whole ROM into a
+re-buildable project in one call: `disasm({target:'project', path, outputDir})`. It splits
+the ROM into regions (per-16KB bank for banked NES, per-32KB for SNES LoROM, slot0+slotX
+for GB, one flat region for SMS/Genesis/C64/Atari), disassembles each through the CPU's
+native objdump, then **reassembles + verifies byte-exact** against the original; any line
+that won't reproduce faithfully heals to a `.byte`/`db` of its real bytes, so the emitted
+`.asm` ALWAYS rebuilds (`roundTrip.allByteExact`). `readablePercent` per region tells you
+how much came back as real instructions vs. data. Alongside the `.asm` it writes the
+turnkey **rebuild glue**: data blobs (NES CHR-ROM → `chr.bin`; stripped Genesis/GBA/Lynx/MSX
+cartridge header → `*.bin`), a `BUILD.md` with the exact steps, and — where a one-call
+rebuild exists — a `rebuild.json` of the precise `build({...})` args. So the loop is
+`disasm({target:'project'})` → edit a `.asm` → rebuild → `romPatch({op:'diff'})` to confirm.
+
+**Two rebuild tiers** (the disasm emits each CPU's native-reassembler syntax — ca65 for
+6502/65816, GNU `as` for m68k/arm/z80/gbz80 — which only some `build()` toolchains consume):
+- **One-call `build()` rebuild, byte-identical** — **NES, C64, Atari 7800, Lynx**. Feed
+  `rebuild.json` straight to `build`. (Lynx: `build()` yields the headerless image; prepend
+  the shipped `lnx_header.bin` for the full `.lnx`.)
+- **Native-recipe rebuild (`buildCall:null`), byte-identical, steps in `BUILD.md`** — **SMS,
+  GG, MSX, GB, GBC, Genesis, GBA, Atari 2600**. Their `build()` toolchains (SDCC/RGBDS/asar/
+  dasm/vasm) can't reassemble ca65/GNU-as syntax, so `BUILD.md` gives the proven native
+  `as`/`ld`/`objcopy` chain.
+- **PC Engine** is the one not-yet-byte-exact case (the region trims real padding / doesn't
+  strip a copier header) — `BUILD.md` flags it.
+
+**Rebuilding a commercial NES (NROM CHR-ROM) game — `build({inesHeader})`:** the most common
+NES RE rebuild. `build({output:'rom', platform:'nes', inesHeader:{prgBanks, chrBanks, mapper,
+mirroring}, sourcesPaths:{…the PRG…}, binaryIncludePaths:{"chr.bin":…}})` auto-emits the
+16-byte iNES header + CHARS-segment wiring + flat NROM `.cfg` — no hand-derived header bytes.
+`disasm({target:'project'})` puts exactly this call in `rebuild.json`. (For homebrew C that
+ships fixed tile art, `linkerConfig:"chr-rom"` is the segment-split equivalent.)
+
+**Readability caveats** (the bytes are ALWAYS correct; only instruction-vs-`.byte` coverage
+varies): SNES and large Genesis ROMs come back byte-exact but DATA-ONLY (flat whole-ROM
+disasm of a mostly-data image heals to `.byte` — meaningful coverage needs recursive
+entry-point following, a known follow-up). GBA reads LOW because GBA C compiles mostly to
+Thumb reached via an ARM crt0 stub, so an ARM-mode disasm decodes Thumb spans as `.byte`.
+Banked-NES is the strongest case (~100% instructions); GB/GBC, SMS/GG, C64, Atari are also
+near-100%.
+
+## 8. Graphics swaps — PNG ↔ tiles round-trip
+
+For sprite/tile edits (not text), don't hand-roll the tile-format math:
+
+- **`tiles({op:'png', source:'path', platform, path, bank, paletteFromEmulator, paletteIndex})`** —
+  a source ROM's tiles → PNG. `bank:N` (NES 4 KB CHR bank) replaces magic file-offset math;
+  `paletteFromEmulator:true`+`paletteIndex` colors the export with the LIVE palette (vs
+  grayscale) so the art is recognizable to edit.
+- **`importArt({from:'rom', sourceRom, sourcePlatform, sourceBank, sourceTileX/Y/W/H, targetPlatform,
+  outputPng, intent, paletteIndex})`** — one-call lift of a tile region from a source ROM into
+  the target platform's format (extract+crop+quantize). `intent:"homebrew"` reads the live
+  source palette; `intent:"rom-hack"` preserves source bytes verbatim.
+- **`encodeArt({stage:'tiles', platform, pngBase64})`** → target-platform tile bytes.
+- **`romPatch({op:'spliceCHR', path, platform, pngBase64, tileIndex, expect, bank, paletteHint})`** —
+  PNG → tile bytes → splice into CHR at tile slot N (auto-locates iNES CHR base; `expect`
+  checks the existing tile bytes; `paletteHint:["#RRGGBB",…]` gives explicit RGB→index
+  mapping). Composes the `encodeArt`+`romPatch({op:'write'})` step in one call.
+- **`background({view:'rendered'})`** — at the current state, the set of tile IDs actually drawn
+  (BG nametable + OAM). Sample at title/gameplay/menu and diff the sets to map tile IDs to
+  assets without scanning sheets by eye. (`romPatch({op:'findFree'})` locates $FF/$00 runs for asm
+  overlays, longest-first.)
+
+---
+
 ## Quick reference
 
 | Goal | Tool |
@@ -276,4 +414,15 @@ and `input({op:'set'})` state it too.)
 | Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |
 | Free RAM map for a known game | `cheats({op:'lookup'})` / `cheats({op:'search'})` |
+| Apply a cheat live (non-destructive) | `cheats({op:'apply'})` (verify a label / fun) |
+| Create a shareable code from a byte | `cheats({op:'make'})` (verified, all 14) |
+| Read on-screen text's tile map | `text({op:'learn', fromScreen})` (live, no offset needed) |
+| Find / encode a font-rendered string | `text({op:'find'})` → `text({op:'encode'})` |
+| Assemble asm → raw patch bytes | `assembleSnippet({cpu, origin, code})` |
+| Mapper-aware diff of two ROMs | `romPatch({op:'diff'})` (CPU addrs, CHR `tile:N`) |
+| Who references this address (static) | `disasm({target:'references'})` (direct modes only) |
+| Split / rebuild a ROM into parts | `cart({op:'extract'})` / `cart({op:'wrap'})` |
+| Swap a sprite/tile (PNG round-trip) | `tiles({op:'png'})` → edit → `romPatch({op:'spliceCHR'})` |
+| Lift art from another game's ROM | `importArt({from:'rom'})` |
+| Tile IDs actually being drawn now | `background({view:'rendered'})` |
 | Safe patch | `romPatch({op:'write'})`/`romPatch({op:'writeMany'})` with `expect` |

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -192,3 +192,40 @@ When you call `build({output:'rom', platform:"atari2600", source: ...})`:
 2. The result is `.a26` — loadable in stella (`loadMedia`).
 
 There's no linker — dasm produces a complete cart in one pass.
+
+## MCP debug & inspection tooling
+
+The 2600 runs on the **stella2014 (patched)** core. Because the 2600 has
+no framebuffer and no standard sound chip, its inspectors look different
+from the tilemap consoles — they decode the live TIA snapshot instead.
+
+What you can read:
+
+- **`palette({source:'live'})`** — the NTSC 128-color palette as a PNG,
+  with the *current* TIA background luma+hue extracted from the live
+  snapshot so you can see what color the beam is painting right now. This
+  is the same 128-entry `HHHHLLLL` palette the 7800 uses.
+- **`sprites({op:'inspect'})`** — there is **no OAM** on the 2600, so this
+  returns the state of the 5 TIA graphics objects (P0, P1, M0, M1, Ball)
+  plus a current-scanline PNG showing how the TIA is composing that line.
+- **`cpu({op:'read'})`** — the 6502 register file (A / X / Y / P / SP / PC)
+  pulled from the M6502 core's internal regs.
+- **`background({view:'renderState'})`** — decodes the 32-byte TIA snapshot
+  into the playfield pattern, per-object enables/positions, and the color
+  registers.
+- **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
+  both anchor to the top of the bank (`$F000-$FFFF`) and label the vector
+  table (NMI / RESET / IRQ at `$FFFA`).
+
+Memory regions for **`memory({op:'read'})`**:
+
+| Region | Size | What it is |
+| --- | --- | --- |
+| `system_ram` | 128 bytes | the RIOT RAM — that's the *entire* console RAM |
+| `a26_tia_regs` | 32 bytes | the live TIA register snapshot |
+| `a26_cpu_regs` | 7 bytes | the 6502 register snapshot |
+
+**No `audioDebug` inspector.** The 2600's sound comes from the two TIA
+audio voices (`AUDC/AUDF/AUDV` at `$15-$1A`), not a standard PSG/FM chip,
+so there's no `audioDebug` decode — read the audio state directly out of
+the `a26_tia_regs` snapshot instead.

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -322,3 +322,39 @@ When you call `build({output:'rom', platform:"atari7800", language:"c"})`:
 3. ld65 links + atari7800.cfg → flat `.a78` ROM.
 
 Loadable via prosystem (`loadMedia`).
+
+## MCP debug & inspection tooling
+
+The 7800 runs on the **prosystem (patched)** core. Like the 2600 it has
+no framebuffer and no tile/sprite-attribute tables, so its inspectors
+decode MARIA's display-list machinery rather than a tilemap.
+
+What you can read:
+
+- **`palette({source:'live'})`** — a 256-color master palette PNG, with
+  the live MARIA palette block at `$20-$3F` decoded into the 8 palettes ×
+  3 colors each, plus the backdrop. This is the Atari NTSC palette shared
+  with the 2600.
+- **`sprites({op:'inspect'})`** — there is **no OAM** on the 7800. Instead
+  this returns the MARIA control registers and the **DPP** display-list-
+  list pointer, leaving the agent to walk the DLL → DL hierarchy itself
+  (the same structure described under "MARIA: the unusual one" above).
+- **`cpu({op:'read'})`** — the 6502 ("Sally") register file (A / X / Y /
+  P / SP / PC) read from prosystem's `sally` globals.
+- **`background({view:'renderState'})`** — the MARIA CTRL bits, DPP,
+  CHARBASE, and the current `dlistPtr`.
+- **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
+  both default to the top 16 KB (`$C000-$FFFF`), where the reset vector
+  lands.
+
+Memory regions for **`memory({op:'read'})`**:
+
+| Region | Size | What it is |
+| --- | --- | --- |
+| `system_ram` | 64 KB | the *entire* 6502 address space — MARIA regs, RAM, and ROM are all visible through this one region |
+| `a78_cpu_regs` | — | the 6502 register snapshot |
+
+**No `audioDebug` inspector.** The 7800's standard audio is the same TIA
+chip carried over from the 2600 (`$15-$1A`), not a decodable PSG/FM chip,
+so there's no `audioDebug` decode. (Some carts add a POKEY, but it's
+non-standard — don't assume it's present.)

package/src/platforms/c64/MENTAL_MODEL.md

@@ -41,6 +41,12 @@ Default after boot = `$37` (all three set) — BASIC + KERNAL ROMs +
 I/O regs. Set CHAREN=0 to read the character-set bitmaps from ROM;
 set HIRAM=0 to swap KERNAL out for RAM (useful for low-memory tricks).
 
+> **cc65 zero-page starts at $02 (same cc65 trap as NES/Atari/Lynx).** cc65
+> reserves `$00-$01` (here it's also the 6510 I/O port), so your first
+> `.res 1` in `ZEROPAGE` lands at **$02**, not $00. Don't hand-write asm that
+> assumes a ZP var is at $00. Confirm with `symbols({op:'map'})` after
+> `build({output:'romWithDebug'})`.
+
 ## VIC-II — character cells, NOT tiles
 
 The C64's video chip displays 25 rows × 40 cols of 8×8 character
@@ -107,12 +113,35 @@ which is what the KERNAL's IRQ uses to update key state every
 
 ### Driving input over MCP
 
-The C64 joystick has **one** fire button. Over MCP press it with
-`input({op:'set', b: true})` or the spatial `input({op:'set', south: true})` — both clear
-`$DC00` bit 4 (verified live against vice). `input({op:'set', a: true})` is a **no-op**
-(no second button — not in `input({op:'layout'})`'s `physicalButtons`). So drive fire
-with `b`/`south`, plus the d-pad. ⚠ A cc65 `.prg` only starts after BASIC
-auto-`RUN`s it — step ~70+ frames past load before input/reads register.
+**Joystick.** One fire button. Press it with `input({op:'set', b: true})` (or
+spatial `south`) — both clear `$DC00` bit 4 (verified live). `a` is a **no-op**
+(no second button). Drive fire with `b`/`south` + the d-pad. The joystick reads
+**port 2** by default; switch with `input({op:'joyport', joyport:1})` /
+`input({op:'joyport'})` to read it.
+
+**Keyboard (the C64-specific part — many games NEED it).** Unlike consoles, most
+C64 games (and cracktros) gate gameplay behind a KEYBOARD setup screen — **F1**
+to pick 1 player, RUN/STOP, SPACE/RETURN — that the joystick can't reach. So if a
+joystick gets you to a title/intro but not into play, you almost certainly need a
+key:
+- `input({op:'pressKey', key:'f1'})` — press one C64 key (held + auto-released).
+  Keys: `f1/f3/f5/f7`, `return`, `space`, `run/stop`, `a-z`, `0-9`, `ctrl`, `cbm`,
+  `home`, `down`, `right`, `lshift`, `rshift`.
+- `input({op:'typeText', text:'LOAD"*",8,1\rRUN\r'})` — type a string (`\r` =
+  RETURN). For BASIC commands / filenames.
+- `input({op:'layout', platform:'c64'})` lists the keyboard keys + the joyport.
+
+A typical C64 RE startup: load → step to the title → `pressKey f1` (1 player) →
+`set {b:true}` (fire to start) → step → you're in gameplay → `state({op:'save'})`.
+
+**Controller-alone (playtest):** a human in `playtest` needs no keyboard — the
+pad's spare buttons map to the C64 keys (X=Space, L2=Run/Stop, R2=Return,
+right-stick=F1/F3/F5/F7, top face=F1; d-pad+Fire=joystick). The same mapping
+applies to the agent's `setInput`, so e.g. `input({op:'set', c64_f1:true})` also
+presses F1. `playtest({op:'open'})` returns `c64Controls` to relay to the user.
+
+⚠ A cc65 `.prg` only starts after BASIC auto-`RUN`s it — step ~70+ frames past
+load before input/reads register.
 
 ## SID — three voices of fame
 
@@ -131,6 +160,54 @@ the `sid_play.s` starter snippet.
 waveform, freq→note, pulse-width, ADSR — plus the filter cutoff/resonance/mode.
 Handy for verifying a `sid_play` routine is actually gating notes.
 
+## MCP debug & inspection tooling
+
+romdev runs the C64 on a patched VICE (`vice_x64`) core that exposes deep live
+state. The inspectors all read the **running** machine — use them to confirm what
+your code actually did to the hardware, not what you think it did.
+
+**Live visual / state inspectors:**
+
+- `palette({source:'live'})` — the 16-color hardware-fixed C64 palette as a PNG,
+  plus the current border / background / extra-background color indices decoded
+  straight from the VIC-II registers.
+- `sprites({op:'inspect'})` — all 8 MOBs decoded into the generic sprite shape:
+  X/Y, color, multicolor flag, expand-X / expand-Y, priority, AND the screen-RAM
+  sprite-data pointers at `$07F8` so you can locate each sprite's pixel block in
+  the VIC bank.
+- `cpu({op:'read'})` — the 6510 registers (A/X/Y/P/SP/PC) read from a live,
+  `#define`-aliased register file, plus the `$0001` I/O port decoded into its
+  LORAM / HIRAM / CHAREN bits (so you can see which ROMs are banked in).
+- `background({view:'renderState'})` — the VIC-II registers decoded into
+  mode / scroll / colors / sprites, the VIC bank resolved from CIA2 `$DD00`, and
+  the **absolute** screen-RAM + character-base addresses (no manual bank math).
+- `audioDebug({op:'inspect', chip:'sid'})` — the SID voice/filter decode covered
+  in the SID section above.
+
+**`c64_*` memory regions** (via `memory({op:'read'})`) — exact, named windows
+onto the hardware, decoded live:
+
+| region          | size  | notes                                           |
+| --------------- | ----- | ----------------------------------------------- |
+| `system_ram`    | 64 KB | full RAM                                         |
+| `c64_color_ram` | 1 KB  | the nibble color RAM                            |
+| `c64_vic_regs`  | 64 B  | VIC-II registers                                |
+| `c64_sid_regs`  | 29 B  | SID registers (read via `sid_peek`)             |
+| `c64_cia1_regs` | 16 B  | CIA1, from the `c_cia[]` array                  |
+| `c64_cia2_regs` | 16 B  | CIA2, from the `c_cia[]` array                  |
+| `c64_cpu_regs`  | 7 B   | 6510 register file                              |
+
+**Disassembly:** `disasm({target:'rom'})` and `disasm({target:'references'})`
+accept `.prg` files (they understand the 2-byte little-endian load-address
+header), and apply the C64 register-annotation table so VIC-II / SID / CIA
+register accesses come back named rather than as bare addresses.
+
+**Starter snippets** cover `vic_init` / `sprite_table` / `sid_play` /
+`read_joystick` / `basic_stub`.
+
+Disk-image loading and disk SAVE/restore tooling have their own sections below
+("Disk images" and "Disk SAVES").
+
 ## Cartridge / load file format
 
 The .prg format is dead simple:

package/src/platforms/gb/MENTAL_MODEL.md

@@ -14,6 +14,62 @@ one call fuses a framebuffer pixel scan with the live LCDC and returns
 `verified:null` = step a frame first. Zero image tokens, frame-0-guarded — use it
 as the first move when a change "did nothing."
 
+## Toolchains
+
+Default is **C** via SDCC's sm83 port (the same SDCC that powers SMS/GG/MSX/
+Coleco). For hand-tuned asm, pass `language:"asm"` to route through RGBDS. The C
+path uses `__sfr __at 0xFFNN` to bind GB I/O regs; the helper headers under
+`src/platforms/gb/lib/c/gb_hardware.h` define LCDC/STAT/SCY/SCX/LY/BGP/OBP0/OBP1/
+etc. for both DMG and CGB. ⚠ SDCC 4.4.0 codegen quirk: `for (;;) { switch + write
+to __sfr }` crashes the register allocator — use `do { ... } while (1)` and
+table-lookup writes instead. (See the GB/GBC SDCC_GOTCHAS for the full set of
+sm83 codegen footguns.)
+
+## MCP debug & inspection tooling
+
+The bundled gambatte core is patched to expose deep live state — sprites,
+palettes, tiles, background/LCDC, CPU, and raw memory regions. This applies to
+**both `gb` and `gbc`** builds (one shared gambatte core).
+
+**Live inspectors (decode hardware state, no manual byte-twiddling):**
+
+- **`sprites({op:'inspect'})`** — decodes all 40 OAM slots and renders a
+  sprite-sheet PNG with sprite-priority + horizontal/vertical flip applied.
+- **`palette({source:'live'})`** — DMG path decodes the BGP / OBP0 / OBP1 bytes
+  into 4 shades each; CGB path decodes the 64-byte BCPS/OCPS palette RAM into
+  8 palettes × 4 colors in BGR555.
+- **`tiles({op:'png'})`** — renders all 384 tiles from $8000-$97FF.
+- **`cpu({op:'read'})`** — SM83 register file: A/F/BC/DE/HL + flags + IME/halt.
+- **`audioDebug({op:'inspect', chip:'gb'})`** — DMG APU decode: 2 pulse + wave
+  + noise channels, with timer→freq→note conversion, sweep, duty, and panning,
+  read straight from the live `NR*` registers.
+- **`background({view:'renderState'})`** — LCDC bit-by-bit, scroll (SCX/SCY),
+  LY/LYC, window state, plus CGB extras: current VRAM bank, KEY1, and the
+  BCPS/OCPS palette index.
+
+**Raw memory regions** via `memory({op:'read', region:...})`:
+
+| Region | Contents |
+|---|---|
+| `gb_vram` | VRAM ($8000-$9FFF) — tile data + BG maps (CGB: the active bank) |
+| `gb_oam` | OAM ($FE00-$FE9F) — 40 sprites × 4 bytes |
+| `gb_io` | I/O register page ($FF00-$FF7F) — LCDC, BGP, JOYP, CGB regs, etc. |
+| `gb_hram` | HRAM ($FF80-$FFFE) — fast scratch |
+| `gb_bgpdata` | CGB BG palette RAM (64 bytes) |
+| `gb_objpdata` | CGB OBJ palette RAM (64 bytes) |
+| `gb_cpu_regs` | SM83 register snapshot |
+
+⚠ **Gotcha: gambatte exposes `gb_vram`, NOT the generic `video_ram` region.**
+Other platforms' cores expose video memory under `video_ram`; on GB/GBC you must
+ask for `gb_vram` (and the other `gb_*` names above). A `video_ram` read here
+returns nothing.
+
+**Disassembly:** `disasm({target:'rom'})` + `disasm({target:'references'})` +
+`disasm({target:'project'})` route through the native binutils z80 `objdump` in
+its `gbz80` machine (WASM, `-m gbz80`) — full CB-prefix coverage plus the
+SM83-specific opcodes (`ld (hl+),a`, `ldh`, `reti`, `ld hl,sp+e8`). One z80-elf
+binutils serves both plain Z80 (SMS/GG/MSX) and the GB CPU.
+
 ## Five silent-failure footguns to know before you start (R26 + R27)
 
 If your ROM compiles cleanly but doesn't render — or sprites land in
@@ -72,6 +128,21 @@ check these first. All five have shipped fixes in the bundled runtime
    If you use the bundled `gb_crt0.s` you're good; if you bring your
    own, make sure gsinit zeros `_DATA`.
 
+6. **Don't poke a hardcoded `$C0xx` WRAM pointer for game state — it
+   overlaps your statics.** SDCC links the C runtime's data + BSS (every
+   `static` global: your PRNG seed, your grids, your scores) at the BOTTOM
+   of WRAM starting `$C000`. A `volatile uint8_t *board = (uint8_t*)0xC000;`
+   then scribbles right over `static uint32_t rng = ...;` et al. Symptom
+   looks exactly like an SDCC *codegen* bug — e.g. a 32-bit xorshift PRNG
+   that "degenerates" so every roll is identical (it's not miscompiling;
+   its seed is being clobbered). **Use a `static` array and let the linker
+   place it** (`static uint8_t board[78]; board[i]=p;`), or, if you must
+   hardcode, put scratch at `$C200`+ and confirm with the linker map
+   (`build({includeSymbols:true})` → check `s__DATA`/`s__BSS`; your scratch
+   must start above the end of `_BSS`). Full write-up + the
+   "is-it-really-a-miscompile" repro in
+   `lib/c/SDCC_GOTCHAS.md` § "sm83 codegen traps in plain game logic".
+
 ## Memory map you actually care about
 
 ```
@@ -81,6 +152,9 @@ $8000-$97FF  VRAM tile data — 384 tiles × 16 bytes (CGB: dual-banked, 768 tot
 $9800-$9FFF  VRAM BG maps + CGB attribute map (in bank 1)
 $A000-$BFFF  Cart RAM (mappers only; not present in 32 KB ROM-only carts)
 $C000-$DFFF  WRAM (8 KB) — your variables, your stack
+             ⚠ statics start at $C000 (rng/grids/scores live here): NEVER
+               hardcode a $C0xx pointer for game state — use a `static`
+               array; for fixed scratch use $C200+ (see footgun #6).
 $FE00-$FE9F  OAM (40 sprites × 4 bytes) — written via DMA
 $FF00       JOYP — joypad I/O
 $FF40-$FF4B I/O registers — LCDC, BGP, OBP0, OBP1, SCY, SCX, etc.

package/src/platforms/gb/lib/c/SDCC_GOTCHAS.md

@@ -188,3 +188,94 @@ build({
   },
 })
 ```
+
+## sm83 codegen traps in plain game logic (WRAM integer/array code)
+
+Every footgun above is about VRAM / OAM-DMA / the cart header — the stuff
+that makes sprites vanish. This section is the opposite: **plain WRAM game
+logic** — PRNGs, collision grids, score math. Two such "miscompiles" were
+reported from a real GBC Columns build session and chased to ground here.
+**Verdict: neither was an sm83 codegen bug.** They are documented so you
+don't burn hours blaming the compiler for what is actually a memory-layout
+or static-init trap.
+
+### NOT a bug: 32-bit math / `uint32_t` shifts ≥ 16
+
+Reported: *"`static uint32_t rng=0x1357; rng ^= rng<<13; rng ^= rng>>17;
+rng ^= rng<<5;` degenerates — every `1+xorshift()%6` roll comes out the
+same (near-monochrome)."*
+
+**Reproduced on sm83: it does NOT degenerate.** A ROM that seeds the PRNG,
+calls `xorshift()` 20×, and writes `1 + (result % 6)` to WRAM reads back a
+fully-varied `5,5,5,1,5,5,4,1,3,2,1,...` — the exact sequence a reference
+implementation produces. Full 32-bit fidelity was confirmed byte-for-byte
+across several seeds (`0xDEADBEEF`, `0x00000001`, …). The `<<13` / `>>17` /
+`<<5` shifts (including the ≥16-bit right shift) and `% 6` are all correct.
+**Do not rewrite a working 32-bit xorshift into 16-bit to "dodge" this.**
+32-bit ops are bigger/slower than 16-bit on an 8-bit CPU, so prefer 16-bit
+PRNGs for *speed* — but not for correctness; both are correct.
+
+### The REAL trap behind "monochrome RNG": writing game state to a fixed
+`0xC0xx` WRAM address that overlaps your statics
+
+This is what actually produces the reported symptom. SDCC links the C
+runtime's `_DATA` / `_INITIALIZED` segment (every value-initialised
+`static`, e.g. `static uint32_t rng = 0x1357;`) **at the very bottom of
+WRAM, starting `$C000`**, with `_BSS` (zero-init statics like
+`static uint8_t grid[78];`) right after it. If your code also pokes a
+**hardcoded** `$C000`-area pointer for game state —
+
+```c
+volatile uint8_t *board = (volatile uint8_t *)0xC000;   /* DON'T */
+board[i] = piece;                 /* clobbers `rng` and friends! */
+```
+
+— you are scribbling directly over your own statics. Then `xorshift()`
+reads a trashed `rng`, the PRNG collapses, and every roll looks the same.
+It presents *exactly* like a compiler bug; it is not.
+
+**Fixes (any one):**
+- **Best — let the linker place it.** Use a `static` array and take its
+  address; never hardcode a WRAM pointer:
+  `static uint8_t board[6*13]; ... board[i] = piece;`
+- If you *must* use a fixed address, put it well clear of the runtime data:
+  `$C200`+ is safe for small projects (statics here end far below `$C100`;
+  `shadow_oam` is pinned at `$C100`). Confirm with the linker map — build
+  with `includeSymbols:true` and look at `s__DATA` / `s__BSS` (e.g.
+  `s__DATA = $C000`, `s__BSS = $C006`): your scratch RAM must start ABOVE
+  the end of `_BSS`.
+- **Diagnose it in seconds:** read `system_ram` offset 0 right after boot
+  and compare against your initialised statics' expected bytes. If a
+  `static uint32_t x = 0x1357;` doesn't read back `57 13 00 00` at its map
+  address, something is overwriting it.
+
+### NOT a bug: short `for` loop with an indexed `static` array read
+
+Reported: *"`for(i=0;i<3;i++){ if(grid[r*6+col]) return 1; }` reads the
+wrong cells (pieces lock mid-air / floating gaps); unrolling the 3
+iterations fixed it."*
+
+**Reproduced on sm83: the looped form reads the CORRECT cells.** A ROM that
+seeds `grid[]` with a sparse occupied/empty pattern and runs `collides()`
+both looped and hand-unrolled, for 8 straddling `(col,topy)` inputs, gets
+**identical, correct** results from both forms (`1,0,1,0,1,1,1,1`). The
+`grid[r*6+col]` index math and the 3-iteration loop are fine. If your real
+collision check "floats," look first at the WRAM-collision trap above (a
+clobbered `grid[]`), at off-by-one row/col limits, or at signed/unsigned
+mix-ups — not at loop codegen. **Don't pre-emptively unroll loops as a
+compiler workaround; with the stack-overflow fix in place, sm83 loops with
+indexed array reads are reliable.**
+
+### z80 (SMS/GG) ONLY — fixed: value-initialised statics booted as 0
+
+Investigating the above on the **z80** port (SMS/GG share the SDCC family)
+surfaced a real bug — but a **crt0** bug, not codegen. The bundled
+`sms_crt0.s` / `gg_crt0.s` placed `_INITIALIZER` (the ROM image of
+value-initialised statics) *after* the `_DATA` RAM block in the area list,
+so sdld put it in RAM; the gsinit `ldir` then copied uninitialised RAM onto
+itself and **every `static uint8_t x = 5;` booted as 0** (and BSS wasn't
+zeroed either). On z80 *this* is what made the xorshift PRNG monochrome
+(seed `rng` booted 0 → stayed 0). Fixed 2026-06-08 by ROM-placing
+`_INITIALIZER` + adding a `_DATA` zero loop, mirroring this sm83 crt0 (which
+was already correct — hence sm83 was never affected). If you bring your own
+z80 crt0, model gsinit on `gb_crt0.s`.

package/src/platforms/gba/MENTAL_MODEL.md

@@ -125,9 +125,9 @@ maxmod (separate library, not bundled here).
 
 **Debugging sound:** `audioDebug({op:'inspect', chip:"gba"})` decodes the live APU —
 per-channel freq→note/duty/volume for the 4 tone channels plus the 2 Direct
-Sound FIFO states. Pair with `sprites({op:'inspect'})`/`palette({source:'live'})`/
-`background({view:'renderState'})`/`cpu({op:'read'})` (ARM7) and `breakpoint({on:'write'})` for the rest of the
-live-debug loop.
+Sound FIFO states. See "MCP debug & inspection tooling" below for the rest of
+the live-debug loop (sprites / palette / background / cpu / breakpoint + the
+memory regions and disasm pipeline).
 
 **For scaffold-level sfx**, the libtonc runtime ships a minimal
 `gba_sfx.h` / `gba_sfx.c` pair (3 functions: `sfx_init`, `sfx_tone`,
@@ -136,6 +136,60 @@ as the NES/GB scaffold sound API, so cross-platform game ports feel
 the same. All 5 GBA genre scaffolds (shmup/platformer/puzzle/sports/
 racing) use it.
 
+## MCP debug & inspection tooling
+
+GBA runs on mGBA (patched). These inspectors read the *live* core state —
+reach for them when a sprite, palette, or BG renders wrong and the source
+alone doesn't explain it. (The audio inspector is also summarized under
+"Sound" above.)
+
+- **`sprites({op:'inspect'})`** — decodes all **128 OAM sprites** into a
+  generic shape: attr0/1/2 unpacked to shape + size, **9-bit signed X**,
+  the affine and hidden flags, and tile / palette / priority.
+- **`palette({source:'live'})`** — reads the palette as **15-bit BGR555**:
+  256 BG entries + 256 OBJ entries. Pass `area:'bg'` or `area:'sprite'` to
+  pick the half.
+- **`cpu({op:'read'})`** — ARM7TDMI dump: the 16 general regs **r0-r15**,
+  `cpsr` + `spsr`, the processor mode, the ARM/THUMB state bit, and an
+  **`execPc`** field that is r15 adjusted back for the pipeline prefetch
+  (r15 reads ahead of the executing instruction, so raw r15 is misleading —
+  use `execPc` for "where am I really").
+- **`audioDebug({op:'inspect', chip:'gba'})`** — the 4 DMG-compatible PSG
+  channels (per-channel freq→note / duty / volume) plus the **2 Direct Sound
+  DMA FIFO** states, and master / bias. See "Sound" above.
+- **`background({view:'renderState'})`** — decodes DISPCNT: the BG mode, and
+  per-BG enable / priority / char-base / map-base / color-mode, the
+  forced-blank bit, and OBJ enable. Use it to confirm REG_DISPCNT and the
+  REG_BGxCNT bases match where you uploaded tiles + maps.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Address / size                     | Contents                                  |
+|-----------------|------------------------------------|-------------------------------------------|
+| `gba_cpu_regs`  | —                                  | ARM7TDMI register snapshot                 |
+| `gba_io_regs`   | $04000000-$040003FE (1 KB)         | the I/O page — **video AND audio** MMIO    |
+| `gba_palette`   | $05000000-$050003FF (1 KB)         | 256 BG + 256 OBJ BGR555 entries            |
+| `gba_oam`       | $07000000-$070003FF (1 KB)         | 128 sprite attribute entries (8 B each)    |
+| `system_ram`    | $02000000 EWRAM / $03000000 IWRAM  | main + on-chip work RAM                    |
+| `video_ram`     | $06000000-$06017FFF (96 KB)        | BG + sprite tile data + framebuffer        |
+| `save_ram`      | $0E000000-$0E00FFFF (64 KB)        | battery-backed SRAM                        |
+
+Pair `sprites` / `palette` / `background` / `cpu` with
+`breakpoint({on:'write'})` for the full live-debug loop.
+
+### Disassembly (`disasm({target:…})`)
+
+`disasm({target:'rom'})`, `disasm({target:'references'})`, and
+`disasm({target:'project'})` run the native binutils
+**`arm-none-eabi-objdump`** (WASM) — **ARM mode by default**, pass
+`thumb:true` for Thumb code. The byte-exact project reassembles through
+`arm-none-eabi-as` / `ld` / `objcopy`.
+
+**Gotcha (until ARM/Thumb mode-tracking lands):** GBA C compiles mostly to
+**Thumb** reached via an **ARM crt0 stub**, so an ARM-mode disasm of a full
+ROM decodes the Thumb spans as `.byte` — still byte-exact, just less readable.
+Disasm the Thumb spans with `thumb:true` to get real mnemonics.
+
 ## Frame heartbeat
 
 ```c