@henols/c64-re-tools 0.2.0 → 0.2.2

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

@@ -1,62 +1,97 @@
-# 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 `anno_*` 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 anno render-memmap game.annostore --provenance sidecar.json
+node <plugin-root>/src/mcp/vice/vice-proxy.ts anno render-memmap game.annostore --provenance sidecar.json
+```
+
+Add `--check` to compare the rendered file on disk against a fresh render — it exits non-zero and
+prints the first differing line. Drift is reported when, and only when, one of these changed: the
+rendered file itself (a hand edit); a store row (a range, a label, a comment, or a comment's
+confidence grade); the provenance sidecar's bytes; the location of the store or the sidecar
+**relative to the workspace root**; or the renderer. **Relocating the checkout is not drift** — the
+same tree at a different absolute path renders the same bytes, because the banner records
+workspace-relative locations rather than absolute ones.
+
+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). That remedy is safe to
+follow on any machine — because the banner records workspace-relative locations, re-running in a
+different checkout or in a worktree does not rewrite the file with that machine's absolute paths.
+The generated file carries a banner naming the store, the sidecar and a content digest — do not
+strip it.
+
+**One-time drift after upgrading, 2026-08-30.** A memory map rendered *before* 2026-08-30 will
+report `drifted` on its first `--check` after this change, exactly once: the banner's `store:` and
+`sidecar:` lines moved from absolute to workspace-relative spellings. Re-run the generator once and
+commit the new banner, after which the file is stable across machines and worktrees. This is a
+one-time, self-clearing banner correction — not a bug, and not a migration.
 
-Character ROM shadow checked: <yes/no — CB in `$1000`/`$9000` of bank 0/2 means no charset in RAM>
+## The provenance sidecar
 
-## Interrupts
+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.
 
-| | Address | Notes |
+| 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 |
 
-## Routines
+A fully-filled example, with plausible values in place of placeholders — copy this shape, never the
+literal values:
 
-| Address | Provisional name | Confirmed by | Confidence |
-|---|---|---|---|
-| | `Maybe_` | | |
+```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"]
+}
+```
 
-## Open questions
+## Confidence vocabulary
+
+Every comment written into the store through `anno_set_comment` that grades a finding leads with
+one of these five bracket tokens (the parser in `anno-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
+`anno_set_comment` call, so the record of when something stopped being a guess survives.

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

@@ -15,7 +15,7 @@ either proves its own precondition or refuses to emit.
 `ledger` will not write a verdict the earlier stages did not earn.
 
 ```bash
-D=.claude/skills/c64-provenance-diff/scripts/diff-images.mjs   # from the repo root
+D=src/skills/c64-provenance-diff/scripts/diff-images.mjs   # from the repo root
 
 node $D anchor-search                        # 1. prove the per-release offset  [WRITES]
 node $D diff                                 # 2. N-way byte diff at that offset
@@ -25,7 +25,7 @@ node $D ledger                                # 4. regenerate recovery/PROVENANC
 node $D diff --json                          # machine-readable, with per-range reasons
 node $D diff --gap-tolerance 16              # coalescing width (default shown)
 node $D anchor-search --reference <id>       # pick the reference release
-node .claude/skills/c64-provenance-diff/scripts/releases.mjs list                 # the release ids in play
+node src/skills/c64-provenance-diff/scripts/releases.mjs list                 # the release ids in play
 ```
 
 Pure Node over committed files — the `.bin` dumps, their `.map.json` manifests, and
@@ -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
@@ -254,4 +254,4 @@ through a GSD command (`/gsd-quick`).
 | A range's `kind` looks wrong past its start | You resolved `kind` from `start`. Use `splitRangeByManifestKind`; coalescing does not respect kind boundaries. |
 | A loader range disagrees with `NOTES.md` | `RELEASES.json`'s `loader_ranges` wins — it is earned from disassembly. Prose is how `$08F5` got misclassified. |
 | Title-screen text shows up as cracktro | You used a bare printable-run scan. The vocabulary scan exists because `$4771-$4779` is the game's own text. |
-| `unknown release "x" -- known releases: …` | `node .claude/skills/c64-provenance-diff/scripts/releases.mjs list` for the valid ids. |
+| `unknown release "x" -- known releases: …` | `node src/skills/c64-provenance-diff/scripts/releases.mjs list` for the valid ids. |

package/skills/c64-provenance-diff/scripts/diff-images.mjs

@@ -693,6 +693,9 @@ export function renderLedger({ generatedRanges, gapTolerance, prose }) {
     throw new Error(`renderLedger: refusing to emit -- generated tier stops at ${hex4(expected - 1)}, does not reach $FFFF`);
   }
 
+  // NOTE (plans 16-01, 16-10): the embedded invocation path below is deliberately the
+  // CONSUMER's installed location (`.claude/skills/...`), not this repository's
+  // source-tree location (`src/skills/...`) -- pinned by diff-images.test.mjs and skill-consumer-paths.test.ts (16-REVIEW.md CR-01).
   let generated = `<!-- GENERATED, DO NOT HAND-EDIT. Regenerate with: node .claude/skills/c64-provenance-diff/scripts/diff-images.mjs ledger --gap-tolerance ${gapTolerance} -->\n\n`;
   generated += `| Start | End | Kind | Verdict | Confidence | Agreeing releases | Evidence / Reason |\n`;
   generated += `|---|---|---|---|---|---|---|\n`;

package/skills/c64-provenance-diff/scripts/recovery-schema.mjs

@@ -25,17 +25,27 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = projectRoot();
 const RECOVERY_DIR = dataRoot();
 const DISKS_DIR = disksRoot();
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
 // The parameterisation gate must cover EVERY module of the recovery pipeline, not
 // just the ones sitting next to this file. When the six modules moved out of
 // `tools/` into the two skills that use them (2026-08-04), a `HERE`-only scan
 // silently stopped covering `d64-parse.mjs` and `dump-artifacts.mjs` -- a static
 // guard that keeps passing while checking less is worse than one that fails.
+// 2026-08-22 (plan 16-01): the second entry used to be built project-root-relative,
+// naming the skills tree's pre-relocation auto-discovery location by hand -- which
+// stopped resolving the moment the skills tree moved to its current source-tree
+// location. Rebuilt `HERE`-relative instead -- correct in both this dev checkout
+// and a consumer's install, since a sibling skill's `scripts/` directory is always
+// one level up and back down from this file's own location either way.
 const SCAN_DIRS = [
-  HERE, // .claude/skills/c64-provenance-diff/scripts
-  resolve(REPO_ROOT, ".claude", "skills", "c64-ram-capture", "scripts"),
+  HERE, // src/skills/c64-provenance-diff/scripts
+  resolve(HERE, "..", "..", "c64-ram-capture", "scripts"),
 ];
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+for (const dir of SCAN_DIRS) {
+  if (!existsSync(dir)) die(`SCAN_DIRS entry does not exist: ${dir} -- a guard that keeps passing while checking less is worse than one that fails`);
+}
 
 function sha256File(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");

package/skills/c64-ram-capture/RELEASES.json.example

@@ -0,0 +1,17 @@
+{
+  "schema_version": "1.0",
+  "schema_notes": "Adding a release is one releases[] entry plus one invocation of tools/recover.mjs -- see c64-ram-capture/SKILL.md '## Release registry shape'.",
+  "releases": [
+    {
+      "id": "example-release",
+      "canonical": true,
+      "disk_image": "disks/example-release.d64",
+      "dumps": [
+        {
+          "label": "example-label",
+          "range_manifest": "recovery/example-release/dumps/example-release-example-label.map.json"
+        }
+      ]
+    }
+  ]
+}

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

@@ -14,7 +14,7 @@ failure and it is invisible in a hex dump. Two committed modules do that byte wo
 and name the offending address when it is wrong.
 
 ```bash
-S=.claude/skills/c64-ram-capture/scripts    # from the repo root
+S=src/skills/c64-ram-capture/scripts    # from the repo root
 P=$S/d64-parse.mjs   A=$S/dump-artifacts.mjs
 C=$S/compare.mjs     L=$S/releases.mjs
 
@@ -33,6 +33,12 @@ node $C floor   a.bin b.bin c.bin                # drift floor across a capture
 All three modules read only committed files and the JSON **you** wrote from your
 own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
 
+**Prerequisite: a resolvable project root.** `scripts/project-paths.mjs` uses
+`C64RE_PROJECT_ROOT` when it is set, and otherwise walks up from the toolkit's
+own location for the nearest ancestor directory containing a `.git` entry. A
+scratch project has neither by default, so `git init` it first or set the
+variable — the thrown error names both when this fails.
+
 ## The order
 
 | # | Phase | Settles |
@@ -78,6 +84,9 @@ directory chain that leaves the image or loops, reported instead of hanging.
 3. `mcp__plugin_c64-re-tools_vice__vice_execution_run`.
 4. `mcp__plugin_c64-re-tools_vice__vice_registers_get` and confirm the program counter has moved.
 
+The broker sets the drive type at launch for every stock instance, so no drive setup
+is needed before attaching.
+
 If the program counter has not moved, type `LOAD"*",8,1` with
 `mcp__plugin_c64-re-tools_vice__vice_keyboard_type`, run it, then type `RUN` and run it.
 
@@ -262,6 +271,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 anno 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.
@@ -271,11 +291,33 @@ 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 |
 
+## Release registry shape
+
+`scripts/releases.mjs` is the only module that reads a release id out of the
+registry — every other module takes the id as an argument. Its shape:
+
+| Field | Level | Required | For |
+|---|---|---|---|
+| `schema_version` | top-level | — | The registry format version. |
+| `schema_notes` | top-level | — | Free-text stating the registry's N-readiness claim (`node $L schema-notes`). |
+| `releases` | top-level | yes | The array of release entries below. |
+| `id` | per-release | yes | The `--release` argument every other script takes. |
+| `canonical` | per-release | — | A boolean on one entry, not "the canonical image" — there are N releases. |
+| `disk_image` | per-release | yes | Project-relative path to the release's `.d64`. |
+| `dumps` | per-release | **yes, as an array** | Per-capture records written by `write-set`. **Must be an array, never omitted** — `releases.mjs`'s `list` command reads `r.dumps.length` with no guard (`releases.mjs:98`), so a missing `dumps` throws `TypeError: Cannot read properties of undefined` instead of listing anything. An empty array (`[]`) is fine; an absent key is not. `releases.mjs` itself imposes no per-entry shape; `scripts/watch-loads.mjs` (a different reader) looks up an entry by `label` and reads its `range_manifest`, which the example below follows. |
+
+The registry lives at `<project root>/recovery/RELEASES.json` by default —
+override the whole path with `C64RE_REGISTRY`, or just the containing
+directory with `C64RE_DATA_DIR`.
+
+`src/skills/c64-ram-capture/RELEASES.json.example` is a copyable starting
+point with every field above populated with placeholder values.
+
 ## References
 
 What this skill ships, and the committed modules it leans on. No `references/`
@@ -287,6 +329,7 @@ split: the workflow fits in one file, which is the right call when it does.
 | `templates/capture-record.template.md` | The per-capture record: identity, machine state read in the same paused window, the void checklist, and the per-pairing comparison table. |
 | `scripts/d64-parse.mjs` | `.d64` directory, BAM, and `--json` fakery detection. Fixture-tested against both real images by `scripts/d64-parse.test.mjs`. |
 | `scripts/dump-artifacts.mjs` | `assemble` / `chip-state` / `manifest` / `write-set` — the guarded byte work, and the source of every `assembleImage:` message in the table below. |
+| `RELEASES.json.example` | A copyable release-registry shape — see `## Release registry shape` above. |
 
 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
@@ -309,3 +352,4 @@ through a GSD command (`/gsd-quick`).
 | `--limit 0` printed nothing | Fixed 2026-08-04 — it now means unlimited. Re-pull the script if you see the old behaviour. |
 | An epoch-drift error appeared mid-capture | The machine restarted under you. Void the run; do not salvage the artifacts. The next call succeeding does not undo it. |
 | The emulator looks dead | `vice-wedge-triage` — and enumerate your own armed checkpoints before concluding anything. |
+| `` `project-paths: could not locate the project root -- no `.git` found above ...` `` | No `.git` ancestor and no `C64RE_PROJECT_ROOT`. `git init` the project, or set the variable to its root. |

package/skills/c64-ram-capture/scripts/project-paths.mjs

@@ -6,7 +6,7 @@
 //
 //   1. The project root is found by walking UP for a `.git` marker. Counting
 //      hops from `import.meta.url` breaks the moment the toolkit is installed
-//      somewhere other than `.claude/skills/<skill>/scripts/`, and it breaks
+//      somewhere other than `src/skills/<skill>/scripts/`, and it breaks
 //      silently -- paths resolve to a plausible wrong place rather than erroring.
 //   2. Every data location is overridable by environment variable, so a project
 //      that does not use this repo's `recovery/` + `disks/` layout can point the

package/skills/c64-ram-capture/scripts/watch-loads.mjs

@@ -445,6 +445,12 @@ function renderReleaseSection(id, log) {
  * string templating over already-fetched data -- nothing here reads a file
  * or contacts anything; the CLI `render` verb below is what reads the
  * hit-log files and writes the result.
+ *
+ * The two script paths named in the output below are deliberately the
+ * consumer's installed location, not this repository's source tree -- this
+ * string is written into a `recovery/LOADING.md` a consumer keeps. Plan
+ * 16-04's blanket sweep rewrote them once (16-REVIEW.md CR-01 class); pinned
+ * by the test below plus the class-level registry in skill-consumer-paths.test.ts.
  */
 export function renderLoading(entries) {
   let out = "# `recovery/LOADING.md` -- the on-demand-load detection record\n\n";

package/skills/routine-queue-walker/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: routine-queue-walker
+description: Drive an existing C64 annotation store's backlog of undocumented routines and auto-named symbols to closure — build the candidate queue from labels and comments, work it one entry at a time against explicit addresses, rebuild it after every pass, and report every leftover. Use when asked to annotate every remaining routine in a project, document all undocumented subroutines left in an annotation project, rename the leftover auto-generated labels, clear a backlog of unnamed symbols, drive an annotation pass to completion, or list what is still unannotated after a pass.
+---
+
+# Walking the routine and symbol queue to closure
+
+**Do not start annotating whatever is in front of you.** The expensive failure
+here is not slow work — it is a pass that *looks* finished while a hundred
+`p_XXXX` labels are still nameless and nobody wrote down which ones. Build the
+queue first, from data, then walk it to the end.
+
+This playbook assumes block classification has already happened and an
+annotation store already exists. If you do not yet know what the program is —
+where it starts, which vector is live, which regions are code — stop and run
+`c64-program-recon` first. That skill answers *what is this program*; this one
+answers *what is still undocumented in it, and how do I finish*.
+
+## The one rule that makes this different from upstream's version
+
+**Work the queue one entry at a time.** Not as a throughput compromise — as an
+accurate model of the store underneath. One `.annostore` is one writer: every
+mutating call opens it, commits and closes inside the call, and every one of
+them accepts an optional `base_revision` compare-and-swap that REFUSES a write
+computed against a revision the store has already moved past. Fanning several
+writers at one store therefore buys **zero** extra throughput and costs
+correctness: the losers come back as named stale-revision refusals you then
+have to re-derive and replay. Reading fan-out — several agents *thinking* over
+already-fetched answers — is fine, and its value is reasoning bandwidth, never
+I/O.
+
+**Every call names its own store.** There is no ambient "current store" on this
+surface: pass `store` (a `.annostore` path) on every call, and pass `image` as
+well on every call that derives its answer from the program's bytes rather than
+from the annotations — `anno_get_binary_info`, `anno_read_region`,
+`anno_disassemble`, `anno_get_cross_references`, `anno_search` and
+`anno_get_address_details`. The store holds annotations and never bytes, so an
+omitted image would read as a plausible success against whatever was recorded
+last.
+
+## Phase 0 — context, and the packed-binary gate
+
+1. Call `anno_get_binary_info`. Keep `origin`, `size`, `system`, `filename`,
+   `description` and `may_contain_undocumented_opcodes` — every later step
+   quotes them.
+2. Read the returned `entropy` against the threshold of **7.5** carried in that
+   tool's own description. At or above it, the bytes are very likely packed.
+3. If the binary looks packed, **stop and say so.** Do not annotate a packed
+   image: you would be documenting a decruncher, and every label you write is
+   thrown away the moment the real image is recovered. This project's route to
+   an unpacked image is `c64-ram-capture` — run the program in the emulator and
+   capture RAM at a checkpoint past the decrunch — plus the packer-identity
+   finding in `c64-program-recon`, which names the packer when an oracle can.
+   Come back with the captured image and start again at Phase 0.
+
+Upstream's in-place `unpack_binary` step is deliberately not carried: it is
+destructive (it clears the comments, labels and blocks already in the store)
+and this project has a non-destructive route to the same answer.
+
+## Phase 1 — make sure blocks are classified
+
+Region classification is a prerequisite for everything below: a routine
+candidate is only meaningful once the bytes around it are known to be code.
+
+1. Follow `src/skills/c64-memory-mapping/SKILL.md` for the classification pass
+   and for what each region type means.
+2. Do that pass yourself, in one sitting. It is a single long walk over the
+   whole binary, not a queue of independent items.
+
+## Phase 2 — the routine queue
+
+### 2.1 Build the candidate list
+
+A routine counts as **already documented** when its entry address carries a
+line comment. That is the only test; do not guess from the label name.
+
+1. Call `anno_get_symbols` for all labels — user, system and external, with
+   an explicit `max_results` above the program's label count (`max_results` is
+   REQUIRED on this surface and has no default, so a truncated answer is always
+   a ceiling you chose). Keep the answer; Phase 3 reuses it.
+2. Call `anno_get_comments`, again with an explicit `max_results`. Keep that
+   too — the true match count rides beside the list, so truncation is a fact
+   you are told rather than one you infer.
+3. Keep a label as a routine candidate when any of these holds:
+   - its name starts with `s_` (an auto-generated subroutine label);
+   - it sits in a code region and is the target of at least one `JSR`
+     cross-reference (`anno_get_cross_references`);
+   - it is a `p_XXXX` label sitting **inside a code region**. These come from
+     split lo/hi immediate loads and from address tables, and they are almost
+     always chained raster-IRQ handlers, hardware- or shadow-vector handlers,
+     or jump-table and callback targets. Treat every one of them as a
+     candidate rather than pattern-matching specific vector addresses;
+   - it is the label named exactly `start`.
+4. Drop every candidate that already carries a line comment.
+5. What is left is the routine queue.
+6. **Order it with `start` first** when `start` is in it. The entry point sets
+   the context every other routine is read against.
+
+### 2.2 Walk it
+
+- **Always work from an explicit address** — `$XXXX`, or the decimal
+  equivalent. Never from "wherever we are"; there is no editor cursor in this
+  project's route, and upstream's own text forbids relying on one anyway. Read
+  the routine's bytes with `anno_read_region` over the explicit range.
+- Take **one** entry at a time, to completion, before starting the next.
+- For each entry, do the full job: rename the label (`anno_set_label_name`),
+  add a header line comment describing what the routine does and what it
+  leaves in the registers and memory, add side comments on the instructions
+  that carry the meaning (`anno_set_comment`), and record anything you are
+  unsure about rather than smoothing it over.
+- Record per entry: the address, the old label, the new label, a one-line
+  summary, and any uncertainty. That record is the report in Phase 4.
+
+### 2.3 Refresh point
+
+When the queue is empty, read the store's revision with `anno_save_project`.
+**It performs no write, and it exists to say so:** every mutating verb on this
+surface has already committed and fsynced its own write by the time it
+returned, so there is nothing for an explicit save to flush. Record the
+revision — it is the checkpoint this pass is measured from, and the
+`base_revision` a later compare-and-swap write would quote. Everything after
+this point re-reads the store, because Phase 2 has just changed the label names
+Phase 3 filters on.
+
+## Phase 3 — the symbol queue
+
+### 3.1 Build the candidate list
+
+A symbol counts as **already documented** when it has a name a human chose, or
+when it is a well-known system address (hardware register, KERNAL entry point,
+OS variable).
+
+1. Call `anno_get_symbols` **again** — Phase 2 renamed things.
+2. Keep every label whose name still matches an auto-generated pattern:
+   `zpp_XX`, `zpf_XX`, `zpa_XX` in the zero page; `p_XXXX`, `f_XXXX`, `a_XXXX`
+   and `e_XXXX` outside it.
+3. Exclude: `s_XXXX` (Phase 2 handled those), `b_XXXX` (branch targets, not
+   data symbols), and any `p_XXXX` inside a code region (also Phase 2's).
+4. What is left is the symbol queue.
+
+### 3.2 Walk it
+
+Same discipline as Phase 2: explicit address, one entry at a time, to
+completion. For each symbol, use `anno_get_cross_references` to find who
+touches it — a symbol's meaning is what its callers do with it — then rename it
+and comment it. Classify it plainly: flag, counter, pointer, state variable,
+buffer, table.
+
+**No premature halting.** The symbol queue is routinely far larger than the
+routine queue — fifty, a hundred entries is normal. Do not truncate it, do not
+skip "secondary" symbols, and do not stop early because it is long. Feeding the
+whole queue through is the job. Stopping early and labelling the remainder
+"skipped for review" is a failed pass, not a completed one — unless the
+remainder is reported explicitly, in full, under Phase 4's leftovers table.
+
+For naming conventions and for what any given hardware or KERNAL address
+means, follow `src/skills/c64-memory-mapping/SKILL.md` rather than guessing.
+
+### 3.3 Refresh point
+
+Read the revision again with `anno_save_project` and record it. No write is
+performed; the writes already landed.
+
+## Phase 4 — save and report
+
+1. Read the revision one last time with `anno_save_project` and quote it in
+   the report, so the pass is attributable to an exact store state.
+2. Write the report. Four sections, all of them required:
+
+**Regions.** How many regions are classified, grouped by type, plus anything
+notable — text at a fixed address, a jump table, a sprite block.
+
+**Routines.**
+
+| Address | Old label | New label | What it does |
+| ------- | --------- | --------- | ------------ |
+| `$C000` | `s_C000`  | `init_screen` | Clears screen RAM, sets the border colour |
+
+**Symbols.**
+
+| Address | Old label | New label | Classification |
+| ------- | --------- | --------- | -------------- |
+| `$02`   | `zpp_02`  | `ptr_screen` | Zero-page indirect pointer |
+
+**Leftovers — uncertain, skipped, or still unannotated.** This section is not
+optional and it is not allowed to be empty when the queues were not emptied.
+List every routine and every symbol that was left undone, with its address and
+the reason. Never report "no uncertain areas" or "nothing left" while a single
+`f_XXXX` or `a_XXXX` label is still auto-named or a queued routine is still
+uncommented — those must be listed by name for a human to pick up.
+
+## Phase 5 — measure the pass instead of asserting it finished
+
+A report that says "all routines documented" is a claim about the report, not
+about the program. Measure it. From the repository root:
+
+```
+node src/mcp/vice/vice-proxy.ts anno coverage game.prg --store game.annostore
+```
+
+**`--store` is REQUIRED and is a second path, not a spelling of the first.**
+`<program>` supplies the payload bytes and the load origin; `--store` names the
+annotation store holding the labels, comments and typed ranges. The store holds
+annotations and never bytes, so the verb refuses to guess either path from the
+other.
+
+**Dated note, 2026-08-30 — the positional is a program IMAGE, and the command
+above is now correct against the shipped verb.** `<program>` is a `.prg` (a
+2-byte little-endian load address followed by the payload) or an
+**exactly-65536-byte** flat capture with a `.raw` or `.bin` extension — the two
+forms every other verb and tool on this surface already reads, and the two
+`c64-ram-capture` produces. The intermediate project-file format this verb
+previously required has **no producer left in this repo**; it is still accepted
+so an existing project file keeps working, but nothing here writes one, so do
+not go looking for a step that produces it.
+
+Dispatch is by **file extension first, length second**. A short flat capture is
+therefore refused by name — `a flat 64K capture must be exactly 65536 bytes` —
+rather than misread as a `.prg` whose first two payload bytes become the load
+address. If you get that refusal, the capture is truncated; re-capture it, do
+not rename it.
+
+Add `--out coverage.json` to keep the machine-readable report, `--force` to
+overwrite one, and `--sample N` to widen the reproducibility sample. The verb
+reads the same store every call in this playbook writes to, and exits **0 even
+when the numbers are bad** — a low measurement is a result, not a failure.
+Non-zero means a caller error, an image it could not read, or a store it could
+not read at all.
+
+**Run it three times:** once before Phase 2, so the pass has a starting point
+to be compared against; once at Phase 2.3's refresh point; and once at the end,
+after Phase 4's final save. The last run is what goes in the report.
+
+**Read the three numbers against each other. Never quote one of them alone.**
+There is deliberately no single "percent documented" figure, because one
+combined number lets a weak measure hide behind a strong one and makes the
+claim unfalsifiable:
+
+- **A high user fraction beside a large unreached count means the wrong things
+  were named.** Every label got a human name, but most of the image was never
+  reached by the descent walk from any seed — the queue was worked over the
+  easily-visible part of the program and the rest was never entered. Go back to
+  Phase 0 and find more entry points (chained IRQ vectors, dispatch tables),
+  not more labels.
+- **A large divergence means the store and the bytes disagree about what is
+  code.** Bytes the census reached as instructions that the store does not call
+  `Code` are places where Phase 1's classification is behind the actual control
+  flow. The reverse direction (the store calls it `Code`, the census never
+  reached it) is ordinary on an image with unreachable filler — read it, do not
+  chase it.
+- **A low distinct-comment ratio means the comments are filler.** Fifty
+  addresses carrying the same sentence counts once, not fifty times. That is
+  the number that catches a pass which renamed everything and explained
+  nothing.
+
+Anything the per-measure findings list names belongs in Phase 4's leftovers
+table, by address. A finding is a named defect in one named measure — it is
+never a rating, and there is no number to report as "the coverage".
+
+## When something fails
+
+- A failed call is not a reason to drop a queue entry. Log the address, the
+  call and the error, put the entry back on the queue, and carry on with the
+  next one. Report every one of those in the leftovers table.
+- A refused write is not silent and must not be treated as one. A
+  stale-revision refusal (a `base_revision` that the store has moved past), an
+  illegal label name, or a scope that overlaps an existing one all come back
+  REFUSED and named, with nothing written. Re-read, re-derive and replay that
+  one entry; never widen the range or drop the `base_revision` to make the
+  refusal go away.
+- Never invent an answer to make a queue entry go away. An honest "this looks
+  like a table, callers unclear" in the leftovers table is worth more than a
+  confident wrong label that the next reader has to un-learn.