c64-kb 0.17.0

package/templates/action-puzzle/tools/gen.py

@@ -0,0 +1,454 @@
+#!/usr/bin/env python3
+"""gen.py: the caves, the autopilot script, the rules model and the note table.
+
+    python3 tools/gen.py            # writes src/gen_caves.h, gen_autopilot.h, gen_notes.h
+    python3 tools/gen.py --show     # also prints the model's cave at game over
+
+Edit CAVES (or SCRIPT) below, run this, rebuild. It
+  1. packs every cave into the RLE row stream of c64-kb's level-rle-decoder
+     recipe (control byte 0x80+n: the next byte n times; 1..127: that many
+     literal bytes follow; 0: end of row), one stream per row of 40 cells;
+  2. runs a model of the same rules as src/cave.c over the autopilot script
+     and writes what the program must find at game over (the cave's fold,
+     score, gems, play frames), which the AUTOPILOT build grades itself on;
+  3. writes the SID frequency tables for PAL and NTSC.
+The model is the specification of the rules: change a rule in cave.c and
+here together, or the autopilot verdict turns red.
+"""
+import os
+import sys
+
+W, H = 40, 22
+
+# Element codes, the same numbers as src/cave.h. Bit 7 is the scanned bit.
+SPACE, DIRT, BRICK, STEEL, BOULDER, BOULDER_F, GEM, GEM_F = range(8)
+EXIT_SHUT, EXIT_OPEN, PLAYER = 8, 9, 10
+SPARK, MOTH, BLAST, BURST = 12, 16, 20, 23   # SPARK/MOTH + heading 0..3; BLAST/BURST + stage 0..2
+SCANNED = 0x80
+STEP = [-1, -W, 1, W]                          # headings: left, up, right, down
+
+LEGEND = {'.': DIRT, ' ': SPACE, '#': BRICK, 'S': STEEL, 'o': BOULDER, '*': GEM,
+          'X': EXIT_SHUT, 'P': PLAYER, 'f': SPARK + 0, 'm': MOTH + 0}
+
+GEM_POINTS = 10
+TICK_CAVE_FRAMES = 12      # cave frames per unit of the time counter
+DEATH_FRAMES = 6           # cave frames between a death and the next life
+SLICE_FRAMES = 4           # display frames per cave frame (the scan's four slices)
+
+# Each cave: name (at most 16 characters), gems needed, time, 20 interior
+# rows of 38 cells (shorter rows are padded with dirt). The steel border is
+# added here. One player, one exit per cave. Original layouts.
+CAVES = [
+    ("FIRST DIG", 6, 99, [
+        "...........o..*.........o............",
+        ".P...*..*..*...*..o  ...........oo...",
+        "...................*.....o...........",
+        "...................*....oo...........",
+        "....................XS........o .....",   # the boulder on the brick end rolls right
+        "..........................##### .....",
+        ".....o...............................",
+        "..............####.......####........",
+        "....*.........#  #.......#  #...*....",
+        "..............# f#.......#m #........",
+        "..............#  #.......#  #........",
+        "..............####.......####........",
+        "." * 11 + "o" * 16 + "." * 11,           # boulder rain: 16 fall and land in one
+        "." + " " * 36 + ".",                      # slice and overflow the dirty list, so
+        "",                                        # the gated run meets render.c's row queue
+        "",
+        "..............*..........#####.......",
+        "......o..............................",
+        "......*........o..............*......",
+        "",
+    ]),
+    ("BOULDER HALL", 8, 120, [
+        "....o................o...............",
+        "..........o.......................o..",
+        "..P..........*.........*.............",
+        "...............o.....f     .X........",
+        "...........#####.....................",
+        "......*..............*.......*.......",
+        "...........o...........o.............",
+        "........  ...........................",
+        "......#####...........#####..........",
+        "...........*....*.........*..........",
+        "",
+        "........m     .......................",
+        "....o.......o.......o........o.......",
+        "....*.......*.......*........*.......",
+        "",
+        "..........####.............####......",
+        "",
+        "...*..................*.........*....",
+        "",
+        "",
+    ]),
+]
+
+# The autopilot's moves, one per cave frame: L U R D, '-' stands still.
+# One string per cave start (a new cave, or the same cave after a lost
+# life), keyed by the game's count of starts; past the end of a string the
+# player stands still.
+SCRIPT = [
+    "RRRRRRRRRRRRRRRRRRDDDR",   # cave 1: gems, two pushes, the exit
+    "RRUD",                     # cave 2: out from under a boulder; it falls on him
+    "RRRRRRRRD",                # cave 2 again: under another boulder, the same end
+    "RRUD",                     # cave 2, last life: game over
+]
+LIVES_AUTOPILOT = 3
+DEFAULT_SCORES = [400, 300, 200, 100, 50]    # hiscore.c's default table
+NAME_AUTOPILOT = "ABE"
+
+
+def build(cave):
+    name, need, time, rows = cave
+    c = [STEEL] * (W * H)
+    for y in range(1, H - 1):
+        r = rows[y - 1] if y - 1 < len(rows) else ""
+        if len(r) > W - 2:
+            sys.exit(f"cave {name}: row {y} is {len(r)} cells, more than {W - 2}")
+        for x, ch in enumerate(r.ljust(W - 2, '.'), 1):
+            if ch not in LEGEND:
+                sys.exit(f"cave {name}: row {y} has '{ch}', not in the legend")
+            c[y * W + x] = LEGEND[ch]
+    for code in (PLAYER, EXIT_SHUT):
+        if c.count(code) != 1:
+            sys.exit(f"cave {name}: {c.count(code)} cells of code {code}, want 1")
+    return c
+
+
+def rle_row(cells):
+    """The level-rle-decoder stream for one row: runs of 3 or more, else literals."""
+    out, i, lit = [], 0, []
+    while i < len(cells):
+        j = i
+        while j < len(cells) and cells[j] == cells[i] and j - i < 127:
+            j += 1
+        if j - i >= 3:
+            if lit:
+                out += [len(lit)] + lit
+                lit = []
+            out += [0x80 | (j - i), cells[i]]
+            i = j
+        else:
+            lit.append(cells[i])
+            i += 1
+            if len(lit) == 127:
+                out += [len(lit)] + lit
+                lit = []
+    if lit:
+        out += [len(lit)] + lit
+    return out + [0]
+
+
+def rle_decode(data):
+    out, i = [], 0
+    for _ in range(H):
+        while True:
+            c = data[i]; i += 1
+            if c == 0:
+                break
+            if c & 0x80:
+                out += [data[i]] * (c & 0x7f); i += 1
+            else:
+                out += data[i:i + c]; i += c
+    return out
+
+
+def fold(cells, chk=0):
+    for v in cells:
+        chk = ((chk ^ (v & 0x7f)) * 5 + 1) & 0xffff
+    return chk
+
+
+class Cave:
+    """One cave's state and the rules. Mirrors src/cave.c line for line."""
+
+    def __init__(self, cells, need, time):
+        self.c = list(cells)
+        self.need, self.time = need, time
+        self.got = self.points = 0
+        self.dead = self.exited = self.exit_open = False
+        self.player = self.c.index(PLAYER)
+        self.exit_at = self.c.index(EXIT_SHUT)
+        self.tick = 0
+        self.move = -1
+        self.seen = 0
+
+    def put(self, d, v, s):
+        if d > s:
+            v |= SCANNED
+        self.c[d] = v
+        self.c[s] = SPACE
+        if v & 0x7f == PLAYER:
+            self.player = d
+
+    def explode(self, centre, kind, at):
+        for dy in (-W, 0, W):
+            for dx in (-1, 0, 1):
+                n = centre + dy + dx
+                t = self.c[n] & 0x7f
+                if t in (STEEL, EXIT_SHUT, EXIT_OPEN):
+                    continue
+                if t == PLAYER:
+                    self.dead = True
+                self.c[n] = kind | (SCANNED if n > at else 0)
+
+    def roll(self, i, fall):
+        for o in (-1, 1):
+            if self.c[i + o] == SPACE and self.c[i + W + o] == SPACE:
+                self.put(i + o, fall, i)
+                return True
+        return False
+
+    @staticmethod
+    def round_(t):
+        return t in (BOULDER, GEM, BRICK)
+
+    def cell(self, i):
+        c, v = self.c, self.c[i]
+        if v & SCANNED:
+            c[i] = v & 0x7f
+            return
+        if v in (BOULDER, GEM):
+            b = c[i + W]
+            if b == SPACE:
+                self.put(i + W, v + 1, i)
+            elif self.round_(b & 0x7f):
+                self.roll(i, v + 1)
+        elif v in (BOULDER_F, GEM_F):
+            b = c[i + W]; bt = b & 0x7f
+            if b == SPACE:
+                self.put(i + W, v, i)
+            elif bt == PLAYER:
+                self.explode(i + W, BLAST, i)
+            elif SPARK <= bt < MOTH:
+                self.explode(i + W, BLAST, i)
+            elif MOTH <= bt < BLAST:
+                self.explode(i + W, BURST, i)
+            elif bt in (BOULDER_F, GEM_F):
+                pass
+            elif not (self.round_(bt) and self.roll(i, v)):
+                c[i] = v - 1
+        elif v == PLAYER:
+            self.seen += 1
+            if 0 <= self.move < 4:
+                t = i + STEP[self.move]
+                tv = c[t]
+                if tv in (SPACE, DIRT):
+                    self.put(t, PLAYER, i)
+                elif tv == GEM:
+                    self.got += 1
+                    self.points += GEM_POINTS
+                    self.put(t, PLAYER, i)
+                elif tv == EXIT_OPEN:
+                    c[i] = SPACE
+                    self.exited = True
+                elif tv == BOULDER and self.move in (0, 2) and c[t + STEP[self.move]] == SPACE:
+                    self.put(t + STEP[self.move], BOULDER, t)
+                    self.put(t, PLAYER, i)
+        elif v >= BLAST:
+            if v in (BLAST + 2,):
+                c[i] = SPACE
+            elif v == BURST + 2:
+                c[i] = GEM
+            else:
+                c[i] = v + 1
+        elif v >= SPARK:
+            base = SPARK if v < MOTH else MOTH
+            kind = BLAST if v < MOTH else BURST
+            d = v & 3
+            for o in STEP:
+                if c[i + o] & 0x7f == PLAYER:
+                    self.explode(i, kind, i)
+                    return
+            first = (d + 3) & 3 if base == SPARK else (d + 1) & 3
+            spin = (d + 1) & 3 if base == SPARK else (d + 3) & 3
+            if c[i + STEP[first]] == SPACE:
+                self.put(i + STEP[first], base + first, i)
+            elif c[i + STEP[d]] == SPACE:
+                self.put(i + STEP[d], base + d, i)
+            else:
+                c[i] = base + spin
+
+    def scan(self):
+        for y in range(1, H - 1):
+            for x in range(1, W - 1):
+                i = y * W + x
+                if self.c[i] >= BOULDER:
+                    self.cell(i)
+        assert not any(v & SCANNED for v in self.c), "a scanned bit survived the scan"
+
+    def end_of_frame(self):
+        """What the game does after the last slice of a cave frame."""
+        if not self.exit_open and self.got >= self.need:
+            self.c[self.exit_at] = EXIT_OPEN
+            self.exit_open = True
+        if self.exited or self.dead:
+            return
+        self.tick += 1
+        if self.tick == TICK_CAVE_FRAMES:
+            self.tick = 0
+            if self.time:
+                self.time -= 1
+            if self.time == 0:
+                self.explode(self.player, BLAST, 0xffff)
+
+
+def play():
+    """The autopilot game, as the program plays it. Returns what it must show.
+
+    The script is keyed by the game's own counter of cave starts: SCRIPT[n]
+    plays the n-th start (a new cave or a restart after a lost life). The
+    fold is chained over every cave the game leaves, so a rule that fires in
+    any cave, not only the last, moves the verdict."""
+    score, gems, frames, lives = 0, 0, 0, LIVES_AUTOPILOT
+    ci, starts, chk = 0, 0, 0
+    while True:
+        name, need, time, _ = CAVES[ci]
+        cv = Cave(build(CAVES[ci]), need, time)
+        script = SCRIPT[starts] if starts < len(SCRIPT) else ""
+        starts += 1
+        f, dead_frames = 0, 0
+        while True:
+            m = script[f] if f < len(script) else '-'
+            cv.move = "LURD".find(m)
+            cv.seen = 0
+            cv.scan()
+            cv.end_of_frame()
+            # the scan meets the living player exactly once a cave frame
+            assert cv.seen <= 1 if cv.dead else cv.seen == 1, (starts, f, cv.seen)
+            f += 1
+            frames += SLICE_FRAMES
+            if cv.exited:
+                break
+            if cv.dead:
+                dead_frames += 1
+                if dead_frames == DEATH_FRAMES:
+                    break
+            if f > 5000:
+                sys.exit("autopilot: the script never ends a cave")
+        score += cv.points
+        gems += cv.got
+        chk = fold(cv.c, chk)
+        if cv.exited:
+            score += cv.time
+            ci = (ci + 1) % len(CAVES)
+            continue
+        lives -= 1
+        if lives == 0:
+            rank = next((r for r, v in enumerate(DEFAULT_SCORES) if v < score), len(DEFAULT_SCORES))
+            return dict(fold=chk, score=score, gems=gems, cave=ci, frames=frames, starts=starts,
+                        rank=rank, cells=[v & 0x7f for v in cv.c])
+
+
+def c_array(name, data):
+    lines = [f"static const char {name}[{len(data)}] = {{"]
+    for k in range(0, len(data), 16):
+        lines.append("    " + ", ".join(f"0x{b:02x}" for b in data[k:k + 16]) + ",")
+    lines.append("};")
+    return "\n".join(lines)
+
+
+def screen_codes(s):
+    return [ord(ch) - 64 if 'A' <= ch <= 'Z' else ord(ch) for ch in s]
+
+
+def write_caves(path):
+    out = ["// gen_caves.h: written by tools/gen.py. Do not edit; edit tools/gen.py.",
+           f"#define CAVE_COUNT {len(CAVES)}", ""]
+    total = 0
+    for k, cave in enumerate(CAVES):
+        cells = build(cave)
+        packed = []
+        for y in range(H):
+            packed += rle_row(cells[y * W:(y + 1) * W])
+        assert rle_decode(packed) == cells
+        total += len(packed)
+        out.append(f"// {cave[0]}: 880 cells -> {len(packed)} bytes, fold 0x{fold(cells):04x}")
+        out.append(c_array(f"cave{k}_rle", packed))
+        out.append(c_array(f"cave{k}_name", screen_codes(cave[0].ljust(16)[:16])))
+    out.append("")
+    out.append("static const CaveInfo cave_info[CAVE_COUNT] = {")
+    for k, (name, need, time, _) in enumerate(CAVES):
+        fold0 = fold(build(CAVES[k]))
+        out.append(f"    {{ cave{k}_rle, cave{k}_name, {need}, {time}, 0x{fold0:04x} }},")
+    out.append("};")
+    open(path, "w").write("\n".join(out) + "\n")
+    return total
+
+
+def write_autopilot(path, result):
+    out = ["// gen_autopilot.h: written by tools/gen.py. Do not edit; edit tools/gen.py.",
+           "// The autopilot: one move per cave frame (L U R D, '-' still), per cave;",
+           "// past the end of a cave's string the player stands still."]
+    for k, s in enumerate(SCRIPT):
+        out.append(f'static const char script{k}[] = "{s}";')
+    out.append(f"static const char * const script_for[{len(SCRIPT)}] = {{ " +
+               ", ".join(f"script{k}" for k in range(len(SCRIPT))) + " };")
+    out.append(f"static const char script_len[{len(SCRIPT)}] = {{ " +
+               ", ".join(str(len(x)) for x in SCRIPT) + " };")
+    out.append(f"#define SCRIPT_STARTS {len(SCRIPT)}")
+    out.append(f"#define LIVES_AUTOPILOT {LIVES_AUTOPILOT}")
+    out.append(f'#define NAME_AUTOPILOT "{NAME_AUTOPILOT}"')
+    out.append("// What the rules model says the program must hold at game over.")
+    out.append(f"#define EXPECT_FOLD 0x{result['fold']:04x}")
+    out.append(f"#define EXPECT_SCORE {result['score']}UL")
+    out.append(f"#define EXPECT_GEMS {result['gems']}")
+    out.append(f"#define EXPECT_CAVE {result['cave']}")
+    out.append(f"#define EXPECT_PLAY_FRAMES {result['frames']}")
+    out.append(f"#define EXPECT_STARTS {result['starts']}")
+    out.append(f"#define EXPECT_RANK {result['rank']}")
+    open(path, "w").write("\n".join(out) + "\n")
+
+
+def write_notes(path):
+    """SID frequency words for notes 0..59 (C1 up), A4 = 440 Hz, PAL and NTSC clocks."""
+    clocks = {"pal": 985248, "ntsc": 1022727}
+    out = ["// gen_notes.h: written by tools/gen.py. Note n is C1 + n semitones; A4 = 440 Hz.",
+           "// Frequency word = Hz * 16777216 / clock (PAL 985,248 Hz; NTSC 1,022,727 Hz)."]
+    for model, clk in clocks.items():
+        words = []
+        for n in range(60):
+            hz = 440.0 * 2 ** ((n - 45) / 12)      # n = 45 is A4 (C1 + 45 semitones)
+            words.append(min(0xffff, round(hz * 16777216 / clk)))
+        out.append(f"static const unsigned note_{model}[60] = {{")
+        for k in range(0, 60, 12):
+            out.append("    " + ", ".join(f"0x{w:04x}" for w in words[k:k + 12]) + ",")
+        out.append("};")
+    open(path, "w").write("\n".join(out) + "\n")
+
+
+def show(cells):
+    rev = {v: k for k, v in LEGEND.items()}
+    for y in range(H):
+        row = ""
+        for x in range(W):
+            v = cells[y * W + x] & 0x7f
+            if SPARK <= v < MOTH:
+                row += 'f'
+            elif MOTH <= v < BLAST:
+                row += 'm'
+            elif v >= BLAST:
+                row += '%'
+            elif v == EXIT_OPEN:
+                row += 'x'
+            else:
+                row += rev.get(v, '?')
+        print(row)
+
+
+if __name__ == "__main__":
+    here = os.path.dirname(os.path.abspath(__file__))
+    src = os.path.join(here, "..", "src")
+    r = play()
+    if "--show" in sys.argv:
+        show(r["cells"])
+    total = write_caves(os.path.join(src, "gen_caves.h"))
+    write_autopilot(os.path.join(src, "gen_autopilot.h"), r)
+    write_notes(os.path.join(src, "gen_notes.h"))
+    print(f"gen: {len(CAVES)} caves, {total} bytes packed; autopilot: score {r['score']}, gems {r['gems']}, "
+          f"game over in cave {r['cave'] + 1} after {r['starts']} starts, {r['frames']} play frames, "
+          f"chained fold 0x{r['fold']:04x}, table row {r['rank'] + 1}")
+    if r["frames"] > 255:
+        print("gen: more than 255 play frames: the meter records the first 255 only")

package/templates/action-puzzle/tools/model_check.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""model_check.py HARNESS_DIR PAL.png NTSC.png: every visible cave cell against the model.
+
+The autopilot shot shows cave 2 as it stood at game over, under the table
+box. For each cave cell outside the box this reads the colour at the cell's
+centre (every element glyph is inked there, see render.c) and compares it
+with the colour of the element tools/gen.py's model holds at game over.
+Exit 0 when all match on both pictures. `make modelcheck` runs it.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import gen  # noqa: E402
+
+TINT = [0, 9, 2, 12, 15, 15, 3, 3, 12, 13, 7, 0,     # render.c tint[], element 0..25
+        8, 8, 8, 8, 4, 4, 4, 4, 1, 1, 1, 14, 14, 14]
+BOX = (6, 7, 19, 32)                                   # main.c draw_box: rows 6-19, columns 7-32
+
+
+def main():
+    harness, pal, ntsc = sys.argv[1:4]
+    sys.path.insert(0, harness)
+    import check  # the harness's geometry and palette
+
+    cells = gen.play()["cells"]
+    bad = 0
+    for path, model in ((pal, "pal"), (ntsc, "ntsc")):
+        shot = check.Shot(path, model)
+        seen = 0
+        for y in range(gen.H):
+            for x in range(gen.W):
+                row, col = y + 1, x
+                if BOX[0] <= row <= BOX[2] and BOX[1] <= col <= BOX[3]:
+                    continue
+                px, py = check.point_xy({"row": row, "col": col}, model)
+                got, want = shot.index(px, py), TINT[cells[y * gen.W + x]]
+                seen += 1
+                if got != want:
+                    bad += 1
+                    print(f"FAIL {model.upper()} cave ({x}, {y}): colour {got}, the model's element "
+                          f"{cells[y * gen.W + x]} is colour {want}")
+        print(f"model_check: {model.upper()} {seen} cave cells compared with the model")
+    print("model_check: PASS" if bad == 0 else f"model_check: {bad} cells differ")
+    sys.exit(1 if bad else 0)
+
+
+if __name__ == "__main__":
+    main()

package/templates/action-puzzle/tools/verdict_codes.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""verdict_codes.py HARNESS_DIR PNG MODEL LETTERS: the verdict's failure letters.
+
+The AUTOPILOT verdict prints one letter per failed test on row 23 from
+column 27 (main.c, verdict). Exit 0 when every letter in LETTERS is there.
+`make selftest-scan` uses it to see that the SCAN_FLAG=0 build fails on E,
+the test that the scan meets the living player exactly once a cave frame.
+"""
+import sys
+
+
+def main():
+    harness, png, model, want = sys.argv[1:5]
+    sys.path.insert(0, harness)
+    import check
+    got = check.read_text(check.Shot(png, model), check.load_glyphs(), 23, 27, 12).strip()
+    missing = [c for c in want if c not in got]
+    print(f"verdict_codes: {model.upper()} failure letters '{got}'" +
+          (f", missing {''.join(missing)}" if missing else ""))
+    sys.exit(1 if missing else 0)
+
+
+if __name__ == "__main__":
+    main()

package/templates/adventure/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "h=\"$CLAUDE_PROJECT_DIR/harness/hooks/plan-gate.py\"; [ -f \"$h\" ] || h=\"$CLAUDE_PROJECT_DIR/../_harness/hooks/plan-gate.py\"; exec python3 \"$h\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/adventure/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "c64-kb": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["../../dist/cli.js", "serve"],
+      "env": {}
+    }
+  }
+}

package/templates/adventure/CLAUDE.md

@@ -0,0 +1,118 @@
+# Rules for an agent working on this C64 program
+
+This program runs on a stock Commodore 64, PAL and NTSC. It is built on the
+c64-kb harness (`./harness`, vendored from c64-kb's `templates/_harness`).
+c64-kb is the reference: its pages give the registers, timings, techniques,
+pitfalls and recipes this program is built from. A wrong number becomes a torn
+screen or a crash, so every claim here is measured or says it is not.
+
+A new program starts in c64-kb with `npm run new-project -- <starter> <dir>`.
+That copies the starter and the harness, points `.mcp.json` and `local.mk`
+at the c64-kb checkout, proves the copy with `make shot check`, and leaves a
+blank `PLAN.md`.
+
+## This starter: adventure
+
+STARWATCH, a two-word text adventure in Oscar64 C: twelve rooms, containers,
+three puzzles, a scored ending, SAVE and LOAD to drive 8, packed text and a
+multicolour picture strip. README.md has the file map and the measured
+frame. Start a program from it with `npm run new-project -- adventure <dir>`
+in c64-kb. `PLAN.md` here is a plan filled from real tool output;
+new-project keeps it as `PLAN-adventure-example.md` and gives the new
+program a blank one.
+
+Rules this starter adds:
+
+- The world lives in `tools/world.py`. Edit it, run `make gen`, then
+  `make shot check`. Never edit the generated `src/gen_*.h`.
+- The engine and the printer live twice: `src/engine.c` and `src/text.c`,
+  and the model in `tools/gen.py`. Change both. The verdict compares the
+  game with the model (state, a fold of every printed line, the frame
+  count); a change on one side only turns it red.
+- A frame does one bounded job: the picture, one window line, or the typed
+  keys and a turn. Keep it that way; the meter's worst is the check. The
+  script must show every picture (gen.py refuses it otherwise) and stay
+  within the meter's 255 frames (gen.py warns).
+- After changing the script or the text, `expect.json`'s texts, the fold
+  on row 24 and the meter's `frames` change: `make gen` prints the new
+  frame count and fold.
+- Disk calls run on a frame outside the meter, muted, followed by `SEI`.
+  Run `make disktest` after any change to `save.c` or the save record.
+
+## Before any code
+
+1. Brief: `npx tsx src/cli.ts game-briefing "<concept>" --archetype <name>`
+   (or `demo-briefing`), in the c64-kb checkout. Read what it proposes.
+2. For each technique you keep: `technique-lookup <name>` and
+   `pitfalls-for <name>`. Start from the recipe it names (`recipe-lookup`).
+3. Fill `PLAN.md`: paste the whole output of `check-compatibility` and of
+   `plan-budget` (same techniques) into their sections, list every technique
+   in its table, and replace every `FILL:` line.
+
+Until `PLAN.md` passes, a hook blocks Edit and Write under `src/`, and every
+make target that builds stops (`make plan-gate` says what is missing). With
+C64KB set, `make` re-runs `check-compatibility` and wants the pasted Verdict.
+The gate cannot see writes made through a shell command, or outputs edited
+into shape by hand: do neither. `make PLAN_GATE=off` overrides it; say why in
+`PLAN.md` if you do.
+
+## The loop
+
+```bash
+make                  # build build/<name>.prg
+make shot check       # autopilot build, headless PAL and NTSC, graded by expect.json
+make selftest         # the FORCE_FAULT build must fail the same checks
+make disk             # build/<name>.d64
+make claims           # every store the program makes, against what it declares
+make run              # windowed VICE, for a human
+```
+
+## Rules
+
+- Build before claiming. Code that has not built is not done.
+- Measure screenshots with `check.py` through `expect.json`, never by eye.
+  Every visible claim gets a check. Add one before you trust a change.
+- PAL and NTSC: both shots pass, or it is not done.
+- Name the rung for every number: measured here (`make shot`, the meter, the
+  VICE monitor), taken from a c64-kb page (say which), arithmetic, or not
+  measured. Never call something verified that was not run.
+- Frame cost comes from the meter: CIA2 timer A, printed as
+  `F<frames> W<worst> T<typical>` at row 24, columns 20 to 39, in AUTOPILOT
+  builds. It records the first `hold` frames: make that the autopilot
+  script's play frames. Typical is the median of those frames, the KB's
+  `cycles_per_frame_typical`. Keep grading, logging and printing outside the
+  bracket; work split between the main loop and IRQs is summed with
+  `METER_PAUSE` / `METER_START`.
+- Do not invent a register, routine or address. Look it up:
+  `lookup-register`, `lookup-kernal`, `memory-map`.
+- Lint every source you change: `npx tsx src/cli.ts lint <file>`.
+- Commit named paths only. Never `git add -A` or `git add .`. `build/`,
+  `shots/` and `local.mk` are never committed.
+
+## Harness facts you will need
+
+- `AUTOPILOT=1` builds read a scripted joystick byte instead of `$DC00` and
+  grade themselves: `$02FF` = `$01` and a green border on pass, `$02` and red
+  on fail. `FORCE_FAULT=1` must turn the verdict red and move something a
+  screenshot check can see.
+- Screenshot geometry (c64-kb `docs/runtime/vice-reference.md`): PAL 384 x 272,
+  row = raster line - 16; NTSC 384 x 247, row = line - 28; x = VIC X + 8. A
+  sprite at Y register y is drawn from line y + 1.
+- `check.py` reads text in the ROM character set unless a check names a
+  `charset` file; the meter's cells need 0-9, F, W and T in the set on screen.
+- A KickAssembler part called from C is a raw blob at its own `* =` address,
+  `$0880` or above; `build/asm.h` gives C its labels as `ASM_<LABEL>`
+  (`ASM_<SCOPE>_<LABEL>` inside a scope). Pass arguments through bytes in the
+  blob, not Oscar64's zero page (`$02` to `$52`).
+- The meter takes CIA2 timer A. Do not open RS-232 (device 2) while it runs.
+- The KERNAL serial routines end in `CLI` (ROM bytes `58 60` / `58 18` at
+  `$EDAB`, `$EDB5`, `$EDDB`, `$EE82`). After any disk call, `SEI` again if
+  the program runs with the KERNAL IRQ off: otherwise that IRQ lands inside
+  the meter's brackets and rewrites `$DC00`.
+
+## Calling c64-kb
+
+- CLI, from the c64-kb checkout (`C64KB` in `local.mk`):
+  `npx tsx src/cli.ts <command>`; `npx tsx src/cli.ts --help` lists them.
+- MCP: `.mcp.json` starts `node <c64-kb>/dist/cli.js serve` (run
+  `npm run build` in c64-kb first).