romdevtools 0.23.0 → 0.24.0

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

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

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -74,6 +74,27 @@ the same wall.
 - **HDMA** ($FF51-$FF55) for fast block transfers during HBlank —
   used for live tile streaming.
 
+## MCP debug & inspection tooling
+
+GBC shares the patched gambatte core with DMG, so **all the live inspectors
+and `gb_*` memory regions documented in the GB MENTAL_MODEL apply unchanged
+here** — `sprites({op:'inspect'})`, `tiles({op:'png'})`, `cpu({op:'read'})`,
+`audioDebug({op:'inspect', chip:'gb'})`, and the `gb_vram` / `gb_oam` / `gb_io`
+/ `gb_hram` / `gb_cpu_regs` regions (same gotcha: it's `gb_vram`, NOT the
+generic `video_ram`). Disassembly routes through the same `-m gbz80` objdump.
+See the GB MENTAL_MODEL for the shared gambatte debug tooling.
+
+CGB-only deltas on top of that shared set:
+
+- **`palette({source:'live'})`** on a CGB ROM decodes the **64-byte BCPS/OCPS
+  palette RAM** into **8 palettes × 4 colors in BGR555** (the DMG path that
+  decodes BGP/OBP0/OBP1 bytes is what runs on a `gb` build instead). The raw
+  CGB palette RAM is also readable directly via the **`gb_bgpdata`** (BG, 64
+  bytes) and **`gb_objpdata`** (OBJ, 64 bytes) memory regions.
+- **`background({view:'renderState'})`** reports the CGB extras the DMG path
+  doesn't have: the current **VRAM bank** (VBK), **KEY1** (double-speed state),
+  and the live **BCPS/OCPS palette index**.
+
 ## CGB vs DMG mode
 
 The CGB boot ROM checks header byte **`$0143`**:

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -413,6 +413,25 @@ headless per-PCM-channel "is it playing" readout for Genesis yet (it would need
 core patch to expose the XGM2 Z80 driver state), so audio verification here is
 record-and-listen, not assert.
 
+## MCP debug & inspection tooling
+
+The shipped genesis_plus_gx (gpgx) core is patched for live introspection.
+Video is deeply readable; the FM audio chip is only partially exposed:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes the live SAT.
+- **Palette:** `palette({source:'live'})` reads live CRAM.
+- **CPU:** `cpu({op:'read', cpu:'main'})` reads the 68000.
+- **Audio (limited):** `getYm2612State` returns the YM2612's internal
+  struct as a raw blob — gpgx doesn't expose it in a safely per-channel
+  decodable form (good for frame-to-frame diffing, see "Debugging sound").
+  `getPsgState` decodes the SN76489 (3 tone + 1 noise channels).
+- **Memory regions:** `memory({op:'read'})` exposes CRAM, VSRAM, VDP_REGS,
+  Z80_RAM (the sound CPU's RAM), M68K work RAM, YM2612, PSG, and VRAM.
+  Remember the gpgx byte-swap quirk: VRAM and WRAM read host-LE
+  word-byte-swapped (a 16-bit value's two bytes are swapped at the offset)
+  — account for it or read single bytes (see "Reading your C globals
+  headlessly").
+
 ## ROM layout
 
 ```

package/src/platforms/gg/MENTAL_MODEL.md

@@ -160,6 +160,30 @@ void main(void) {
 }
 ```
 
+## MCP debug & inspection tooling
+
+Game Gear runs on the same genesis_plus_gx (gpgx, patched) core as SMS, so the
+inspectors are identical. **The canonical reference lives in the SMS
+MENTAL_MODEL** (`src/platforms/sms/MENTAL_MODEL.md`, "MCP debug & inspection
+tooling" section): `sprites({op:'inspect'})`, `tiles({op:'png'})`,
+`cpu({op:'read'})` (Z80), `background({view:'renderState'})`,
+`audioDebug({op:'inspect', chip:'psg'})` (SN76489, the shared
+SMS/GG/Genesis region), and the z80 `objdump` disasm pipeline all apply
+unchanged.
+
+Game-Gear-only deltas:
+
+- **`palette({source:'live'})`** decodes **12-bit BGR (4-4-4)**, twice the
+  depth of SMS's 6-bit. CRAM is **64 bytes** (2 little-endian bytes per
+  entry) instead of 32.
+- The Game-Gear memory regions are **`gg_vram`** and **`gg_cram`** (the
+  64-byte palette); use these instead of `sms_vram` / `sms_cram`. The
+  `sms_vdp_regs` / `sms_z80_regs` register regions are shared (same VDP and
+  Z80).
+- `sprites({op:'inspect'})` X/Y fields are reported in **256×192 hardware
+  coordinates**, not the 160×144 visible window — match them with
+  hardware-coord arithmetic (see "Sprite coords are hardware-space" above).
+
 ## Differences from SMS — quick reference
 
 - Visible 160×144 vs 256×192 — center content

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -35,13 +35,39 @@ Mikey handles:
 - **Joystick** — read via SWITCHES register at `$FCB0`. cc65 provides
   `joy_read(JOY_1)` + `JOY_LEFT/RIGHT/UP/DOWN/BTN_1/BTN_2` macros.
 
-**Live debug:** `audioDebug({op:'inspect', chip:"mikey"})` decodes the 4 audio voices
-(volume, period→freq→note, LFSR state); `palette({source:'live'})` reads the 16-entry
-palette; `background({view:'renderState'})` shows DISPCTL + the display base address;
-`cpu({op:'read'})` reads the 65C02; `breakpoint({on:'write'})` is the write watchpoint. **Sprites
-are the exception** — the Lynx has no fixed OAM (sprites are SCB linked lists
-walked by Suzy), so `sprites({op:'inspect'})` returns the SCB list head ($FC10/$FC11) and
-you walk the chain over `system_ram`, rather than reading a sprite table.
+**Live debug:** the MCP inspectors (`palette` / `cpu` / `audioDebug` /
+`background` / `breakpoint`, and the SCB-list-head `sprites` special case) are
+documented in "MCP debug & inspection tooling" below.
+
+## MCP debug & inspection tooling
+
+The Lynx runs on handy (patched). The inspectors read the *live* core state —
+reach for them when a sprite or palette renders wrong and the source alone
+doesn't explain it. Details and the per-tool facts:
+
+- **`palette({source:'live'})`** — the **16-entry, 12-bit RGB** Mikey palette
+  (`$FDA0-$FDBF`) converted to RGB.
+- **`cpu({op:'read'})`** — 65C02 dump: A / X / Y / P / SP / PC plus the
+  decoded flag bits.
+- **`audioDebug({op:'inspect', chip:'mikey'})`** — the 4 Mikey voices: volume,
+  the timer→period→frequency→note chain, and the **12-bit LFSR** state.
+- **`background({view:'renderState'})`** — decodes DISPCTL: the DMA-enable,
+  flip, and color-mode bits plus the display base address.
+- **`sprites({op:'inspect'})` is the special case.** The Lynx has **no fixed
+  OAM** — sprites are **SCB (Sprite Control Block) linked lists in RAM** that
+  Suzy walks at blit time. So this tool can't return a sprite table; instead
+  it returns the **SCB list head (SCBNEXT, `$FC10`/`$FC11`)** plus
+  instructions to walk the chain yourself over `system_ram`.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Address / size        | Contents                                              |
+|-----------------|-----------------------|-------------------------------------------------------|
+| `lynx_cpu_regs` | —                     | 65C02 register snapshot                               |
+| `lynx_hw_regs`  | $FC00-$FDFF window     | the **Suzy + Mikey** register window — sprite-engine regs, LCD control, audio, palette |
+| `system_ram`    | 64 KB                 | full address space (also where the SCB chain lives)   |
+
+Pair these with `breakpoint({on:'write'})` for the full live-debug loop.
 
 ## Frame heartbeat (cc65 + tgi)
 

package/src/platforms/msx/MENTAL_MODEL.md

@@ -117,3 +117,30 @@ exactly this.
   generator + the envelope (period + shape bits).
 - `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
   `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).
+
+## MCP debug & inspection tooling
+
+MSX is a **Tier-1** platform with deep introspection — the full set of
+inspectors and memory regions is listed under **"Debugging tools"** above
+(`cpu` / `background` / `palette` / `sprites` / `symbols` / `audioDebug` for
+the AY-3-8910 PSG, and the `msx_vram` / `msx_vdp_regs` / `msx_vdp_status` /
+`msx_palette` / `msx_cpu_regs` / `msx_psg_regs` / `system_ram` regions). The
+PSG-channel decode means `audioDebug({op:'inspect', chip:'ay8910'})` gives
+you the 3 square-wave channels plus the shared noise generator and envelope
+without poking at `msx_psg_regs` by hand.
+
+### ColecoVision shares this core family — but is bring-up only
+
+ColecoVision runs the same toolchain family and exposes only the **standard**
+introspection: `system_ram` + `save_ram` + `video_ram`. It has **no deep
+inspectors** (no `palette` / `sprites` / `background` / `audioDebug` decode)
+and **no MENTAL_MODEL of its own** — treat it as a bring-up target, not a
+finished Tier-1 platform.
+
+### Extending introspection (for whoever adds a platform)
+
+Deeper, decoded inspectors are not free — each is implemented by **patching
+the emulator core** to expose the extra register/VRAM regions, then wiring a
+decoder. To add deep introspection to ColecoVision (or any thin platform),
+follow the existing core-patch pattern used for snes9x / gpgx / fceumm / vice
+under **`scripts/patches/`**.

package/src/platforms/nes/MENTAL_MODEL.md

@@ -25,6 +25,13 @@ The cc65 runtime claims:
 - ZP $1C+ available to your game (with our chr-ram crt0)
 - `$0500-$07FF` (3 pages): cc65 C parameter stack
 
+> **cc65 zero-page starts at $02, not $00 (applies to every cc65 platform —
+> NES, C64, Atari, Lynx, …).** cc65 reserves `$00-$01` for its runtime, so your
+> first `.res 1` in the `ZEROPAGE` segment lands at **$02**, not $00. If you
+> hand-write asm that assumes a zero-page var is at $00 you'll clobber the
+> runtime. Confirm actual addresses with `symbols({op:'map'})` after
+> `build({output:'romWithDebug'})`.
+
 ## PPU memory map (separate from CPU bus!)
 
 ```
@@ -94,6 +101,15 @@ The `nes_runtime` helper `tile_set_palette(nt, x, y, palette)` does
 the read-modify-write dance and the bit-twiddling — use it instead
 of writing attributes by hand.
 
+> **256-tile cap per pattern table (the busy-image trap).** The nametable's
+> tile index is 8-bit, so a single pattern table holds at most **256 unique
+> tiles** — and a per-frame BG can therefore use at most 256 distinct tiles.
+> Auto-converting a busy full-screen illustration almost always needs more than
+> 256 unique 8×8 tiles and **overflows**; `encodeArt({stage:'tilemap'})` warns
+> when it does. The only real workaround is mid-frame CHR bank switching
+> (an MMC3-class mapper) — the bundled NROM presets can't do it, so design BG
+> art to reuse tiles (≤256 unique per table).
+
 ## Palettes
 
 32 bytes at $3F00-$3F1F:
@@ -329,6 +345,25 @@ incorrectly aligned."
   scrolling worlds you need to manage the nametable buffer + bank
   switching yourself.
 
+## MCP debug & inspection tooling
+
+The shipped fceumm core is patched for live introspection — read state
+instead of guessing:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes live OAM.
+- **Palette:** `palette({source:'live'})` reads the live 32-byte palette RAM.
+- **CPU:** `cpu({op:'read'})` reads the 6502.
+- **Background render state:** `background({view:'renderState'})` decodes
+  PPUCTRL/PPUMASK and resolves the active CHR bank (plus its file offset) —
+  this is what tells you which pattern table BG vs sprites are fetching from
+  (the bit-4 footgun above).
+- **Memory regions:** `memory({op:'read'})` exposes OAM, Palette,
+  Nametables (CIRAM — including the 2-bit-per-16x16 attribute data that
+  selects each tile group's sub-palette, decoded by `inspectBackgroundMap`),
+  CHR (live MMC1-banked CHR — don't parse the iNES file), CPU_REGS,
+  PPU_REGS, and APU_REGS (the synthesized $4000-$4017 snapshot consumed by
+  `audioDebug`).
+
 ## Rebuilding a CHR-ROM NROM image (reverse-engineering)
 
 The homebrew presets above are CHR-**RAM** (the CPU uploads tiles at runtime).

package/src/platforms/sms/MENTAL_MODEL.md

@@ -267,6 +267,57 @@ Loadable via genesis_plus_gx (`loadMedia`).
 - Game Gear-specific buttons add port $00 read (Start) and stereo
   PSG control on port $06.
 
+## MCP debug & inspection tooling
+
+SMS and Game Gear share the genesis_plus_gx (gpgx, patched) core, so the
+inspectors below behave identically on both. This section is the **canonical
+shared reference**; the Game Gear MENTAL_MODEL points back here and only lists
+its own deltas (12-bit CRAM, etc.). Reach for these when something renders
+wrong and you can't see why from the source alone — they read the *live* core
+state, which beats trusting comments.
+
+- **`sprites({op:'inspect'})`** — decodes the live SAT (sprite attribute
+  table) and renders a sprite-sheet PNG. Reports each slot's X/Y/tile plus
+  `spriteTileDataBase` (the VRAM address the VDP is actually fetching sprite
+  tiles from). This is the tool that catches the $D0-terminator and the
+  R6/$2000-vs-$0000 sprite-bank footguns described above — trust its bytes
+  over any comment.
+- **`palette({source:'live'})`** — reads CRAM and converts to RGB. On SMS
+  that's **6-bit BGR** (2-2-2, 32 bytes). On Game Gear it's **12-bit BGR**
+  (4-4-4, 64 bytes) — see the GG MENTAL_MODEL for that delta.
+- **`tiles({op:'png'})`** — dumps VRAM tile patterns as a sheet. The format
+  is 4bpp bitplane-interleaved (32 bytes/tile); the 16 KB VRAM renders as a
+  512-tile sheet.
+- **`cpu({op:'read'})`** — Z80 register dump: A/F, BC/DE/HL, IX/IY, the
+  shadow register set, the flag bits, and interrupt state (IM mode / IFF).
+- **`audioDebug({op:'inspect', chip:'psg'})`** — decodes the live SN76489:
+  3 tone channels + 1 noise channel. The PSG region is shared by SMS, GG, and
+  Genesis (same gpgx region).
+- **`background({view:'renderState'})`** — reads the VDP registers and reports
+  the derived addresses (name table, BG-tile base, sprite-tile base, SAT base),
+  the scroll registers, and the display-enable / mode state. Use this to
+  confirm the R2/R4/R5/R6 baseline matches where you actually uploaded data.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Contents                                             |
+|-----------------|------------------------------------------------------|
+| `sms_vram`      | 16 KB VRAM — tiles + name table + SAT + sprite tiles |
+| `sms_cram`      | 32-byte palette (2-2-2 BGR)                          |
+| `sms_vdp_regs`  | the 11 VDP control registers ($00-$0A)              |
+| `sms_z80_regs`  | Z80 register snapshot                                |
+| `gg_vram`       | Game Gear VRAM                                        |
+| `gg_cram`       | Game Gear 64-byte palette (4-4-4 BGR)                |
+
+### Disassembly (`disasm({target:…})`)
+
+`disasm({target:'rom'})`, `disasm({target:'references'})`, and
+`disasm({target:'project'})` all run the live ROM through the native binutils
+**z80 `objdump`** (WASM, `-m z80`). It has full prefix coverage —
+CB/ED/DD/FD/DDCB/FDCB — and feeds the same auto-label, register-annotation,
+file-offset, and `untilReturn` pipeline used by the NES and SNES
+disassemblers.
+
 ## Horizontal scrolling (for side-scrollers)
 
 The `platformer` scaffold is single-screen. To make it a side-scroller:

package/src/platforms/snes/MENTAL_MODEL.md

@@ -208,6 +208,27 @@ per-voice vol/pitch/ADSR + `env` (0 = silent regardless of vol) + `bufLastSample
 produced output" from "muted by mixer." GOTCHA: S-DSP FLG is $6C, KOFF is $5C
 (many refs swap them); power-on FLG=$E0 means your driver MUST clear bit 6.
 
+## MCP debug & inspection tooling
+
+The shipped snes9x core is patched for deep introspection — both audio and
+video are fully readable, so you assert live state instead of guessing:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes live OAM (per-sprite
+  renderable/hidden, resolved tile VRAM addr, CGRAM palette range, and the
+  uninitialized-OBJ-palette warning described under "The OBJ stable-path
+  recipe").
+- **Palette:** `palette({source:'live'})` reads live CGRAM.
+- **CPUs:** `cpu({op:'read', cpu:'main'})` for the 65816, `cpu({op:'read',
+  cpu:'spc700'})` for the sound CPU.
+- **Audio:** the S-DSP is fully decodable — full per-voice state plus the
+  master mixer (see "Debugging sound" above for `audioDebug`).
+- **Memory regions:** `memory({op:'read'})` exposes OAM, CGRAM, ARAM (SPC700
+  audio RAM), and **FillRAM**. Note the FillRAM quirk: snes9x mirrors the
+  PPU registers $2100-$213F (OBSEL/BGMODE/TM/TS/color-math, etc.) into
+  FillRAM indexed by the FULL address (e.g. `FillRAM[0x2101]` = OBSEL), so
+  the PPU register state is readable through the `snes_fillram` region — no
+  core patch needed.
+
 ## ROM layout (LoROM)
 
 ```

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -193,6 +193,49 @@ Expected. tcc-65816.wasm + wla-65816.wasm cold-load + compile takes
 1-2s. Subsequent builds reuse the warm worker pool (R12 crash
 isolation infrastructure). Steady-state builds are sub-second.
 
+## "asm build fails with `ok:false` and an empty/cryptic `issues[]`" (asar idioms)
+
+The `language:"asm"` SNES path runs through **asar**, which **silently crashes**
+(a heap-pointer Emscripten exit code, no diagnostic) on a handful of source
+idioms. romdev's asar wrapper has a preflight that catches the common cases and,
+when asar dies with `ok:false` and no parsed errors, retries with `--verbose` and
+synthesizes a fallback `issues[]` entry with a hint. The idioms to avoid:
+
+- **`$ - label` size expressions** (current-PC minus a label) crash asar. Use an
+  explicit `end_label - start_label` difference instead:
+  ```asm
+  ; WRONG — crashes asar silently
+  my_size = $ - my_data
+  ; RIGHT
+  my_data_end:
+  my_size = my_data_end - my_data
+  ```
+- **Opcode + operand arithmetic on an `=`-defined symbol**, e.g.
+  `STA SYMBOL + N` where `SYMBOL` is a `=` constant (not a label), can also crash
+  silently. The preflight flags the label-arithmetic-across-bank case
+  (`label-arithmetic constant`); for the rest, if you see `ok:false` with no real
+  error, suspect a `SYMBOL + N` and rewrite to a plain label or pre-compute the
+  address.
+- **Bank-border crossed.** If your `org` + `dw`/data runs past `$00FFFF` you've
+  crossed a bank boundary and the layout is wrong. Native interrupt vectors live
+  at `$FFE4-$FFEE`, emulation vectors at `$FFF4-$FFFF` — keep your header/vector
+  block where the layout expects it. Use
+  `scaffold({op:'snippets', platform:"snes", mode:"get", name:"lorom_header.asm"})`
+  for the canonical layout (and `lorom_multibank.asm` for multi-bank).
+
+(This is the asar/asm path. The default PVSnesLib **C** path goes through
+tcc-65816 + wla-65816 and has its own C89 trap, above.)
+
+## "CHR and tilemap overlap in VRAM / background renders as garbage tiles"
+
+SNES CHR (tile patterns) and the BG tilemap share the 64 KB VRAM, addressed in
+**words**. CHR starts at word `$0000`; if your CHR is 16 KB it occupies words
+`$0000-$1FFF`, so a tilemap placed at word `$2000` collides with the tail of CHR
+and you get garbage. **Put the tilemap at word `$4000` or later when your CHR is
+big.** Verify the bases with `background({view:'renderState', platform:'snes'})`
+(it decodes the BG char/map base) and cross-check the tile region with
+`tiles({op:'png'})` at the CHR base.
+
 ## "I want to use real graphics from a PNG"
 
 `gfx4snes` (the PVSnesLib companion tool) converts PNG → .pic + .pal.