@henols/c64-re-tools 0.1.4

package/skills/acme-build/scripts/acme.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// ACME -> C64 assembler driver.  Target is fixed: C64, 6510 CPU, cbm output.
+// Scope is assembling only: source in, .prg + symbol files out.  Running the
+// result on a C64 belongs to the emulator skill.
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join, basename, relative, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SELF = fileURLToPath(import.meta.url);
+const HERE = dirname(SELF);
+
+// The ACME library (<cbm/c64/vic.a> and friends) lives wherever the package put
+// it.  Probe instead of assuming; validated by a file we actually include.
+const LIB_MARKER = join("cbm", "c64", "vic.a");
+function findAcmeLib() {
+  const tried = [];
+  for (const c of [
+    process.env.ACME,
+    "/usr/local/share/acme", "/usr/share/acme", "/usr/lib/acme",
+    process.env.HOME && join(process.env.HOME, ".acme"),
+  ].filter(Boolean)) {
+    tried.push(c);
+    if (existsSync(join(c, LIB_MARKER))) return { path: c, tried };
+  }
+  return { path: null, tried };
+}
+const ACME_LIB = findAcmeLib();
+
+// How to refer to this script in hints, from wherever we were run.
+function selfPath() {
+  const r = relative(process.cwd(), SELF);
+  return !r || r.startsWith("..") || isAbsolute(r) ? SELF : r;
+}
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
+// ------------------------------------------------------------------- build
+
+// ACME's --msvc format:  file(line) : Error (Zone <z>): message.
+const MSVC = /^(.*?)\((\d+)\)\s*:\s*(Error|Warning|Serious error)\s*(?:\(([^)]*)\))?\s*:\s*(.*)$/;
+
+function parseDiagnostics(text) {
+  const out = [];
+  for (const line of text.split("\n")) {
+    const m = line.match(MSVC);
+    if (m) {
+      out.push({
+        file: m[1], line: Number(m[2]),
+        severity: m[3].toLowerCase().replace(" ", "_"),
+        zone: m[4] || null, message: m[5].trim(),
+      });
+    } else if (line.trim()) {
+      out.push({ file: null, line: null, severity: "note", zone: null, message: line.trim() });
+    }
+  }
+  return out;
+}
+
+// The symbol list marks address-typed symbols with a leading "!addr" and
+// never-referenced ones with a trailing "; unused".  Both matter downstream.
+function parseSymbols(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n").flatMap((raw) => {
+    const m = raw.match(/^(!addr\s+)?(\S+)\s*=\s*(\S+?)\s*(?:;\s*(.*))?$/);
+    if (!m) return [];
+    return [{
+      name: m[2], value: m[3],
+      isAddress: Boolean(m[1]),
+      used: !/^unused/.test(m[4] || ""),
+    }];
+  });
+}
+
+// ACME's label file lists every global symbol, constants included, in address
+// form.  A debugger reads `viccolor_WHITE = $1` as a name for address $0001 and
+// relabels the 6510 processor port with it.  Keep referenced addresses only, so
+// the emitted file is safe to load anywhere.
+function curateLabels(vsPath, symbols) {
+  if (!existsSync(vsPath)) return { kept: 0, dropped: 0 };
+  const addr = new Set(symbols.filter((s) => s.isAddress && s.used).map((s) => s.name));
+  const kept = [];
+  let dropped = 0;
+  for (const l of readFileSync(vsPath, "utf8").split("\n")) {
+    const m = l.match(/^al\s+C:[0-9a-f]+\s+\.(\S+)/i);
+    if (!m) continue;
+    if (addr.has(m[1])) kept.push(l); else dropped++;
+  }
+  writeFileSync(vsPath, kept.join("\n") + (kept.length ? "\n" : ""));
+  return { kept: kept.length, dropped };
+}
+
+function build(src, opts) {
+  if (!existsSync(src)) die(`no such source file: ${src}`);
+  // Side files follow the .prg, not the source: two -DVARIANT builds of one
+  // source must not overwrite each other's symbol tables.
+  const prg = opts.out || join(opts.outDir || dirname(src),
+    basename(src).replace(/\.(a|asm|s)$/i, "") + ".prg");
+  const outDir = dirname(prg);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  const stem = prg.replace(/\.prg$/i, "");
+
+  const args = [
+    "--cpu", "6510",              // C64: enables the 6510 illegal opcodes
+    "-f", opts.format || "cbm",   // cbm = 2-byte load address, what LOAD wants
+    "-Wtype-mismatch",            // catches a missing '#' on an immediate
+    "--strict-segments",          // overlapping segments are reported as errors
+    "--msvc",                     // machine-parseable diagnostics
+    "-v1",                        // report the address range actually emitted
+    "-o", prg,
+    "-l", `${stem}.sym`,
+    "--vicelabels", `${stem}.vs`,
+  ];
+  if (!opts.noReport) args.push("-r", `${stem}.rep`);
+  for (const d of opts.defines) args.push(`-D${d}`);
+  for (const i of opts.includes) args.push("-I", i);
+  if (opts.setpc) args.push("--setpc", opts.setpc);
+  args.push(src);
+
+  // `<cbm/c64/vic.a>` style includes resolve through the ACME env var, so set
+  // it here rather than depending on the shell environment carrying it.
+  const env = { ...process.env };
+  if (ACME_LIB.path) env.ACME = ACME_LIB.path;
+  const r = spawnSync("acme", args, { encoding: "utf8", env });
+  if (r.error) {
+    die(r.error.code === "ENOENT"
+      ? "install the ACME cross assembler and put `acme` on PATH"
+      : String(r.error));
+  }
+
+  const diags = parseDiagnostics(((r.stderr || "") + (r.stdout || "")).trim());
+  if (diags.some((d) => /ACME.*environment variable/i.test(d.message))) {
+    diags.push({
+      file: null, line: null, severity: "note", zone: null,
+      message: `for <...> includes, set $ACME to the directory holding ${LIB_MARKER} ` +
+               `(looked in: ${ACME_LIB.tried.join(", ")})`,
+    });
+  }
+  const errors = diags.filter((d) => d.severity.endsWith("error"));
+  const ok = r.status === 0 && existsSync(prg);
+
+  let range = null, size = null, symbols = [], labels = null;
+  if (ok) {
+    symbols = parseSymbols(`${stem}.sym`);
+    labels = curateLabels(`${stem}.vs`, symbols);
+    const buf = readFileSync(prg);
+    size = buf.length;
+    if ((opts.format || "cbm") === "cbm" && buf.length >= 2) {
+      const load = buf[0] | (buf[1] << 8);
+      range = { load, end: load + buf.length - 2, bytes: buf.length - 2 };
+    }
+  }
+  return { ok, prg, stem, diags, errors, symbols, labels, range, size };
+}
+
+const hex = (n, w = 4) => n.toString(16).padStart(w, "0");
+
+function reportBuild(res, { json }) {
+  if (json) { console.log(JSON.stringify(res, null, 2)); return; }
+  for (const d of res.diags) {
+    if (d.file) console.log(`${d.file}:${d.line}: ${d.severity}: ${d.message}`);
+    else console.log(`  ${d.message}`);
+  }
+  if (!res.ok) { console.error(`build FAILED (${res.errors.length} error(s))`); return; }
+  const r = res.range;
+  console.log(
+    `built ${res.prg} (${res.size} bytes)` +
+    (r ? `  load $${hex(r.load)}-$${hex(r.end)}  ${r.bytes} bytes of code` : "")
+  );
+  const used = res.symbols.filter((s) => s.used).length;
+  console.log(`symbols: ${res.stem}.sym (${used} used / ${res.symbols.length} total)`);
+  if (res.labels) {
+    console.log(`debug labels: ${res.stem}.vs (${res.labels.kept} addresses)`);
+  }
+}
+
+// -------------------------------------------------------------------- verbs
+
+function cmdBuild(argv) {
+  const o = parseOpts(argv);
+  const res = build(o.src, o);
+  reportBuild(res, o);
+  process.exit(res.ok ? 0 : 1);
+}
+
+function cmdSym(argv) {
+  const o = parseOpts(argv);
+  const res = build(o.src, { ...o, noReport: true });
+  if (!res.ok) { reportBuild(res, o); process.exit(1); }
+  const used = res.symbols.filter((s) => s.used).sort((a, b) => a.name.localeCompare(b.name));
+  if (o.json) { console.log(JSON.stringify(used, null, 2)); return; }
+  for (const s of used) console.log(`${s.isAddress ? "addr " : "const"} ${s.value.padStart(6)}  ${s.name}`);
+}
+
+// A skeleton that is correct on the first try: BASIC stub with a computed SYS
+// target, the C64 symbol libraries, and no !to (the CLI supplies -o).
+function cmdNew(argv) {
+  const path = argv[0];
+  if (!path) die("usage: new <file.a>");
+  if (existsSync(path)) die(`${path} already exists`);
+  // template.a lives at the skill root, one level up from scripts/, by
+  // decision (D-03): only .mjs modules move into scripts/.
+  writeFileSync(path, readFileSync(join(HERE, "..", "template.a"), "utf8"));
+  console.log(`wrote ${path}`);
+  console.log(`next: node ${selfPath()} build ${path}`);
+}
+
+// `toacme` ships with ACME and turns object code back into ACME source.
+function cmdDisasm(argv) {
+  const src = argv[0];
+  if (!src) die("usage: disasm <file.prg> [out.a]");
+  const out = argv[1] || src.replace(/\.prg$/i, "") + ".dis.a";
+  const r = spawnSync("toacme", ["object", src, out], { encoding: "utf8" });
+  if (r.error) die("install the ACME cross assembler and put `toacme` on PATH");
+  if (r.status !== 0) die(`toacme: ${(r.stderr || r.stdout).trim()}`);
+  const n = readFileSync(out, "utf8").split("\n").filter((l) => /^L[0-9a-f]{4}/.test(l)).length;
+  console.log(`${out}: ${n} lines`);
+  console.log("Read it as a linear decode: trust the instruction stream, and");
+  console.log("treat strings, tables and the BASIC stub as data. To reassemble,");
+  console.log("define the out-of-range labels it emits (Ld020, Lffd2, ...) and");
+  console.log("indent its illegal-opcode lines to the operand column.");
+}
+
+// ------------------------------------------------------------------ options
+
+function parseOpts(argv) {
+  const o = { defines: [], includes: [], json: false };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") o.json = true;
+    else if (a === "--no-report") o.noReport = true;
+    else if (a === "-o" || a === "--out") o.out = argv[++i];
+    else if (a === "--out-dir") o.outDir = argv[++i];
+    else if (a === "-f" || a === "--format") o.format = argv[++i];
+    else if (a === "--setpc") o.setpc = argv[++i];
+    else if (a === "-D") o.defines.push(argv[++i]);
+    else if (a.startsWith("-D")) o.defines.push(a.slice(2));
+    else if (a === "-I") o.includes.push(argv[++i]);
+    else rest.push(a);
+  }
+  o.src = rest[0];
+  if (!o.src) die("no source file given");
+  return o;
+}
+
+// --------------------------------------------------------------------- main
+
+const [cmd, ...rest] = process.argv.slice(2);
+const VERBS = { new: cmdNew, build: cmdBuild, sym: cmdSym, disasm: cmdDisasm };
+if (!cmd || !VERBS[cmd]) {
+  console.log(`usage: node ${selfPath()} <command> [options]
+
+  new <file.a>              scaffold a C64 program (BASIC stub + libs)
+  build <file.a>            assemble -> .prg .sym .vs .rep
+  sym <file.a>              list the symbols the program uses
+  disasm <file.prg> [out.a] turn object code back into ACME source
+
+options: -o FILE  --out-dir DIR  -f FORMAT  --setpc ADDR  -DSYM=VAL  -I DIR
+         --no-report  --json`);
+  process.exit(cmd ? 1 : 0);
+}
+VERBS[cmd](rest);

package/skills/acme-build/template.a

@@ -0,0 +1,39 @@
+; C64 / 6510 program skeleton.
+; Build:  node .claude/skills/acme-build/scripts/acme.mjs build THIS.a
+; No !to here on purpose - the driver passes -o, and having both makes ACME
+; warn "Output file already chosen" and silently ignore the !to.
+
+!cpu 6510                       ; C64's CPU: legal 6502 + the illegal opcodes
+!source <cbm/c64/vic.a>         ; vic_*  registers, viccolor_* constants
+!source <cbm/c64/kernal.a>      ; k_*    KERNAL entry points ($ff81-$fff5)
+!source <cbm/c64/cia1.a>        ; cia1_* keyboard / joystick 2
+
+* = $0801                       ; start of BASIC RAM
+
+; --- BASIC stub: "10 SYS <entry>", so LOAD"...",8,1 + RUN reaches the code.
+; The SYS digits are computed from `entry`, so inserting code above never
+; breaks the stub - which is the classic way to lose an afternoon.
+        !word .eol, 10          ; link to next line, line number
+        !byte $9e               ; SYS token
+        !byte '0' + entry % 10000 / 1000
+        !byte '0' + entry %  1000 /  100
+        !byte '0' + entry %   100 /   10
+        !byte '0' + entry %    10
+        !byte 0                 ; end of BASIC line
+.eol    !word 0                 ; end of BASIC program
+
+entry
+        lda #viccolor_BLACK
+        sta vic_cbg             ; $d021 background
+        lda #viccolor_GREEN
+        sta vic_cborder         ; $d020 border
+
+        ldx #0
+-       lda .msg,x
+        beq +
+        jsr k_chrout            ; $ffd2 print one PETSCII char
+        inx
+        bne -
++       rts
+
+.msg    !pet "hello from acme", 13, 0

package/skills/c64-memory-mapping/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: c64-memory-mapping
+description: Look up what any C64 address means and turn raw 6502 disassembly into documented assembly, by resolving every address against the C64 memory map, KERNAL ROM routine list, canonical assembler symbols, and per-bit VIC-II/SID/CIA register tables. Use when asked to annotate or comment assembly, document a disassembly listing, or look up an address like $D020, $EA24 or $FFD2.
+---
+
+# C64 memory mapping & annotated disassembly
+
+Look up what a C64 address means, and document a 6502 listing by resolving every
+address it touches. One script does both, offline, anywhere Node ≥18 runs:
+
+```bash
+D=.claude/skills/c64-memory-mapping/scripts/driver.mjs   # relative to the repo root
+
+node $D lookup '$D011' '$FFD2'      # what lives at an address
+node $D annotate --file game.asm    # document a listing or .asm file
+… | node $D annotate                # ... or one piped in on stdin
+node $D memmap                      # refresh the table from its sources (needs network)
+```
+
+Write an address however the source you copied it from wrote it — hex `$D011`,
+`0xD011`, `D011h` or `D011`, binary `%1101000000010001`, or decimal `53265` all
+reach the same register, in either letter case.
+
+## Look up an address
+
+`lookup` prints the full published prose for an address, most specific match
+first, each tagged with the source it came from and the memory region it sits in.
+Registers carry their per-bit breakdown, and the wider regions enclosing the
+address follow it:
+
+```
+=== $D011 ===
+$D011  [$D000-$D3FF, 53248-54271 VIC-II; video display]  <sta>
+  Screen control register #1. Bits: Bits #0-#2: Vertical raster scroll. Bit #3: Screen height; 0 =
+  24 rows; 1 = 25 rows. Bit #4: 0 = Screen off, complete screen is covered by border; 1 = Screen
+  on, normal screen contents are visible. Bit #5: 0 = Text mode; 1 = Bitmap mode. Bit #6: 1 =
+  Extended background mode on. Bit #7: Read: Current raster line (bit #8). Write: Raster line to
+  generate interrupt at (bit #8). Default: $1B, %00011011.
+$D011  [MOS 6566 VIDEO INTERFACE CONTROLLER (VIC)]  <io>
+  VIC Control Register
+    bit 7    Raster Compare: (Bit 8) See 53266
+    bit 6    Extended Color Text Mode 1 = Enable
+    bit 5    Bit Map Mode. 1 = Enable
+    bit 4    Blank Screen to Border Color: O = Blank
+    bit 3    Select 24/25 Row Text Display: 1 = 25 Rows
+    bit 2-0  Smooth Scroll to Y Dot-Position (0-7)
+$D000-$D02E  [C64 memory map (labelled)]  <zim>
+  6566 Video Interface Chip, VIC II.
+…
+```
+
+Reach for this whenever a bare address needs a meaning — a register you are about
+to write, a `JSR` target, or a symbol name to give a variable.
+
+## Annotate a listing
+
+```bash
+node $D annotate --file game.asm --out game.documented.asm
+```
+
+The input is any text carrying 6502 mnemonics: hand-written source, or a listing
+from whichever disassembler produced it. Lines come back byte-for-byte —
+indentation, labels, directives, blank lines and existing comments intact — with
+a `; $addr (SYMBOL) = description` comment appended:
+
+```
+        * = $C000
+start   lda #$00
+        sta $d021                           ; $D021 = Background color (only bits #0-#3)
+loop:   ldx $dc01                           ; $DC01 = Port B, keyboard matrix rows and joystick #1
+        inc $d020                           ; $D020 = Border color (only bits #0-#3)
+        jsr $ffd2                           ; $FFD2 = Output Vector, chrout
+        lda ($fb),y                         ; $00FB-$00FE (FREKZP, pointer) = Unused (4 bytes)
+        sta $0400,x                         ; $0400-$07E7 (VICSCN, indexed) = Default area of screen memory (1000 bytes)
+        bne loop
+        jmp ($0314)                         ; $0314-$0315 (CINV, pointer) = Execution address of interrupt service routine
+        rts
+```
+
+A header block listing every referenced address with its full description, symbol
+and region is prepended (elided above): measured on the two examples on this page,
+the eleven-line listing above grows a 23-line header and the nine-line IRQ excerpt
+below grows a 25-line one — a little over 2x the input either way. Pass
+`--no-header` to drop it and get the annotated body alone.
+
+Options:
+
+- `--out FILE` writes the result to a file instead of stdout.
+- `--max-span N` keeps comments to hits narrower than N bytes, for terser output.
+  Default is 4096 bytes: at that width a hit as wide as screen RAM
+  (`$0400-$07E7`, 1000 bytes) or the `$C000-$CFFF` block still earns an inline
+  comment, while the 8 KB BASIC and KERNAL ROM blocks do not — a branch
+  annotated "KERNAL ROM (8192 bytes)" teaches nobody anything. The cap applies
+  only to non-flow instructions: flow instructions (`JMP`, `JSR`, branches,
+  `RTS`, `RTI`) are held to 2 bytes regardless of `--max-span`, so a jump or
+  branch only earns a comment when it targets a specific vector such as
+  `$0314`. `--max-span 2` gives register- and variable-level comments only.
+- `--no-header` suppresses the prepended header block, for piping annotated
+  output straight into a file across a large listing set.
+- `--file -` reads stdin, identical to a bare `annotate`.
+
+Piping works the same way, to annotate straight from another command:
+
+```bash
+node $D annotate --max-span 2 < irq.txt
+```
+
+```
+$EA31: 20 EA FF    JSR $FFEA                ; $FFEA = Increment Real-Time Clock
+$EA34: A5 CC       LDA $CC                  ; $00CC (BLNSW) = Cursor visibility switch
+$EA36: D0 29       BNE $EA61
+$EA38: C6 CD       DEC $CD                  ; $00CD (BLNCT) = Delay counter for changing cursor phase
+$EA3C: A9 14       LDA #$14
+$EA40: A4 D3       LDY $D3                  ; $00D3 (PNTR) = Current cursor column
+$EA44: AE 87 02    LDX $0287                ; $0287 (GDCOL) = Color of character under cursor
+$EA47: B1 D1       LDA ($D1),Y              ; $00D1-$00D2 (PNT, pointer) = Pointer to current line in screen memory
+$EA4F: 20 24 EA    JSR $EA24                ; $EA24 = Syncronise Color Pointer
+```
+
+## Reading the annotations
+
+Weigh a comment by the region it describes:
+
+- **`$D000-$DFFF` is authoritative.** Hardware decides what these mean, so a VIC,
+  SID or CIA comment holds for any program. `LDA $DC01 / AND #$10 / BNE` annotates
+  as "Port B, keyboard matrix rows and joystick #1", bit 4 is the fire button, and
+  that reading is sound because it rests on hardware. KERNAL entry points are
+  equally solid wherever ROM is banked in — `$01` bits #0-#2 select it, and the
+  vector at `$0314` shows whether the KERNAL IRQ path is in use.
+- **Zero page, `$0200-$07FF` and the BASIC area describe BASIC and KERNAL usage.**
+  Read them as a strong hint and confirm against the program's own behaviour
+  before adopting the name. A game that banks ROM out keeps its own variables
+  there. A real case: at `$08E6` a game's `LDA $49` gets labelled `FORPNT`
+  ("value of current variable during LET"), when `$49` is really one of that
+  game's own variables. Take the address, verify the meaning.
+- **A region-only answer is not an error.** An address that no source names
+  specifically prints only the wider regions enclosing it — no error, no
+  not-found line. `node $D lookup '$1234'` prints:
+  ```
+  === $1234 ===
+  $0801-$9FFF  [$0800-$9FFF, 2048-40959 BASIC area]  <sta>
+    Default BASIC area (38911 bytes).
+  $0800-$9FFF  [C64 memory map (labelled)]  <zim>
+    Normal BASIC Program space.
+  ```
+  This is the dominant case for any game's own code: a region-only answer
+  means "the four tables do not name this exact address", not "this address is
+  unmapped". It differs from the genuine zero-hit case, where `lookup` prints
+  `(not in memory map)` because nothing at all covers the address
+  (driver.mjs:485-487). Checked directly against the committed table (a scan of
+  `memmap.json`, not a `memmap` rebuild): every address `$0000`-`$FFFF` is
+  covered by at least one entry as of this build, so `(not in memory map)` is
+  not reachable for any valid address today — the branch exists for a future
+  table that loses coverage, not for anything the current one omits.
+
+For a game, the fastest route to a real name is to annotate with `--max-span 2`,
+trust the I/O lines immediately, and confirm the rest by watching what the code
+does with them.
+
+## Where the data comes from
+
+`node $D memmap` rebuilds the table from four published sources, each covering
+what the others leave out:
+
+| Source | Contribution |
+|---|---|
+| [sta.c64.org/cbm64mem.html](https://sta.c64.org/cbm64mem.html) | richest prose for zero page, work areas, screen RAM, I/O |
+| [C64.MemoryMap.txt](https://www.zimmers.net/anonftp/pub/cbm/maps/C64.MemoryMap.txt) | canonical assembler symbols — `PNT`, `CINV`, `VICSCN`, `TXTTAB` |
+| [krnromma.htm](http://unusedino.de/ec64/technical/aay/c64/krnromma.htm) | every KERNAL ROM routine by name, so `JSR $EA24` reads as "Syncronise Color Pointer" |
+| [C64io.txt](https://www.zimmers.net/anonftp/pub/cbm/maps/C64io.txt) | VIC/SID/CIA registers broken down per bit |
+
+The built table is committed alongside the script, so `lookup` and `annotate` need
+only Node. Rebuild when a source publishes a correction; `lookup`'s `<src>` tags
+show which table any given claim came from.
+
+`memmap` overwrites the committed, git-tracked `memmap.json` (driver.mjs:270 —
+235,925 bytes as of 2026-08-04, confirm with `wc -c`) **in place, with no backup
+and no diff.** One of the four sources (`http://unusedino.de/…`, driver.mjs:33)
+is fetched over plain HTTP with no TLS, and the only guard against a bad rebuild
+is a per-source emptiness check plus a 600-entry floor across all sources
+combined (driver.mjs:262, 268) — so a partially-reachable or partially-changed
+source set can silently replace good tracked data with less of it. Rebuild, then
+run `git diff --stat` on `memmap.json` before accepting the result, and
+`git checkout` the file if the diff is not explainable as the correction you
+were expecting. Because it mutates the repo, `memmap` belongs behind a GSD
+command (`/gsd-quick`), per this project's GSD Workflow Enforcement rule — it is
+not a read-only lookup like `lookup` and `annotate`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Comments land on regions too wide to be useful | `--max-span 2`; the default is 4096 bytes. |
+| A `JSR` or branch target got no comment at all | Flow instructions are capped at 2 bytes regardless of `--max-span`; `lookup` the target directly for the ROM routine name. |
+| The output is mostly header | `--no-header`. |
+| `lookup` printed only wide region lines and no specific name | Nothing in the four tables names that address; expected for the game's own code — take the region and name the address from what the code does with it. |
+| `lookup` printed `(not in memory map)` | Nothing covers it; check the address parsed as intended, since a bare `1234` reads as decimal. |
+| `no memmap.json; run: node driver.mjs memmap` | Restore the committed table with `git checkout` rather than rebuilding; the rebuild needs network and overwrites tracked data. |
+| `memmap` rewrote `memmap.json` and the diff is large or negative | A source was unreachable or changed; `git checkout` the file. |