@henols/c64-re-tools 0.2.1 → 0.2.3

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

@@ -1,6 +1,6 @@
 ---
 name: c64-memory-mapping
-description: Look up what any C64 address means and turn raw 6502 disassembly into documented assembly, by resolving every address against the C64 memory map, KERNAL ROM routine list, canonical assembler symbols, and per-bit VIC-II/SID/CIA register tables. Use when asked to annotate or comment assembly, document a disassembly listing, or look up an address like $D020, $EA24 or $FFD2.
+description: Look up what any C64 address means and turn raw 6502 disassembly into documented assembly, by resolving every address against the C64 memory map, KERNAL ROM routine list, canonical assembler symbols, and per-bit VIC-II/SID/CIA register tables. Use when asked to annotate or comment assembly against the published memory map, document a disassembly listing by resolving every address it touches, or look up an address like $D020, $EA24 or $FFD2.
 ---
 
 # C64 memory mapping & annotated disassembly
@@ -9,7 +9,7 @@ Look up what a C64 address means, and document a 6502 listing by resolving every
 address it touches. One script does both, offline, anywhere Node ≥18 runs:
 
 ```bash
-D=.claude/skills/c64-memory-mapping/scripts/driver.mjs   # relative to the repo root
+D=src/skills/c64-memory-mapping/scripts/driver.mjs   # relative to the repo root
 
 node $D lookup '$D011' '$FFD2'      # what lives at an address
 node $D annotate --file game.asm    # document a listing or .asm file
@@ -182,44 +182,440 @@ 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
 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. Because it mutates the repo, `memmap` belongs behind a GSD
-command (`/gsd-quick`), per this project's GSD Workflow Enforcement rule — it is
-not a read-only lookup like `lookup` and `annotate`.
+were expecting. **`memmap` mutates tracked files** — unlike `lookup` and
+`annotate`, which are read-only — so run it deliberately, on a clean working
+tree, and review the diff before you commit it.
 
 ## Feeding the enum generator
 
 `memmap.json`'s structured `bits` entries are the source of the curated register bit-name table used
-to generate program-specific enums for regenerator2000's annotation store (R2000-13): register
+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 `.claude/mcp/vice/r2000-regbits-gen.ts`; its committed output is
-`.claude/mcp/vice/r2000-regbits.json`; and that output is **digest-pinned** to `memmap.json` — a
-`node r2000-regbits-gen.ts` run compares its own fresh build against the committed file, and CI fails
+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
+`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.
 
 **The honest gap:** only 29 of this file's 959 entries carry a structured `bits` array. `$D015`,
 `$D017`, `$D01A` and `$D01B`–`$D01D` — the sprite-plane bitmask registers a real game writes
 constantly — are **not** among those 29, so the enum generator supplies them from its own curated
-override table (`OVERRIDES` in `r2000-regbits-gen.ts`), not from this file. Widening `memmap.json`'s
+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
 the digit `0`) so those registers get a real structured entry here is separate work belonging to this
 skill, not the generator.
 
-**Installing those bit names into a project's own disassembly:** the table above only builds
-`r2000-regbits.json` — turning a specific project's register *writes* into named enum variants is a
-separate, later step, once a `.regen2000proj` already exists (`r2000 bootstrap`, see
-`c64-program-recon`):
+**Installing those bit names into a program's own disassembly — dated withdrawal, 2026-08-29.** The
+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
+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
+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
+program's own disassembly, created one enum variant per DISTINCT value actually written at each
+matching immediate-load address (named from the curated table above), and printed
+total/paired/unpaired register-store counts plus a per-enum variant count.
+
+**The by-hand route is open in the meantime, and it is the same one this skill already documents
+for any other enum.** `anno_create_project_enum` defines the variants and `anno_apply_enum_usage`
+binds one to the accessing instruction's address — see "Name it" and "Document it" below. That is
+manual where `gen-enums` was bulk, but it writes exactly the same rows into the store.
+
+## Reference material for annotating
+
+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.
+
+### Classifying every region of an annotation project
+
+Everything above answers *what does this published address mean*. This section
+answers a different question over the same map: **given a loaded binary in an
+annotation project, what is each region of it — code, or one of eight kinds of
+data?**
+
+**This is the static answer, taken from bytes on disk.** `c64-program-recon`
+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
+the thing that overrules it.
+
+When a binary is first loaded, the auto-analyzer traces reachable code from the
+entry point and marks it **Code**. Everything else is **Undefined** — not
+"data", just unexplored. The job here is to walk the Undefined regions, work
+out what each one actually is, and set it.
+
+#### The one mistake that matters more than the rest
+
+**Never disassemble a region without concrete proof that it executes.** Random
+data routinely disassembles into plausible-looking instruction sequences, and
+that is *not* evidence of code — it is a property of the 6502's dense opcode
+map. A region earns the Code type only when at least one of these holds:
+
+- **It is a `JSR`/`JMP` target.** Already-analysed code contains `JSR $addr` or
+  `JMP $addr` landing in it. Check with `anno_get_cross_references` — it names
+  the `image` as well as the `store`, takes a REQUIRED `max_results`, and unions
+  three sources on every call without caching any of them: the instructions
+  decoded fresh out of every range typed `code`, the typed split ADDRESS tables
+  (the `_address` forms produce cross-references and the `_word` forms do not),
+  and the stored rows, which exist because a computed dispatch cannot be
+  recovered from bytes at all.
+- **It is a branch target** of an already-analysed `BNE`/`BEQ`/`BCC`/`BCS`/
+  `BPL`/`BMI`/`BVC`/`BVS`.
+- **It is a vector or handler**: its address appears in a vector table
+  (`$FFFA`–`$FFFF`, `$0314`–`$0319`), in an `address` or split-address block,
+  or in a jump table reached by `JMP ($addr)`.
+- **A human says so explicitly.**
+
+None of those? Leave it **Undefined**, or classify it as data — even when the
+bytes disassemble cleanly. "It looked like code" is how a sprite sheet becomes
+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.
+
+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
+   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
+   the one you read and judged.
+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
+   met the proof bar.
+
+#### Scope, and reading a region
+
+1. `anno_get_binary_info` first. Keep `origin`, `size`, `system`, `filename`,
+   `description` and `may_contain_undocumented_opcodes`.
+   - `system` names the target machine. On a C64 the rest of this skill *is*
+     the memory map you need — `lookup` any address a region touches before
+     guessing at it.
+   - `filename` and `description` are the software context. A known title, a
+     known music driver or a known packer changes what a region is likely to
+     be.
+   - `may_contain_undocumented_opcodes: true` means illegal opcodes (`LAX`,
+     `SAX`, `SLO`, `DCP`, `ISC`) may appear. **Do not misclassify those as
+     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
+   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.
+   Chunks of **256–512 bytes** are the practical working size for
+   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
+  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
+  instructions out of later.
+- **Data**: batch the `anno_set_data_type` calls through
+  `anno_batch_execute`. A real classification pass is dozens of ranges, and one
+  batch is one open/commit/close rather than dozens.
+- **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
+  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
+  the entry-address pairs it read before and the pairs each surviving remainder
+  reads now. A split table's entries re-pair as a function of the row's start
+  **and** its length, so a fragment decodes to different 16-bit values than the
+  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.
+
+Example of a valid data-only batch, then the code regions separately:
 
-```bash
-npx -y @henols/vice-mcp r2000 gen-enums game.regen2000proj                            # npm install
-node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 gen-enums game.regen2000proj  # in-repo/plugin
+```
+anno_batch_execute:
+  - anno_set_data_type  start=2304  end=2367  data_type="byte"
+  - anno_set_data_type  start=2368  end=2431  data_type="petscii"
+then: anno_disassemble address=2049          # read, writes nothing
+then: anno_set_data_type start=2049 end=2303 data_type="code"
+then: anno_get_blocks max_results=500        # refresh
 ```
 
-`r2000 gen-enums` requires an EXISTING `.regen2000proj` — it does not bootstrap one from a raw
-input. It reads the project's own disassembly, creates one enum variant per DISTINCT value actually
-written at each matching immediate-load address (named from the curated table above), and prints
-total/paired/unpaired register-store counts plus a per-enum variant count. It exits non-zero, naming
-the reason, when either of its two internal search passes hits its own 10000-row ceiling — pass
-`--max-results` to raise that ceiling for a program whose store exceeds it.
+#### The block types
+
+| 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. |
+| 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 |
+| PETSCII text | `petscii` | PETSCII strings: messages, prompts, anything bound for `$FFD2` |
+| Screencode text | `screencode` | Text written straight to screen RAM (`$0400`–`$07E7`) |
+| Lo/Hi address | `lo_hi_address` | Split address table, low bytes first. Even byte count required |
+| Hi/Lo address | `hi_lo_address` | Split address table, high bytes first. Even byte count required |
+| Lo/Hi word | `lo_hi_word` | Split word table, low half first — e.g. a SID frequency table |
+| Hi/Lo word | `hi_lo_word` | Split word table, high half first |
+| External file | `external_file` | Large blobs to export as-is: SID tunes, bitmaps, charsets |
+| Undefined | `undefined` | Reset to unknown. The honest answer for a region you cannot place |
+
+#### 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
+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`.
+
+**Address tables** — byte pairs that read as little-endian addresses landing
+*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
+bytes and one of plausible high bytes, referenced separately:
+`LDA lo,X / STA ptr / LDA hi,X / STA ptr+1 / JMP (ptr)`. Recombine the halves
+and check the addresses are real. Lo/Hi (low half first) is the commoner form
+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)
+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
+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
+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
+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
+the answer upstream reached for was a `toggle_splitter` call this project never
+exposed.
+
+**The annotation store does not do that.** It never joins two rows of its own
+accord: adjacent same-type ranges stay two rows, and `anno_get_blocks` reports
+them as two. A range you name that *spans* several existing rows still collapses
+to the one row you asked for — that is you asking, not the store deciding — and
+partial overlaps split and preserve the addresses outside your range rather than
+swallowing them.
+
+So the working rules are now the ordinary ones:
+
+- **Do** rely on the block listing to tell two adjacent same-type tables apart.
+  It can, provided you typed them as two calls rather than one spanning call.
+- **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.
+- **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.
+
+#### Labelling, and the report
+
+Name what you classified — `anno_set_label_name` on entry points, tables and
+strings — and comment it with `anno_set_comment` (`"line"` above,
+`"side"` beside). For the conventions to name things *by*, and for the
+comment-block format to use on a subroutine, follow the absorbed routine
+procedure in `src/skills/c64-program-recon/SKILL.md`.
+
+Then report, and mean it:
+
+- Total blocks by type.
+- Notable findings — "three PETSCII strings", "a lo/hi jump table at `$1200`".
+- **Every region still uncertain or still Undefined, by address.** This is the
+  part that makes the pass reusable. A classification report with no uncertain
+  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
+  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. |
+| 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. |
+| Two tables you classified separately show up as one block | The adjacent-table limitation above. Not your error. |
+| Text renders as garbage on screen but fine through CHROUT | It is PETSCII, typed as screencode — or the reverse. |
+
+### What a symbol in the store actually represents
+
+`lookup` at the top of this page answers what a **published** address means —
+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.
+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.
+
+#### 1. Target and context
+
+- **Always start from an explicit address**, `$XXXX` or its decimal
+  equivalent. There is no editor cursor in this project's route, and upstream's
+  own text forbids relying on one anyway. `anno_get_address_details` composes
+  the symbol, comments, block type and cross-references for one explicit
+  address in a single call.
+- `anno_get_binary_info` for `system`, `filename`, `description` and
+  `may_contain_undocumented_opcodes`. `filename` and `description` are how a
+  symbol gets a *domain* name — `lap_counter` in a racing game, `lives` in a
+  platformer — instead of a generic one. With undocumented opcodes in play,
+  remember that `LAX`, `SAX` and `DCP` have real read/write side effects that
+  belong in the data-flow picture.
+
+#### 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
+instruction at each site, because the instruction is the evidence:
+
+- **Writes**: `STA`, `STX`, `STY`
+- **Reads**: `LDA`, `LDX`, `LDY`, `BIT`, `CMP`, `CPX`, `CPY`, `ADC`, `SBC`
+- **Read-modify-write**: `INC`, `DEC`, `ASL`, `LSR`, `ROL`, `ROR`
+
+**Zero cross-references is a result, not a dead end.** Three explanations, in
+order of likelihood:
+
+1. It is reached **indirectly**. Check whether it is in the zero page
+   (`$00`–`$FF`) and whether nearby code uses `($addr),Y` or `($addr,X)`. An
+   indirect pointer's *target* has no direct reference by construction.
+2. It is a **well-known system address** the disassembler does not cross-
+   reference. Run `lookup` on it — that is exactly the case the four tables
+   above cover.
+3. It is genuinely **dead**: unused variable, or code no longer reached. Say so
+   in the report rather than inventing a purpose.
+
+#### 3. Place it
+
+**A hardware register?** `lookup` it. If one of the four tables names it, take
+the published name and the per-bit breakdown with it — that reading rests on
+hardware and holds for any program.
+
+**Inside a well-known global block?** Screen RAM (`$0400`–`$07E7`), colour RAM
+(`$D800`–`$DBFF`), a sprite pointer at VM+`$03F8`. **Do not skip these as
+"obvious".** Name them systematically from the base plus the offset —
+`SCREEN_ROW03_COL12` — so contiguous structures read as structures instead of a
+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
+`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`
+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 =
+VISIBLE`) and apply it with `anno_apply_enum_usage` so every bitmask test
+reads as words rather than hex.
+
+**A counter or index?** `INC`/`DEC` inside a loop, compared against a limit
+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
+real `description` if none matches, then apply it to every instruction reading
+or writing the variable.
+
+#### 4. Name it
+
+| Symbol kind | Convention | Example |
+|---|---|---|
+| Zero-page variable | `zp_` prefix | `zp_player_lives`, `zp_delay_timer` |
+| Zero-page pointer | `zp_ptr_` prefix | `zp_ptr_screen`, `zp_ptr_dest` |
+| RAM variable | `snake_case` | `score_hi`, `current_level` |
+| Pointer / vector | `ptr_` / `vec_` prefix | `ptr_screen`, `vec_irq` |
+| Hardware register | `UPPER_SNAKE` | `VIC_SPR0_X`, `SID_FREQ_LO1` |
+| Constant / address | `UPPER_SNAKE` | `SCREEN_RAM`, `CHR_ROM_BASE` |
+| Routine entry point | `snake_case` | `init_screen`, `draw_sprite` |
+| External ROM call | `KERNAL_` / `OS_` | `KERNAL_CHROUT`, `KERNAL_CLRCHN` |
+
+> **The zero-page rule overrides all of the above.** An address at or below
+> `$FF` **must** carry the `zp_` prefix — a zero-page pointer becomes
+> `zp_ptr_`, a zero-page flag becomes `zp_is_active`, and a zero-page OS
+> variable becomes `zp_`-prefixed too. The prefix makes the addressing mode
+> visible at every use site, which is the whole point.
+
+Apply it with `anno_set_label_name`.
+
+#### 5. Document it
+
+- `anno_set_comment` `"line"` at the definition: the range it occupies, its
+  purpose, its bitfield layout if it has one.
+- `anno_set_comment` `"side"` at the interesting *uses*: why this read, why
+  this write. "Reset life counter" beside a `STA` is worth more than any name.
+- Define and apply enums where the values form a set (above).
+
+**The pointer-formatting step this project does not have.** Where a pointer is
+initialised by immediate loads of a target's low and high bytes — `LDA #<target
+/ STA ptr / LDA #>target / STA ptr+1` — upstream calls `set_immediate_format`
+twice to turn both immediates into a single readable symbol reference. **That
+call is not exposed on this project's surface.** The rule it would serve — "every branch,
+`JSR`/`JMP` and data reference goes through a symbol, so code can move" — still
+supplies the criterion, and the per-call disposition is
+recorded in the manifest named in the attribution header above. Until then,
+reconstruct the target by hand and put it in a side comment on both
+instructions — `; low byte of ptr_sprite_table ($C240)` — so the pointer is
+still readable even though the store cannot format it.
+
+#### 6. Report
+
+- **Address** and its current label.
+- **Classification**: flag, counter, pointer, hardware register, state
+  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
+  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
 

package/skills/c64-memory-mapping/scripts/driver.mjs

@@ -21,7 +21,7 @@ import { dirname, join, resolve } from "node:path";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 // memmap.json lives at the skill root, one level up from scripts/, by decision
-// (D-03): only .mjs modules move into scripts/, data files stay put.
+// only .mjs modules move into scripts/, data files stay put.
 const MEMMAP_JSON = join(HERE, "..", "memmap.json");
 
 // Reference tables, merged into one address -> meaning index. `kind` selects the

package/skills/c64-petcat/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: c64-petcat
+description: Convert a Commodore .prg between PETSCII and ASCII, detokenize a BASIC program into readable text, and read the machine-code handover address out of its startup line, using VICE's own petcat conversion tool as the reference implementation. Use when asked to detokenize a BASIC listing, list what a BASIC stub does, find where a program hands over to machine code, or convert C64 text between PETSCII and ASCII.
+---
+
+# Detokenizing BASIC with petcat
+
+One capability, one script, one binary (`petcat`) reached only through the
+host-tool execution seam:
+
+```bash
+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
+`acme-build`/`c64-disk-access` already go through.
+
+Options: `--image PATH` `--out-dir DIR` `--json`.
+
+## Detokenizing and resolving the handover point
+
+```bash
+node $S decode --image game.prg --json
+```
+
+Prints the seam's response verbatim as one line of JSON:
+
+```json
+{"ok":true,"tool":"petcat.decode","exitStatus":0,"results":[{"path":"/abs/path/game.bas.txt","sha256":"...","byteLength":21}],"stderrTail":"","entrypoint":2064,"entrypointReason":"literal SYS argument on BASIC line 10: sys2064"}
+```
+
+`results[0].path` names the detokenized listing file the seam wrote —
+`petcat`'s own decoded text, captured and digested. The listing itself never
+crosses inline, no matter how short it is.
+
+Two fields carry the handover verdict, and BOTH are present on every
+`ok: true` response:
+
+- **`entrypoint`** — a number when the program's `SYS` argument is a literal
+  decimal value, `null` otherwise.
+- **`entrypointReason`** — always a string. When `entrypoint` is a number, it
+  names the BASIC line the value came from. When `entrypoint` is `null`, it
+  quotes the unresolved expression verbatim, or states that the listing
+  carries no handover instruction at all.
+
+A `null` entrypoint is **not a failure** — it is a resolved "no": the tool
+detokenized the program correctly and correctly concluded the entry point is
+not a static address. Reported this way, never as a guessed address: a
+guessed entry point is expensive downstream, spent on a disassembler that
+then has nothing real to work from.
+
+Non-JSON mode prints the same information as two lines — the resolved entry
+point (or the decline and its reason) and the listing file's path — never the
+listing's contents inline.
+
+## The BASIC dialect
+
+Fixed server-side, not a flag on this script or a field on the wire — this
+project's target is fixed to C64 BASIC V2.0 everywhere already, the same
+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.
+
+## What this skill does NOT do
+
+- **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.
+- **No guessed entry point.** A computed or otherwise unresolvable `SYS`
+  argument is always reported as a named decline with `entrypoint: null` —
+  never a fallback value, never an inline listing scan for "something that
+  looks like an address".
+- **No emulator dependency.** This skill names no VICE emulator tool at all
+  — it works entirely on files, never on a running machine, by construction.