@henols/c64-re-tools 0.2.3 → 0.2.5

package/bin/cli.mjs

@@ -30,7 +30,9 @@ const PKG_ROOT = dirname(HERE);
 const SKILLS_SRC = join(PKG_ROOT, "skills");
 
 // The single version-resolution seam this repo maintains is
-// `src/mcp/vice/version.ts` (quick-260819-tsz, D-5). This package
+// `src/mcp/vice/version.ts` -- one algorithm for resolving a VERSION
+// template against a published version, kept in exactly one place after
+// this repo once carried several independent copies of it. 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
@@ -42,12 +44,13 @@ const SKILLS_SRC = join(PKG_ROOT, "skills");
 // 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.
+// publish time. Do not reimplement the seam's own VERSION-template
+// parsing and prefix-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";
 // The dev placeholder every derived, publishable version string carries in
-// the working tree (R-2, quick-260819-tsz). Defined authoritatively as
+// the working tree outside a stamped release. Defined authoritatively as
 // `DEV_PLACEHOLDER` in `src/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
@@ -57,7 +60,7 @@ const MCP_PKG = "@henols/vice-mcp";
 // 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):
+// against -- EXCEPT when run from an unstamped dev checkout:
 // `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

package/package.json

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

package/skills/acme-build/SKILL.md

@@ -22,10 +22,10 @@ absent `run` verb is not an omission). It contacts nothing.
 Options: `-o FILE` `--out-dir DIR` `-f FORMAT` `--setpc ADDR` `-DSYM=VAL`
 `-I DIR` `--no-report` `--json`.
 
-`-I DIR` is resolved **workspace-relative** to the project root the host
-broker was launched with — the same resolution `source`/`--out-dir` already
-go through — before it ever reaches the assembler. An absolute or escaping
-`-I` directory is refused by the seam rather than passed to ACME; this is a
+The seam resolves `-I DIR` **workspace-relative** to the project root the host
+broker starts with — the same resolution `source`/`--out-dir` already
+go through — before it ever reaches the assembler. The seam refuses an absolute
+or escaping `-I` directory rather than passing it to ACME. This is a
 documented contract change from earlier releases, when an absolute include
 reached the assembler unchecked.
 
@@ -96,13 +96,13 @@ Inspect the result with `od`:
 od -An -tx1 game.prg | head -2
 ```
 
-The first two bytes are the little-endian load address (`01 08` = `$0801`); code
+The first two bytes are the little-endian load address (`01 08` = `$0801`). Code
 follows.
 
 ## Writing source
 
-Start from the scaffold — it carries a BASIC stub whose `SYS` target is computed,
-so the entry point stays correct as the program grows:
+Start from the scaffold — it carries a BASIC stub that computes its `SYS` target
+rather than hard-coding it, so the entry point stays correct as the program grows:
 
 ```bash
 node $A new game.asm
@@ -142,17 +142,17 @@ you also assemble by hand, so these stay recognised as mnemonics.
 This skill does not disassemble. The route that does is `anno export-asm`, and
 it lives in the `anno` CLI rather than here.
 
-**Dated withdrawal 2026-08-29, dated return 2026-08-31 — both halves are kept,
-because the withdrawal is the record of why the route is shaped the way it is.**
+**Dated withdrawal 2026-08-29, dated return 2026-08-31 — this document keeps
+both halves, because the withdrawal records why the route has its current shape.**
 Whole-program static disassembly was WITHDRAWN on 2026-08-29 rather than left standing on an unverified reassembly claim: the removed route
 settled correctness with a transcript parser, and the recorded false pass that
 discipline exists against read `ACME not found in PATH (skipped)` / `All
 roundtrip verifications passed.` / `EXIT=0` — exit zero, an aggregate line
 reading as a full pass, and the one assembler this project cares about never
 having run. On **2026-08-31 the route returned**, rebuilt over the annotation
-store as `anno export-asm`. It is not a rename of what was removed: its
-correctness is settled by **assembling the output with a real ACME and diffing
-the bytes against the input** — never by an exit code, and never by a string
+store as `anno export-asm`. It is not a rename of the removed route: its
+correctness comes from **assembling the output with a real ACME and diffing
+the bytes against the input** — never from an exit code, and never from a string
 match on the exporter's own output.
 
 **The live invocation:**
@@ -162,14 +162,14 @@ npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out ga
 node <plugin-root>/src/mcp/vice/vice-proxy.ts anno export-asm game.prg --store game.annostore
 ```
 
-`<image>` and `--store` are **two separate arguments and neither is derived from
+`<image>` and `--store` are **two separate arguments, and neither one derives from
 the other** — the image supplies the bytes, the store supplies the names, ranges,
 typed regions and comments, and naming one does not name the other. `--out` names
-a **directory** the whole export is written into, defaulting to the image's
+a **directory**: the verb writes the whole export into it, defaulting to the image's
 basename stem beside the **store**, not beside the image, because the export is a
 generated view of the annotations. The directory holds a root file that sources
 the rest, one file per annotation scope, and an `unscoped.a` for anything inside
-no scope. A non-empty destination is refused rather than overwritten unless you
+no scope. The verb refuses a non-empty destination rather than overwriting it, unless you
 pass `--force`.
 
 **The verb writes source text and runs no assembler.** Its own second output line
@@ -180,10 +180,10 @@ export-asm: this file has NOT been assembled -- this command writes source text
 ```
 
 The real-ACME byte-diff oracle is **test-only** — it lives in
-`src/mcp/vice/acme-verify.ts`, is exercised by `acme-verify.test.ts` (hard-failed
-in CI with `VICE_REQUIRE_ACME=1`), and is deliberately absent from the published
+`src/mcp/vice/acme-verify.ts`, `acme-verify.test.ts` exercises it (hard-failed
+in CI with `VICE_REQUIRE_ACME=1`), and it stays deliberately absent from the published
 package, so nothing on the runtime path can reach it. A clean `export-asm` run is
-therefore evidence that source was written and nothing more; it is not an
+therefore evidence that the verb wrote source and nothing more. It is not an
 assembler verdict. If you need to know the emitted source reassembles, assemble
 it yourself — that is what this skill's own build route is for.
 
@@ -191,7 +191,7 @@ it yourself — that is what this skill's own build route is for.
 `anno_read_region` and `anno_disassemble` render an explicit inclusive range out
 of the image on demand, capped at 4096 bytes per call and REFUSED by name above
 the cap rather than truncated. `c64-program-recon` documents that route and this
-history together; it is not restated there.
+history together. It is not restated there.
 
 ## Setup
 
@@ -245,11 +245,11 @@ This one turns source into bytes. It does not restate what the others carry.
 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 | Correct |
 |---|---|
 | `install the ACME cross assembler and put acme on PATH` | Install ACME. |
 | `for <...> includes, set $ACME to …` | `export ACME=<dir holding cbm/c64/vic.a>`. |
@@ -257,4 +257,4 @@ grade is only worth anything if it says what was actually known when it was writ
 | `Label name not in leftmost column` + `Syntax error` on a mnemonic | Add `!cpu 6510`. |
 | `Output file already chosen` | Remove `!to` from the source and keep `-o`. |
 | `Number does not fit in 8 bits` | Pass a value 0–255, or drop the `#` if you meant an address. |
-| `This tool cannot read binary files. The file appears to be a binary .a file.` | The file is fine — ACME source is plain text; the agent's Read tool refuses the `.a` extension regardless of content, and Edit needs a prior successful Read. Scaffold and write source as `.asm` instead — the driver accepts `.a`/`.asm`/`.s`, all three assemble byte-identically (verified both directions in this container, 2026-08-04). To read an existing `.a` file, use `sed -n '1,60p' file.a`. |
+| `This tool cannot read binary files. The file appears to be a binary .a file.` | The file is fine. ACME source is plain text. The agent's Read tool refuses the `.a` extension regardless of content. Edit needs a prior successful Read. Scaffold and write source as `.asm` instead — the driver accepts `.a`/`.asm`/`.s`, all three assemble byte-identically (verified both directions in this container, 2026-08-04). To read an existing `.a` file, use `sed -n '1,60p' file.a`. |

package/skills/c64-disk-access/SKILL.md

@@ -20,7 +20,7 @@ node $S audit --image path/to/image.d64                     # find fabricated/co
 ```
 
 The script wraps `c1541` and nothing else — **read-only**. `bam`/`dir`/`audit`
-need only `--image`; `entry`/`chain`/`read` also need `--name`, a CBM
+need only `--image`. `entry`/`chain`/`read` also need `--name`, a CBM
 filename or glob pattern (never a path). No `-format`, `-write`, `-bwrite`
 or `-delete` verb is reachable from here, deliberately: this skill only
 ever reads a disk image, never mutates one.
@@ -30,11 +30,11 @@ Options: `--image PATH` `--name CBM-NAME` `--out-dir DIR` `--json`.
 `--out-dir` defaults to the image's own directory, exactly like
 `acme-build`'s own `--out-dir` default. Both `--image` and `--out-dir` are
 resolved **workspace-relative** to the smallest ancestor directory
-containing both, before the request ever reaches the seam — the same
-resolution `acme-build`'s `source`/`--out-dir` already go through. `--name`
-is passed straight through, never resolved as a path; a value beginning
-with `-` is refused by the seam before any child process is spawned (it
-would otherwise be read as a flag by `c1541`'s own CLI).
+containing both, before the request reaches the seam. This is the same
+resolution `acme-build`'s `source`/`--out-dir` already go through. The seam
+passes `--name` straight through and never resolves it as a path. The seam
+refuses a value beginning with `-` before it spawns any child process.
+Otherwise `c1541`'s own CLI would read it as a flag.
 
 ## Directory listing
 
@@ -57,9 +57,9 @@ Prints the seam's response verbatim as one line of JSON:
 node $S bam --image game.d64 --json
 ```
 
-Same response shape as `dir`; `results[0].path` names a file carrying one
-per-sector allocation row per track (a run of `*`/`.` characters, `*` for
-an allocated sector).
+Same response shape as `dir`. `results[0].path` names a file carrying one
+per-sector allocation row per track. Each row is a run of `*`/`.`
+characters, `*` for an allocated sector.
 
 ## One directory entry's raw fields
 
@@ -68,10 +68,11 @@ node $S entry --image game.d64 --name FILENAME --json
 ```
 
 `results[0].path` names a file carrying the entry's raw 32-byte directory
-record (as a hex dump) followed by its `T/S: <t>/<s>, <n> blocks` summary
-line. This script ALSO parses that line back and adds `firstTrack`/
-`firstSector` as numeric fields on the JSON response, purely for display —
-the file itself is still the authoritative source.
+record (as a hex dump). A `T/S: <t>/<s>, <n> blocks` summary line follows
+the record. This script also parses that line back and adds
+`firstTrack`/`firstSector` as numeric fields on the JSON response. These
+fields exist purely to show the values — the file itself is still the
+authoritative source.
 
 ## A named file's sector chain
 
@@ -81,7 +82,7 @@ node $S chain --image game.d64 --name FILENAME --json
 
 `results[0].path` names a file listing every `(track,sector)` hop the file
 occupies, in order. A single-sector file's chain shows one hop with no
-second tuple on the arrow's right side; a multi-sector file's chain repeats
+second tuple on the arrow's right side. A multi-sector file's chain repeats
 the tuple at every hop.
 
 ## Extracting a named file's bytes
@@ -90,8 +91,8 @@ the tuple at every hop.
 node $S read --image game.d64 --name FILENAME --out-dir /scratch --json
 ```
 
-Writes the file's raw bytes (unlike the other four capabilities, this one
-is NOT a captured-stdout listing — `c1541` writes the output file itself).
+Writes the file's raw bytes. Unlike the other four capabilities, this one
+is NOT a captured-stdout listing — `c1541` writes the output file itself.
 `results[0]` carries that file's `path`/`sha256`/`byteLength`.
 
 ## Auditing for fabricated or corrupted entries
@@ -100,56 +101,58 @@ is NOT a captured-stdout listing — `c1541` writes the output file itself).
 node $S audit --image game.d64 --json
 ```
 
-Composes `dir` (names and block counts), `bam` (the per-sector allocation
-map), and one `entry` call per name (each file's own claimed first track/
-sector, and its directory sector's "next directory" pointer) into a ported,
+The `audit` command composes `dir` (names and block counts) and `bam` (the
+per-sector allocation map). For each name, it also makes one `entry` call
+to get that file's own claimed first track/sector and its directory
+sector's "next directory" pointer. Together these calls form a ported,
 read-only detector — no `-format`/`-write`/mutating verb, and no seventh
-`host_tool` id; this is three existing capabilities composed client-side.
+`host_tool` id. This is three existing capabilities composed client-side.
 
-A directory entry is flagged `suspicious`, with **named reasons, never a
-bare boolean**, on any of:
+The `audit` command flags a directory entry `suspicious`, with **named
+reasons, never a bare boolean**, on any of:
 
-1. its block count is `0`;
-2. its first track/sector lies outside the image's own geometry (there is
-   no such track, or no such sector on that track);
-3. its first **sector** — not merely its whole track — is reported free by
-   the allocation map, meaning the file cannot really start there. This is
+1. its block count is `0`.
+2. its first track/sector lies outside the image's own geometry. There is
+   no such track, or no such sector on that track.
+3. the allocation map reports its first **sector** — not merely its whole
+   track — free, meaning the file cannot really start there. This is
    sharper than checking only whether the whole track is free, because the
    per-sector map is available.
 
-A cyclic or self-referential directory chain (two entries claiming the same
-first track/sector, or a "next directory" pointer that refers back to a
-sector already seen — including the directory's own starting sector) stops
-being treated as new information and is reported as a top-level
-`chain_error` naming the repeated pointer, rather than looping. Every
-remaining entry is still audited afterward — a chain error on one entry
-never hides another entry's own independent flag.
+A directory chain is cyclic or self-referential when two entries claim the
+same first track/sector. It is also cyclic or self-referential when a
+"next directory" pointer refers back to a sector already seen, including
+the directory's own starting sector. When this happens, the command stops
+treating the repeat as new information. Instead of looping, it reports a
+top-level `chain_error` naming the repeated pointer. Every remaining entry
+is still audited afterward — a chain error on one entry never hides another
+entry's own independent flag.
 
 ```json
 {"entries":[{"name":"basicstub","blocks":1,"first_track":17,"first_sector":0,"suspicious":false,"suspicious_reasons":[]}],"chain_error":null}
 ```
 
 **A flag is a signal to investigate, not a verdict.** A directory entry a
-cracker fabricated for a file never actually written, a genuinely corrupted
-image, and (rarely) an unusual-but-legitimate disk layout can all produce a
-flag; this command reports what it finds, named, and leaves the
-interpretation to whoever is looking at the disk.
+cracker fabricated for a file never actually written, a genuinely
+corrupted image, and (rarely) an unusual-but-legitimate disk layout can
+all produce a flag. This command reports what it finds, named, and leaves
+the interpretation to whoever is looking at the disk.
 
 ## Failure shape
 
-A nonexistent image, a nonexistent named entry, or any other call `c1541`
-cannot service is reported as `{"ok":false,"message":"..."}` with a
-non-zero exit code — **never** a success envelope over an empty or partial
-result. `c1541` itself exits `0` even on a genuine failure (it prints its
-own `Error - ...` lines to stdout instead); the seam's own classifier, not
-the exit code, is what decides success here.
+The seam reports a nonexistent image, a nonexistent named entry, or any
+other call `c1541` cannot service as `{"ok":false,"message":"..."}` with a
+non-zero exit code. This is **never** a success envelope over an empty or
+partial result. `c1541` itself exits `0` even on a genuine failure (it
+prints its own `Error - ...` lines to stdout instead). The seam's own
+classifier, not the exit code, is what decides success here.
 
 ## What this skill does NOT do
 
 - **No mutating verb.** `-format`/`-write`/`-bwrite`/`-delete` are never
   reachable from this script, on the wire, or anywhere in this skill's tree
-  — only the six read-only capabilities above are exposed.
-- **No direct binary spawn.** `c1541` runs host-side; this script only ever
+  — this skill exposes only the six read-only capabilities above.
+- **No direct binary spawn.** `c1541` runs host-side. This script only ever
   constructs a typed request and reads the produced files back off the
   shared workspace tree — the host-tool execution seam is the only route.
 - **No emulator dependency.** This skill names no VICE emulator tool at