romdevtools 0.30.0 → 0.40.0

package/src/http/routes.js

@@ -189,7 +189,7 @@ export function buildOpenApi(registry, version) {
         parameters: [{
           name: SESSION_HEADER, in: "header", required: true,
           schema: { type: "string" },
-          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.",
+          description: "REQUIRED. Per-agent session id — pick one stable, UNIQUE, task-DESCRIPTIVE string (e.g. 'nes-platformer-build', 'rpg-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.",
         }],
       },
     };

package/src/http/skill-doc.js

@@ -39,7 +39,7 @@ export const skillPreamble = [
   "  • GET  /openapi.json — the full machine-readable API; GET /documentation — a browsable console.",
   "",
   "## 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.",
+  "**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`, `rpg-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",

package/src/mcp/tools/cart-parts.js

@@ -407,10 +407,12 @@ export async function extractCartCore({ path: romPath, platform, outputDir, inli
  *   mirror   — "horizontal" | "vertical" | "four-screen" (default horizontal)
  *   prgBanks — count of 16KB banks (default infer from prgPath size)
  *   chrBanks — count of 8KB banks (default infer; 0 for CHR-RAM)
+ *   hasBattery — battery-backed SRAM (iNES flags6 bit 1); preserved on round-trip
  */
-function wrapNes({ prgPath, chrPath, mapper, mirror, prgBanks, chrBanks }) {
+function wrapNes({ prgPath, chrPath, mapper, mirror, prgBanks, chrBanks, hasBattery }) {
   const m = mapper ?? 0;
   const mirrorFlag = mirror === "vertical" ? 1 : mirror === "four-screen" ? 8 : 0;
+  const batteryFlag = hasBattery ? 0x02 : 0;
   const prg = prgPath;
   const chr = chrPath ?? null;
 
@@ -445,7 +447,7 @@ function wrapNes({ prgPath, chrPath, mapper, mirror, prgBanks, chrBanks }) {
   .byte $4E, $45, $53, $1A     ; "NES\\x1a"
   .byte $${banks.toString(16).toUpperCase().padStart(2, "0")}    ; PRG-ROM banks (16KB each)
   .byte $${chrBanksNum.toString(16).toUpperCase().padStart(2, "0")}    ; CHR-ROM banks (8KB each; 0 = CHR-RAM)
-  .byte ${hex2((m << 4 | mirrorFlag) & 0xFF)}    ; mapper-lo + mirroring
+  .byte ${hex2((m << 4 | mirrorFlag | batteryFlag) & 0xFF)}    ; mapper-lo + mirroring + battery
   .byte ${hex2(m & 0xF0)}    ; mapper-hi + NES 2.0 flags
   .byte $00, $00, $00, $00, $00, $00, $00, $00
 
@@ -682,6 +684,7 @@ export function registerCartPartsTools(server, z) {
       mirror: z.enum(["horizontal", "vertical", "four-screen"]).optional().describe("op=wrap NES: nametable mirroring."),
       prgBanks: z.number().int().min(1).max(255).optional().describe("op=wrap NES: PRG bank count (16KB each); only 1 (NROM-128) or 2 (NROM-256) supported, default 1."),
       chrBanks: z.number().int().min(0).max(255).optional().describe("op=wrap NES: CHR bank count (8KB each); 0 = CHR-RAM."),
+      hasBattery: z.boolean().optional().describe("op=wrap NES: set the iNES battery-backed-SRAM flag (flags6 bit 1). Pass the value from extractCart's manifest.hasBattery for a byte-exact round-trip."),
       // wrap — SNES
       romPath: z.string().optional().describe("op=wrap SNES/SMS/GG/Atari 2600/Atari 7800/C64: whole-ROM body for a one-shot incbin (skips the per-part paths)."),
       copierHeaderPath: z.string().optional().describe("op=wrap SNES: path to a 512B copier header to prepend."),

package/src/mcp/tools/disasm.js

@@ -6,6 +6,13 @@ import { jsonContent, safeTool, writeOutput } from "../util.js";
 import { parseSymbols, buildSymbolMap } from "../../toolchains/common/symbols.js";
 import { registersForPlatform } from "../../platforms/common/registers.js";
 import { findReferencesCore } from "./find-references.js";
+import { analyzeCfg, analyzeXrefs, analyzeFunctions, analyzeDecompile } from "../../analysis/analyze.js";
+
+/** cfg/xrefs/functions all operate on a ROM file. Reuse the `path` arg. */
+function requireRomPath(args) {
+  if (!args.path) throw new Error(`disasm target='${args.target}' requires \`path\` (the ROM file).`);
+  return args.path;
+}
 
 // ── Per-platform CPU-address → file-offset mappers ────────────────
 // Each returns { bytes, fileOffset, cpu, notes } given the full ROM
@@ -839,7 +846,7 @@ async function disassembleRomCore(args) {
         }
       }
       // Dedup vector labels by ADDRESS. Two interrupt vectors legitimately
-      // sharing one target is valid 6502 (Rygar points NMI and IRQ both at
+      // sharing one target is valid 6502 (e.g. one NES cart points NMI and IRQ both at
       // $C0F6) — but da65's LABELDEF and every dasm injector reject two labels
       // at the same address ("Label for address $XXXX already defined"). Keep
       // the first name (vector iteration order is reset/nmi/irq) and record the
@@ -1158,9 +1165,25 @@ export function registerDisasmTools(server, z) {
     "'references' = scan a ROM's code for operands matching a CPU `address` and classify each (call/jump/branch/" +
     "read/write); also walks the vector table. Banked carts are scanned PER BANK (all of the formats above) — " +
     "refs carry `prgBank` (NES) / `romBank` (everything else). LIMITATION: direct addressing only " +
-    "(indirect/computed jumps are missed).",
+    "(indirect/computed jumps are missed).\n" +
+    "── RE ENGINE (Rizin + Ghidra, all 14 platforms) ──\n" +
+    "'functions' = Rizin auto-detected function list {address,size,nbbs,cc,callers,callees}; the structural map of " +
+    "an unknown ROM. 'cfg' = basic-block control-flow graph of the function at `address` (nodes + typed edges: " +
+    "jump/branch_true/branch_false). 'xrefs' = every cross-reference TO `address`, following Rizin's analysis graph " +
+    "(DEEPER than 'references', which is a flat da65 operand scan — prefer 'xrefs' once you've run a function pass, " +
+    "'references' for a quick header-less operand sweep). Typical RE loop: 'functions' to carve → 'cfg'/'xrefs' to " +
+    "trace → then the live tools (memory search, write-breakpoints, watch copy) to LABEL what you carved.\n" +
+    "'decompile' = Ghidra C-like PSEUDOCODE for the function at `address`, with the decompiler's own WARNINGs and a " +
+    "`qualityNote`. ALTITUDE RULE: decompile is for UNDERSTANDING (and as a port spec when retargeting to a bigger " +
+    "machine) — it is NOT the same-platform edit path. To CHANGE a ROM and rebuild it, use target:'project' " +
+    "(byte-exact rebuildable asm); read the pseudocode as documentation alongside it. Per-CPU quality (calibrate, " +
+    "don't treat low quality as a bug): ARM/GBA + M68K/Genesis = excellent (mostly-C games, real stack frames); " +
+    "SM83/GB + Z80/SMS/GG/MSX = good; 65816/SNES + HuC6280/PCE = medium; 6502 family (NES/2600/7800/C64/Lynx) = " +
+    "rough — carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an " +
+    "LLM folds it. `address` for all four comes from target:'functions' (a CPU/virtual address; the file-offset " +
+    "mapping is handled for you).",
     {
-      target: z.enum(["bytes", "rom", "project", "references"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = find refs to an address."),
+      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode. See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
       // shared
       path: z.string().optional().describe("target=bytes: raw binary path. target=rom/project/references: ROM file path."),
       base64: z.string().optional().describe("target=bytes: base64 of the bytes (OR `path`)."),
@@ -1190,8 +1213,8 @@ export function registerDisasmTools(server, z) {
       annotateFileOffsets: z.boolean().default(true).describe("target=rom: append `; @0xNNNN` file offset to every line (for romPatch)."),
       // project
       outputDir: z.string().optional().describe("target=project: directory to write the project into (one .asm per region)."),
-      // references
-      address: z.number().int().min(0).max(0xFFFFFF).optional().describe("target=references: CPU address to find references TO."),
+      // references / cfg / xrefs
+      address: z.number().int().min(0).max(0xFFFFFFFF).optional().describe("target=references: CPU address to find references TO. target=cfg: address inside the function to graph. target=xrefs: address to find cross-references TO. target=decompile: address of the function to decompile (use an address from target='functions')."),
       maxRefsReturned: z.number().int().min(1).max(2048).default(256).describe("target=references: cap the references returned."),
     },
     safeTool(async (args) => {
@@ -1200,6 +1223,10 @@ export function registerDisasmTools(server, z) {
         case "rom":        return await disassembleRomCore(args);
         case "project":    return await disassembleProjectCore(args);
         case "references": return jsonContent(await findReferencesCore(args));
+        case "cfg":        return jsonContent(await analyzeCfg(requireRomPath(args), args.address, args.platform));
+        case "xrefs":      return jsonContent(await analyzeXrefs(requireRomPath(args), args.address, args.platform));
+        case "functions":  return jsonContent(await analyzeFunctions(requireRomPath(args), args.platform));
+        case "decompile":  return jsonContent(await analyzeDecompile(requireRomPath(args), args.address, args.platform));
         default: throw new Error(`disasm: unknown target '${args.target}'`);
       }
     }),

package/src/mcp/tools/font-map.js

@@ -1,7 +1,7 @@
 // learnFontMap / encodeTextForRom / findEncodedText — text-hack workflow.
 //
-// Every retro game maps characters to tile-IDs differently (Excitebike:
-// A=$0A, B=$0B, ..., Z=$23; Mario: ASCII offset; FF: sparse table). The
+// Every retro game maps characters to tile-IDs differently (one NES racer:
+// A=$0A, B=$0B, ..., Z=$23; another game: ASCII offset; a third: sparse table). The
 // agent currently reverse-engineers this by hand each session. These
 // three tools automate it:
 //
@@ -186,7 +186,7 @@ async function makeTilemapReader(host, platform, which) {
  * Decide whether a run of (char, tileId) reads from a live tilemap is FONT TEXT
  * (a reusable character→tile map) or a PRE-RENDERED GRAPHIC (a name/logo drawn as
  * a bitmap, where each cell is a unique tile). The trap a long RE session hit:
- * NBA Jam's player names are bitmaps, so patching the ASCII string did nothing.
+ * Some games' player names are bitmaps, so patching the ASCII string does nothing.
  * Signals a graphic when: (1) a repeated character used a DIFFERENT tile each
  * time (a real font reuses one tile per letter) — the direct proof; OR (2) every
  * tile is unique AND the ids form a near-contiguous run (tiles X,X+1,X+2,… = one

package/src/mcp/tools/index.js

@@ -116,8 +116,8 @@ const CATEGORIES = [
   },
   {
     name: "debug",
-    description: "Cross-platform debugging primitives: inspectSprites, inspectPalette, getCPUState (main/spc700/z80), getAudioState (dsp/psg/ym2612), disassemble, symbol lookup.",
-    useWhen: ["sprites rendering wrong", "audio silent or distorted", "CPU stuck in unknown state", "need to read what existing ROM bytes do"],
+    description: "Cross-platform debugging + reverse-engineering: inspectSprites, inspectPalette, getCPUState (main/spc700/z80), getAudioState (dsp/psg/ym2612), and the disasm/RE engine — disassemble (raw/ROM/rebuildable-project), plus the Rizin/Ghidra ops disasm({target:'cfg'|'xrefs'|'functions'|'decompile'}) (control-flow graphs, deep xrefs, auto-detected functions, and C pseudocode — all 14 platforms) and symbols({op:'analyze'}) (one-shot structural map).",
+    useWhen: ["sprites rendering wrong", "audio silent or distorted", "CPU stuck in unknown state", "need to read what existing ROM bytes do", "reverse-engineering an unknown ROM — carve its functions/structure before labeling them live", "want C-like pseudocode to understand a routine"],
     register: (s, z, k) => {
       registerPlatformSpecificTools(s, z, k); // inspectSprites/Palette, getCPUState, getDspState, ...
       registerSymbolTools(s, z, k);            // buildSourceWithDebug, resolveSymbol, lookupAddress, ...

package/src/mcp/tools/project.js

@@ -1464,7 +1464,7 @@ TEMPLATES.genesis = {
     runtimeDirs: SGDK_RUNTIME_DIRS,
     lang: SGDK_LANG,
     ext: ".bin",
-    describe: "Two-plane parallax SCROLLING scaffold — the smooth-feel starting point for a Uridium/Sonic-style side-scroller. Plane A = a painted foreground world (ground + platform blocks), Plane B = a repeated starfield, one player sprite. The frame loop does HARDWARE SCROLL ONLY (two VDP_setHorizontalScroll writes + one VDP_updateSprites) — ZERO tilemap writes per frame, which is what keeps movement smooth (rewriting a plane each frame is the #1 'choppy horizontal movement' bug). Plane B scrolls at 1/4 speed for depth. Exposes volatile g_player_x / g_cam_x so you can motion-trace it headlessly (symbols->memory->recordSession). Extend by streaming one offscreen column per 8-px camera step for worlds wider than 512 px — see Genesis MENTAL_MODEL.md 'Scrolling, parallax & the feel trap'.",
+    describe: "Two-plane parallax SCROLLING scaffold — the smooth-feel starting point for a parallax side-scroller. Plane A = a painted foreground world (ground + platform blocks), Plane B = a repeated starfield, one player sprite. The frame loop does HARDWARE SCROLL ONLY (two VDP_setHorizontalScroll writes + one VDP_updateSprites) — ZERO tilemap writes per frame, which is what keeps movement smooth (rewriting a plane each frame is the #1 'choppy horizontal movement' bug). Plane B scrolls at 1/4 speed for depth. Exposes volatile g_player_x / g_cam_x so you can motion-trace it headlessly (symbols->memory->recordSession). Extend by streaming one offscreen column per 8-px camera step for worlds wider than 512 px — see Genesis MENTAL_MODEL.md 'Scrolling, parallax & the feel trap'.",
   },
   puzzle: {
     main: "templates/puzzle.c",

package/src/mcp/tools/reinject.js

@@ -390,7 +390,7 @@ const PLATFORM_REGISTRY = {
   msx:       { forms: msxPointerForms,       verdict: "literal-escape", formats: ["raw", "konami-rle"],
                note: "RAW when uncompressed; Konami/other RLE has a literal-run token, so a literal-escape stored block is producible." },
   genesis:   { forms: genesisPointerForms, verdict: "literal-escape", formats: ["raw", "kosinski-literal"],
-               note: "Pointers are 32-bit BE = ROM offset (1:1 at $000000). Kosinski has an all-literal path (experimental terminator — self-verify). Nemesis is Huffman — NO stored escape; custom LZ (e.g. NBA Jam) — confirm the literal-run shape per game." },
+               note: "Pointers are 32-bit BE = ROM offset (1:1 at $000000). Kosinski has an all-literal path (experimental terminator — self-verify). Nemesis is Huffman — NO stored escape; custom LZ (e.g. some Genesis sports titles) — confirm the literal-run shape per game." },
   snes:      { forms: snesPointerForms, verdict: "literal-escape", formats: ["raw", "lz2-direct"],
                note: "Pointers 16-bit (bank-implied) or 24-bit long LE; needs LoROM/HiROM (auto-detected). LC_LZ2 has a clean direct-copy (000) literal command + 0xFF end — common but per-game; confirm the codec." },
   gba:       { forms: gbaPointerForms, verdict: "literal-escape", formats: ["raw", "lz77-literal"],

package/src/mcp/tools/symbols.js

@@ -10,6 +10,7 @@
 import { writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { jsonContent, safeTool, writeOutput } from "../util.js";
+import { analyzeStructure } from "../../analysis/analyze.js";
 import { addressToSymbolCore } from "./address-to-symbol.js";
 
 // Tail length kept inline when a big log is written to a sibling file.
@@ -459,7 +460,7 @@ function registerSymbolsTool(server, z) {
     "Auto-detects GNU ld (Genesis/m68k + GBA/ARM), sdld (`XXXX  _name`, GB/GBC/SMS/GG/MSX), and ld65 VICE " +
     "(`al XXXX .name`, cc65/dasm).",
     {
-      op: z.enum(["resolve", "lookup", "map", "list", "addr"]).describe("resolve name→addr; lookup addr→sym; map = layout by region; list all; addr = PC→nearest symbol."),
+      op: z.enum(["resolve", "lookup", "map", "list", "addr", "analyze"]).describe("resolve name→addr; lookup addr→sym; map = layout by region; list all; addr = PC→nearest symbol; analyze = Rizin structural map of a ROM (no .dbg/.map needed — auto-detected functions + strings + entrypoints)."),
       dbg: z.string().optional().describe("op=resolve/lookup/list/map: cc65 .dbg text from build({output:'romWithDebug'}) (NES/C64/Atari7800/Lynx/PCE). Pass this OR `map`/`dbgPath`/`mapPath`."),
       map: z.string().optional().describe("op=resolve/lookup/list/map: .map text (build's `mapText`/`symbols`) — auto-detects sdld (GB/GBC/SMS/GG/MSX) vs GNU ld (Genesis/m68k). Pass this OR `dbg`/`dbgPath`/`mapPath`."),
       dbgPath: z.string().optional().describe("op=resolve/lookup/list/map: ABSOLUTE path to a cc65 .dbg on disk (the `dbgPath` build({output:'romWithDebug'}) returned). Server reads it — the map never enters your context. Inline `dbg` wins if both passed."),
@@ -472,11 +473,16 @@ function registerSymbolsTool(server, z) {
       pc: z.number().int().min(0).max(0xFFFFFF).optional().describe("op=addr: CPU address to look up (e.g. 0x01A7)."),
       symbolsText: z.string().optional().describe("op=addr: inline .map/.sym text (build's `symbols`). Takes precedence over symbolsPath."),
       symbolsPath: z.string().optional().describe("op=addr: path to a .map/.sym file (used only if symbolsText absent)."),
+      // analyze
+      romPath: z.string().optional().describe("op=analyze: ABSOLUTE path to the ROM file to structurally map via Rizin."),
     },
     safeTool(async (args) => {
-      // dbgPath/mapPath → read the .dbg/.map TEXT off disk so resolve/lookup/map/
-      // list work without the agent ever loading the map into context. (addr has
-      // its own symbolsPath handling.)
+      // op=analyze and op=addr don't take a .dbg/.map source. Everything else
+      // resolves dbgPath/mapPath → text off disk so the map never enters context.
+      if (args.op === "analyze") {
+        if (!args.romPath) throw new Error("symbols op='analyze' requires `romPath` (the ROM file).");
+        return jsonContent(await analyzeStructure(args.romPath, args.platform));
+      }
       const a = args.op === "addr" ? args : { ...args, ...(await loadDebugSource(args)) };
       switch (a.op) {
         case "resolve": return jsonContent(await resolveSymbolCore(a));

package/src/mcp/tools/trace-vram-source.js

@@ -1,6 +1,6 @@
 // traceVramSource (Genesis) — "which ROM offset did this VRAM graphic come from?"
 //
-// The trap it kills: NBA Jam-style player names are pre-rendered tile bitmaps
+// The trap it kills: some sports games' player names are pre-rendered tile bitmaps
 // DMA'd into VRAM from ROM, not font-rendered from a string. You can SEE the
 // name but patching the ASCII string does nothing — the source is the bitmap in
 // ROM. Genesis makes this traceable: a memory→VRAM DMA leaves its SOURCE address

package/src/mcp/tools/watch-memory.js

@@ -1027,7 +1027,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "hours diffing a CORRECT codec against that poisoned output. Prefer pure for every decompressor/codec call.\n" +
     "• op:'decompress' — convenience wrapper over op:'call' for the common decompressor shape: call `entryPC` with " +
     "A0=`sourceAddress` (and optionally A1=`destAddress`), run until it returns, then read `destAddress`. For the " +
-    "NBA-Jam-style 'name + portrait are LZ-compressed' wall: point it at the game's own decompressor.",
+    "the 'pre-rendered name + portrait are LZ-compressed' wall: point it at the game's own decompressor.",
     {
       op: z.enum(["read", "setReg", "call", "decompress"])
         .describe("read=CPU registers/flags; setReg=write one register; call=drive a subroutine until it returns; decompress=call shortcut (A0=source, A1=dest)."),

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -18,6 +18,10 @@ read that platform's `platform({op:'doc', platform, name:'mental_model'})`.
    loose name (fuzzy) before assuming it's absent. Cheats are a STARTING point,
    not the whole job — combine with disassembly below.
 3. `symbols({op:'map', platform})` / the platform MENTAL_MODEL for the layout.
+4. `symbols({op:'analyze', romPath})` — for an unknown ROM with no cheats and no
+   debug file, this carves the structure (functions + strings + entrypoints) in
+   one call. The static map you hang everything else onto (see §5f for the full
+   Rizin/Ghidra analysis loop — cfg, xrefs, decompile).
 
 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.
@@ -110,7 +114,7 @@ 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 — it infers the game's char→tile-ID map
-   (games use their own encoding: Excitebike A=$0A, Mario ASCII-offset, FF sparse). Two
+   (games use their own encoding: e.g. one NES racer maps A=$0A, another uses an ASCII offset, a third a sparse table). 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
@@ -310,6 +314,40 @@ Breakpoints are great once you KNOW the address. To FIND it:
 
 ---
 
+## 5f. Carve the program STRUCTURE before you label it — the RE engine (all 14)
+
+The watch/breakpoint tools above find routines *dynamically* (run the game, see
+what touches an address). The **Rizin/Ghidra analysis engine** carves the program
+*statically* — the map you label the dynamic findings onto. All 14 platforms.
+
+- **`symbols({op:'analyze', romPath})`** — one call, the whole shape: auto-detected
+  functions + strings + entrypoints. Start here on an unknown ROM.
+- **`disasm({target:'functions', path})`** — the function list with sizes,
+  basic-block counts, and caller/callee counts. The most-called functions are
+  usually the engine primitives (read-joypad, draw-tile, RNG).
+- **`disasm({target:'cfg', path, address})`** — the basic-block control-flow graph
+  of one function (nodes + typed branch edges). "Is this a loop? where does it
+  bail?" without reading the whole disassembly.
+- **`disasm({target:'xrefs', path, address})`** — every cross-reference TO an
+  address, following the analysis graph. DEEPER than `target:'references'` (a flat
+  operand scan): once a function pass has run, `xrefs` resolves calls the flat
+  scan misses. Use it to answer "what calls this routine / reads this table?"
+- **`disasm({target:'decompile', path, address})`** — Ghidra **C-like pseudocode**
+  for a function. Read it to UNDERSTAND a routine fast; it is NOT the edit path
+  (use `target:'project'`, §7b, to change and rebuild). Quality tracks the CPU —
+  see the `qualityNote` it returns: excellent on ARM (GBA) / 68000 (Genesis),
+  good on SM83 (GB) / Z80 (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE),
+  rough on the 6502 family (carry-flag idioms and 16-bit-math-on-8-bit decompile
+  to noise — read the disassembly there, or let an LLM fold the pseudocode).
+
+**The loop:** `symbols({op:'analyze'})` or `disasm({target:'functions'})` to carve →
+`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate → then the
+dynamic tools (memory search, `breakpoint({on:'write'})`, `watch`) to CONFIRM and
+label which carved function owns the value you care about. Static narrows the
+search space; dynamic proves it.
+
+---
+
 ## 6. Driving menus (the real wall-clock sink)
 
 Use `input({op:'navigate', steps:[{button, maxWaitFrames}]})` — it advances on **screen
@@ -397,7 +435,11 @@ 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
+re-buildable project in one call: `disasm({target:'project', path, outputDir})`.
+(To UNDERSTAND a routine before you edit it, read its `disasm({target:'decompile'})`
+pseudocode or `disasm({target:'cfg'})` graph first — §5f. `project` is the *edit*
+path; decompile is the *understanding* path. They pair: read the C, edit the asm.)
+It splits
 the ROM into regions (per-bank on EVERY banked format: 16KB banks for NES/GB/SMS-GG/MSX/
 7800-SuperGame, 32KB for SNES LoROM, 4KB for banked 2600, 8KB pages for >32KB HuCards;
 one flat region for Genesis/C64/Lynx/GBA and small carts), disassembles each through the CPU's
@@ -496,7 +538,10 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 | 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) |
+| Who references this address (static) | `disasm({target:'references'})` (flat scan) / `disasm({target:'xrefs'})` (deeper, graph-following) |
+| Map an unknown ROM's structure | `symbols({op:'analyze'})` / `disasm({target:'functions'})` (functions + strings + entrypoints) |
+| Graph one function's control flow | `disasm({target:'cfg', address})` (basic blocks + branch edges) |
+| Read a routine as C pseudocode | `disasm({target:'decompile', address})` (Ghidra; all 14, quality per CPU) |
 | 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'})` |

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -233,3 +233,9 @@ Memory regions for **`memory({op:'read'})`**:
 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.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -379,3 +379,9 @@ Memory regions for **`memory({op:'read'})`**:
 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.)
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/c64/MENTAL_MODEL.md

@@ -334,3 +334,9 @@ moving further is a software char-cell shift.
 
 Track `camX` in pixels: `fine = camX & 7` → `$D016`; `coarseCol = camX >> 3`
 indexes your world map for which columns are on screen.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/gb/MENTAL_MODEL.md

@@ -359,3 +359,9 @@ The `platformer` example is single-screen. To make it a side-scroller:
 Pattern: keep a `world_map[col][row]` array, a `camX` in pixels, convert
 actor world-X → screen-X as `worldX - camX`, and only ever touch the one
 column entering the screen per 8-px step.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on SM83: GOOD.** A dedicated SLEIGH plugin gives clean block-level pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

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

@@ -65,7 +65,7 @@ Templates ship in `examples/{gb,gbc}/templates/`:
 |---|---|
 | `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
 | `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
-| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the top-down dungeon-crawler / room-puzzle shape. |
 
 ## SDCC 4.4.0 quirks
 

package/src/platforms/gba/MENTAL_MODEL.md

@@ -55,7 +55,7 @@ mixing ARM + Thumb in the same binary. libgba is built Thumb-interwork.
 ```
 240×160 pixels visible, 6 BG modes (0-5)
 
-Mode 0: 4 tile BGs, scrolling. The classic 2D Mario-style mode.
+Mode 0: 4 tile BGs, scrolling. The classic 2D platformer mode.
 Mode 1: 2 tile BGs + 1 affine BG (rotation/scale).
 Mode 2: 2 affine BGs only. Mode 7-style perspective.
 Mode 3: 240×160 BGR555 framebuffer at $06000000. 16-bit per pixel.
@@ -268,3 +268,9 @@ entering view into the map's screen-blocks as the camera advances. A fixed HUD
 goes on its own BG layer left unscrolled (or via an HBlank IRQ that resets the
 offset for the HUD scanlines). Track camX in pixels; actor screen-X = worldX -
 camX.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on ARM7TDMI: EXCELLENT.** Most GBA code was compiled C, so the decompiler often recovers something close to the original source — lean on it. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -222,3 +222,9 @@ on CGB, its BG attribute byte in VRAM bank 1) each time the camera crosses an
 8-px boundary. Use the Window (LCDC bit 5) for a fixed HUD. CGB adds nothing
 that changes the scroll mechanism — just remember the per-tile attribute in
 bank 1 when you stream columns. See the GB MENTAL_MODEL for the full pattern.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on SM83: GOOD.** A dedicated SLEIGH plugin gives clean block-level pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/gbc/lib/c/README.md

@@ -65,7 +65,7 @@ Templates ship in `examples/{gb,gbc}/templates/`:
 |---|---|
 | `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
 | `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
-| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the top-down dungeon-crawler / room-puzzle shape. |
 
 ## SDCC 4.4.0 quirks
 

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -219,7 +219,7 @@ size and treat your logical world coords separately.
 | 32×64              | 256×512  | vertical scroller                    |
 | 64×64              | 512×512  | uses the most VRAM for name tables   |
 
-### How Sonic-style large maps REALLY work (wider than one plane)
+### How large scrolling maps REALLY work (wider than one plane)
 
 You do NOT make the plane "as wide as the level," and you do NOT redraw
 the plane. The 64-cell hardware plane is a **circular buffer**: as the
@@ -242,7 +242,7 @@ if (newTileCol != lastTileCol) {
 
 That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
 The `platformer` example scrolls within one plane (no
-streaming); add the column-stream above to go wider. (Real Sonic also
+streaming); add the column-stream above to go wider. (Real large-scroller engines also
 splits the screen with H-blank raster effects for independent strips —
 that's an IRQ/raster topic, see the `asm` template.)
 
@@ -518,3 +518,9 @@ When you call `build({output:'rom'})`:
    image from the ELF → `.bin` Genesis ROM.
 
 Loadable via genesis_plus_gx (`loadMedia`).
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 68000: EXCELLENT.** An orthogonal ISA with real stack frames decompiles close to readable C — lean on it. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -260,5 +260,5 @@ Diagnose it without guessing (no core rebuild):
 
 For a world WIDER than one 512-px plane, don't make the plane bigger and
 don't redraw it — stream ONE offscreen column per 8-px camera step
-(circular-buffer the 64-cell plane). See MENTAL_MODEL.md "How Sonic-style
-large maps REALLY work".
+(circular-buffer the 64-cell plane). See MENTAL_MODEL.md "How large scrolling
+maps REALLY work".

package/src/platforms/genesis/lib/wram.s

@@ -35,7 +35,7 @@ pad1_released     equ WRAM_BASE + $0006   ; 2 bytes
 game_state        equ WRAM_BASE + $0010   ; 1 byte: 0=title, 1=play, 2=gameover
 state_timer       equ WRAM_BASE + $0012   ; 2 bytes: frames in current state
 
-; Player / score (Tetris-shaped example).
+; Player / score (falling-block puzzle example).
 score             equ WRAM_BASE + $0020   ; 4 bytes (BCD or binary)
 lines_cleared     equ WRAM_BASE + $0024   ; 2 bytes
 level             equ WRAM_BASE + $0026   ; 1 byte

package/src/platforms/gg/MENTAL_MODEL.md

@@ -197,3 +197,9 @@ Everything else (Z80, VDP control protocol, tile format, sprite SAT
 layout, joypad polling, BG name table at $3800) is identical to SMS.
 You can use sms_hw.h notes + helpers as a reference; the GG runtime
 files in lib/c/ are direct ports.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -272,3 +272,9 @@ into `.lnx`. handy accepts both.
 - One controller (handheld) — no port 2 fallback patterns.
 - 64 KB total RAM, mapped ROM. C64 has 64 KB RAM but most is shadowed
   by ROM by default.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 65C02: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/msx/MENTAL_MODEL.md

@@ -150,3 +150,9 @@ 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/`**.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/nes/MENTAL_MODEL.md

@@ -415,6 +415,12 @@ multi-bank `.cfg` referenced via `linkerConfigPath`. Either way: feed
 is the RE workhorse loop: `disasm({target:'project'})` → edit the `.asm` →
 rebuild → `diffRoms` to confirm your patch landed.
 
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.
+
 ## When to drop to asm
 
 Game-loop in C is fine for ~80% of homebrew. Drop to asm when:

package/src/platforms/pce/MENTAL_MODEL.md

@@ -110,3 +110,9 @@ screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
   PCE asm toolchain IS cc65/ca65 — a **one-call byte-identical `build()`
   rebuild** via `rebuild.json` (flat and banked; a 512-byte copier header is
   split out and re-emitted as a HEADER segment).
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on HuC6280: MEDIUM.** The Ghidra HuC6280 SLEIGH covers all custom opcodes + MPR banking; pseudocode is usable. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/sms/MENTAL_MODEL.md

@@ -340,3 +340,9 @@ The `platformer` example is single-screen. To make it a side-scroller:
 
 Track `camX` in pixels; actor screen-X = `worldX - camX`. (Game Gear is the
 same VDP — only the visible window differs.)
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/snes/MENTAL_MODEL.md

@@ -47,13 +47,13 @@ The SNES has 8 BG modes selected via PPU register $2105 (BGMODE):
 
 ```
 0  4 BGs × 4 colors      — text-mode look
-1  3 BGs (16+16+4 col)   — default for most games (Super Mario World)
-2  2 BGs × 16 col + tilemap offset-per-tile (Yoshi's Island)
-3  1 BG × 256 col + 1 BG × 16 col (Donkey Kong Country)
+1  3 BGs (16+16+4 col)   — default for most games (typical 2D platformer)
+2  2 BGs × 16 col + tilemap offset-per-tile (a pre-rendered-sprite platformer)
+3  1 BG × 256 col + 1 BG × 16 col (pre-rendered-sprite platformer)
 4  1 BG × 256 col + 1 BG × 4 col with offset-per-tile
 5  2 BGs hi-res (512 px wide, half-height)
 6  hi-res mosaic
-7  1 BG with affine transform (Mario Kart, F-Zero)
+7  1 BG with affine transform (mode-7 racers)
 ```
 
 PVSnesLib's default is `BG_MODE1` (`setMode(BG_MODE1, 0)`) — three
@@ -313,3 +313,9 @@ and parallax is nearly free.
   scanlines.
 
 Track `camX` in pixels; actor screen-X = `worldX - camX`.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 65816: MEDIUM.** The M/X register-width flags make instruction meaning context-dependent, but the Ghidra 65816 SLEIGH tracks them, so pseudocode is usable. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/toolchains/_worker/wasm-worker.js

@@ -109,6 +109,11 @@ async function runJob(job) {
       return buf[idx++];
     };
   }
+  // Optional environment variables for the WASM (e.g. SLEIGHHOME for the Ghidra
+  // decompiler). Seed Module.ENV in preRun, before libc reads getenv().
+  if (job.env && typeof job.env === "object") {
+    moduleArgs.preRun = [(m) => { Object.assign((m.ENV || (m.ENV = {})), job.env); }];
+  }
 
   const mod = await factory(moduleArgs);