@henols/c64-re-tools 0.2.4 → 0.2.5

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

@@ -77,10 +77,11 @@ loop:   ldx $dc01                           ; $DC01 = Port B, keyboard matrix ro
         rts
 ```
 
-A header block listing every referenced address with its full description, symbol
-and region is prepended (elided above): measured on the two examples on this page,
-the eleven-line listing above grows a 23-line header and the nine-line IRQ excerpt
-below grows a 25-line one — a little over 2x the input either way. Pass
+`annotate` prepends a header block that lists every referenced address with its
+full description, symbol and region (elided above). Measured on the two examples
+on this page, the eleven-line listing above grows a 23-line header and the
+nine-line IRQ excerpt below grows a 25-line one — a little over 2x the input
+either way. Pass
 `--no-header` to drop it and get the annotated body alone.
 
 Options:
@@ -91,8 +92,8 @@ Options:
   (`$0400-$07E7`, 1000 bytes) or the `$C000-$CFFF` block still earns an inline
   comment, while the 8 KB BASIC and KERNAL ROM blocks do not — a branch
   annotated "KERNAL ROM (8192 bytes)" teaches nobody anything. The cap applies
-  only to non-flow instructions: flow instructions (`JMP`, `JSR`, branches,
-  `RTS`, `RTI`) are held to 2 bytes regardless of `--max-span`, so a jump or
+  only to non-flow instructions. `annotate` holds flow instructions (`JMP`,
+  `JSR`, branches, `RTS`, `RTI`) to 2 bytes regardless of `--max-span`, so a jump or
   branch only earns a comment when it targets a specific vector such as
   `$0314`. `--max-span 2` gives register- and variable-level comments only.
 - `--no-header` suppresses the prepended header block, for piping annotated
@@ -128,11 +129,11 @@ Weigh a comment by the region it describes:
   equally solid wherever ROM is banked in — `$01` bits #0-#2 select it, and the
   vector at `$0314` shows whether the KERNAL IRQ path is in use.
 - **Zero page, `$0200-$07FF` and the BASIC area describe BASIC and KERNAL usage.**
-  Read them as a strong hint and confirm against the program's own behaviour
+  Read them as a strong hint and check against the program's own behaviour
   before adopting the name. A game that banks ROM out keeps its own variables
   there. A real case: at `$08E6` a game's `LDA $49` gets labelled `FORPNT`
   ("value of current variable during LET"), when `$49` is really one of that
-  game's own variables. Take the address, verify the meaning.
+  game's own variables. Take the address, check the meaning.
 - **A region-only answer is not an error.** An address that no source names
   specifically prints only the wider regions enclosing it — no error, no
   not-found line. `node $D lookup '$1234'` prints:
@@ -154,7 +155,7 @@ Weigh a comment by the region it describes:
   table that loses coverage, not for anything the current one omits.
 
 For a game, the fastest route to a real name is to annotate with `--max-span 2`,
-trust the I/O lines immediately, and confirm the rest by watching what the code
+trust the I/O lines immediately, and check the rest by watching what the code
 does with them.
 
 ## Where the data comes from
@@ -170,16 +171,16 @@ what the others leave out:
 | [C64io.txt](https://www.zimmers.net/anonftp/pub/cbm/maps/C64io.txt) | VIC/SID/CIA registers broken down per bit |
 
 The built table is committed alongside the script, so `lookup` and `annotate` need
-only Node. Rebuild when a source publishes a correction; `lookup`'s `<src>` tags
+only Node. Rebuild when a source publishes a correction. `lookup`'s `<src>` tags
 show which table any given claim came from.
 
 `memmap` overwrites the committed, git-tracked `memmap.json` (driver.mjs:270 —
-235,925 bytes as of 2026-08-04, confirm with `wc -c`) **in place, with no backup
-and no diff.** One of the four sources (`http://unusedino.de/…`, driver.mjs:33)
-is fetched over plain HTTP with no TLS, and the only guard against a bad rebuild
+235,925 bytes as of 2026-08-04, check with `wc -c`) **in place, with no backup
+and no diff.** `memmap` gets one of the four sources (`http://unusedino.de/…`,
+driver.mjs:33) over plain HTTP with no TLS. The only guard against a bad rebuild
 is a per-source emptiness check plus a 600-entry floor across all sources
-combined (driver.mjs:262, 268) — so a partially-reachable or partially-changed
-source set can silently replace good tracked data with less of it. Rebuild, then
+combined (driver.mjs:262, 268). A partially-reachable or partially-changed source
+set can therefore silently replace good tracked data with less of it. Rebuild, then
 run `git diff --stat` on `memmap.json` before accepting the result, and
 `git checkout` the file if the diff is not explainable as the correction you
 were expecting. **`memmap` mutates tracked files** — unlike `lookup` and
@@ -191,8 +192,8 @@ tree, and review the diff before you commit it.
 `memmap.json`'s structured `bits` entries are the source of the curated register bit-name table used
 to generate program-specific enums for this project's annotation store: register
 writes disassemble as `lda #D011_YSCROLL3_ROW25_SCREENON_TEXT` instead of a bare `#$1b`. The
-generator is `src/mcp/vice/anno-regbits-gen.ts`; its committed output is
-`src/mcp/vice/anno-regbits.json`; and that output is **digest-pinned** to `memmap.json` — a
+generator is `src/mcp/vice/anno-regbits-gen.ts`. Its committed output is
+`src/mcp/vice/anno-regbits.json`. That output is **digest-pinned** to `memmap.json`. A
 `node anno-regbits-gen.ts` run compares its own fresh build against the committed file, and CI fails
 if `memmap.json` changed without a re-run.
 
@@ -200,7 +201,7 @@ if `memmap.json` changed without a re-run.
 `$D017`, `$D01A` and `$D01B`–`$D01D` — the sprite-plane bitmask registers a real game writes
 constantly — are **not** among those 29, so the enum generator supplies them from its own curated
 override table (`OVERRIDES` in `anno-regbits-gen.ts`), not from this file. Widening `memmap.json`'s
-`io` parser (or repairing the OCR damage already present in some `bits` prose, e.g. a letter `O` for
+`io` parser (or correcting the OCR damage already present in some `bits` prose, e.g. a letter `O` for
 the digit `0`) so those registers get a real structured entry here is separate work belonging to this
 skill, not the generator.
 
@@ -208,10 +209,10 @@ skill, not the generator.
 table above only builds `anno-regbits.json`. Turning a specific program's register *writes* into
 named enum variants was the `gen-enums` CLI verb, and **that verb is WITHDRAWN from this surface, and
 no phase currently owns its return.** This notice previously forecast that it would come
-back as a rebuild over the annotation store alongside the ACME export route; the ACME export route
+back as a rebuild over the annotation store alongside the ACME export route. The ACME export route
 did come back on 2026-08-31, but the phase that rebuilt it covered that route only — no requirement
-and no success criterion of it mentioned `gen-enums`. That forecast is corrected here rather than
-deleted. Do not invoke the verb — it does not exist, and the invocation fails with an unknown-verb
+and no success criterion of it mentioned `gen-enums`. This notice corrects that forecast rather than
+removing it. Do not invoke the verb — it does not exist, and the invocation fails with an unknown-verb
 error and nothing to explain it.
 
 What it did, so the rebuild has a specification and so a reader knows what is missing: it read the
@@ -229,7 +230,7 @@ manual where `gen-enums` was bulk, but it writes exactly the same rows into the
 Two deeper jobs feed the annotate/lookup job above, rather than standing apart from it: knowing
 what a whole region actually is (code, or one of eight kinds of data) before it can be annotated
 at all, and knowing what one of a program's own addresses represents when no published table can
-say. Both exist to serve a documented listing; neither is invoked as a job on its own.
+say. Both exist to serve a documented listing. You do not invoke either one as a job on its own.
 
 ### Classifying every region of an annotation project
 
@@ -242,7 +243,7 @@ data?**
 answers the *live* code-versus-data question — its step 5 is "what the PC
 actually visits across full coverage", and an execution trace beats every
 static heuristic on this page. Run the live pass when you have a running
-machine; run this one when all you have is a file, and treat a later trace as
+machine. Run this one when all you have is a file, and treat a later trace as
 the thing that overrules it.
 
 When a binary is first loaded, the auto-analyzer traces reachable code from the
@@ -279,11 +280,11 @@ four hundred lines of fiction.
 #### The order of the passes
 
 Work the Undefined blocks in four passes, in this order. Do not interleave
-them; each pass makes the next one cheaper.
+them. Each pass makes the next one cheaper.
 
 1. **Provably-reachable code** — read from the entry point of each region that
    meets the proof bar above with `anno_disassemble`, then type the range you
-   actually verified as `code` with `anno_set_data_type`. **Reading and typing
+   actually checked as `code` with `anno_set_data_type`. **Reading and typing
    are two calls on this surface, and that is deliberate:** `anno_disassemble`
    decodes fresh from the image bytes and writes nothing at all, so nothing is
    ever classified as code by a decoder's guess — the boundary you record is
@@ -291,7 +292,7 @@ them; each pass makes the next one cheaper.
 2. **Text** — PETSCII and screencode strings.
 3. **Tables** — byte, word, address and split (lo/hi, hi/lo) tables.
 4. **Whatever is left** — decide data, or leave it Undefined for a human.
-   **Never** speculatively disassemble in this pass; by definition nothing here
+   **Never** speculatively disassemble in this pass. By definition nothing here
    met the proof bar.
 
 #### Scope, and reading a region
@@ -309,24 +310,24 @@ them; each pass makes the next one cheaper.
      data** — they are valid instructions. The flag is a human's hint, not a
      guarantee: some programs use them with the flag false.
 2. `anno_get_blocks` to see what is already classified, and focus on the
-   Undefined entries. `max_results` is REQUIRED with no default; pass a ceiling
+   Undefined entries. `max_results` is REQUIRED with no default. Pass a ceiling
    above the range count you expect and compare the returned count against it.
 3. Read each candidate region twice, through `anno_read_region` (which names
    both the `store` and the `image`): `view:
    "hexdump"` shows the byte patterns, and **omitting `view`** gives the
    disassembly view — that is the parameter's documented default — which shows
-   how the region would decode. The combined byte count is capped at **4096 bytes** per call
-   (`ANNO_READ_REGION_MAX_BYTES`), and a request above the cap is refused by
-   name rather than truncated — so walk a large binary in consecutive ranges.
+   how the region would decode. `anno_read_region` caps the combined byte count
+   at **4096 bytes** per call (`ANNO_READ_REGION_MAX_BYTES`). It refuses a
+   request above the cap by name rather than truncating it — so walk a large binary in consecutive ranges.
    Chunks of **256–512 bytes** are the practical working size for
-   classification; a 4096-byte hexdump is more than can be read carefully in
+   classification. A 4096-byte hexdump is more than can be read carefully in
    one pass.
 
 #### Applying the classification
 
 - **Code**: `anno_disassemble` from the entry-point address to READ, then
-  `anno_set_data_type` with `"code"` to RECORD the range you verified.
-  `anno_disassemble` performs no write, so nothing is classified until you say
+  `anno_set_data_type` with `"code"` to RECORD the range you checked.
+  `anno_disassemble` performs no write, so it classifies nothing until you say
   so. Type only as far as you actually followed the flow — the end of a routine
   at its `RTS`/`RTI`/`JMP`, not "to the end of the region" — because the typed
   `code` ranges are what `anno_get_cross_references` and `anno_search` decode
@@ -337,9 +338,9 @@ them; each pass makes the next one cheaper.
 - **A wrong classification is not a disaster and does not need undoing.**
   `anno_set_data_type` is idempotent over a range: set the correct type again
   over the same range and the previous one is gone, and an identical repeat
-  succeeds reporting `changed: false`. (Upstream reaches for an undo call here;
-  this project does not expose one, and does not need to.)
-- **Read the disclosures on a successful retype; they are not errors and they
+  succeeds reporting `changed: false`. (Upstream reaches for an undo call here.
+  This project does not expose one, and does not need to.)
+- **Read the disclosures on a successful retype. They are not errors and they
   are never dropped.** `contradictedComments` names comments whose recorded
   confidence now contradicts the type you just applied, and
   `reinterpretedSplitTables` names every split table the write FRAGMENTED, with
@@ -349,9 +350,9 @@ them; each pass makes the next one cheaper.
   ones a human recorded.
 - A split layout REFUSES an odd byte count — the low half and the high half must
   be the same length.
-- Re-read `anno_get_blocks` after each batch to confirm what actually landed.
-  `max_results` is REQUIRED on that read and has no default; the true match
-  count is returned beside the list.
+- Re-read `anno_get_blocks` after each batch to check what actually landed.
+  `max_results` is REQUIRED on that read and has no default. That read returns
+  the true match count beside the list.
 
 Example of a valid data-only batch, then the code regions separately:
 
@@ -368,7 +369,7 @@ then: anno_get_blocks max_results=500        # refresh
 
 | Block type | `data_type` | When |
 |---|---|---|
-| **Code** | `code` | Provably-executed instructions. Read the extent with `anno_disassemble` first — it writes nothing — then record exactly what you verified. |
+| **Code** | `code` | Provably-executed instructions. Read the extent with `anno_disassemble` first — it writes nothing — then record exactly what you checked. |
 | Byte | `byte` | Raw 8-bit data: sprites, bitmaps, charsets, lookup tables, variables, unknowns |
 | Word | `word` | 16-bit little-endian values: 16-bit variables, math constants, SID frequencies |
 | Address | `address` | 16-bit LE pointers — jump tables, vector lists. Creates cross-references |
@@ -383,17 +384,17 @@ then: anno_get_blocks max_results=500        # refresh
 
 #### Recognising each kind
 
-**Byte data** — regular patterns that form no valid instruction sequence;
-addressed by `LDA addr,X` / `LDA addr,Y` table lookups; sprite data in 63-byte
-(padded to 64) units, usually grouped; bitmap data in 8-byte character cells;
-colour data confined to `$00`–`$0F`; or random-looking bytes between two code
+**Byte data** — regular patterns that form no valid instruction sequence.
+Addressed by `LDA addr,X` / `LDA addr,Y` table lookups. Sprite data in 63-byte
+(padded to 64) units, usually grouped. Bitmap data in 8-byte character cells.
+Colour data confined to `$00`–`$0F`. Or random-looking bytes between two code
 blocks whose disassembly is nonsense.
 
 **Word data** — byte pairs forming meaningful 16-bit values (screen addresses,
-timer values); loaded low-then-high by adjacent `LDA addr` / `LDA addr+1`.
+timer values). Loaded low-then-high by adjacent `LDA addr` / `LDA addr+1`.
 
 **Address tables** — byte pairs that read as little-endian addresses landing
-*inside* the binary; reached by `JMP ($addr)` or indexed indirect reads. Jump
+*inside* the binary. Reached by `JMP ($addr)` or indexed indirect reads. Jump
 tables, dispatch tables and vector lists all live here.
 
 **Split lo/hi (or hi/lo) tables** — two equal halves, one of plausible low
@@ -404,25 +405,25 @@ on the 6502. **The total byte count must be even and the halves equal** — an
 odd count means the boundary is in the wrong place.
 
 **PETSCII text** — bytes in `$20`–`$7E` (unshifted) or `$C0`–`$DF` (shifted),
-often recognisably English since PETSCII shares `$20`–`$5F` with ASCII;
-terminated by `$00`, `$0D`, or a high-bit sentinel; reached by `$FFD2` (CHROUT)
+often recognisably English since PETSCII shares `$20`–`$5F` with ASCII.
+Terminated by `$00`, `$0D`, or a high-bit sentinel. Reached by `$FFD2` (CHROUT)
 or `$AB1E` (BASIC STROUT). `GAME OVER`, `PRESS FIRE`, menus, credits.
 
-**Screencode text** — bytes in `$00`–`$3F` where `$00` is `@` and `$01` is `A`;
-copied directly to `$0400`–`$07E7`. `LDA data,X / STA $0400,X` is the
+**Screencode text** — bytes in `$00`–`$3F` where `$00` is `@` and `$01` is `A`.
+Copied directly to `$0400`–`$07E7`. `LDA data,X / STA $0400,X` is the
 give-away. A full screen dump is exactly 1000 bytes.
 
 **External file** — a large contiguous non-code block matching a known format:
 a `PSID`/`RSID` header, a 2048-byte charset (256 chars × 8 bytes), sprite data
 in multiples of 64, or a bitmap. Export it rather than annotate it.
 
-**PETSCII is not screencode.** If it is copied to `$0400`, it is screencode; if
-it is passed to CHROUT, it is PETSCII. Getting this backwards produces text
+**PETSCII is not screencode.** If the program copies it to `$0400`, it is
+screencode. If the program passes it to CHROUT, it is PETSCII. Getting this backwards produces text
 that renders as garbage in exactly one of the two places.
 
 #### The adjacent-table limitation, and how it was closed
 
-**Dated limitation, recorded 2026-08-24; CLOSED 2026-08-29 when the store
+**Dated limitation, recorded 2026-08-24. CLOSED 2026-08-29 when the store
 changed underneath it.** The old store auto-merged two adjacent regions of the
 *same* type into one block, so two byte tables side by side — or the two halves
 of a split table sitting next to each other — lost their boundary on read, and
@@ -443,7 +444,7 @@ So the working rules are now the ordinary ones:
 - **Do** still record the boundary in the annotations as well — an
   `anno_set_label_name` at the start of the second table and a line comment on
   both naming the extent you determined. A name and an evidence line survive a
-  later retype; a row boundary does not.
+  later retype. A row boundary does not.
 - **Do not** carry the old over-merge caveat into a report taken from this
   store. It was true of the retired one and is not true here.
 
@@ -464,14 +465,14 @@ Then report, and mean it:
   regions on a real game is almost always a report that stopped looking.
 - The store revision, read with `anno_save_project`. That verb performs **no
   write** — every classification call above already committed and fsynced its
-  own — so quoting the revision is how the report is pinned to an exact store
+  own — so quoting the revision pins the report to an exact store
   state rather than to "after the pass".
 
 #### What goes wrong
 
 | Symptom | What it actually is |
 |---|---|
-| A region disassembles beautifully but has no incoming reference | Data. Decodability is not evidence; leave it Undefined. |
+| A region disassembles beautifully but has no incoming reference | Data. Decodability is not evidence. Leave it Undefined. |
 | Disassembly full of impossible branches or `BRK` (`$00`) floods | Data misread as code. |
 | Odd-looking instructions, but real `JSR`/`JMP` cross-references land here | Probably code using undocumented opcodes. Check the `may_contain_undocumented_opcodes` hint. |
 | A split table's addresses recombine to nonsense | The half boundary is misplaced, or the table is hi/lo rather than lo/hi. |
@@ -485,7 +486,7 @@ a hardware register, a KERNAL entry point, an OS variable. That answer comes
 from four tables and holds for every program.
 
 This section is the other half: **what a program's *own* address represents.**
-No table can tell you, because the meaning was decided by the program's code.
+No table can tell you, because the program's code decided the meaning.
 When `lookup` returns a region-only answer — the dominant case for a game's own
 code and variables, as noted above — this is the procedure that gets you a
 name.
@@ -507,7 +508,7 @@ name.
 #### 2. Gather the usage
 
 `anno_get_cross_references` on the address — naming the `store`, the `image` and
-a REQUIRED `max_results` — returns everywhere it is touched. Read the
+a REQUIRED `max_results` — returns every site that touches it. Read the
 instruction at each site, because the instruction is the evidence:
 
 - **Writes**: `STA`, `STX`, `STY`
@@ -540,14 +541,14 @@ field of auto-generated offsets.
 
 **An external ROM or system routine?** An `e_` prefix, or an address in KERNAL
 space (`$E000`–`$FFFF`), or a standard shadow vector. `lookup` gives the
-routine's published name; rename to the conventional form — `$FFD2` becomes
+routine's published name. Rename to the conventional form — `$FFD2` becomes
 `KERNAL_CHROUT`, `$EA31` becomes `SYSTEM_IRQ_HANDLER`.
 
 **A 16-bit pointer?** Below `$0100`, and used with indirect-indexed `($xx),Y`
 or indexed-indirect `($xx,X)`. Rename to `ptr_`/`vec_` form and comment what it
 points *to*, which is the thing the name cannot carry.
 
-**A flag or bitmask?** Only ever `$00`/`$01` or `$00`/`$FF`; tested with `BIT`
+**A flag or bitmask?** Only ever `$00`/`$01` or `$00`/`$FF`. Tested with `BIT`
 or `LDA`/`BEQ`. Name it as a predicate — `is_active`, `has_collided`. When the
 individual bits carry separate meanings, that is an enum: define it with
 `anno_create_project_enum` (`$01 = ACTIVE`, `$02 = COLLIDED`, `$04 =
@@ -559,8 +560,8 @@ with `CPX`/`CPY`/`CMP`. `loop_idx`, `sprite_count`, `delay_timer`.
 
 **A state variable?** Several distinct values, often feeding a dispatch
 (`ASL` / `TAX` / `JMP (table,X)`). Name it `game_state` or `current_mode` — and
-these are the best enum candidates of all. Look for an existing enum first;
-define one (`0 = INIT`, `1 = TITLE`, `2 = GAMEPLAY`, `3 = GAME_OVER`) with a
+these are the best enum candidates of all. Look for an existing enum first.
+Define one (`0 = INIT`, `1 = TITLE`, `2 = GAMEPLAY`, `3 = GAME_OVER`) with a
 real `description` if none matches, then apply it to every instruction reading
 or writing the variable.
 
@@ -612,19 +613,19 @@ still readable even though the store cannot format it.
   variable, dead.
 - **Evidence**: the specific cross-references or usage patterns that decided
   it. A classification with no evidence line is a guess wearing a name.
-- **Actions taken**: what was renamed, what was commented, which enums were
+- **Actions taken**: what you renamed, what you commented, which enums were
   defined or applied.
 - **Uncertainty**: if `anno_get_cross_references` returned nothing, say which
   of the three explanations in step 2 you could and could not rule out.
 
 ## Troubleshooting
 
-| Symptom | Fix |
+| Symptom | Correction |
 |---|---|
-| Comments land on regions too wide to be useful | `--max-span 2`; the default is 4096 bytes. |
-| A `JSR` or branch target got no comment at all | Flow instructions are capped at 2 bytes regardless of `--max-span`; `lookup` the target directly for the ROM routine name. |
+| Comments land on regions too wide to be useful | `--max-span 2`. The default is 4096 bytes. |
+| A `JSR` or branch target got no comment at all | `annotate` caps flow instructions at 2 bytes regardless of `--max-span`. `lookup` the target directly for the ROM routine name. |
 | The output is mostly header | `--no-header`. |
-| `lookup` printed only wide region lines and no specific name | Nothing in the four tables names that address; expected for the game's own code — take the region and name the address from what the code does with it. |
-| `lookup` printed `(not in memory map)` | Nothing covers it; check the address parsed as intended, since a bare `1234` reads as decimal. |
-| `no memmap.json; run: node driver.mjs memmap` | Restore the committed table with `git checkout` rather than rebuilding; the rebuild needs network and overwrites tracked data. |
-| `memmap` rewrote `memmap.json` and the diff is large or negative | A source was unreachable or changed; `git checkout` the file. |
+| `lookup` printed only wide region lines and no specific name | Nothing in the four tables names that address. This answer is normal for the game's own code. Take the region and name the address from what the code does with it. |
+| `lookup` printed `(not in memory map)` | Nothing covers it. Check the address parsed as intended, since a bare `1234` reads as decimal. |
+| `no memmap.json; run: node driver.mjs memmap` | Restore the committed table with `git checkout` rather than rebuilding. The rebuild needs network and overwrites tracked data. |
+| `memmap` rewrote `memmap.json` and the diff is large or negative | A source was unreachable or changed. `git checkout` the file. |

package/skills/c64-petcat/SKILL.md

@@ -14,11 +14,11 @@ S=src/skills/c64-petcat/scripts/petcat.mjs   # from the repo root
 node $S decode --image path/to/program.prg   # detokenize + resolve the SYS handover
 ```
 
-The script wraps `petcat` and nothing else. `--image` is required; `--out-dir`
-is optional, defaulting to the image's own directory, exactly like
-`acme-build`'s own `--out-dir` default. Both are resolved
-**workspace-relative** to the smallest ancestor directory containing both,
-before the request ever reaches the seam — the same resolution
+The script wraps `petcat` and nothing else. The script requires `--image`.
+`--out-dir` is optional, defaulting to the image's own directory, exactly like
+`acme-build`'s own `--out-dir` default. The script resolves both
+**workspace-relative** to the smallest ancestor directory containing both.
+This happens before the request ever reaches the seam — the same resolution
 `acme-build`/`c64-disk-access` already go through.
 
 Options: `--image PATH` `--out-dir DIR` `--json`.
@@ -67,15 +67,15 @@ posture `acme-build` already takes for its own assembler target.
 
 ## Failure shape
 
-A file `petcat` does not recognise as a BASIC program at all — including a
-missing file — is reported as `{"ok":false,"message":"..."}` with a
-non-zero exit code, never a success envelope carrying an empty or guessed
-verdict. `petcat` itself exits `0` even on garbage input; the seam's own
-classifier, not the exit code, is what decides success here.
+The seam reports a file `petcat` does not recognise as a BASIC program at
+all — including a missing file — as `{"ok":false,"message":"..."}` with a
+non-zero exit code. It never reports a success envelope carrying an empty
+or guessed verdict. `petcat` itself exits `0` even on garbage input. The
+seam's own classifier, not the exit code, is what decides success here.
 
 ## What this skill does NOT do
 
-- **No direct binary spawn.** `petcat` runs host-side; this script only ever
+- **No direct binary spawn.** `petcat` runs host-side. This script only ever
   constructs a typed request and reads the produced listing file back off
   the shared workspace tree — the host-tool execution seam is the only
   route.