c64-kb 0.17.0

package/docs/CONVENTIONS-archetypes.md

@@ -0,0 +1,158 @@
+# Archetype Reference Conventions
+
+Archetype docs describe the shapes a C64 game or demo takes: the vertical
+shooter, the single-screen platformer, the text adventure, the crack
+intro. Today there are two: `docs/game-design/c64-game-archetypes.md`
+for kind `game` and `docs/demo-design/intro-cracktro-patterns.md` for
+kind `demo`. Each H2 in them is one `Archetype` node, and two lines under
+the H2 become its edges: the technique fingerprint (`FEATURES`, Archetype
+to Technique) and the common pitfalls (`RISKS`, Archetype to Pitfall).
+`c64_game_briefing` and `c64_demo_briefing` read both.
+
+The marker `<!-- doc-type: archetype-reference -->` MUST appear in the
+first 10 lines for the extractor to process the file.
+
+## File-level frontmatter
+
+```yaml
+---
+kind: game                    # game | demo; optional, defaults to game
+---
+```
+
+`kind` applies to every archetype in the file. Any other word refuses the
+whole file with a warning, the way an unknown technique category does.
+
+`kind: demo` is the demo forms: the source is
+`docs/demo-design/intro-cracktro-patterns.md`, whose crack intro, demo
+intro, pack intro, dentro and 4K party intro are each one `Archetype`
+node. A form is the node; the parts a multi-part production is cut into
+are not a node type, and a page must not try to make them one. The entry
+format, the edge lines and the ingest counts are the same as for games,
+and `c64_demo_briefing` with `archetype` reads the node exactly as
+`c64_game_briefing` does. Archetype names are unique across every
+archetype page, not just within one: the ingest merges the node on its
+name alone, so a name repeated on a second page overwrites the first
+page's node (its kind, title and source) and both pages' edges land on
+the one node. The extractor only refuses a repeat within a single file.
+`archetype_not_found` lists the names of both kinds.
+
+## Archetype entries
+
+The H2 is the human-readable title, free-form, and is NOT the node name.
+Technique and pitfall H2s carry `## name — Title`; archetype titles have
+slashes and hyphens in them ("Text Adventure / Parser-Driven",
+"Beat-em-up"), so the name is a separate line instead. The first line
+after the H2 is:
+
+```
+## Vertical Shmup
+
+**Archetype:** `vertical_shmup`
+```
+
+- `vertical_shmup` is the snake_case node name (`Archetype.name`), unique
+  in the file. Backticks are optional.
+- An H2 with no `**Archetype:**` line is not an archetype: it is warned
+  about and skipped, so a prose section cannot become a node by accident.
+- A second H2 with the same name is warned about and skipped.
+
+Two more lines under the H2 are the edge sources. Both existed on the page
+before the graph read them; the format did not change.
+
+```
+**Technique fingerprint:** `soft_scroll_v`, `sprite_multiplex_24`, `stable_raster_irq`
+**Common pitfalls:** `sprite_dma_overflow`, `badline_cycle_loss`
+```
+
+- Comma-separated, backticks optional. Each word must be a snake_case
+  name. A word that is not one is refused at extract time with a warning
+  and never reaches the graph.
+- `**Technique fingerprint:**` makes one `FEATURES` edge per word to the
+  `Technique` of that name. `**Common pitfalls:**` makes one `RISKS` edge
+  per word to the `Pitfall` of that name.
+- Both ends are MATCHed, never MERGEd. A name that matches no node is
+  dropped at link time with a `[falkor]` warning and counted in the ingest
+  summary (`archetype_features: … dropped`, `archetype_risks: … dropped`),
+  beside `triggered_by` and `mitigated_by`. It is never silently dropped
+  and it never creates a stub node. Fix the page, do not ignore the count.
+- Only name a technique the archetype's own prose supports. The
+  fingerprint is what `c64_game_briefing` forces into a plan for that
+  archetype, so a name here is a claim that every such game needs it.
+
+One more line routes a brief that names no archetype (schema 30):
+
+```
+**Brief words:** vertical shooter, vertically scrolling, road shooter, road, car, spy hunter
+```
+
+- Comma-separated words or phrases, backticks optional. The extractor
+  lowers the case, drops apostrophes and reads any other run of
+  non-letters and non-digits as one space, so "Beat-'em-up" is stored as
+  `beat em up`. It becomes the `brief_words` property of the node, not an
+  edge; an entry with no line stores an empty list.
+- Only kind `game` is routed. `c64_game_briefing` with no `archetype`
+  normalises the brief the same way and counts, per archetype, the
+  distinct words it contains, a plural "s" or "es" allowed. The archetype
+  with the most wins; a tie or no match routes nowhere.
+- Choose words that name the genre, not a technique. A word on two
+  entries cancels itself out ("puzzle" is on `puzzle` and `action_puzzle`,
+  so "Boulder Dash puzzle" still routes by "boulder dash"). A word that
+  every brief carries ("game", "screen", "columns") routes everything.
+- The line is how a genre reaches its archetype. It is data here, so no
+  genre word or game title is spelled in the briefing code.
+
+One more optional line names the playable starter for the archetype
+(schema 31):
+
+```
+**Starter:** `shmup-vertical`
+```
+
+- The word is a directory in `templates/` (lower case, digits, hyphens).
+  It becomes the Archetype's `starter` property, and `c64_game_briefing`
+  or `c64_demo_briefing` returns it in `archetype.starter` and tells the
+  agent to run `npm run new-project -- <starter> <dir>` in this checkout.
+- The extractor does not read the tree. `test/extract-archetype-starters.test.ts`
+  fails when a starter named on a real page has no `Makefile` and
+  `expect.json` in `templates/`.
+- Name a starter only where it is a game or effect of that archetype.
+  An archetype with no fitting starter carries no line.
+
+The other lines on the page (`**Reference titles:**`, `**Modern
+examples:**`) are prose for the reader and are not read by the extractor.
+
+## What the briefing does with it
+
+`c64_game_briefing` with `archetype: "vertical_shmup"` (also accepted:
+"Vertical Shmup", "vertical-shmup") looks the node up. Its `FEATURES`
+targets are proposed regardless of the keyword scorer's verdict and are
+exempt from the three-per-category cap; its `RISKS` targets are added to
+the pitfalls when no proposed technique already surfaced them; its title
+is appended to the search text. The output repeats what the graph held
+in an `archetype` field.
+
+With no `archetype`, `c64_game_briefing` routes the brief by the brief
+words above and does the same with the winner; the output's
+`archetype.inferred_from` lists the words that chose it, and the text
+says so. A named `archetype` always wins over the words.
+
+A name the graph does not have returns `archetype_not_found` with the
+known names and builds the rest of the plan from the description alone.
+The briefing does not guess a near match. Only a graph with no
+`Archetype` nodes at all falls back to a small built-in table; with this
+page ingested, the page is the source of truth.
+
+## Section structure inside an Archetype
+
+After the H2 and the `**Archetype:**` line, free-form prose covering:
+
+1. **What it is** — the defining mechanic and the scene tradition
+2. **Where the budget goes** — the technical constraint that shapes it
+3. **How the pieces fit** — sprites, scroll, SID, loading, in plain terms
+4. The `**Technique fingerprint:**`, `**Common pitfalls:**` and
+   `**Brief words:**` lines
+5. `**Reference titles:**` and `**Modern examples:**`
+
+H3 inside an archetype is fine; the extractor reads only the H2 and the
+five bold lines (`**Brief words:**` and `**Starter:**` are optional).

package/docs/CONVENTIONS-failures.md

@@ -0,0 +1,46 @@
+# Failure Pattern Reference Conventions
+
+Failure-pattern docs live in `docs/c64-failure-patterns.md` (single
+file). Each entry is one CrashPattern node, keyed by `symptom`.
+
+The marker `<!-- doc-type: failure-reference -->` MUST appear in the
+first 10 lines for the extractor to process the file.
+
+## CrashPattern entries
+
+Every CrashPattern in the doc gets an H2 in this exact format:
+
+```
+## black_screen — Display goes solid color or stays $00
+```
+
+Breakdown:
+- `## ` (H2)
+- `black_screen` — snake_case symptom canonical name
+- ` — ` — em-dash separator
+- Free-form one-line description
+
+Following each H2 block:
+
+```
+**Likely causes:** vic_bank_misconfigured, screen_pointer_outside_bank, di_d011_blanked
+**Diagnosis steps:** Check $D018 video matrix pointer; verify $DD00 VIC bank bits; inspect $D011 bit 4 (blank).
+**Caused by registers:** D011, D018, DD00
+**Caused by kernal:** SCREEN
+**Caused by techniques:** vic_bank_select
+```
+
+`Likely causes` is a comma-separated list of free-form cause tags
+(short snake_case strings). Stored as a JSON-encoded array on the
+node. NOT graph edges — graph edges go through the `Caused by …`
+lines.
+
+`Caused by …` lines emit CAUSED_BY edges, same structure as Pitfall's
+TRIGGERED_BY.
+
+## Section structure inside a CrashPattern
+
+1. **Visible/audible symptom** (1–2 sentences, vivid)
+2. **Likely causes** (parallel to the metadata list, expanded)
+3. **Diagnosis steps** (numbered, concrete — what to inspect in vice-mcp)
+4. **Common fixes** (1–3 paragraphs)

package/docs/CONVENTIONS-game-designs.md

@@ -0,0 +1,75 @@
+# Game Design Conventions
+
+A game design page describes one whole game: which archetype it is, which
+recipe builds it, which techniques it runs in each phase, and, once the
+built game has been timed, what its frame took. Each H2 is one
+`GameDesign` node (schema 28). `c64_plan_budget` takes a design name and
+budgets its phases; `c64_game_briefing` lists the designs of the archetype
+it resolved.
+
+Pages live in `docs/game-design/designs/`, one design per file. The marker
+`<!-- doc-type: game-design -->` MUST appear in the first 10 lines.
+
+## The lines under each H2
+
+```
+## Single-screen platformer scaffold (Oscar64)
+
+**Game design:** `platformer_scaffold_oscar64`
+**Instance of:** single_screen_platformer
+**Realised by:** oscar64-platformer-scaffold
+**Region:** both
+**Composes:** tile_map_render (init), decimal_print, lfsr_random (init), kernal_file_write_seq (transition)
+**Measured frame:** play pal worst=8693 typical=4966; play ntsc worst=10287 typical=6628 (measured-vice, CIA1 timer B around the loop body, recipes/oscar64/platformer-scaffold.md "Expected output")
+```
+
+| Line | Required | Becomes |
+|---|---|---|
+| `**Game design:**` | yes | the node's `name`, snake_case. Without it the H2 is prose and is not ingested; with a `**Composes:**` line but no name, the extractor warns. |
+| `**Instance of:**` | no | `INSTANCE_OF` edges to Archetype names from `c64-game-archetypes.md`. |
+| `**Realised by:**` | no | `REALISED_BY` edges to canonical recipe names (`<toolchain>-<recipe>`). |
+| `**Region:**` | no | `PAL`, `NTSC` or `both`: the region the budget uses when the caller names none. |
+| `**Composes:**` | yes | `COMPOSES` edges, one per technique and phase. |
+| `**Measured frame:**` | no | the node's `measured` property. More than one line is allowed. |
+
+Every name is MATCHed at ingest, never created. A name that matches no
+node is warned about and counted in the ingest summary as dropped.
+
+## Composes
+
+A comma-separated list of Technique names. A name alone runs in `play`,
+the frame loop. `name (init)` runs once before play; `name (transition)`
+runs between plays (a level load, a game-over save). A technique used in
+two phases is listed twice, once per phase. Any other phase word is
+refused with a warning.
+
+List what the listing runs, not what the recipe's frontmatter says. Read
+the frame loop. When the two differ, fix the frontmatter or say why in the
+page's prose.
+
+## Measured frame
+
+`<phase> <pal|ntsc> worst=N [typical=N]`, entries separated by `;`, then
+a parenthetical: the basis word first (`measured-vice`, `derived-listing`,
+`arithmetic`, `estimated`), then the instrument and where the figures are.
+A malformed line is refused whole, because part of it would read as the
+whole measurement.
+
+- `worst` is the largest frame the run recorded, in CPU cycles.
+- `typical` is a common frame. Say in prose what it is: a mean, or one
+  frame's reading.
+- State what the timed region holds. A figure that leaves out the HUD, the
+  IRQ or the badline stalls says so in prose under the lines.
+- Figures come from the realising recipe's page, with its rung. A figure
+  this repo did not measure is `estimated` and names its source.
+
+`c64_plan_budget` prints each measured figure beside its prediction for
+the same phase and region. The two answer different questions: the
+prediction adds up each technique's own recipe; the measurement is this
+game's listing.
+
+## What is not here
+
+No claims, zero page or memory lines yet: those are per-technique
+(`CONVENTIONS-techniques.md`) and per-recipe. `c64_check_compatibility`
+takes the technique list.

package/docs/CONVENTIONS-hardware-reference.md

@@ -0,0 +1,184 @@
+# Hardware Reference Conventions
+
+All hardware reference docs in `docs/` follow these structural patterns so
+the entity extractor in `src/graph/extract.ts` can parse them. Deviation
+breaks the graph build.
+
+## File-level frontmatter (optional)
+
+```yaml
+---
+chip: VIC-II   # for chip refs only
+region: PAL    # for region-specific docs only
+---
+```
+
+## Section structure
+
+Top of file: `# Doc Title` (H1). One H1 per doc.
+
+Followed by an "Overview" section (H2) describing what's covered.
+
+Followed by a "Quick reference" section (H2) with tables.
+
+Followed by detail sections (H2 per topic, H3 per item).
+
+Followed by a "Pitfalls" cross-reference section (H2) at end.
+
+## Register definitions
+
+Every register gets an H3 in this exact format:
+
+```
+### $D011 — D011 — Screen Control Register 1 (RW)
+```
+
+Breakdown:
+- `### ` (H3) at start of line
+- ` $D011 ` — hex address, dollar-prefix, 4 hex digits, surrounded by spaces
+- ` — ` — em-dash separator (Unicode U+2014)
+- `D011` — canonical register name (no spaces; uppercase letters + digits)
+- ` — ` — em-dash separator
+- `Screen Control Register 1` — description (free-form)
+- ` (` — opening paren
+- `RW` — one of `R`, `W`, or `RW`
+- `)` — closing paren
+
+Following each register H3 block, an optional `**Chip:** VIC-II` line
+identifies the owning chip. If absent, the extractor falls back to the
+doc's frontmatter `chip` field.
+
+Bit definitions use a sub-H4 or a table. Example:
+
+```
+### $D011 — D011 — Screen Control Register 1 (RW)
+
+**Chip:** VIC-II
+
+| Bit | Name | Description |
+|-----|------|-------------|
+| 7   | RST8 | Bit 8 of raster line |
+| 6   | ECM  | Extended color mode |
+| 5   | BMM  | Bitmap mode |
+```
+
+## KERNAL routine definitions
+
+Every KERNAL routine gets an H3 in this exact format:
+
+```
+### $FFD2 — CHROUT — Output a character
+```
+
+Breakdown:
+- `### ` (H3) at start of line
+- ` $FFD2 ` — hex address (jump-table entry), 4 hex digits
+- ` — ` — em-dash separator
+- `CHROUT` — canonical routine name (uppercase letters)
+- ` — ` — em-dash separator
+- description
+
+Following each routine H3, optional structured fields:
+
+```
+**Input:** A = byte to print
+**Output:** None
+**Affects:** A
+**Pairs with:** CHROUT
+**Description:** ...
+```
+
+The `**Pairs with:**` marker is what `PAIRS_WITH` graph edges are extracted from.
+Multiple pair names are comma-separated.
+
+After `**Affects:**`, one or more `**Clobbers zero page:**` lines (schema
+26) state the zero-page bytes the routine writes. Each becomes a
+`CLOBBERS_ZP` edge to the `zero_page` HardwareUnit:
+
+```
+**Clobbers zero page:** $B8-$BA (may; ROM walk from $FFBA, power-on vectors)
+**Clobbers zero page:** $B8-$BA (must; VICE x64sc store trace, SETLFS 2,8,2)
+```
+
+- The value is `<bytes> (<bound>; <basis>)`. Bytes are `$XX` or
+  `$XX-$YY`, comma-separated, anywhere in `$00-$FF`, or `none`.
+- `may` lines are not hand-written. `node scripts/kernal-zp-walk.ts
+  --write` sets one per routine from a static walk of the 901227-03 ROM;
+  `npm test` runs its `--check` and fails on any difference.
+- `must` lines come from `node scripts/kernal-zp-trace.ts --write`, which
+  runs `scripts/kernal-zp-trace.asm` in VICE with a store trace. The basis
+  names the traced call. Every must byte has to lie inside the may set.
+- A line that does not parse is warned about at ingest and dropped.
+
+## Memory region definitions
+
+Every memory region gets an H3 in this exact format:
+
+```
+### $0400-$07FF — Default Screen RAM
+```
+
+Breakdown:
+- `### ` (H3) at start of line
+- ` $START-$END ` — start/end hex addresses, 4 hex digits each, separated by `-`
+- ` — ` — em-dash separator
+- description
+
+Following each H3, optional structured fields:
+
+```
+**Default use:** Screen character codes (40x25 = 1000 bytes)
+**Bank-switchable:** No
+**Notes:** ...
+```
+
+## Opcode definitions (for 6510-cpu-reference.md and 6502-illegal-opcodes.md)
+
+Every opcode gets an H3 in this exact format:
+
+```
+### $A9 — LDA #imm — Load Accumulator immediate
+```
+
+Breakdown:
+- `### ` (H3) at start of line
+- ` $A9 ` — opcode byte, 2 hex digits
+- ` — ` — em-dash separator
+- `LDA #imm` — mnemonic with addressing mode
+- ` — ` — em-dash separator
+- description
+
+Following each opcode H3:
+
+```
+**Cycles:** 2
+**Flags:** N Z
+**Legal:** yes      (or "no" for illegal opcodes — defaults to yes if absent)
+**Page-cross:** +1  (or absent if no page-cross penalty)
+```
+
+## Pitfalls cross-reference
+
+End-of-doc H2 `## Pitfalls` with bullet list:
+
+```
+## Pitfalls
+
+- **$D012 raster wrap**: comparing $D012 against >=256 requires combining
+  with $D011 bit 7 — see `d012_wrap_around` in
+  [pitfalls/raster-and-badline.md](pitfalls/raster-and-badline.md).
+- ...
+```
+
+## Cross-references between docs
+
+Use relative markdown links: `[VIC-II screen mode](vic-ii-reference.md#screen-modes)`.
+
+## File-end checklist
+
+Every hardware reference doc must end with this comment so the extractor
+can quickly verify it's a hardware-reference doc:
+
+```
+<!-- doc-type: hardware-reference -->
+```

package/docs/CONVENTIONS-pitfalls.md

@@ -0,0 +1,91 @@
+# Pitfall Reference Conventions
+
+Pitfall docs live in `docs/pitfalls/<category>.md`. Each doc covers ONE
+category (raster, sprite, sid, region, kernal, banking, cpu, loader,
+input, render, scroll, cia, maths, logic) and contains multiple Pitfall
+entries as H2 sections. The extractor parses each H2 as one Pitfall
+node. The category is carried into the node as written; the extractor
+keeps no whitelist, so this list is the set in use, not a constraint it
+enforces (it read eight names until 2026-09-22 while twelve docs
+existed; maths and logic were added on 2026-09-23 when their pages
+were created). A new category is allowed when no existing page's
+intro covers the fault: copy the marker and front matter from the
+newest page and add the name here.
+
+The marker `<!-- doc-type: pitfall-reference -->` MUST appear in the
+first 10 lines for the extractor to process the file.
+
+## File-level frontmatter
+
+```yaml
+---
+category: raster              # raster | sprite | sid | region | kernal | banking | cpu | loader | input | render | scroll | cia | maths | logic
+---
+```
+
+## Pitfall entries
+
+Every Pitfall in the doc gets an H2 in this exact format:
+
+```
+## badline_cycle_loss — Badline DMA steals 40-43 cycles from the CPU
+```
+
+Breakdown:
+- `## ` (H2)
+- `badline_cycle_loss` — snake_case canonical name (matches ontology Pitfall.title surrogate; the extractor uses the snake_case form as the node primary key and the prose form as the human-readable title)
+- ` — ` — em-dash separator (Unicode U+2014)
+- Free-form one-line title
+
+Following each Pitfall H2 block:
+
+```
+**Severity:** critical            # critical | high | medium | low
+**Region:** both                  # PAL | NTSC | both (use 'both' if the pitfall manifests in either region)
+**Triggered by registers:** D011, D012
+**Triggered by kernal:** CHKIN
+**Triggered by techniques:** stable_raster_irq, sprite_multiplex_8
+```
+
+All `Triggered by …` lines are optional and additive — the extractor emits one TRIGGERED_BY edge per item. At least ONE Triggered-by line must be present (otherwise the pitfall has no graph anchor and won't surface through `c64_pitfalls_for`). The other direction matters too: a technique no pitfall names cannot reach any pitfall through the graph, and `c64_pitfalls_for` falls back to a semantic guess for it. `npm run check:pitfall-anchors` lists those techniques and fails on a name that matches no Technique H2; when you add a technique, add it to the Triggered-by line of every pitfall whose mechanism its code meets.
+
+After the `Triggered by …` lines, one optional additive line names the
+technique(s) whose application is the Fix section's remedy:
+
+```
+**Mitigated by techniques:** double_irq
+```
+
+Comma-separated existing Technique names; the extractor emits one
+MITIGATED_BY edge per item, Pitfall to Technique, and nothing else — a
+register or KERNAL routine is never a remedy in this sense. The line
+separates two relations one vocabulary used to carry: the technique in
+whose code the pitfall arises (Triggered by) and the technique that cures
+it (Mitigated by). A technique on the Mitigated-by line may also be on
+the Triggered-by line when the pitfall arises inside a naive version of
+the technique and a correct version cures it — `sprite_dma_overflow` and
+`sprite_multiplex_8`, `raster_irq_first_line_jitter` and
+`stable_raster_irq`, `jmp_indirect_page_boundary_bug` and
+`jump_table_dispatch`, three of the six pitfalls that carry the line — and
+Mechanism should say so; otherwise a technique is on one line or the
+other. If the remedy is not a Technique node — the SID hard restart
+lives in `hardware/sid-reference.md`, "take `$0318`" in
+`restore_nmi_not_maskable` is a handler, not a technique — write nothing;
+do not invent a technique to have something to point at. A name that
+matches no Technique node is dropped at link time with a warning and
+counted in the ingest summary beside triggered_by. `c64_pitfalls_for`
+returns a pitfall for its remedy technique as well as for its triggers,
+with the two lists kept apart; `c64_technique_lookup` lists the pitfalls a
+technique mitigates.
+
+## Section structure inside a Pitfall
+
+After the H2 + metadata lines, free-form prose covering:
+
+1. **Symptom** — what the developer sees when this bites
+2. **Mechanism** — what's actually happening at the hardware level
+3. **Fix** — concrete code/timing change
+4. **Worked example** — short asm or C snippet showing both the bad pattern and the fix
+5. **Cross-references** — related techniques, registers, recipes
+
+A pitfall whose bad pattern can be recognised in source text may also have a lint rule, named after the pitfall and pointing at its page; the rules live in `src/tools/lint.ts` and are served as `c64_lint_source` (CLI `lint <file>`). Nothing on the page declares the rule, and a pitfall without one is the common case.

package/docs/CONVENTIONS-recipes.md

@@ -0,0 +1,106 @@
+# Recipe Conventions
+
+Recipes live in `docs/recipes/<toolchain>/<recipe-name>.md`. Each recipe is a
+complete, buildable example with source, build command, expected output, and a
+description of why it's done this way. The same conceptual demo MAY have one
+recipe per toolchain (e.g. `oscar64/raster-bars.md`, `kickassembler/raster-bars.md`)
+— they are distinct Recipe nodes IMPLEMENTS-edged to the same Technique.
+
+The marker `<!-- doc-type: recipe -->` MUST appear immediately after the
+frontmatter — line 12 of every recipe, after the ten frontmatter lines and
+one blank; the extractor matches it anywhere in the file. An earlier
+version of this line said "in the first 10 lines", which no recipe
+satisfied.
+
+## File-level frontmatter (required)
+
+```yaml
+---
+recipe: hello-world             # short identifier, lowercase, hyphen-separated
+toolchain: oscar64              # canonical toolchain name (matches a Tool node; becomes a REQUIRES_TOOL edge)
+output_format: PRG              # one of PRG, CRT, BIN, D64
+region: both                    # pal | ntsc | both
+techniques: []                  # array of Technique names this recipe implements (Phase 2: empty for hello-worlds)
+file_formats: [PRG]             # FileFormat nodes this recipe produces
+uses_registers: []              # array of Register canonical names referenced
+uses_kernal: [CHROUT]           # array of KernalRoutine names called
+scaffolds: []                   # optional: Archetype names this recipe is a starting point for
+---
+```
+
+`recipe`, `toolchain`, `output_format`, and `region` are required. The rest may be
+empty arrays but the keys must be present.
+
+`scaffolds` is the exception: it is optional, and absent reads as empty.
+Set it only on a recipe that is a whole playable game an agent should copy
+and change rather than start from nothing, such as `simple-shmup`. Each
+entry must be the `name` of an Archetype on an archetype page
+(`CONVENTIONS-archetypes.md`); the ingest links `Recipe -[:SCAFFOLDS]->
+Archetype`, drops a name that matches no Archetype with a warning, and
+`c64_game_briefing` offers the recipe as the first build step for that
+archetype.
+
+## Section structure
+
+After the frontmatter:
+
+1. `# <Human-readable title>` (H1, exactly one)
+2. `## Synopsis` — one paragraph: what this recipe demonstrates and when to use it
+3. `## Source` — a single fenced code block with the complete source listing
+4. `## Build` — the exact shell command(s) to produce the artifact
+5. `## Expected output` — what you should see on screen / in the .prg
+6. `## Why this works` — one to three paragraphs walking through the load-bearing
+   lines, calling out chip-specific quirks or toolchain idioms
+
+Recipes are atomic — no "and another variation". Variations are separate recipes.
+
+## Naming
+
+The filename matches the `recipe:` frontmatter value. Directory matches `toolchain:`.
+`oscar64/hello-world.md` produces a Recipe node with `name: oscar64-hello-world`
+(directory and basename joined with `-`).
+
+## Verification (required)
+
+A recipe page is not done when it reads well. Before it lands:
+
+1. The listing is extracted from the page and built with the toolchain the
+   page names — `npm run check:listings` does exactly that and is run by
+   `npm test`. A listing that does not build does not land.
+2. For anything that draws, the PRG is run headless in VICE with the
+   pinned command (`x64sc -default -warp +sound +autostart-delay-random
+   -autostartprgmode 1 -limitcycles N [-model ntsc] -exitscreenshot
+   out.png -autostart recipe.prg`) and the screenshot is measured against
+   the "Expected output" section; the PNG goes in
+   `recipes/<toolchain>/screenshots/<recipe>.png` and the page names it.
+   The cycle count, models, extra flags and any fresh disk are pinned per
+   recipe in `recipes/runs.json`, and `npm run verify:recipes` re-runs
+   every recipe from that manifest and fails on a pixel that differs from
+   the committed PNG. A recipe whose listing builds a cartridge instead of
+   a PRG is pinned with a `"cartridge"` key: `{"file": "x.crt", "write":
+   true, "runs": 2}`. The verifier takes `x.crt` from the build's work
+   directory (a KickAssembler listing writes it with `outBin`), boots a
+   fresh copy of it per model with `-cartcrt` in place of `-autostart`,
+   adds `-easyflashcrtwrite` when `write` is true so VICE saves the flash
+   back into the copy, and boots that copy `runs` times in sequence. Run 1
+   is shot key `pal`; run N is `pal-runN`, default path
+   `screenshots/<recipe>[-<model>]-runN.png`. The pixel geometry, the
+   palette RGB values per model and a decode snippet are in `runtime/vice-reference.md`, section
+   "Reading the exit screenshot"; a program that reports its own verdict
+   through a result byte and the border colour, with a harness that turns
+   it into a shell exit code, is the section "Verifying a run without a
+   human" on the same page and the two `headless-verify` recipes.
+   A recipe the verifier cannot run because it needs an input the harness
+   has no key for (a TAP on the datasette, a prepared disk image, a key
+   press) is listed in `runs.json` with a `"skip"` key whose value says why;
+   the verifier reports it as skipped rather than failed, the listing gate
+   still builds its Source listing, the page keeps its own pictures under
+   `figures/` with the exact command that made them, and its "Expected
+   output" says it is not pinned.
+3. Any timing constant that was found by trying values (a sync padding, a
+   line padding) is labelled as measured in VICE, with what the picture
+   looks like when it is off by one. VICE is the instrument; the pages do
+   not claim bench measurements.
+4. If the page corrects an earlier version, it says what was wrong. That
+   history is worth more to the next reader than a clean surface.
+