@henols/c64-re-tools 0.1.12 → 0.2.1

package/bin/cli.mjs

@@ -26,14 +26,57 @@ const HERE = dirname(fileURLToPath(import.meta.url)); // installer/bin (packed)
 const PKG_ROOT = dirname(HERE);
 const SKILLS_SRC = join(PKG_ROOT, "skills");
 
+// The single version-resolution seam this repo maintains is
+// `.claude/mcp/vice/version.ts` (quick-260819-tsz, D-5). This package
+// deliberately does NOT import it: it ships without the seam file (its
+// `files[]` is `bin/`, `skills/`, `README.md`) and targets node >= 18, which
+// cannot type-strip the seam's `.ts` the way the vice-mcp package's own
+// node >= 22.18 runtime can. What follows is exactly the seam's own
+// precedence step 1 -- "read my own package.json's `.version`, trust it
+// when it is a real published number" -- not a second, independent
+// implementation of the resolution algorithm; there is no template/`-`
+// handling here because this package is never resolved from `VERSION`,
+// only ever published with a concrete version already stamped in. That
+// number is PRODUCED elsewhere: `scripts/version.mjs stamp` writes the
+// working-tree placeholder, and CI's `npm version` writes the real one at
+// publish time. Do not reimplement D-2's template-resolution rules here.
 const SELF = readJson(join(PKG_ROOT, "package.json")) ?? {};
 const SELF_VERSION = typeof SELF.version === "string" ? SELF.version : "0.0.0";
 const MCP_PKG = "@henols/vice-mcp";
-// Wire the project to the exact vice-mcp version this installer was built against.
-const MCP_VERSION =
-  (SELF.dependencies && typeof SELF.dependencies[MCP_PKG] === "string"
+// The dev placeholder every derived, publishable version string carries in
+// the working tree (R-2, quick-260819-tsz). Defined authoritatively as
+// `DEV_PLACEHOLDER` in `.claude/mcp/vice/version.ts` -- repeated here as a
+// literal, NOT imported, because this package deliberately ships without
+// that seam file (see the comment above) and targets node >= 18, which
+// cannot type-strip a `.ts` import the way the vice-mcp package's own
+// node >= 22.18 runtime can. This is the same disclosed divergence as
+// `SELF_VERSION` above: one literal, kept in sync by hand, documented here
+// so a future edit to the seam's placeholder is not missed.
+const MCP_DEV_PLACEHOLDER = "0.0.0-dev";
+// Wire the project to the exact vice-mcp version this installer was built
+// against -- EXCEPT when run from an unstamped dev checkout (MED-3):
+// `installer/package.json`'s dependency pin is the permanent working-tree
+// placeholder outside a CI-stamped publish job, and `@henols/vice-mcp` at
+// that literal version will never exist on the npm registry. Silently
+// writing it into a consumer's .mcp.json would 404 every time Claude Code
+// tries to launch the server, with no error until the user actually tries
+// to use it -- strictly worse than falling back to "latest". Fall back AND
+// warn loudly, so a developer testing the installer locally knows their
+// .mcp.json is unpinned rather than discovering it via a silent 404 later.
+const MCP_VERSION_RAW =
+  SELF.dependencies && typeof SELF.dependencies[MCP_PKG] === "string"
     ? SELF.dependencies[MCP_PKG].replace(/^[\^~]/, "")
-    : SELF_VERSION);
+    : SELF_VERSION;
+if (MCP_VERSION_RAW === MCP_DEV_PLACEHOLDER) {
+  console.error(
+    `c64-re-tools: WARNING -- running from an unstamped dev checkout (installer/package.json pins ` +
+      `${MCP_PKG}@${MCP_DEV_PLACEHOLDER}, the dev placeholder, not a real published version). ` +
+      `Falling back to "${MCP_PKG}@latest" in the generated .mcp.json instead of writing an ` +
+      `unresolvable pin. If you intended to test against a specific version, pass --vendor or fix ` +
+      `installer/package.json's dependency pin before packaging a release.`
+  );
+}
+const MCP_VERSION = MCP_VERSION_RAW === MCP_DEV_PLACEHOLDER ? "latest" : MCP_VERSION_RAW;
 
 function readJson(path) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "0.1.12",
+  "version": "0.2.1",
   "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "installer"
   ],
   "dependencies": {
-    "@henols/vice-mcp": "0.1.12"
+    "@henols/vice-mcp": "0.2.1"
   },
   "scripts": {
     "sync-skills": "node scripts/sync-skills.mjs",

package/skills/acme-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acme-build
-description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, list the symbols a program uses, or turn a .prg back into ACME source.
+description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, or list the symbols a program uses.
 ---
 
 # Assembling C64 source with ACME
@@ -13,10 +13,9 @@ A=.claude/skills/acme-build/scripts/acme.mjs   # from the repo root
 node $A new game.asm          # scaffold a C64 program
 node $A build game.asm        # assemble -> .prg .sym .vs .rep
 node $A sym game.asm          # the symbols the program uses
-node $A disasm game.prg       # object code back into ACME source
 ```
 
-The script wraps `acme` and `toacme` and nothing else — **assembling only**. Running
+The script wraps `acme` and nothing else — **assembling only**. Running
 the result on a C64 belongs to the emulator skills (`acme.mjs:3-4` says so, and the
 absent `run` verb is not an omission). It contacts nothing.
 
@@ -133,57 +132,43 @@ you also assemble by hand, so these stay recognised as mnemonics.
 
 ## Disassembly
 
-```bash
-node $A disasm game.prg
-```
-```
-game.dis.a: 28 lines
-Read it as a linear decode: trust the instruction stream, and
-treat strings, tables and the BASIC stub as data. To reassemble,
-define the out-of-range labels it emits (Ld020, Lffd2, ...) and
-indent its illegal-opcode lines to the operand column.
-```
-
-The default output is `<stem>.dis.a` — one more `.a` file the agent's Read tool
-refuses (see Troubleshooting). Pass a second positional ending `.asm` for an
-agent-readable listing instead (same stdout shape, `game.dis.asm: 28 lines` in
-place of the first line):
+This skill does not disassemble. Static disassembly of a `.prg` or flat 64K image
+is a **required prerequisite** of this plugin, not an optional accelerator:
+regenerator2000, reached through
 
 ```bash
-node $A disasm game.prg game.dis.asm
+npx -y @henols/vice-mcp r2000 export-asm game.prg          # npm installs
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 export-asm game.prg  # in-repo/plugin
 ```
 
-`game.dis.asm` itself then holds:
+A recursive-descent disassembler with an auto-analyzer does not render strings,
+tables and the BASIC stub as instructions, so there are no out-of-range labels
+to hand-define and no illegal-opcode lines to re-indent — the caveats this
+section used to carry were structural to a flat linear decoder and do not
+apply here. The exported source is verified reassemblable by a real ACME
+via `vice-mcp r2000 verify` (evidence:
+`.planning/phases/10-adoption-boundaries-automated-bootstrap-and-the-removal/evidence/10-verify-transcript.txt`).
+`c64-program-recon` points at this same route; it is not restated there.
 
-```
-		*=$0801
-L0801		!by$0b;ANC#      <- BASIC stub, read as data
-L0802		php
-L0805		 SHX L3032, y
-...
-L080d		lda #$00         <- code, decoded correctly
-L080f		sta Ld021
-L0812		lda #$05
-L0814		sta Ld020
-L081e		jsr Lffd2
-L0824		rts
-L0825		pha              <- PETSCII string, read as data
-```
+## Setup
 
-Read it as a linear decode: the instruction stream is accurate, and strings,
-tables and the BASIC stub appear as instructions — interpret those regions as
-data. To reassemble the listing, define the out-of-range labels it emits
-(`Ld020`, `Lffd2`) and indent its illegal-opcode lines to the operand column.
+`acme` on `$PATH` is the **only** requirement. The scaffold that `new` writes
+assembles against a bare install with no standard hardware-register library —
+that's deliberate: neither a plain `~/.local/bin/acme` build nor the Debian
+trixie `apt` candidate ships one, so a scaffold that depended on it would fail
+to assemble on a fresh install (Phase 8.1 FINDING-A1).
 
-## Setup
+`$ACME` and the wrapper's auto-probe (`$ACME`, `/usr/local/share/acme`,
+`/usr/share/acme`, `/usr/lib/acme`, `~/.acme`) still exist and still matter —
+but only for **your own** sources that use angle-bracket includes (see
+"Writing source" above), not for the scaffold. If you have that library
+somewhere, point `$ACME` at its directory and angle-bracket includes work as
+before; if you don't, the scaffold doesn't need it.
 
-Put `acme` and `toacme` on `$PATH`. The wrapper auto-probes `$ACME`,
-`/usr/local/share/acme`, `/usr/share/acme`, `/usr/lib/acme` and `~/.acme` itself,
-so `$ACME` only needs setting by hand when calling `acme` directly. Verified live
-in this container on 2026-08-04: the library resolves to `/usr/local/share/acme`
-(`/usr/share/acme` doesn't exist), ACME release 0.97 "Zem" (31 Jan 2021) at
-`/usr/bin/acme`. **Confidence: HIGH** — read off `acme --version` and the probe
-result, not off a package manifest.
+Re-checked against ACME release 0.97 "Zem" (31 Jan 2021). CI now assembles
+the shipped scaffold on every build with `$ACME` cleared (the "Assemble the
+acme-build scaffold (library-free)" step in `.github/workflows/ci.yml`), so
+this claim is re-checkable rather than a one-machine observation.
 
 Copy `acme.mjs` into any project's `.claude/skills/acme-build/scripts/`, and
 `template.a` into `.claude/skills/acme-build/`, to use this elsewhere.
@@ -197,14 +182,15 @@ This one turns source into bytes. It does not restate what the others carry.
 | Where to start on an unknown program, and which address to read next | `c64-program-recon` |
 | What a specific address or bit means, or annotating a listing | `c64-memory-mapping` — `node … lookup '$D018'` |
 | A verified 64K image, or comparing two captures | `c64-ram-capture` |
-| **Source in, `.prg` out — and a first-pass dead listing back** | here |
+| Static disassembly of a `.prg` or flat image | `vice-mcp r2000 export-asm` (see Disassembly above) |
+| **Source in, `.prg` out** | here |
 
 ## References
 
 | File | Covers |
 |---|---|
 | `scripts/acme.mjs` | The driver. Its comments are the contract for every flag above |
-| `template.a` | The scaffold `new` writes: BASIC stub with a computed `SYS`, the three `!source` libraries, no `!to` |
+| `template.a` | The scaffold `new` writes: BASIC stub with a computed `SYS`, five local hardware constants (no library needed), no `!to` |
 
 Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you
 find them**, graded with `Evidence:` and `Confidence:`. Promote by re-logging with

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

@@ -205,22 +205,6 @@ function cmdNew(argv) {
   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) {
@@ -247,14 +231,13 @@ function parseOpts(argv) {
 // --------------------------------------------------------------------- main
 
 const [cmd, ...rest] = process.argv.slice(2);
-const VERBS = { new: cmdNew, build: cmdBuild, sym: cmdSym, disasm: cmdDisasm };
+const VERBS = { new: cmdNew, build: cmdBuild, sym: cmdSym };
 if (!cmd || !VERBS[cmd]) {
   console.log(`usage: node ${selfPath()} <command> [options]
 
-  new <file.a>              scaffold a C64 program (BASIC stub + libs)
+  new <file.a>              scaffold a C64 program (BASIC stub, no libraries needed)
   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`);

package/skills/acme-build/template.a

@@ -2,11 +2,25 @@
 ; 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.
+;
+; No angle-bracket library includes here on purpose. Neither documented ACME
+; provisioning route ships the standard hardware-register library - a bare
+; `~/.local/bin/acme` install and the Debian trixie `apt` candidate were both
+; verified to lack it (Phase 8.1 FINDING-A1) - so a scaffold that depends on
+; it fails to assemble on a fresh install. The five constants below are
+; exactly what this scaffold's body uses, defined locally instead. If you
+; want the full library for your own sources' angle-bracket includes, set
+; $ACME to a directory containing that library (with vic.a inside it);
+; acme.mjs's findAcmeLib() already probes for it and passes it through to
+; the child.
 
 !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
+
+!address vic_cborder = $d020    ; VIC-II border color register
+!address vic_cbg     = $d021    ; VIC-II background color register
+viccolor_BLACK = 0
+viccolor_GREEN = 5
+!address k_chrout    = $ffd2    ; KERNAL: print one PETSCII char
 
 * = $0801                       ; start of BASIC RAM
 

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

@@ -186,6 +186,41 @@ 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`.
 
+## Feeding the enum generator
+
+`memmap.json`'s structured `bits` entries are the source of the curated register bit-name table used
+to generate program-specific enums for regenerator2000's annotation store (R2000-13): register
+writes disassemble as `lda #D011_YSCROLL3_ROW25_SCREENON_TEXT` instead of a bare `#$1b`. The
+generator is `.claude/mcp/vice/r2000-regbits-gen.ts`; its committed output is
+`.claude/mcp/vice/r2000-regbits.json`; and that output is **digest-pinned** to `memmap.json` — a
+`node r2000-regbits-gen.ts` run compares its own fresh build against the committed file, and CI fails
+if `memmap.json` changed without a re-run.
+
+**The honest gap:** only 29 of this file's 959 entries carry a structured `bits` array. `$D015`,
+`$D017`, `$D01A` and `$D01B`–`$D01D` — the sprite-plane bitmask registers a real game writes
+constantly — are **not** among those 29, so the enum generator supplies them from its own curated
+override table (`OVERRIDES` in `r2000-regbits-gen.ts`), not from this file. Widening `memmap.json`'s
+`io` parser (or repairing the OCR damage already present in some `bits` prose, e.g. a letter `O` for
+the digit `0`) so those registers get a real structured entry here is separate work belonging to this
+skill, not the generator.
+
+**Installing those bit names into a project's own disassembly:** the table above only builds
+`r2000-regbits.json` — turning a specific project's register *writes* into named enum variants is a
+separate, later step, once a `.regen2000proj` already exists (`r2000 bootstrap`, see
+`c64-program-recon`):
+
+```bash
+npx -y @henols/vice-mcp r2000 gen-enums game.regen2000proj                            # npm install
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 gen-enums game.regen2000proj  # in-repo/plugin
+```
+
+`r2000 gen-enums` requires an EXISTING `.regen2000proj` — it does not bootstrap one from a raw
+input. It reads the project's own disassembly, creates one enum variant per DISTINCT value actually
+written at each matching immediate-load address (named from the curated table above), and prints
+total/paired/unpaired register-store counts plus a per-enum variant count. It exits non-zero, naming
+the reason, when either of its two internal search passes hits its own 10000-row ceiling — pass
+`--max-results` to raise that ceiling for a program whose store exceeds it.
+
 ## Troubleshooting
 
 | Symptom | Fix |

package/skills/c64-program-recon/SKILL.md

@@ -115,6 +115,130 @@ same IRQ entry that phase-01 live work established independently (chain `$1103
 The method reproduces a known-good result from a static image with no emulator running, and the
 `$1116` pair is new — see `references/control-flow.md` § 2. **Confidence: HIGH** for steps 1-2.
 
+## Writing findings into the annotation store
+
+Recon's findings are not memory-map prose written once and left to rot — they are entries in a
+queryable annotation store, and the Markdown memory map is a *generated view* of that store (D-24),
+not something you hand-edit yourself.
+
+**Open or bootstrap the store**, then hand its path to every call that follows:
+
+```bash
+npx -y @henols/vice-mcp r2000 bootstrap game.prg                            # npm install
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 bootstrap game.prg   # in-repo/plugin
+```
+
+Every `r2000_*` tool takes an explicit `project` path pointing at the resulting `.regen2000proj`
+(D-19) — there is no ambient session state naming the store, so which project a call touched is
+always visible in the transcript.
+
+**Write findings with the named tools, not a Markdown row:**
+
+| Tool | Use for |
+|---|---|
+| `r2000_set_label_name` | Naming a routine or table (`init_screen`, `sprite_table`) |
+| `r2000_set_data_type` | Classifying a block (`code`, `byte`, `address`, `petscii`, …) |
+| `r2000_add_scope` | Marking a handler's extent as a lexical scope |
+| `r2000_set_comment` | Recording the evidence — the carrier for the confidence grade below |
+| `r2000_batch_execute` | Bulk annotation, 5+ independent calls at once — a real memory map is dozens of labels/comments/block ranges, and batching is what makes that affordable under the per-call spawn-load-mutate-save-exit lifecycle |
+
+**Grade with the confidence prefix.** Lead every evidence comment with exactly one of these five
+bracket tokens (quoted verbatim from `r2000-confidence.ts`, the parser's own source of truth):
+
+`[confirmed-code]` (confirmed code), `[probable-code]` (probable code), `[confirmed-data]`
+(confirmed data), `[probable-data]` (probable data), `[unknown]` (unknown).
+
+A typo in the bracket token — wrong case, an underscore, a plural, stray whitespace — **fails
+loudly**; it does not silently degrade into an ungraded comment. As with `RE-FINDINGS.md`, do not
+promote a row by editing its grade in place: re-verify and restate the evidence with a fresh
+`r2000_set_comment` call, so the record of when something stopped being a guess survives.
+
+**Query instead of re-deriving.** `r2000_get_symbols`, `r2000_get_comments`, `r2000_get_blocks` and
+`r2000_get_cross_references` answer straight from the store. `r2000_search_disassembly` searches
+labels, comments and instructions together — but `max_results` is **REQUIRED** on this surface,
+because regenerator2000's own default is 50 and silently truncates a full-program pass. The query
+this whole workflow exists to make cheap:
+
+> "Show me everything still `[unknown]`" → `r2000_search_disassembly` with `query: "[unknown]"` and
+> an explicit `max_results` set above your program's comment count.
+
+(The composite address-details lookup is deliberately not on this surface — D-32, a 64K-project
+defect filed upstream — its answer is reachable as a combination of the tools above.)
+
+### Take names to the running machine, and bring live findings back
+
+The store and the running emulator are not two independent destinations for a name — writing one
+into the store and discovering one live are two legs of **one loop**, in this order, matching how
+`R2000-14`/`R2000-15` were actually proven (see Phase 11's live walkthrough,
+`evidence/criterion4/WALKTHROUGH.md`):
+
+1. **Export what the store already knows.** `r2000 export-lbl <project>` writes `al C:xxxx .Name`
+   lines that `stock-symbols.ts`'s own parser accepts — the verb reads the written file back
+   through that same parser before it reports success, never trusting a regenerator2000 exit code
+   alone.
+
+   ```bash
+   npx -y @henols/vice-mcp r2000 export-lbl game.regen2000proj                            # npm install
+   node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 export-lbl game.regen2000proj  # in-repo/plugin
+   ```
+
+2. **Load it into the running machine — `vice_symbols_load`, exactly once.** Load that `.lbl` file
+   into the live emulator with `vice_symbols_load`. Call it **exactly once** per regenerated file:
+   it REPLACES the machine's symbol table rather than merging into it, so loading an older export a
+   second time after the store has moved on would silently discard the newer names.
+3. **Discover something live the static pass could not, then write it to the store first.**
+   Disassembling or reading the running machine (`vice_disassemble`, a checkpoint hit, …) can turn
+   up a name the static store never had. Write it with `r2000_set_label_name` *before* regenerating
+   anything — the store is the merge point (D-29), not your own notes.
+4. **Regenerate the whole `.lbl` and bring it back with `import-lbl`, never an incremental patch.**
+   `r2000 import-lbl <project> <lbl>` imports an externally-produced `.lbl` file into the project,
+   and reports whether the import was **disk-verified** — re-read from disk in a fresh process,
+   never trusted from the child's own success text alone.
+
+   ```bash
+   npx -y @henols/vice-mcp r2000 import-lbl game.regen2000proj discovered.lbl                            # npm install
+   node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 import-lbl game.regen2000proj discovered.lbl  # in-repo/plugin
+   ```
+
+Two traps: `export-lbl` exports **USER** labels only — the auto-generated `a_D011`/`e_FFD2`
+externals never appear in the written file. And both verbs require an EXISTING `.regen2000proj`;
+neither one bootstraps a project from a raw input.
+
+`r2000 gen-enums` — turning register writes into named enum variants — is documented in
+`c64-memory-mapping`, alongside the `memmap.json` bit table it consumes.
+
+**Generate the memory map; do not hand-author it.** Fill in the provenance sidecar (schema and a
+filled example live in `templates/memory-map.template.md`), then:
+
+```bash
+npx -y @henols/vice-mcp r2000 render-memmap game.regen2000proj --provenance sidecar.json
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 render-memmap game.regen2000proj --provenance sidecar.json
+```
+
+Add `--check` to detect drift — either a hand edit to the rendered file, or a store change since it
+was last rendered. The rendered file carries a generated-file banner; treat it like every other
+generated artifact in this repo and never hand-edit it.
+
+## Static disassembly
+
+Turning a `.prg` or a flat 64K image into ACME source, offline, is not part of this
+skill's own method — it is a separate route:
+
+```bash
+npx -y @henols/vice-mcp r2000 export-asm game.prg          # npm installs
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 export-asm game.prg  # in-repo/plugin
+```
+
+This is **static**, over a file on disk — `vice_disassemble` (the live-RAM route
+this skill's own table above uses) reads a running emulator's RAM at a checkpoint
+instead. The two are complementary: reach for the static route before the emulator
+is even running, and for `vice_disassemble` once you have a live checkpoint to
+decode from.
+
+Extracting from a `.d64` image: name the file inside the image explicitly. The
+tool lists the directory and refuses rather than guess (D-02) — a guess could
+analyse a cracktro or loader stub instead of the game.
+
 ## Before you touch the emulator
 
 Two hazards cost this project real sessions. Both are in `references/observation-hazards.md`; these
@@ -137,7 +261,8 @@ This one is the route between the stations. It does not restate what the others
 |---|---|
 | A verified 64K image, or comparing two captures | `c64-ram-capture` |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
-| Assembling, or a first-pass dead listing | `acme-build` |
+| Assembling | `acme-build` |
+| Static disassembly of a `.prg` or flat image | `vice-mcp r2000 export-asm` (see above) |
 | Whether a byte is original or cracker-changed | `c64-provenance-diff` |
 | The emulator stopped moving — wedged, self-trapped, or respawned | `vice-wedge-triage` |
 | **Which address to read next, and what the answer rules out** | here |
@@ -152,7 +277,7 @@ This one is the route between the stations. It does not restate what the others
 | `references/observation-hazards.md` | Every way a live read gives a wrong answer. **Read before driving.** |
 | `references/tool-selection.md` | Which `mcp__plugin_c64-re-tools_vice__*` call answers which question, and what to delegate |
 | `references/reconstruction.md` | Binary inclusion, behavioural-equivalence correctness bar, SMC labels, label vocabulary |
-| `templates/memory-map.template.md` | Region map with per-row confidence grading |
+| `templates/memory-map.template.md` | `render-memmap`'s provenance sidecar schema and the confidence vocabulary — the rendered map itself is generated, not hand-authored |
 
 Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you find them**,
 graded with `Evidence:` and `Confidence:`. Promote by re-logging with the new evidence, never by
@@ -168,5 +293,5 @@ editing a grade in place. File-changing work enters through a GSD command (`/gsd
 | A sprite decodes as noise | Check `$D015` first; a disabled sprite's registers are stale. Then check MCM — multicolor decoded as hires comes out twice as wide. |
 | Computed mode is "INVALID — screen goes black" | You caught the registers mid-update inside a raster split. Re-read. |
 | The emulator looks dead | Enumerate armed checkpoints before anything else. See hazard 2. |
-| `vice_keyboard_type` does nothing | The game polls `$DC00`/`$DC01` directly. Use `vice_keyboard_matrix`. |
+| `vice_keyboard_type` does nothing | The game polls `$DC00`/`$DC01` directly. Use `vice_keyboard_matrix` (**requires the fork backend** — see `references/observation-hazards.md` § 4 for the stock route). |
 | Two captures of the same checkpoint differ | Expected. Full-64K identity is impossible in principle; use `c64-ram-capture`'s drift rules. |

package/skills/c64-program-recon/references/control-flow.md

@@ -87,6 +87,11 @@ address to checkpoint when the emulator is next available — press RESTORE with
 until the line is released, so it is a press→release **edge**), then `vice_machine_reset` soft and
 hard, and record where the PC actually lands.
 
+**`vice_keyboard_restore` requires the fork backend.** The RESTORE key pulses the NMI line
+directly and is not part of the keyboard matrix, so stock's `KEYBOARD_FEED` (which only injects
+PETSCII text into the buffer) cannot produce it. Calling it on the stock backend returns an error
+naming the reason and the fork backend, rather than pulsing RESTORE.
+
 **Evidence:** derived mechanically from six three-run-verified captures; every value identical
 across all three runs of its release, so none of it is drift.
 **Confidence:** HIGH for the values and for the cross-release divergence. The *interpretation* of
@@ -156,6 +161,10 @@ at a title screen and again in gameplay, diff the two captures, and look for a s
 changed in zero page or low RAM. `vice_memory_compare` narrows this; `c64-ram-capture` § Compare
 two captures gives the volatility rules that stop you chasing drift.
 
+On stock, only `mode: 'ranges'` is served — capture the two states at different points in time and
+compare two live ranges. `mode: 'snapshot'` is refused with an explanatory message; there is no
+memory-only snapshot producer on either backend.
+
 ## Verified against this project — 2026-08-04
 
 Running `derive.mjs vectors` cold on both releases' `*-gameentry-run1.bin` returns `$01` = `$40`

package/skills/c64-program-recon/references/graphics.md

@@ -71,3 +71,9 @@ hardware registers are what the game uses.
 `vice_sprite_get` / `vice_sprite_inspect` do the pointer arithmetic and the multicolor bit-pair
 unpacking. Verify what they return once against a hand-resolved pointer — `derive.mjs sprites`
 gives you that hand resolution — then trust them.
+
+On stock, `vice_vicii_get_state`'s `$D018` pointers are reported **bank-relative**;
+`vice_sprite_get` resolves the absolute `screenBase` and per-sprite `dataAddress` for you.
+`vice_sprite_inspect`'s ASCII grid is the sprite's native 24x21 (hi-res) or 12x21 (multicolour)
+**data block** — it is **not** scaled by the `$D017`/`$D01D` expansion bits, so a sprite shown
+double-size on screen still renders at its native resolution in the grid.

package/skills/c64-program-recon/references/observation-hazards.md

@@ -80,6 +80,21 @@ Prefer the whole-chip reads — `vice_vicii_get_state`, `vice_cia_get_state`, `v
 — over raw register reads. Whether the VICE monitor's own read path is side-effect-free is
 **unverified**: treat it as verify-don't-assume rather than taking it on faith.
 
+On the stock backend, `vice_vicii_get_state`/`vice_cia_get_state` reads are `sidefx: false` with
+no argument able to override it — **VERIFIED**, asserted on the wire body by a regression test.
+Whether the emulator's own `MEM_GET` read path actually honours that flag for
+`$D01E`/`$D01F`/`$DC0D`/`$DD0D` — i.e. whether it truly cannot clear them — is **ASSUMED**, with
+no probe recorded in this repo; treat it as no worse than the fork's own unverified path, not as
+a proven guarantee. `vice_sid_get_state` is **fork-only**, since SID `$D400-$D418` is write-only
+in hardware and the binary monitor has no SID command. Also: on stock, an internal field the
+register map cannot expose is marked `{ available: false, reason }` in the answer, never a bare
+`0` — do not record a stock `0` from one of these fields as a measurement; check `available`
+first. A stock chip-state or sprite answer also **names the memory view it read** (`bank`, or
+`registerBank`/`dataBank`), read through the emulator's own `io`/`ram` banks, so it stays valid
+even while the program has I/O banked out ($01 driving the RAM/ROM/I-O switch). An answer with
+**no** bank field — an older transcript, or the fork backend — is suspect whenever `$01` may not
+have been `$37`: those bytes may be the RAM underneath the I/O area, not registers.
+
 ## 4. The keyboard buffer is not how games read keys
 
 **Evidence: live. Confidence: HIGH. Cost: an afternoon.**
@@ -88,6 +103,14 @@ Games and cracks poll the `$DC00`/`$DC01` matrix directly, bypassing the KERNAL
 `vice_keyboard_type` is invisible to them. Use `vice_keyboard_matrix`, and hold a key across a
 gate by releasing it at the trigger checkpoint, never earlier.
 
+**`vice_keyboard_matrix` requires the fork backend.** The binary monitor's `KEYBOARD_FEED` (0x72)
+only injects PETSCII text into the KERNAL keyboard buffer; the emulator recomputes CIA port B from
+its own keyboard array on every read, so there is no wire command that can drive the raw matrix —
+this is unrecoverable on stock, not merely unbuilt. On stock, use `vice_keyboard_type` /
+`vice_keyboard_petscii` when the gate reads the KERNAL buffer, or `vice_joystick_set` when it polls
+the matrix directly instead; either way, buffer injection is invisible to a program polling
+`$DC00`/`$DC01` itself, so a matrix-polling gate must be driven by the joystick or not at all.
+
 ## 5. Most state reads pause the emulator and do not resume it
 
 Read all state first, poll with `vice_ping` (the non-pausing poll), and resume **exactly once** at

package/skills/c64-program-recon/references/sound-and-input.md

@@ -53,12 +53,20 @@ One that programs `$DC04-$DC07` and enables timer A runs its own timebase.
   writing `$DD00` is usually talking to the drive.
 - **`$DC0D`/`$DD0D` clear the interrupt flags on read**, the same shape as `$D01E`/`$D01F`. Reading
   one steals an interrupt the game was about to service. Prefer `vice_cia_get_state`. The VICE
-  monitor's exact behaviour here is **unverified** — verify, don't assume.
+  monitor's exact behaviour here is **unverified** — verify, don't assume. On stock,
+  `vice_cia_get_state` reports the **read** side of `$xx0D` as `interruptStatus` and marks the
+  write-side enable mask `unavailable` — the two share one address with different meanings, so a
+  reader looking for "which interrupts are enabled" is not silently handed the flags that have
+  fired.
 - **Direct `$DC00`/`$DC01` polling is the norm, and it defeats `vice_keyboard_type`.**
   **Evidence: live, established on this project during recovery work. Confidence: HIGH. Cost: an
   afternoon.** Games and cracks bypass the KERNAL keyboard buffer and read the matrix directly.
   Assume it until shown otherwise, and drive input with `vice_keyboard_matrix` or the joystick
-  tools instead.
+  tools instead. **`vice_keyboard_matrix` requires the fork backend** — the binary monitor's
+  `KEYBOARD_FEED` only injects PETSCII buffer text and cannot drive the raw matrix. On stock, use
+  `vice_keyboard_type` / `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or
+  `vice_joystick_set` when it polls the matrix directly; buffer injection stays invisible to a
+  program polling `$DC00`/`$DC01` itself.
 
 ## Finding input handling from the observable side
 

package/skills/c64-program-recon/references/tool-selection.md

@@ -14,11 +14,12 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | What does the handler at this vector do? | `vice_disassemble` — the emulator's own decoder, not a dead listing |
 | Is this really the main loop? | `vice_checkpoint_add` + `vice_run_until` + `vice_registers_get` — fires once per frame ⇒ proven |
 | What code writes this? | `vice_watch_add` — finds **writers**. Best targets: `$D018`, VM+`$03F8`, `$D404` |
-| Whole-chip state without the read hazards | `vice_vicii_get_state` / `vice_sid_get_state` / `vice_cia_get_state` — **prefer these over raw register reads** |
-| Decode sprite data | `vice_sprite_get` / `vice_sprite_inspect` |
-| Find a known byte pattern | `vice_memory_search` |
-| Carry labels across sessions | `vice_symbols_load` / `vice_symbols_lookup` — ACME `--vicelabels` and regenerator2000 output share this channel |
-| Is the machine wedged, or did it stop itself? | `vice_diagnose` — five-state verdict with its evidence. **Reachable and proxy-intercepted as of 2026-08-04** (verified live). Triage tree: `vice-wedge-triage` |
+| Whole-chip VIC-II/CIA state without the read hazards | `vice_vicii_get_state` / `vice_cia_get_state` (**both backends**) — prefer these over raw register reads |
+| Whole-chip SID state without the read hazards | `vice_sid_get_state` (**requires the fork** — SID `$D400-$D418` is write-only in hardware and the binary monitor has no SID command; unrecoverable on stock) |
+| Decode sprite data | `vice_sprite_get` / `vice_sprite_inspect` (**both backends**) |
+| Find a known byte pattern | `vice_memory_search` (**both backends**) |
+| Carry labels across sessions | `vice_symbols_load` / `vice_symbols_lookup` (**both backends**) — ACME `--vicelabels` and regenerator2000 output share this channel |
+| Is the machine wedged, or did it stop itself? | `vice_diagnose` — five-state verdict with its evidence (the two backends' verdict sets differ by one; see `docs/stock-vice-parity.md` D-03). **Reachable and proxy-intercepted as of 2026-08-04** (verified live). Triage tree: `vice-wedge-triage` |
 | Replace a wedged instance | `vice_recycle` — destructive, requires a `reason`, and that reason is written into `.planning/incidents/` **before** anything is killed. The reason *is* the evidence record |
 | Read the restart epoch | **No tool does.** The proxy compares it around every forwarded call and raises drift itself; a value comes from that error or from `vice_diagnose` |
 
@@ -29,15 +30,18 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | What does address X mean? | the `c64-memory-mapping` skill — `node … lookup '$D018'`. **Do not restate its tables.** |
 | Is this byte original or cracker-changed? | the `c64-provenance-diff` skill |
 | A verified 64K image, or comparing two captures | the `c64-ram-capture` skill |
-| Fast first-pass listing | `toacme` — decodes data as instructions; never the deliverable |
-| Traced disassembly with code/data separation | regenerator2000 — still MEDIUM per `STACK.md`; its first real run is its verification |
+| Traced disassembly with code/data separation | regenerator2000, via `vice-mcp r2000 export-asm` — a recursive-descent disassembler with an auto-analyzer; verified live: its `--verify` run reassembled byte-identically through a real ACME for both a `.prg` and a flat 64K image (`.planning/phases/10-adoption-boundaries-automated-bootstrap-and-the-removal/evidence/10-verify-transcript.txt`) |
 
 ## Three traps in this table
 
-**`vice_run_until` has no working timeout.** Its schema documents `cycles` as *"not yet
-implemented"*, so a run to an address the program never reaches has nothing to bound it and looks
-exactly like a wedged emulator. Prefer `vice_checkpoint_add` + a bounded poll when the address is
-a hypothesis rather than a certainty. **Confidence: MEDIUM** — read off the schema, not reproduced.
+**`vice_run_until`'s timeout is backend-qualified — it has none on the fork, but stock bounds it
+(Phase 7, D-02).** On the fork, `cycles` is documented as *"not yet implemented"* and there is no
+`timeout_ms` either, so a run to an address the program never reaches has nothing to bound it and
+looks exactly like a wedged emulator; prefer `vice_checkpoint_add` + a bounded poll when the
+address is a hypothesis rather than a certainty. **Confidence: MEDIUM on the fork** — read off the
+schema, not reproduced. On stock, `timeout_ms` (default 30000, ceiling 600000) bounds the wait, and
+a timed-out answer says the machine is left halted rather than looking like a wedge — see
+`vice-wedge-triage` for the full triage judgement and its live evidence; do not restate it here.
 
 **`vice_diagnose` leaves the machine paused.** When it measures a cycle bracket it resumes the
 machine once or twice and then leaves it **paused** — resuming is your own next call. And a

package/skills/c64-program-recon/templates/memory-map.template.md

@@ -1,62 +1,83 @@
-# Memory map — <program name> @ <checkpoint where this was captured>
-
-Capture: `<path to the 64K image>`  ·  SHA-256 `<hash>`
-`$01` = `<value>`  ·  VIC bank `<n>` (`$DD00` = `<value>`)  ·  video standard `<PAL/NTSC>`
-Live vector pair: `<$0314/$0315 or $FFFE/$FFFF>` → `<handler>`
-
-Every row carries a confidence. Do not promote a row by editing its grade — re-verify and restate
-the evidence, so the record of when something stopped being a guess survives.
-
-| Range | Contents | Confidence | Evidence |
-|---|---|---|---|
-| `$0000-$00FF` | Zero page — game variables | | |
-| `$0100-$01FF` | Stack | CONFIRMED | hardware |
-| `$0200-$03FF` | KERNAL work area / vectors | | |
-| `$0400-$07E7` | Screen RAM (if VM resolves here) | | |
-| `$0801-$` | | | |
-| `$D800-$DBFF` | Colour RAM | CONFIRMED | hardware, not banked |
-| `$E000-$FFFF` | RAM under KERNAL (HIRAM=0) or KERNAL ROM | | |
-
-Confidence vocabulary — the project's HIGH / MEDIUM / LOW scale, applied to classification:
-
-| Grade | Means |
-|---|---|
-| **confirmed code** | Executed during tracing, PC observed inside it |
-| **probable code** | Reachable through a `JSR`/`JMP`/vector, not yet observed executing |
-| **confirmed data** | Never hit as an instruction stream across full gameplay coverage |
-| **probable data** | Indexed-load target, or matches a data shape (sprite blocks, PETSCII, address tables) |
-| **unknown** | No reliable interpretation yet |
+# Memory map generation
 
-Do not force an unknown range through a disassembler and record the output as code. A linear
-decode of data is silently wrong and contaminates everything downstream.
+**The memory map is GENERATED, not hand-authored (D-24).** The store — labels, comments, block
+types and scopes written through the `r2000_*` tools described in `../SKILL.md` — is canonical. This
+file used to be a fill-in-the-rows document; it is now the schema for the one input the generator
+needs beyond the store itself, plus the confidence vocabulary that store comments carry.
 
-## Graphics chain
+Run the generator once findings are in the store:
 
-| What | Address | Derived from |
-|---|---|---|
-| VIC bank | | `$DD00` bits 0-1, inverted |
-| Screen RAM (VM) | | `$D018` bits 4-7 |
-| Charset / bitmap (CB) | | `$D018` bits 1-3 |
-| Mode | | `$D011` bits 5-6, `$D016` bit 4 |
-| Sprite pointers | | VM + `$03F8` |
+```bash
+npx -y @henols/vice-mcp r2000 render-memmap game.regen2000proj --provenance sidecar.json
+node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 render-memmap game.regen2000proj --provenance sidecar.json
+```
 
-Character ROM shadow checked: <yes/no — CB in `$1000`/`$9000` of bank 0/2 means no charset in RAM>
+Add `--check` to compare the rendered file on disk against a fresh render — it exits non-zero and
+prints the first differing line on **either** a hand edit to the rendered file **or** a store change
+since it was last rendered. There is no way to "fix" drift by editing the rendered file directly:
+the fix is always to re-run the generator (or, if the sidecar itself is stale, correct it and
+re-run). The generated file carries a banner naming the store, the sidecar and a content digest —
+do not strip it.
 
-## Interrupts
+## The provenance sidecar
 
-| | Address | Notes |
+Some facts belong to the **run** (which capture, which `$01`, which video standard) rather than to
+any address, and the store has no address-keyed shape for them (D-27). They are supplied to the
+renderer as a small JSON sidecar, hand-authored from `c64-ram-capture`'s and `derive.mjs`'s own
+outputs and validated by the renderer — a missing or malformed key is a named error listing every
+problem at once, never a `<placeholder>` silently rendered into a published document.
+
+| Key | Type | Where it comes from |
 |---|---|---|
-| Live IRQ handler | | |
-| Raster positions | | one per `$D012` write on the way out of a handler |
-| NMI handler | | `$0318/$0319` or `$FFFA/$FFFB` |
-| Timebase | | `$DC0D` untouched ⇒ raster; programmed ⇒ own timebase |
+| `capturePath` | string | The path to the captured 64K image, as given to `c64-ram-capture` |
+| `captureSha256` | string, 64 hex chars | `compare.mjs digest`'s `sha256` — proves which image the map describes |
+| `port01` | string | `derive.mjs vectors`' `$01` value |
+| `dd00` | string | `derive.mjs vic`'s `--dd00` input, i.e. the observed `$DD00` |
+| `vicBank` | string | `derive.mjs vic` — VIC bank derived from `$DD00` bits 0-1, inverted |
+| `screenRam` | string | `derive.mjs vic` — screen RAM derived from `$D018` bits 4-7 |
+| `charsetOrBitmap` | string | `derive.mjs vic` — charset/bitmap derived from `$D018` bits 1-3 (note the char-ROM shadow case) |
+| `mode` | string | `derive.mjs vic` — graphics mode derived from `$D011` bits 5-6 and `$D016` bit 4 |
+| `videoStandard` | `"PAL"` or `"NTSC"` | Known from the capture's origin/hardware context |
+| `liveVectorPair` | string | `derive.mjs vectors` — the live vector pair (`$0314/$0315` or `$FFFE/$FFFF`) |
+| `vectorHandler` | string | The address the live vector pair points at, confirmed live at a checkpoint |
+| `rasterPositions` | string array, optional | One entry per observed `$D012` write on the way out of the live IRQ handler; `derive.mjs sprites` where sprite coordinates are relevant |
+
+A fully-filled example, with plausible values in place of placeholders — copy this shape, never the
+literal values:
 
-## Routines
+```json
+{
+  "capturePath": "captures/game.raw",
+  "captureSha256": "3f8a1c9e2b7d4a6f0c5e8b2d9a1f4c7e6b3d0a9c8f5e2b1d4a7c0f3e6b9d2a5c",
+  "port01": "$40",
+  "dd00": "$06",
+  "vicBank": "1 ($4000-$7FFF)",
+  "screenRam": "$0400",
+  "charsetOrBitmap": "$1000 (ROM shadow)",
+  "mode": "text, multicolor off",
+  "videoStandard": "PAL",
+  "liveVectorPair": "$FFFE/$FFFF",
+  "vectorHandler": "$1103",
+  "rasterPositions": ["$F8", "$00"]
+}
+```
 
-| Address | Provisional name | Confirmed by | Confidence |
-|---|---|---|---|
-| | `Maybe_` | | |
+## Confidence vocabulary
 
-## Open questions
+Every comment written into the store through `r2000_set_comment` that grades a finding leads with
+one of these five bracket tokens (the parser in `r2000-confidence.ts` throws on anything that is
+close but not exact — a typo never silently degrades into an ungraded comment):
+
+| Grade | Bracket token | Means |
+|---|---|---|
+| **confirmed code** | `[confirmed-code]` | Executed during tracing, PC observed inside it |
+| **probable code** | `[probable-code]` | Reachable through a `JSR`/`JMP`/vector, not yet observed executing |
+| **confirmed data** | `[confirmed-data]` | Never hit as an instruction stream across full gameplay coverage |
+| **probable data** | `[probable-data]` | Indexed-load target, or matches a data shape (sprite blocks, PETSCII, address tables) |
+| **unknown** | `[unknown]` | No reliable interpretation yet |
+
+Do not force an unknown range through a disassembler and record the output as code. A linear
+decode of data is silently wrong and contaminates everything downstream.
 
-- 
+**Do not promote a row by editing its grade.** Re-verify and restate the evidence with a fresh
+`r2000_set_comment` call, so the record of when something stopped being a guess survives.

package/skills/c64-provenance-diff/SKILL.md

@@ -231,7 +231,7 @@ addresses.
 | A verified 64K image, or proving two captures equivalent | `c64-ram-capture` |
 | Which address to read next, and what the answer rules out | `c64-program-recon` |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
-| Assembling, or a first-pass dead listing | `acme-build` |
+| Assembling | `acme-build` |
 | **Whether a byte is original, cracker-changed, or unknown** | here |
 
 Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you

package/skills/c64-ram-capture/SKILL.md

@@ -156,6 +156,11 @@ only after the provenance diff partitions loader from cracktro from game — see
 ## Find an entry point
 
 1. Press past any "hit any key" gate with `mcp__plugin_c64-re-tools_vice__vice_keyboard_matrix`.
+   **This call requires the fork backend** — the binary monitor's `KEYBOARD_FEED` only injects
+   PETSCII text into the KERNAL buffer and cannot drive the raw matrix. On stock, use
+   `vice_keyboard_type` / `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or
+   `vice_joystick_set` when it polls the matrix directly; buffer injection stays invisible to a
+   program polling `$DC00`/`$DC01` itself.
 2. Step forward in batches with `mcp__plugin_c64-re-tools_vice__vice_execution_step`, reading
    `mcp__plugin_c64-re-tools_vice__vice_registers_get` after each batch.
 3. Stop when the program counter and the stack pointer both settle into a
@@ -257,6 +262,17 @@ Capture the power-on image as the very first action against a fresh machine, the
 idle-capture twice more and run `floor` over the set. State the result as a
 floor, not a complete set — more captures can only widen it.
 
+## Feeding the memory map's provenance sidecar
+
+`c64-program-recon`'s generated memory map (`vice-mcp r2000 render-memmap`) takes a small provenance
+sidecar as input, and this skill supplies one of its fields: `scripts/compare.mjs digest`'s `sha256`
+and `size` become the sidecar's `captureSha256`, proving which image the rendered map describes. The
+sidecar's other run-scoped keys (`port01`, `dd00`, `vicBank`, `screenRam`, `charsetOrBitmap`, `mode`,
+`liveVectorPair`, `vectorHandler`, `rasterPositions`) come from `c64-program-recon`'s own
+`derive.mjs` — **this skill does not emit the sidecar itself.** The sidecar is hand-authored from
+those two skills' outputs and validated by the renderer, which throws naming every missing or
+malformed key at once rather than rendering a document that silently carries a placeholder.
+
 ## Which skill does what
 
 This one owns the image and its identity. It does not restate what the others carry.
@@ -266,7 +282,7 @@ This one owns the image and its identity. It does not restate what the others ca
 | Which address to read next, and what the answer rules out | `c64-program-recon` |
 | Every way a live read gives a wrong answer | `c64-program-recon` — `references/observation-hazards.md`. **Read before driving.** |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
-| Assembling, or a first-pass dead listing | `acme-build` |
+| Assembling | `acme-build` |
 | Whether a byte is original or cracker-changed, and what `bucketed` means | `c64-provenance-diff` |
 | Whether the emulator is wedged, and whether it is safe to recycle | `vice-wedge-triage` |
 | **A verified 64K image, or proving two captures equivalent** | here |

package/skills/vice-wedge-triage/SKILL.md

@@ -5,8 +5,9 @@ description: Decide whether a VICE emulator that has stopped responding is genui
 
 # Triage a VICE that stopped moving
 
-**Four states look identical from outside, and the intuitive fix destroys a healthy machine in
-one of them.** Work the order below. Do not start with a remedy.
+**On the fork, four states look identical from outside; on stock, it is five, and the intuitive
+fix destroys a healthy machine in more than one of them.** Work the order below. Do not start with
+a remedy.
 
 | State | Cheap tell | Safe action |
 |---|---|---|
@@ -14,14 +15,22 @@ one of them.** Work the order below. Do not start with a remedy.
 | **Stopped itself at your checkpoint** | An armed *stopping* checkpoint on the live IRQ path | Delete/disable the checkpoint. **Never recycle** |
 | **Crashed and respawned** | The proxy raises epoch drift on the next forwarded call | Void the run, reboot from scratch. Already handled for you |
 | **Genuinely wedged** | Two consecutive cycle brackets read exactly `0` | `vice_recycle` with a reason, as a last resort |
+| **Monitor held elsewhere (stock only)** | A second client already holds this instance's single binary-monitor socket | Find the other holder. **Never recycle** — the instance is healthy, just claimed elsewhere |
 
 ```
-mcp__plugin_c64-re-tools_vice__vice_diagnose        # one call, no arguments, answers which of the five it is
+mcp__plugin_c64-re-tools_vice__vice_diagnose        # one call, no arguments, answers which state it is
 ```
 
-`vice_diagnose` returns a closed five-verdict vocabulary — `restarted`, `checkpoint_trap`,
-`wedged`, `stale_read_path`, `live` — with the evidence that produced it. Read its schema for the
-contract; this skill is the judgement around it.
+`vice_diagnose`'s verdict vocabulary differs by backend, because stock VICE's binary monitor
+services exactly one client and the fork's non-pausing `vice_ping` has no stock equivalent (see
+`docs/stock-vice-parity.md` D-03 for the full reasoning). The fork answers `restarted`,
+`checkpoint_trap`, `wedged`, `stale_read_path`, `live`; stock answers `restarted`,
+`checkpoint_trap`, `wedged`, `monitor_held_elsewhere`, `live`. Read the tool's own schema for the
+exact contract on whichever backend is active — as of **07-16 (WR-07)** this instruction is
+finally sound: `tools/list`'s advertised stock schema is the corrected stock manifest entry, not
+the fork's synthetic literal it was silently overwritten by before. Stock `vice_diagnose` can also
+answer a `diagnosis_unavailable` outcome when no verdict could be established at all — that is
+**not** a sixth verdict; see the table below.
 
 ## The order
 
@@ -31,7 +40,13 @@ contract; this skill is the judgement around it.
 2. **Read the verdict, not the vibe.** Each verdict has exactly one correct response — the table
    below. A verdict is not a suggestion to try things.
 3. **`diagnose` leaves the machine paused** when it ran a bracket. Resuming is your own next call.
-   Do not treat "still paused afterwards" as a symptom.
+   Do not treat "still paused afterwards" as a symptom. Every established verdict also reports
+   `machinePaused` plus `machinePausedSource` (07-15), so you can tell an actual observation from
+   an inference: `observed` means a wire `stopped`/`resumed`/`jam` event directly reported the
+   state; `structural` means it was inferred from the fact that every stock read halts the machine
+   (D-05), not from a specific event; `no_session` means no session was ever obtained (e.g. the
+   `monitor_held_elsewhere` verdict, or a `diagnosis_unavailable` acquisition failure) so no claim
+   about pause state is being made at all.
 4. **If the verdict is `wedged`, capture evidence before recovering.** `vice_recycle` requires a
    `reason`, and that string is written verbatim into a permanent, repo-tracked incident record
    under `.planning/incidents/` **before anything is killed**. That record is the evidence
@@ -43,11 +58,52 @@ contract; this skill is the judgement around it.
 
 | Verdict | What it means | Do |
 |---|---|---|
-| `live` | Cycles advanced | Resume and carry on. Suspect your own checkpoint conditions, not the emulator |
+| `live` | Cycles advanced | Resume and carry on. Suspect your own checkpoint conditions, not the emulator — **unless `evidence.jamObserved` is true** (below) |
 | `checkpoint_trap` | The machine stopped **itself** at an armed checkpoint | `vice_checkpoint_delete` or `vice_checkpoint_toggle` it, or `vice_execution_step` past it, then re-run `diagnose`. **Recycling here destroys a healthy instance** |
 | `restarted` | The epoch changed — a crash-and-respawn already happened | The run is void. `c64-ram-capture` § Void a run gives the artifact procedure. Reboot from `vice_disk_attach` |
-| `stale_read_path` | Some reads move while others do not | Do not trust any measurement taken across the boundary. Treat as void and re-derive |
-| `wedged` | Two brackets, zero cycles, no epoch change | Last resort: `vice_recycle` with a real reason |
+| `stale_read_path` **(fork only)** | Some reads move while others do not | Do not trust any measurement taken across the boundary. Treat as void and re-derive |
+| `monitor_held_elsewhere` **(stock only)** | A different client already holds this instance's single binary-monitor slot | Release or identify the other holder. **Never a reason to recycle** — recycling here destroys an instance that is not even wedged |
+| `wedged` | Two brackets, zero cycles, no epoch change | Last resort: `vice_recycle` with a real reason — **but check `evidence.jamObserved` first** (below) |
+| `diagnosis_unavailable` **(stock only, non-verdict outcome — not one of the five)** | No verdict could be established at all; the message starts `vice_diagnose: diagnosis_unavailable (<reason>)`. The machine's state is **UNKNOWN**, not any of the five above | **Do not recycle on this answer alone.** Read the reason class in the message and act on it — see below |
+
+### `evidence.jamObserved` — read it before acting on `wedged` *or* `live` (stock only, 07-REVIEW WR-04)
+
+Every stock `vice_diagnose` verdict carries `evidence.jamObserved` (always present, never omitted).
+It is `true` once a `JAM` (0x61) event has arrived on this instance's wire — the 6510 executed an
+illegal opcode and **the CPU is dead regardless of the verdict above**. The flag latches: it stays
+true for the rest of the session.
+
+It cuts across two verdicts in opposite directions, which is exactly why it is separate evidence
+rather than a sixth verdict:
+
+| `jamaction` | What `vice_diagnose` answers | Why | What to actually do |
+|---|---|---|---|
+| `-jamaction 2` (Monitor) | `wedged` | The machine stopped, so both brackets read zero advance | **`vice_machine_reset`, not `vice_recycle`.** Recycling destroys an instance a reset recovers — the same trap as `checkpoint_trap` |
+| default (continue) | `live` | The emulator keeps burning cycles refetching the same opcode, so both brackets **advance** | **`vice_machine_reset`.** "Cycles advanced" is true and irrelevant: the machine will never execute another instruction |
+
+**`jamObserved: true` is never a reason to recycle.** A jam is recovered by a reset; the instance
+itself is healthy. Treat a `live` verdict with `jamObserved: true` as a false negative on liveness,
+and a `wedged` verdict with it as a false positive on wedging.
+
+### `diagnosis_unavailable` — reason classes and response (07-15)
+
+`diagnosis_unavailable` is what `vice_diagnose` answers, on the `isError:true` channel, when it
+could not reach any of the five verdicts above — including a CR-01-class decode failure. It is
+never added to the verdict enum and is never grounds to `vice_recycle` by itself: the message says
+so explicitly. **Every** `isError:true` answer this tool can produce carries this prefix — there is
+no unclassified no-verdict path left (07-REVIEW.md WR-02). Eight reason classes exist, each with
+its own next move:
+
+| Reason | What it means | Do |
+|---|---|---|
+| `connection_lost` | The socket died mid-session | Retry once. If it recurs, treat as a real transport problem, not a wedge |
+| `request_timeout` | The wire went silent past the request bound | Retry once. If it recurs, fall to the manual cycle bracket below |
+| `monitor_acquisition_timeout` | Another client holds the monitor and the wait bound expired | Wait for the current holder to release, then retry — this is the bounded sibling of `monitor_held_elsewhere`, not a wedge. **The abandoned acquisition is not cancelled** (07-REVIEW WR-19): a session may be established moments after this answer, so a later-appearing held session is not a ghost. Its real outcome is written to stderr |
+| `session_refused` | The broker/lease itself refused the session | Read the raw detail in the message; this is a broker-level problem, not an emulator state |
+| `protocol_decode_failure` | This build answered a frame the client cannot decode | Report it as a tool defect — check `docs/stock-vice-parity.md`'s `CPUHISTORY_GET` history for a known class of this — and fall back to the manual cycle bracket below |
+| `evidence_gathering_failed` | A session was obtained but a read needed to build the verdict failed | `vice_execution_run` may be needed to unstick a stalled read path, then retry |
+| `liveness_unmeasurable` | The liveness bracket could not be **measured at all** — no `CPUHISTORY_GET` (needs VICE ≥ 3.10) and no `LIN`/`CYC` enumerated. **The expected outcome on a stock 3.9-class build**, e.g. every current Debian/Ubuntu package | **Not a wedge and not a tool defect.** A bracket that cannot measure is not one that measured zero. Judge liveness from outside the monitor (screenshot, process state), or use the fork backend. Retrying will produce the same answer |
+| `unknown` | None of the above classified the failure | Read the raw detail in the message; retry once before escalating |
 
 ## What is not recoverable
 
@@ -72,10 +128,53 @@ at a checkpoint — VICE's flag flips before the trap fires. Checkpoint bookkeep
 (`vice_checkpoint_add`/`list`/`delete`) also keeps returning healthy, self-consistent responses
 throughout a real wedge, so "the tools respond" proves nothing.
 
-**A `vice_run_until` on an address that is never reached looks exactly like a wedge.** Its `cycles`
-parameter is documented in its own schema as *"not yet implemented"*, so there is no working
-timeout to bound it. Before concluding anything, check whether you asked the machine to run to an
-address it cannot reach. **Confidence: MEDIUM** — read off the tool schema, not reproduced.
+**A `vice_run_until` on an address that is never reached looks exactly like a wedge — on the fork,
+still without a bound.** Its `cycles` parameter is *"not yet implemented"* on both backends, and the
+fork has no timeout to bound the wait for an address either — an unreachable address there is
+unbounded and indistinguishable from a wedge. **On stock, passing `cycles` is now REFUSED rather
+than ignored** (07-REVIEW WR-18) — including alongside `address`, where it used to be silently
+dropped while the answer still reported `reached: true`. Unexpected argument names are refused by
+name too, so a `timeoutMs`/`timeout_ms` typo can no longer run with the default bound in silence.
+**On stock, this is now bounded (D-02):** pass `timeout_ms` (default 30000, clamped to a ceiling of
+600000); an unreachable address returns an explicit, bounded `timedOut: true` answer — with the
+temporary checkpoint already cleaned up — rather than looking like a wedge. **Two further
+behaviours (07-14, closing WR-01/WR-02):** every non-error answer, hit or timeout, carries
+`machineHalted` plus a `machineHaltedNote` naming the resume call — the tool halts the machine on
+every read and says so explicitly. **`machineHalted` is `true` on a hit and on a timeout whose
+cleanup delete was answered (`cleanup: "deleted"` / `"already_gone"`); it is `false` when
+`cleanup: "delete_failed"` or the socket is already gone** and the run-state projection does not
+say `"stopped"`. **Do not read `machineHalted: false` as "still running"** — it means nothing here
+could establish the state, `machineHaltedNote` says so, and the next call should be
+`vice_diagnose`, not `vice_execution_run` (which may not reach the instance at all). And a timeout whose cleanup
+delete lands on an already-gone race no longer asserts `reached: false` outright: it reads the
+program counter and resolves the race (`raceResolved: "pc_at_address"` / `"pc_elsewhere"`), or, if
+the PC read itself fails, omits `reached` entirely and reports `reachedUnknown: true`
+(`raceResolved: "unresolved"`). **An absent `reached` is not "false"** — check `reachedUnknown`
+before assuming a miss. The underlying judgement is unchanged and still the right first question on
+either backend: before concluding anything, check whether you asked the machine to run to an
+address it cannot reach. **Confidence: HIGH on stock for the reach/timeout mechanism** —
+live-confirmed against genuine, unmodified `/usr/bin/x64sc` (VICE 3.9) and `/usr/local/bin/x64sc`
+(VICE 3.10): a real KERNAL address ($EA31) reached within its timeout, an unreached one ($C000)
+timing out with the checkpoint deleted (07-10's live pass). **MEDIUM for the WR-01/WR-02 honesty
+fields above** — unit-proven (`stock-run-until.test.ts`, 21/21, 07-14) but not independently
+re-exercised against a real emulator by this gap-closure batch. **MEDIUM on the fork** — read off
+the tool schema, not reproduced.
+
+**A second binary-monitor client is contention, not a wedge, and it has a cheap tell — stock
+only.** Stock VICE's binary monitor services exactly one client; a second `connect()` sits
+unserviced in the backlog with no reply and no EOF. The discriminator: a socket that *accepts* the
+connection but never answers is contention, not a hung emulator — and the broker itself already
+knows whether it holds a lease on that port, which is the thing a human or agent can actually go
+check instead of guessing. Named causes, so a reader knows where to look: a hand-run `nc` session
+left open against the port, a second Claude Code session driving the same instance, VICE's own
+`-remotemonitor`, and any other 6502 debugger that dials in — including regenerator2000's own
+`--vice` flag. **This plugin's own regenerator2000 route can never be one of them:** the launch
+path refuses `--vice` by construction (no caller-supplied argv passthrough exists to inject it in
+the first place) *and* by a scan that throws if the flag is ever present in the final argv — not by
+documentation alone (`R2000-01`, plan 10-01) — so a user chasing a silent emulator can rule this
+project's own r2000 integration out immediately, rather than suspecting it. The standing advice
+does not change: contention is **never** a reason to recycle — the instance is healthy, merely
+claimed elsewhere.
 
 ## The manual fallback, when `vice_diagnose` cannot answer
 
@@ -84,7 +183,7 @@ exists, that is a **host action for a human** — say so and stop. Nothing conta
 the emulator by another route.
 
 When the broker is up but you want the raw measurement, the cycle bracket is the only trustworthy
-liveness test, and it is four calls:
+liveness test. **On the fork**, it is four calls:
 
 1. `vice_cycles_stopwatch` `{action: "reset"}`
 2. `vice_execution_run`
@@ -96,6 +195,18 @@ liveness test, and it is four calls:
 thing — merely slow, a separate documented hazard measured at ~6,000/s when a loop polls without
 re-resuming. Read all state first, poll with `vice_ping`, resume exactly once at the end.
 
+**On stock, there is no non-pausing call at all — any inbound byte halts the machine — so the
+`vice_ping` ×3 poll measures nothing there and is fork-only.** The stock equivalent is the same
+bracket shape with zero calls during the wait:
+
+1. `vice_cycles_stopwatch` `{action: "reset"}`
+2. `vice_execution_run`
+3. A real wall-clock wait, with **no calls at all** during it
+4. `vice_cycles_stopwatch` `{action: "read"}`
+
+`vice_diagnose` already runs exactly this bracket internally on stock, so the manual fallback above
+is only for when the broker itself is unreachable and `vice_diagnose` cannot be called at all.
+
 **Enumerate your own checkpoints before running any bracket.** `vice_checkpoint_list`, then
 resolve the live IRQ handler (`$0314/$0315`, or `$FFFE/$FFFF` when `$01` has the ROMs banked out).
 An armed stopping checkpoint at or inside the live IRQ path, with the PC pinned at or just past
@@ -114,7 +225,8 @@ session, the last three all on that call).
 | Checkpoint delete / reset / step can all fail to recover | One recorded incident, all four attempts in sequence | HIGH, single incident |
 | A checkpoint trap explains all three recorded "silent stalls" | Cross-read, 3/3 correlation, mechanism consistent with every symptom — **not reproduced** | MEDIUM |
 | `vice_diagnose`'s five-verdict path behaves as its schema says | Schema read, and cross-checked against the tracked implementation's own report builders. **Not exercised end to end** | MEDIUM |
-| `vice_run_until` has no working timeout | Its schema says `cycles` is "not yet implemented" | MEDIUM |
+| `vice_run_until` has no working timeout **(fork only)** | Its schema says `cycles` is "not yet implemented"; the fork has no `timeout_ms` bound | MEDIUM |
+| Stock's five-verdict path (`restarted`, `checkpoint_trap`, `wedged`, `monitor_held_elsewhere`, `live`) and its bounded `vice_run_until` | Unit-proven (40/40 `stock-diagnose.test.ts`, 21/21 `stock-run-until.test.ts`, 07-15/07-14). **Live-proven** against genuine `/usr/bin/x64sc` (VICE 3.9) and `/usr/local/bin/x64sc` (VICE 3.10) for `live` (07-10), `checkpoint_trap`, `wedged` (confirmed on both capability routes — `frame_position` on 3.9, `cpu_history` on 3.10) and `restarted` (07-17). `monitor_held_elsewhere`'s **socket-level** contention bound is live-proven (07-13, ~1501-1502ms against a 1500ms bound). **UPDATED 2026-08-18 (quick task 260818-obc, `stock-live-broker-monitor.test.ts`, command `VICE_LIVE_BROKER_BIN=/usr/bin/x64sc` (or `/usr/local/bin/x64sc`) `node --test stock-live-broker-monitor.test.ts`):** both remaining unit-only residuals are now ALSO live-proven, on both binaries, in one real run — the **broker-mediated** `monitor_held_elsewhere` verdict (a real second `claimMonitor()` refusal from a genuine host broker daemon, naming the other real grant's id, settling in 1ms against the 10000ms bound) and the **broker-supervised** (not test-performed) `restarted` respawn (the host broker's OWN crash supervision relaunched the killed instance; `vice_diagnose` answered `restarted` with `baselineEpoch:1`/`currentEpoch:2` at zero-to-minimal emulator cost). `vice_run_until`'s reach/timeout mechanism is live-proven against both binaries (07-10); its WR-01/WR-02 honesty fields (`machineHalted`, `raceResolved`, `reachedUnknown`) remain unit-proven only (07-14) — NOT re-exercised live by this task, no blanket claim made here | HIGH for the five verdicts (including both the broker-mediated `monitor_held_elsewhere` path and the broker-supervised `restarted` path, both now live-proven) and the run_until reach/timeout mechanism; MEDIUM for the run_until honesty fields only, which stay unit-only |
 
 Full provenance in `.planning/RE-FINDINGS.md`. **Log a new incident there at the moment you hit
 it**, graded with `Evidence:` and `Confidence:`; promote by re-logging, never by editing a grade.
@@ -146,4 +258,5 @@ others carry.
 | Zero cycles, nothing armed, epoch unchanged | A wedge. `vice_recycle` with a reason that names the evidence |
 | A run "survived a reset" | Distrust it. You cannot read the epoch to confirm — but an unintended respawn inside the bracket would have raised a drift error on the next forwarded call, so absence of that error is the only evidence available |
 | `vice_recycle` refused for a missing reason | It is required, by design — the reason *is* the incident record |
+| `vice_diagnose` answers `monitor_held_elsewhere`, or a call hangs with no reply and no EOF (stock only) | Not a wedge. Find the other client holding this instance's single binary-monitor slot |
 </content>