@henols/c64-re-tools 0.2.4 → 1.0.0

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

@@ -1,7 +1,7 @@
 # Hazards: how observing a running C64 gives you the wrong answer
 
 The entries here are graded higher than the method files, because most were established live on
-this project at real cost. A wrong answer from a register table is cheap; a wrong answer from a
+this project at real cost. A wrong answer from a register table is cheap. A wrong answer from a
 machine that changed *because you looked at it* discredits a whole session without announcing
 itself.
 
@@ -78,18 +78,18 @@ Reading one while the game runs steals the event the game was about to service.
 
 Prefer the whole-chip reads — `vice_vicii_get_state`, `vice_cia_get_state`, `vice_sid_get_state`
 — 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.
+**unverified**: treat it as check-don't-assume rather than taking it on faith.
 
 `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 unverified, not as a proven guarantee.
+no probe recorded in this repo. Treat it as unverified, not as a proven guarantee.
 `vice_sid_get_state` read-back is **permanently unavailable**: SID `$D400-$D418` is write-only
 in hardware and the binary monitor has no SID command, so there is no route to recover it.
 Writes to those addresses still work fine. See `docs/stock-hard-losses.md`. Also: an internal
 field the register map cannot expose is marked `{ available: false, reason }` in the answer, never
-a bare `0` — do not record a `0` from one of these fields as a measurement; check `available`
+a bare `0` — do not record a `0` from one of these fields as a measurement. Check `available`
 first. A 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
@@ -105,11 +105,11 @@ Games and cracks poll the `$DC00`/`$DC01` matrix directly, bypassing the KERNAL
 gate by releasing it at the trigger checkpoint, never earlier.
 
 **`vice_keyboard_matrix` is permanently unavailable.** The binary monitor's `KEYBOARD_FEED` (0x72)
-only injects PETSCII text into the KERNAL keyboard buffer; the emulator recomputes CIA port B from
+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, not merely unbuilt. See `docs/stock-hard-losses.md`. 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
+`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.
 
@@ -140,4 +140,4 @@ real measured rate, so plan a live session to tolerate re-deriving a boot sequen
 Never-written RAM drifts continuously, so two captures of the same checkpoint will not match
 across all 64K. The recovery procedure is deterministic **for the program image**, not for 64K.
 `c64-ram-capture` § Compare two captures carries the volatility regions and the drift
-discriminator; use them rather than treating any difference as a divergence.
+discriminator. Use them rather than treating any difference as a divergence.

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

@@ -4,8 +4,8 @@ Do not wait until everything is understood. Stand up a buildable tree early, inc
 unidentified bulk as binary, and replace regions with real source as they are confirmed. The tree
 stays assemblable at every commit, so a regression has a small blast radius.
 
-`acme-build` covers assembling; this file covers the shape of the source and what makes a
-reconstruction correct.
+`acme-build` covers assembling. This file covers the shape of the source and what makes a
+reconstruction right.
 
 ## Start with binary inclusion
 
@@ -43,9 +43,9 @@ at a checkpoint is not verified** — the constraint's own conclusion, and the r
 design is part of the reconstruction work rather than something to bolt on afterwards.
 
 **That bar is what buys you the freedom to rename routines, reorganise files, replace constants
-with symbols and add macros**. **But** reorganising changes addresses, which breaks self-modifying code and
+with symbols and add macros**. **But** reorganising shifts addresses, which breaks self-modifying code and
 timing-sensitive raster routines. Replay through the checkpoint set after EACH reorganisation, not
-at the end of several: one changed address per failing replay is a short diagnosis, ten is a
+at the end of several: one shifted address per failing replay is a short diagnosis, ten is a
 bisect.
 
 A full 64K RAM capture is not a comparison surface: never-written RAM drifts continuously, so
@@ -91,7 +91,7 @@ Provisional names that carry their own uncertainty beat confident names that tur
 | `Unknown_` | no reliable interpretation yet |
 
 `Routine_43A2` → `Maybe_UpdatePlayer` → `UpdatePlayerPosition`, promoted only when behaviour is
-confirmed. Avoid `AmazingCollisionRoutine`-style names entirely; they encode a guess as a fact.
+confirmed. Avoid `AmazingCollisionRoutine`-style names entirely. They encode a guess as a fact.
 
 Record the confidence next to the thing, in the same grammar the project uses everywhere else:
 
@@ -123,7 +123,7 @@ stream across full gameplay coverage is data, whatever the tracer guessed.
 
 ACME's `--vicelabels` output is the `al C:xxxx .Name` format `vice_symbols_load` /
 `vice_symbols_lookup` consume, so labels flow source → build → debugger without translation.
-`acme-build` emits the `.vs` file on every build; load it after each one and your checkpoints carry
+`acme-build` emits the `.vs` file on every build. Load it after each one and your checkpoints carry
 real names.
 
 **The other direction — exporting the annotation store into that same format — is withdrawn as of

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

@@ -1,7 +1,7 @@
 # SID and CIA: music, effects, the RNG, input, timing
 
 Graded 2026-08-01, **MEDIUM**, doc-derived, except where marked. Per-register bit detail lives in
-`c64-memory-mapping`; this file carries the idioms and the order.
+`c64-memory-mapping`. This file carries the idioms and the order.
 
 ## SID — separating the player from the game logic
 
@@ -36,8 +36,8 @@ Confusing them is a frequent early error.
 
 | | CIA#1 `$DC00` — keyboard, joysticks, **IRQ** | CIA#2 `$DD00` — VIC bank, serial, user port, **NMI** |
 |---|---|---|
-| Port A | `$DC00` keyboard **column** select; joystick port 2 | `$DD00` VIC bank (bits 0-1, inverted); serial ATN/CLK/DATA |
-| Port B | `$DC01` keyboard **row** read; joystick port 1 | `$DD01` user port / RS-232 |
+| Port A | `$DC00` keyboard **column** select. Joystick port 2 | `$DD00` VIC bank (bits 0-1, inverted). Serial ATN/CLK/DATA |
+| Port B | `$DC01` keyboard **row** read. Joystick port 1 | `$DD01` user port / RS-232 |
 | Timers | `$DC04-$DC07`, control at `$DC0E`/`$DC0F` | `$DD04-$DD07`, `$DD0E`/`$DD0F` — these drive **NMI** |
 | Interrupt | `$DC0D` | `$DD0D`, same bit layout |
 
@@ -52,7 +52,7 @@ 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. On stock,
+  monitor's exact behaviour here is **unverified** — check, 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
@@ -62,13 +62,13 @@ One that programs `$DC04-$DC07` and enables timer A runs its own timebase.
   afternoon.** Games and cracks bypass the KERNAL keyboard buffer and read the matrix directly.
   Assume it until shown otherwise. **`vice_keyboard_matrix` is permanently unavailable** — the
   binary monitor's `KEYBOARD_FEED` only injects PETSCII buffer text and cannot drive the raw
-  matrix; see `docs/stock-hard-losses.md`. 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.
+  matrix. See `docs/stock-hard-losses.md`. 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
 
 Watch reads of `$DC00`/`$DC01` to find the input routine, then trace forward to what it stores.
 The joystick bits are active-low: bit 4 is fire, bits 0-3 up/down/left/right. A routine that reads
-`$DC01`, masks one bit and branches is the input decoder; the variable it writes is the one to
+`$DC01`, masks one bit and branches is the input decoder. The variable it writes is the one to
 name first.

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

@@ -1,7 +1,7 @@
 # Which `mcp__plugin_c64-re-tools_vice__*` call answers which question
 
 **This is not a restatement of the tool surface.** You already hold typed schemas for every
-call; read parameters off those. What the schemas cannot tell you is *which call to reach for
+call. Read parameters off those. What the schemas cannot tell you is *which call to reach for
 first*, and that ordering is the whole value here.
 
 Curated 2026-08-01, doc-derived, **Confidence: MEDIUM** — the mapping is reasoned from the tool surface and this project's own
@@ -9,7 +9,7 @@ usage, not measured). Individual rows that have since been exercised live are ma
 
 | Question | Call |
 |---|---|
-| Vectors, `$01`, `$D011`/`$D012`/`$D018`/`$D019`/`$D01A`, `$DC0D`/`$DD0D`, `$DD00` | `vice_memory_read` — highest-value first move; answers most vector questions in one or two calls |
+| Vectors, `$01`, `$D011`/`$D012`/`$D018`/`$D019`/`$D01A`, `$DC0D`/`$DD0D`, `$DD00` | `vice_memory_read` — highest-value first move. Answers most vector questions in one or two calls |
 | 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` |
@@ -17,33 +17,33 @@ usage, not measured). Individual rows that have since been exercised live are ma
 | Whole-chip SID state without the read hazards | `vice_sid_get_state` — **permanently unavailable**: SID `$D400-$D418` is write-only in hardware and the binary monitor has no SID command, so read-back cannot be recovered. Writes to those addresses still work fine over the memory-set primitive. See `docs/stock-hard-losses.md` |
 | 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` emits the format they consume. The annotation store's own export into that format is **withdrawn as of 2026-08-29, and no phase currently owns its return** — an earlier forecast naming a numbered phase for it is superseded |
+| Carry labels across sessions | `vice_symbols_load` / `vice_symbols_lookup` — ACME `--vicelabels` emits the format they consume. The annotation store's own export into that format is **withdrawn as of 2026-08-29, and no phase currently owns its return**. An earlier forecast named a numbered phase for it, and that forecast is superseded now |
 | Is the machine wedged, or did it stop itself? | `vice_diagnose` — five-state verdict with its evidence (one state is `monitor_held_elsewhere`, because this monitor serves exactly one client at a time). **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 `.c64-re-tools/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` |
+| 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` |
 
 ## Delegate rather than restate
 
 | Question | Go to |
 |---|---|
 | 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 |
+| Is this byte original or cracker-patched? | the `c64-provenance-diff` skill |
 | A verified 64K image, or comparing two captures | the `c64-ram-capture` skill |
-| Whole-program static disassembly with code/data separation | **`anno export-asm`** — withdrawn 2026-08-29, returned 2026-08-31, settled by assembling the output with a real ACME and diffing the bytes against the input. That oracle is test-only, so the verb itself writes source and runs no assembler. For a single routine, read one explicit range at a time with `anno_read_region` / `anno_disassemble` (4096-byte cap per call, refused rather than truncated above it) and record what you verified with `anno_set_data_type` |
+| Whole-program static disassembly with code/data separation | **`anno export-asm`** — withdrawn 2026-08-29, returned 2026-08-31. It settles correctness by assembling the output with a real ACME and diffing the bytes against the input. That oracle is test-only, so the verb itself writes source and runs no assembler. For a single routine, read one explicit range at a time with `anno_read_region` / `anno_disassemble` (4096-byte cap per call, refused rather than truncated above it). Record what you checked with `anno_set_data_type` |
 
 ## Runtime evidence versus the byte-derived guess
 
 | Question | Call |
 |---|---|
-| Where the store's byte-derived block table (`anno_set_data_type`'s own ranges) disagrees with what the emulator was actually observed executing | **`anno evid-disagreements`** (also `anno_evid_disagreements`) — joins the typed ranges against the runtime-observed rows an `anno_evid_ingest` call already wrote, reporting disagreements first, agreement as a count only, and a never-observed count that is explicitly NOT evidence the address holds data |
+| Where the store's byte-derived block table (`anno_set_data_type`'s own ranges) disagrees with what the emulator was actually observed executing | **`anno evid-disagreements`** (also `anno_evid_disagreements`) — joins the typed ranges against the runtime-observed rows an `anno_evid_ingest` call already wrote. It reports disagreements first, agreement as a count only, and a never-observed count. A never-observed count is explicitly NOT evidence the address holds data |
 | What evidence a store already holds, without re-running the program | `anno_evid_runs` — every run identity's observation count beside its denominator |
-| Reset one run identity's evidence for a fresh re-measurement | `anno_evid_reset` — clears only that run identity's rows; pair it with `vice_memmap_zap` on the emulator side |
+| Reset one run identity's evidence for a fresh re-measurement | `anno_evid_reset` — clears only that run identity's rows. Pair it with `vice_memmap_zap` on the emulator side |
 
 ## What blocks this program's code from being moved
 
 | Question | Call |
 |---|---|
-| Which constructions block relocating, rebasing or stripping part of this program | **`anno hazard-report`** (also `anno_hazard_report`) — enumerates movement-hazard findings derived from decoded bytes alone (for example, a store or read-modify-write instruction whose literal target lands on another instruction's opcode or operand byte, changing what runs or what value is read on a later pass). Each finding carries its own detection mechanism and a detection-strength token. Reports and changes NOTHING: it never relocates, strips or rebases anything, and it never emits a flag a caller could act on as an automatic relocation |
+| Which constructions block relocating, rebasing or stripping part of this program | **`anno hazard-report`** (also `anno_hazard_report`) — enumerates movement-hazard findings derived from decoded bytes alone. For example, a store or read-modify-write instruction may land its literal target on another instruction's opcode or operand byte. A later pass may then run different code or read a different value there. Each finding carries its own detection mechanism and a detection-strength token. It reports and touches NOTHING. It never relocates, strips or rebases anything, and it never emits a flag a caller could act on as an automatic relocation |
 
 **A region this report does not flag is undecided or unflagged, never certified safe to move.** Every checked
 region reports one of exactly three outcomes, and only one of them means a construction was actually found
@@ -58,9 +58,9 @@ moved.
 
 **`vice_run_until`'s `timeout_ms` bounds the wait.** `timeout_ms` (default 30000, ceiling 600000)
 bounds a run to an address the program never reaches, and a timed-out answer says the machine is
-left halted rather than looking like a wedged emulator; prefer `vice_checkpoint_add` + a bounded
+left stopped rather than looking like a wedged emulator. Prefer `vice_checkpoint_add` + a bounded
 poll when the address is a hypothesis rather than a certainty — see `vice-wedge-triage` for the
-full triage judgement and its live evidence; do not restate it here.
+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,8 +1,8 @@
 # Memory map generation
 
-**The memory map is GENERATED, not hand-authored.** The store — labels, comments, block
+**A generator writes the memory map. Nobody hand-authors it.** 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
+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.
 
 Run the generator once findings are in the store:
@@ -13,15 +13,19 @@ node <plugin-root>/src/mcp/vice/vice-proxy.ts anno render-memmap game.annostore
 ```
 
 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.
+prints the first differing line. `--check` reports drift 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**
+- 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
+the generator (or, if the sidecar itself is stale, fix 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
@@ -38,7 +42,7 @@ one-time, self-clearing banner correction — not a bug, and not a migration.
 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. 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
+outputs and confirmed 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 |
@@ -54,7 +58,7 @@ problem at once, never a `<placeholder>` silently rendered into a published docu
 | `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 |
+| `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:
@@ -93,5 +97,5 @@ close but not exact — a typo never silently degrades into an ungraded comment)
 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
+**Do not promote a row by editing its grade.** Re-confirm 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

@@ -42,7 +42,7 @@ Pure Node over committed files — the `.bin` dumps, their `.map.json` manifests
 
 ## Two verbs write to tracked files
 
-`anchor-search` updates `recovery/RELEASES.json`; `ledger` rewrites
+`anchor-search` updates `recovery/RELEASES.json`. `ledger` rewrites
 `recovery/PROVENANCE.md` and touches `RELEASES.json` too. So `git status` is
 **expected** to be dirty after a run.
 
@@ -61,10 +61,10 @@ changed.
 ## Worked example — the real corpus
 
 Two independently-cracked releases of one title, both captured at the same
-post-loader entry trigger. **The release ids below are shown as `release-a` and
-`release-b`; every number is real output from a live run against a two-release
-corpus, with only the ids renamed** — the tool has no opinion about what a
-release is called.
+post-loader entry trigger. **This example shows the release ids below as
+`release-a` and `release-b`.** **Every number is real output from a live run
+against a two-release corpus, with only the ids renamed** — the tool has no
+opinion about what you call a release.
 
 ```
 $ node $D anchor-search
@@ -94,15 +94,15 @@ naming the alternatives it ruled out:
 
 `UNKNOWN` with a rule-out list is the honest answer. Do not upgrade it to
 `CRACKER-PATCH` because a byte differs. **Confidence: HIGH** — run live against the
-committed corpus; `ledger` reproduced the committed
+committed corpus. `ledger` reproduced the committed
 `generated_tier_sha256 dc7eb080…` byte-identically, so the classification is
 deterministic.
 
 **One qualifier on the 102, and it is the example's premise rather than its output:**
-"independently-cracked" is asserted at the top of this example, not proven by it. The
-determinism is HIGH; the `ORIGINAL` verdicts inherit whatever confidence that
-independence claim carries. See § *The independence precondition* below before
-quoting an `ORIGINAL` count as settled.
+This example asserts "independently-cracked" at the top, and does not prove it.
+The determinism is HIGH. The `ORIGINAL` verdicts inherit whatever confidence
+that independence claim carries. See § *The independence precondition* below
+before quoting an `ORIGINAL` count as settled.
 
 ## The five kinds and the three verdicts
 
@@ -112,13 +112,13 @@ quoting an `ORIGINAL` count as settled.
 
 The two seeds are where this goes wrong, and both failure modes are on record:
 
-- **`loader` is seeded from `RELEASES.json`'s earned `loader_ranges`** — live
-  disassembly evidence — **never from `NOTES.md` prose.** Reading a loader range
-  out of prose is the documented root cause of `$08F5`, a permanent joystick-poll
-  instruction, once being classified as loader code.
-- **`cracktro` is seeded from a crack-credit *vocabulary* scan**, not a bare
-  printable-ASCII scan. A bare scan was tried and produced a real false positive
-  against a real corpus: **the game's own title-screen text** is printable ASCII
+- **`bucketManifest` seeds `loader` from `RELEASES.json`'s earned `loader_ranges`**
+  — live disassembly evidence — **never from `NOTES.md` prose.** Reading a loader
+  range out of prose once classified `$08F5`, a permanent joystick-poll
+  instruction, as loader code — the documented root cause.
+- **`bucketManifest` seeds `cracktro` from a crack-credit *vocabulary* scan**, not
+  a bare printable-ASCII scan. A bare scan produced a real false positive against
+  a real corpus: **the game's own title-screen text** is printable ASCII
   too, and it differed between the two releases. A bare scan called that cracker
   credit. It is not — a differing string is not a cracker string, and it is
   correctly left `UNKNOWN`.
@@ -127,7 +127,7 @@ The two seeds are where this goes wrong, and both failure modes are on record:
 assigned at capture time and kept verbatim. Everything the trace reaches is `game`.
 
 The `.bin` files are **never** edited or zeroed. Classification lives in
-the manifests; the bytes stay verbatim evidence.
+the manifests. The bytes stay verbatim evidence.
 
 ## Carrying the verdict into the rebuild
 
@@ -147,7 +147,7 @@ verb writes.
 
 **The flag makes the verdict VISIBLE and decides nothing.** Every byte in
 scope is still emitted, whatever the verdict says — a `CRACKER-PATCH` row does
-not drop, filter or alter a single byte, it only makes the evidence readable
+not drop, filter or change a single byte, it only makes the evidence readable
 at the point of use. What gets reversed, kept or left out remains the
 end-user's decision, never the tool's. `--ledger` is optional: omitting it
 exports exactly as before, with no provenance comment anywhere in the output.
@@ -160,15 +160,15 @@ WITH the reason the operator gave, and `anno_include_range` takes the record
 back if the decision changes. Recording an exclusion changes nothing about
 which bytes the export emits — the exported block still carries every byte
 of that span, now with a visible marker naming the exclusion and its reason,
-so nothing is removed and no gap appears in the output. The ledger's verdict
-is information the operator reads at this point; it is never wired as an
-input to an automatic exclusion, here or anywhere else on this surface.
+so the export removes nothing and no gap appears in the output. The ledger's
+verdict is information the operator reads at this point. It is never wired as
+an input to an automatic exclusion, here or anywhere else on this surface.
 
 ## A `CRACKER-PATCH` in `game` code is a trainer until proven otherwise
 
 `count-patches` counts exactly one intersection — verdict `CRACKER-PATCH`, kind
 `game`. That intersection has a name the pipeline never says out loud: a **trainer**.
-A cracker changing bytes *inside game code* is altering gameplay, and unlimited
+A cracker who changes bytes *inside game code* changes gameplay, and unlimited
 lives, disabled collision or a frozen timer is the usual reason.
 
 This matters because the three verdicts answer **who wrote a range**, not **what it
@@ -190,21 +190,21 @@ game as it shipped*.
 
 ### The independence precondition — this skill's own premise
 
-`ORIGINAL` means "identical across two **independently**-cracked releases". Delete the
+`ORIGINAL` means "identical across two **independently**-cracked releases". Remove the
 word *independently* and the verdict is worthless: two releases sharing an ancestor
 are identical everywhere the ancestor was, **including everywhere the ancestor's
 cracker patched**. Establish the independence. Do not infer it from two releases
 carrying different group names, different loaders, or different cracktros — those are
 the cheapest things for a re-cracker to replace.
 
-Until it is established, the diff is directional, and the direction is the trap:
+Until you establish it, the diff is directional, and the direction is the trap:
 
 - A diff **hit** is informative — something was patched.
 - A diff **miss** is not, and it is the miss that reads as reassurance.
 
 So `count-patches` reporting `0` is not evidence that no trainer exists. It is
 evidence that no trainer exists **in one release and not the other**. With unproven
-ancestry those are different claims, and only the second one was tested.
+ancestry those are different claims, and the diff tested only the second one.
 
 ### The detector that does not depend on the diff
 
@@ -219,7 +219,7 @@ why it survives the shared-ancestor case:
    way this hunt returns a false negative.
 2. **Armed but never reached.** Code jumped to from a patched region that never
    executes across full gameplay coverage is either dead crack scaffolding or a
-   trainer waiting on a trigger. Both need a verdict; neither should be reproduced
+   trainer waiting on a trigger. Both need a verdict. Neither should be reproduced
    without one.
 3. **Trigger scanners.** Reads of the keyboard or joystick registers in code that is
    not the game's own input handler, and comparisons against key codes inside a range
@@ -235,8 +235,8 @@ four signatures, at this coverage level" is an answer. "The diff was clean" is n
 ## Before you trust a verdict
 
 - **Coverage is incomplete, and the ledger says so out loud.**
-  a load-coverage record is not a finished coverage claim until every game state
-  has actually been visited. An on-demand-loaded
+  a load-coverage record is not a finished coverage claim until you have actually
+  visited every game state. An on-demand-loaded
   region — bytes that only appear after reaching a room or state nobody visited —
   is by construction **absent from the primary dumps this diffs**. Every verdict is
   scoped to "the addresses visible at the post-loader game-entry point", not to the
@@ -244,14 +244,14 @@ four signatures, at this coverage level" is an answer. "The diff was clean" is n
   complete `LOADING.md` reopens it.
 - **Never resolve a range's `kind` from its `start` address.** Coalescing groups on
   *verdict* continuity, not *kind* continuity, so one range can span several kind
-  zones. `splitRangeByManifestKind` exists for this, and the bug was found live:
-  a wide `ORIGINAL` range was found running straight through a `loader` sub-range
-  nested inside it. Resolving from `start` silently mislabels every address after
+  zones. `splitRangeByManifestKind` exists for this. This bug appeared in a live
+  run: a wide `ORIGINAL` range ran straight through a `loader` sub-range nested
+  inside it. Resolving from `start` silently mislabels every address after
   the first boundary.
 - **`--gap-tolerance` is off-by-one sensitive by design.** A gap of identical bytes
-  *strictly shorter* than N coalesces; a run of *exactly* N stays its own row.
+  *strictly shorter* than N coalesces. A run of *exactly* N stays its own row.
 - **More agreeing independent releases is the only thing that raises confidence.**
-  Two releases can establish `ORIGINAL`; they cannot establish intent. And *agreeing*
+  Two releases can establish `ORIGINAL`. They cannot establish intent. And *agreeing*
   only counts once *independent* is proven — releases sharing an ancestor agree on
   the ancestor's patches too, so unproven ancestry makes every `ORIGINAL` verdict
   conditional rather than earned.
@@ -272,21 +272,21 @@ addresses.
 Record findings that make RE faster in your own project notes **at the moment you
 find them**, graded with `Evidence:` and `Confidence:`. Promote a finding by
 re-logging it with the new evidence, never by editing an old grade in place — the
-grade is only worth anything if it says what was actually known when it was written.
+grade is only worth anything if it says what you actually knew when you wrote it.
 
 ## Troubleshooting
 
-| Symptom | Fix |
+| Symptom | What to do |
 |---|---|
 | `anchor-search` reports `ok=false` | Anchors disagreed, so there is no single offset. Do **not** pick the majority — the images are not the same fully-loaded state, or one capture is bad. Re-capture rather than force it. |
-| `git status` dirty after a run | Expected — two verbs write. Diff the two files; if only `proven_at`/`generated_at` moved, `git checkout --` them. |
-| `generated_tier_sha256` changed | The classification changed, not just a timestamp. Find the cause before committing; the digest is the determinism check. |
-| `count-patches` reports 0 | Usually correct. It counts `CRACKER-PATCH` **and** `game`-kind addresses; with two releases and no signature match, nothing qualifies. Check the `diff --json` tally before treating it as a bug. But do not read it as "no trainer" — see the next two rows. |
+| `git status` dirty after a run | Expected — two verbs write. Diff the two files. If only `proven_at`/`generated_at` moved, `git checkout --` them. |
+| `generated_tier_sha256` changed | The classification changed, not just a timestamp. Find the cause before committing. The digest is the determinism check. |
+| `count-patches` reports 0 | Usually accurate. It counts `CRACKER-PATCH` **and** `game`-kind addresses. With two releases and no signature match, nothing qualifies. Check the `diff --json` tally before treating it as a bug. But do not read it as "no trainer" — see the next two rows. |
 | Asked whether the crack added a trainer | `count-patches` is the diff-side answer: `CRACKER-PATCH` ∧ `game` **is** the trainer count. It is necessary and not sufficient — it cannot see a trainer both releases carry. Run the signature hunt too. |
-| Asked to confirm a release has no trainer | You cannot confirm that from a diff alone, and saying so is the answer. A clean diff only rules out a trainer in *one* release and not the other; with unproven ancestry that is a weaker claim than it sounds. Report the signature-hunt result with its coverage limits. |
+| Asked to prove a release has no trainer | You cannot prove that from a diff alone, and saying so is the answer. A clean diff only rules out a trainer in *one* release and not the other. With unproven ancestry that is a weaker claim than it sounds. Report the signature-hunt result with its coverage limits. |
 | Two releases agree everywhere suspicious | Suspect shared ancestry before concluding `ORIGINAL`. Different group names, loaders and cracktros are the cheapest things for a re-cracker to swap and prove nothing about independence. |
-| Everything is `UNKNOWN` | Also usually correct. `UNKNOWN` means "differs, no recognised signature, alternatives ruled out". Read the range's `reason` field. |
-| 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. |
+| Everything is `UNKNOWN` | Also usually accurate. `UNKNOWN` means "differs, no recognised signature, alternatives ruled out". Read the range's `reason` field. |
+| 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 because live disassembly evidence earns it. 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 src/skills/c64-provenance-diff/scripts/releases.mjs list` for the valid ids. |