romdevtools 0.24.0 → 0.25.0

package/AGENTS.md

@@ -148,10 +148,12 @@ worry about ground truth:
 
 1. **`scaffold({op:'project', platform, template, name, path})`** — drops a
    complete, self-contained project tree on disk (main.c + the
-   runtime files it needs + your `vendor/` library source for
-   reference + README + .gitignore). Build with `build({output:'run'})` against
-   the project's files; the bundled examples ARE the reference
-   implementation.
+   runtime files it needs + the vendored library source for
+   reference + README + .gitignore). The response lists only the files you EDIT
+   (`files`) + a `vendorFileCount`; pass `verbose:true` for the full manifest.
+   Build the whole dir in one call with `build({output:'project', path,
+   outputPath})` (toolchain/crt0/linker inferred — no manifest); the bundled
+   examples ARE the reference implementation.
 2. **`scaffold({op:'game', platform, genre})`** — same but picks a known-good
    genre scaffold (shmup / platformer / puzzle / sports / racing).
 3. **`scaffold({op:'snippets', platform, mode})`** (mode `list`/`get`/`getAll`)

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.25.0
+
+### Added — C64 input scripting + verification (RE startup-flow telemetry)
+Follow-up to the 0.24.0 C64 keyboard work: an agent RE'ing C64 Uridium could now
+press keys, but couldn't (a) script a keyboard+joystick startup TIMELINE in one
+call, or (b) tell whether a non-responsive key reached VICE at all. Both added — no
+core rebuild (the `c64_cia1_regs` region + key matrix already existed):
+- **`recordSession` `inputScript[].keys`** — hold C64 keyboard keys from a frame
+  until the next entry, interleaved with joystick `ports`, in one deterministic
+  timeline (e.g. `{atFrame:0,keys:['f1']},{atFrame:30,ports:[{b:true}]},
+  {atFrame:60,keys:['run/stop']},{atFrame:90,keys:[]}`). `ports` is now optional
+  (a step may set just keys). Unknown keys are **rejected with a clear error**, not
+  silently ignored.
+- **`input({op:'pressKey', verify:true})`** — also samples CIA1 **`$DC00`/`$DC01`**
+  (the keyboard/joystick scan ports the KERNAL reads) **before / during (key held)
+  / after**, plus matrix coords + active joyport. Lets you distinguish "my key
+  never reached VICE" (`before==during`) from "VICE saw it but the game ignored it"
+  (they differ, no reaction) when a C64 game doesn't respond.
+
+### Changed — `scaffold` no longer echoes the vendored toolchain manifest
+`scaffold({op:'project'|'game'})` used to return a flat `files[]` of EVERY written
+file — including the toolchain copies (35 of 44 entries on NES, **173 of 264 on
+GBA**, ~270 on SGDK Genesis) that an agent never touches. Across a matrix run (one
+game × every genre × every platform) that was ~100 KB of pure vendored-path lists
+in context with zero decision value. Now the response is a compact receipt:
+- `files` — only the project-**OWNED** files you edit (main source, runtime, crt0,
+  cfg, README).
+- `fileCount` (total written) + `vendorFileCount` (the summarized vendored copies,
+  on disk if you ever need them).
+- `verbose:true` restores the full flat list as `allFiles`.
+
+"Owned" is classified by what a file **is**, not just a `vendor/` prefix — so it
+correctly excludes the SDK header trees the GBA (libtonc `include/`+`sysinclude/`)
+and Genesis (SGDK `include/`) toolchains drop OUTSIDE `vendor/`, plus prebuilt
+`crt*.o` / `*.a` / `*.lib`. (The initial fix used a `vendor/`-prefix denylist and
+missed exactly those two SDK platforms — caught + fixed via a 0.24.0 matrix-run
+report. GBA dropped 173→9 owned, Genesis 82→13.) Mirrors the `inline`/`outputPath`
+choose-your-payload pattern the snippets op already had.
+
+### Changed — scaffold README + `nextStep` lead with `build({output:'project'})`
+The generated project README and the scaffold's `nextStep` now lead with the
+one-call **`build({output:'project', platform, path, outputPath})`** form (infers
+toolchain/crt0/linker from the directory — no `sourcesPaths`/`includePaths`/
+`linkerConfig` to hand-specify), and demote the verbose `output:'run'` + manifest
+form to a collapsed "compiling edited loose source" alternative. The project-dir
+build was already the easier path; now it's the one a fresh agent copies first.
+
+### Fixed — SMS shmup + Atari 7800 sports scaffolds rendered with wrong colors
+Both built and booted but looked broken (a 0.24.0 matrix report flagged them):
+- **SMS shmup** rendered the starfield as blue/**GREEN** striped bands. The BG
+  palette had colour 1 = `0x08`, which in SMS 2-2-2 BGR is green (G bits), not the
+  "deep space blue" the comment claimed. Fixed to a pure-blue depth gradient
+  (`0x10/0x20/0x30`) — the bands now read as space, dominant colour went green
+  `#00aa00` → blue `#0000ad`.
+- **Atari 7800 sports** rendered a near-black playfield that looked dead. Two MARIA
+  colour-byte bugs: the court walls used `0x48` (hue 4 = RED → **pink**, not the
+  intended blue) and the court floor was `0x00` (black, indistinguishable from a
+  blank screen). Fixed to blue walls (`0x8A`, hue 8) + a dark-green court floor
+  (`0xB4`) — now reads as an actual court (dominant black → green `#008221`).
+
+Both verified by screenshot + `frame({op:'verify'})`. (These were colour-value
+bugs in the scaffold templates, not the render pipeline.)
+
+### Removed — `catalog({op:'whatsNew'})` + the old→new tool rename table
+`whatsNew` returned a 125-entry map of pre-1.0 renamed tool names (plus, until now,
+~1.4k tokens of inlined CHANGELOG prose) so an agent resuming an old handoff could
+re-map a tool that had moved. The pre-1.0 consolidation is long settled — the old
+names are git history, and no running agent carries them — so maintaining a
+forever-growing rename record (and risking it landing in context) wasn't worth it.
+Dropped the op, the `tool-manifest.js` map, and its tests. An agent that hits an
+unknown tool name now just reads the current surface (`catalog({op:'categories'})`
+or the tool list); full release notes remain in CHANGELOG.md for humans.
+
 ## 0.24.0
 
 ### Added — C64 keyboard + joyport input (VICE core patch)

package/examples/atari7800/templates/sports.c

@@ -180,11 +180,15 @@ void main(void) {
   p1y = 110; p2y = 110;
   serve_ball(0);
 
-  BACKGRND = 0x00;   /* black court */
+  /* MARIA color byte = (hue<<4)|lum. Court = dark green so the play area
+   * reads as an actual field (0x00 black looked like a blank/dead screen);
+   * walls = blue. NB: 0x48 is hue 4 = RED-magenta (renders PINK), not blue —
+   * blue is hue 8/9, so the walls use 0x8A. */
+  BACKGRND = 0xB4;   /* dark green court floor (hue 11) */
   P0C1     = 0x0F;   /* white paddles + ball */
   P0C2     = 0x0F;
   P0C3     = 0x0F;
-  P1C1     = 0x48;   /* court walls (blue) */
+  P1C1     = 0x8A;   /* court walls — BLUE (hue 8); was 0x48 = pink */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/sms/templates/shmup.c

@@ -30,8 +30,11 @@ extern void sms_sat_upload(void);
 #define T_ENEMY  2
 
 static const uint8_t palette[32] = {
-  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white */
-  0x10,0x08,0x20,0x3F, 0x00,0x00,0x00,0x00,
+  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white.
+   * SMS CRAM is 2-2-2 BGR (bits --BB GGRR), so PURE blue uses only the B bits:
+   * 0x10=dark, 0x20=medium, 0x30=bright. (The old 0x08 for colour 1 was G=2 =
+   * GREEN, which made the alternating starfield bands render blue/GREEN striped.) */
+  0x10,0x20,0x30,0x3F, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   /* Sprite palette: white, yellow, red */
   0x00,0x3F,0x0F,0x03, 0x00,0x00,0x00,0x00,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/host/LibretroHost.js

@@ -928,6 +928,86 @@ export class LibretroHost {
     return { key: String(key).toLowerCase(), row, col, frames: Math.max(1, frames | 0) };
   }
 
+  /**
+   * Press a C64 key like pressC64Key, but sample the machine-visible input
+   * state (CIA1 $DC00/$DC01 — the keyboard/joystick scan ports) BEFORE,
+   * DURING (key held), and AFTER (released). Lets an RE agent tell apart
+   * "my key never reached VICE" from "VICE saw it but the game didn't scan
+   * it this frame". No core change — reads the already-exposed c64_cia1_regs
+   * region ($DC00..$DC0F).
+   * @param {string} key
+   * @param {number} frames  frames to hold (sampled at the midpoint)
+   * @returns {object} matrix coords + held flag + per-phase CIA snapshots
+   */
+  pressC64KeyVerify(key, frames = 4) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const pos = C64_KEY_MATRIX[String(key).toLowerCase()];
+    if (!pos) {
+      throw new Error(`unknown C64 key '${key}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`);
+    }
+    const [row, col] = pos;
+    const held = Math.max(1, frames | 0);
+    // $DC00 = CIA1 PRA (port A — joystick 2 + keyboard col select),
+    // $DC01 = CIA1 PRB (port B — joystick 1 + keyboard row read).
+    const cia = () => {
+      try {
+        const r = this.readMemory("c64_cia1_regs", 0, 2);
+        return { DC00: r[0], DC01: r[1] };
+      } catch { return null; }
+    };
+    const before = cia();
+    mod._romdev_key_matrix(row, col, 1);          // press
+    this.stepFrames(Math.ceil(held / 2));
+    const during = cia();                          // key still held
+    this.stepFrames(Math.max(1, held - Math.ceil(held / 2)));
+    mod._romdev_key_matrix(row, col, 0);          // release
+    this.stepFrames(1);
+    const after = cia();
+    return {
+      key: String(key).toLowerCase(),
+      row, col,
+      frames: held,
+      joyport: this.getC64JoyPort?.() ?? null,
+      autoReleased: true,
+      cia1: { before, during, after },
+      note: "CIA1 $DC00 (port A) / $DC01 (port B) are the keyboard/joystick scan ports the KERNAL reads. `during` is sampled with the key held; if before==during the key never moved the matrix line (didn't reach VICE); if they differ but the game didn't react, it scanned a different key/port or that screen ignores it.",
+    };
+  }
+
+  /**
+   * Set the SET of C64 keyboard keys held down (for scripted timelines like
+   * recordSession). Diffs against the currently-held set: presses newly-added
+   * keys' matrix lines, releases removed ones. Pass [] to release all. Does NOT
+   * step frames — the caller's loop owns stepping. Unknown keys throw.
+   * @param {string[]} keys
+   * @returns {{held: string[], matrix: Array<[number,number]>}}
+   */
+  setC64HeldKeys(keys) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const want = new Set((keys ?? []).map((k) => String(k).toLowerCase()));
+    for (const k of want) {
+      if (!C64_KEY_MATRIX[k]) {
+        throw new Error(`unknown C64 key '${k}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`);
+      }
+    }
+    const have = this._c64HeldKeys ?? (this._c64HeldKeys = new Set());
+    // release keys no longer wanted
+    for (const k of have) {
+      if (!want.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 0); have.delete(k); }
+    }
+    // press newly-added keys
+    for (const k of want) {
+      if (!have.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 1); have.add(k); }
+    }
+    return { held: [...have], matrix: [...have].map((k) => C64_KEY_MATRIX[k]) };
+  }
+
   /**
    * Feed a PETSCII string into the C64 kernal keyboard buffer (for typing
    * LOAD/RUN/filenames). `\r` (or `\n`) becomes RETURN. Non-blocking — the

package/src/mcp/tools/index.js

@@ -58,13 +58,11 @@ import { registerCheatTools } from "./cheats.js";
 import { createDisclosure } from "../disclosure.js";
 import { jsonContent, safeTool, withClearToolErrors } from "../util.js";
 import { getHostOrNull, setDisclosure } from "../state.js";
-import { MERGE_MAP } from "../tool-manifest.js";
-import { readFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
-// Package version — surfaced by catalog({op:'status'|'whatsNew'}) so an agent can
+// Package version — surfaced by catalog({op:'status'}) so an agent can
 // check the running romdev version with a plain TOOL CALL (works over MCP AND the
 // HTTP/skill surface), e.g. to detect a saved skill is stale. (GET /healthz also
 // reports it for non-tool HTTP clients.)
@@ -76,42 +74,6 @@ const PKG_VERSION = (() => {
   }
 })();
 
-// catalog({op:'whatsNew'}): the recent CHANGELOG + an old→new RENAME TABLE
-// derived from MERGE_MAP (the single source of truth for the consolidation), so
-// an agent resuming a handoff written against an older server can re-map every
-// renamed tool in ONE read. Pre-1.0 the surface is consolidated freely with NO
-// deprecated aliases (see the consolidation), which is exactly why this exists.
-async function buildWhatsNew() {
-  // old name → "newTool({axis:'oldOpName'})". The op value is best-effort: most
-  // absorbed tools become an op whose name is a shortened form, so we surface the
-  // axis + the new tool and let the tool's own description give the exact op enum.
-  const renames = {};
-  for (const [newTool, entry] of Object.entries(MERGE_MAP)) {
-    if (entry.unchanged) continue;
-    for (const old of entry.absorbs ?? []) {
-      renames[old] = { nowOn: newTool, axis: entry.axis };
-    }
-  }
-  // Recent CHANGELOG entries (top of the file = newest). Best-effort: if the file
-  // isn't packaged in some install, return the rename table alone.
-  let changelog = null;
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    // src/mcp/tools/ → package root is three up.
-    const text = await readFile(join(here, "..", "..", "..", "CHANGELOG.md"), "utf8");
-    // Keep the two most recent version sections.
-    const sections = text.split(/^## /m);
-    changelog = sections.slice(0, 3).join("## ").trim();
-  } catch { /* changelog not present in this install */ }
-  return {
-    romdevVersion: PKG_VERSION,
-    note: "Pre-1.0 the tool surface is consolidated freely with NO deprecated aliases. If a tool name from an older handoff is missing, it's almost certainly now an `op` (or other axis) on a domain tool — find it below, then read that tool's description for the exact op enum and params.",
-    renameTable: renames,
-    axisLegend: "Every domain tool is keyed by ONE axis: op (most), output (build), on (breakpoint), target (disasm), view (background), source (palette), stage (encodeArt), from (importArt). The value names the operation, e.g. romPatch({op:'findPointer'}).",
-    ...(changelog ? { changelog } : { changelogNote: "CHANGELOG.md not bundled in this install." }),
-  };
-}
-
 /**
  * Categories for progressive disclosure. Each entry's `register` is the
  * existing per-module registration function — we don't rewrite the
@@ -225,16 +187,12 @@ export function registerTools(server, z, sessionKey) {
     "catalog",
     "Orient yourself, keyed by `op`.\n" +
     "• op:'categories' (default) — the catalog of tool categories, each {name, description, useWhen[], loaded}. This server registers EVERY tool at session start, so this is just a map grouped by purpose for orientation, NOT a gate — you do NOT need to load anything before calling a tool.\n" +
-    "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.\n" +
-    "• op:'whatsNew' — the recent CHANGELOG + an OLD→NEW tool RENAME TABLE. Call this FIRST if you're resuming work from a handoff written against an older server: pre-1.0 the surface is consolidated freely (no deprecated aliases), so a name you remember may now be an `op` on a domain tool. This maps them in one read instead of probing each tool.",
+    "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.",
     {
-      op: z.enum(["categories", "status", "whatsNew"]).default("categories")
-        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale); whatsNew=recent CHANGELOG + old→new tool rename table."),
+      op: z.enum(["categories", "status"]).default("categories")
+        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale)."),
     },
     safeTool(async ({ op = "categories" }) => {
-      if (op === "whatsNew") {
-        return jsonContent(await buildWhatsNew());
-      }
       if (op === "status") {
         const host = getHostOrNull(sessionKey);
         const cats = disclosure.listCategories();

package/src/mcp/tools/input.js

@@ -228,6 +228,7 @@ export function registerInputTools(server, z, sessionKey) {
       key: z.string().optional().describe("op=pressKey (C64): key name — f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, ctrl, cbm, home, down, right, lshift, rshift."),
       text: z.string().optional().describe("op=typeText (C64): string fed into the keyboard buffer; \\r / \\n become RETURN. e.g. 'LOAD\"*\",8,1\\rRUN\\r'."),
       joyport: z.number().int().min(1).max(2).optional().describe("op=joyport (C64): set the active joystick port (1 or 2). Omit to just GET the current port. Default is 2 (most C64 games)."),
+      verify: z.boolean().default(false).describe("op=pressKey (C64): also sample CIA1 $DC00/$DC01 (the keyboard/joystick scan ports the KERNAL reads) BEFORE / DURING (key held) / AFTER, plus matrix coords + active joyport. Use to tell apart 'my key never reached VICE' (before==during) from 'VICE saw it but the game ignored it' (they differ but no reaction) when a C64 game doesn't respond to a key."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -256,6 +257,10 @@ export function registerInputTools(server, z, sessionKey) {
         case "pressKey": {
           if (!args.key) throw new Error("input({op:'pressKey'}): `key` is required (C64 keyboard key, e.g. 'f1', 'return', 'run/stop').");
           const host = getHost(sessionKey);
+          if (args.verify) {
+            const v = host.pressC64KeyVerify(args.key, args.frames ?? 4);
+            return jsonContent({ pressedKey: v.key, matrix: [v.row, v.col], frames: v.frames, joyport: v.joyport, autoReleased: v.autoReleased, cia1: v.cia1, frameCount: host.status.frameCount, note: v.note });
+          }
           const r = host.pressC64Key(args.key, args.frames ?? 4);
           return jsonContent({ pressedKey: r.key, matrix: [r.row, r.col], frames: r.frames, frameCount: host.status.frameCount });
         }

package/src/mcp/tools/project.js

@@ -1422,7 +1422,7 @@ async function copyDirRecursive(fs, path, srcDir, dstDir, writtenFiles, dstPrefi
  *   handler returns: {path, platform, template, files, sourceFile,
  *   toolchain, nextStep}.
  */
-export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false }) {
+export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false, verbose = false }) {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");
   const { fileURLToPath } = await import("node:url");
@@ -1768,7 +1768,12 @@ Compiles **C89**, not C99/C11. Stick to:
   }
   filesSection += `\nEvery byte that compiles into your ROM is in this directory. If you move the repo somewhere else, you don't need to install anything from romdev to rebuild it — the compiler binaries are the only external dependency.\n\n`;
 
-  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\n${buildBlock}\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Call \`build({output:"run", ...})\` to see your changes. It builds + loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`memory({op:"read"})\`, \`sprites({op:"inspect"})\`, \`palette({source:"live"})\`, \`background({view:"rendered"})\`.\n- Open a playtest window for human eyes: \`playtest({op:"open"})\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
+  // Lead with the project-dir build — ONE call, no manifest. The verbose
+  // output:'run' + sourcesPaths form (buildBlock) is the "editing loose
+  // source" variant, shown second.
+  const projectBuildBlock =
+    "```js\nbuild({\n  output: \"project\",\n  platform: \"" + platform + "\",\n  path: \"" + projPath + "\",\n  outputPath: \"" + name + romExt + "\",\n})\n```";
+  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\nThe whole project directory builds in ONE call — romdev infers the toolchain, crt0, and linker from the directory, so you don't pass a file manifest:\n\n${projectBuildBlock}\n\nAdd \`output:"run"\` instead of \`"project"\` to also load + run + screenshot in the same round trip. Re-run the exact same call after every edit.\n\n<details>\n<summary>Alternative: build from a hand-specified source manifest (when compiling edited loose source, not a project dir)</summary>\n\n${buildBlock}\n</details>\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Re-run the \`build({output:"project"|"run", path})\` call above to see your changes — it builds + (for run) loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`memory({op:"read"})\`, \`sprites({op:"inspect"})\`, \`palette({source:"live"})\`, \`background({view:"rendered"})\`.\n- Open a playtest window for human eyes: \`playtest({op:"open"})\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
   await fs.writeFile(path.join(projPath, "README.md"), readme, "utf-8");
   writtenFiles.push("README.md");
 
@@ -1828,19 +1833,46 @@ Compiles **C89**, not C99/C11. Stick to:
     }
   }
 
+  // Split the manifest: project-OWNED files (main.c, runtime helpers, crt0,
+  // cfg, README…) are the only ones an agent touches; the rest are internal
+  // toolchain copies on disk that never enter a decision. Echoing all of
+  // them — 35/44 on NES (vendor/cc65/libsrc/*), 173/264 on GBA (libtonc
+  // include/+sysinclude/), ~270 on SGDK Genesis — was pure context noise
+  // across a matrix run. Default to a compact receipt (owned list + a
+  // not-owned COUNT); `verbose:true` restores the full flat list.
+  //
+  // Classify NON-owned by what it actually is, NOT just a `vendor/` prefix:
+  // the cc65 path lands under vendor/, but the GBA/Genesis SDKs drop their
+  // header trees at include/ + sysinclude/ (no vendor/ prefix) and prebuilt
+  // crt objects/archives at the root — none of which an agent edits. (R: the
+  // original `!startsWith('vendor/')` denylist missed exactly these two SDK
+  // platforms — same bug class as the original fix, second location.)
+  const isVendored = (f) =>
+    f.startsWith("vendor/") ||                    // cc65 libsrc, pvsneslib, sgdk src
+    f.startsWith("include/") ||                   // SDK header trees (libtonc/libgba/SGDK/maxmod)
+    f.startsWith("sysinclude/") ||                // libgba/libtonc system headers
+    /^crt[a-z0-9]*\.o$/i.test(f) ||               // prebuilt crt objects (crti/crtn/crtbegin/crtend)
+    /\.(a|lib)$/i.test(f);                         // prebuilt static archives
+  const ownedFiles = writtenFiles.filter((f) => !isVendored(f));
+  const vendorFileCount = writtenFiles.length - ownedFiles.length;
   return {
     path: projPath,
     platform,
     template: hasTemplates ? (template ?? "default") : null,
-    files: writtenFiles,
+    // The files you actually edit. Vendored toolchain copies are summarized,
+    // not listed — they're on disk under vendor/ if you ever need them.
+    files: ownedFiles,
+    fileCount: writtenFiles.length,
+    vendorFileCount,
+    ...(verbose ? { allFiles: writtenFiles } : {}),
     snippetsCopied: withSnippets ? snippetFiles : null,
     sourceFile: path.join(projPath, mainFilename),
     toolchain: lang,
-    nextStep: `Edit ${path.join(projPath, mainFilename)} and call build({output:"run", ...}) with sourcesPaths/includePaths pointing at the project's files (see the README's "Build + run" block for the exact call). Everything you need is in the directory — nothing is hidden.`,
+    nextStep: `Build the scaffold AS-IS in one call: build({output:"project", platform:"${platform}", path:"${projPath}", outputPath:"<game>.<ext>"}) — it infers the toolchain/crt0/linker from the directory, no sourcesPaths/includePaths/linkerConfig needed. Then edit ${mainFilename} and re-run the same call. (build({output:"run", ...}) with a hand-specified sourcesPaths manifest is the alternative when you're compiling edited loose source instead of a project dir.)`,
   };
 }
 
-async function createGameCore({ platform, genre, name, path: projPath, title, overwrite }) {
+async function createGameCore({ platform, genre, name, path: projPath, title, overwrite, verbose = false }) {
       // The five canonical genres. A genre is available on a platform iff
       // TEMPLATES[platform] has a matching template entry — we DERIVE
       // availability from TEMPLATES rather than maintain a parallel table,
@@ -1887,7 +1919,7 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
       // Genre id IS the template id (they're 1:1 by construction).
       const templateId = genre;
       const result = await createProjectImpl({
-        platform, template: templateId, name, path: projPath, title, overwrite,
+        platform, template: templateId, name, path: projPath, title, overwrite, verbose,
       });
       return { ...result, genre, template: templateId };
 }
@@ -1917,6 +1949,7 @@ export function registerProjectTools(server, z) {
       // project
       template: z.string().optional().describe("op=project: template id ('default' | 'hello_sprite' | 'tile_engine' on NES/GB/GBC; 'default' elsewhere)."),
       withSnippets: z.boolean().default(false).describe("op=project: also drop every vetted snippet alongside main (= scaffold copySnippets after)."),
+      verbose: z.boolean().default(false).describe("op=project/game: echo the FULL flat file manifest (incl. vendor/** toolchain copies) as `allFiles`. Default false — the response lists only project-OWNED files you edit (`files`) plus a `vendorFileCount`, since the vendored toolchain copies are on disk and never need echoing (they're 35 of 44 entries on NES, ~270 on SGDK Genesis). Set true only if you specifically need every path in the response."),
       // game
       genre: z.string().optional().describe("op=game: 'shmup' | 'platformer' | 'puzzle' | 'sports' | 'racing'."),
       // snippets

package/src/mcp/tools/record.js

@@ -44,11 +44,12 @@ export function registerRecordTools(server, z, sessionKey) {
         .array(
           z.object({
             atFrame: z.number().int().min(0),
-            ports: z.array(inputShape).max(2),
+            ports: z.array(inputShape).max(2).optional(),
+            keys: z.array(z.string()).optional().describe("C64-ONLY: C64 keyboard keys held from this frame until the next entry (f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, …). [] releases all held keys. Unknown keys are rejected with a clear error. Lets you script a keyboard+joystick startup timeline (e.g. {atFrame:0,keys:['f1']},{atFrame:30,ports:[{b:true}]},{atFrame:90,keys:['run/stop']}) in one call."),
           }),
         )
         .optional()
-        .describe("Per-frame input changes. Each entry sets the input at `atFrame` and holds it until the next entry."),
+        .describe("Per-frame input changes. Each entry sets the input at `atFrame` (joystick `ports` and/or C64 `keys`) and holds it until the next entry. Either field is optional — a step may set just keys, just ports, or both."),
       memorySamples: z
         .array(
           z.object({
@@ -99,7 +100,12 @@ export function registerRecordTools(server, z, sessionKey) {
       while (elapsed < frames) {
         // Apply any scripted inputs whose atFrame ≤ current frame.
         while (scriptIdx < script.length && script[scriptIdx].atFrame <= elapsed) {
-          host.setInput({ ports: script[scriptIdx].ports });
+          const entry = script[scriptIdx];
+          if (entry.ports) host.setInput({ ports: entry.ports });
+          // C64 keyboard keys held from this entry until the next. Pass [] to
+          // release all. Only valid on a C64/VICE host (setC64HeldKeys throws
+          // otherwise — surfaced as a clear error, not a silent no-op).
+          if (entry.keys !== undefined) host.setC64HeldKeys(entry.keys);
           scriptIdx++;
         }
         const batch = Math.min(sampleEvery, frames - elapsed);

package/src/platforms/c64/MENTAL_MODEL.md

@@ -134,6 +134,26 @@ key:
 A typical C64 RE startup: load → step to the title → `pressKey f1` (1 player) →
 `set {b:true}` (fire to start) → step → you're in gameplay → `state({op:'save'})`.
 
+**Script the whole startup in one call.** `recordSession`'s `inputScript` takes
+C64 `keys` alongside joystick `ports` — held from each entry until the next — so a
+key+joystick startup is one deterministic timeline instead of many calls:
+```js
+recordSession({ frames:600, sampleEvery:60, outputDir:'…', inputScript:[
+  { atFrame:0,  keys:['f1'] },        // 1 player
+  { atFrame:30, ports:[{ b:true }] }, // fire (port 2)
+  { atFrame:90, keys:['run/stop'] },  // start
+  { atFrame:120, keys:[] } ] })       // release
+```
+A step may set just `keys`, just `ports`, or both; `keys:[]` releases all. An
+unknown key is rejected with a clear error (not a silent no-op).
+
+**When a key seems ignored, probe it.** `input({op:'pressKey', key:'run/stop',
+verify:true})` returns the matrix coords, active joyport, and a CIA1 snapshot
+(`$DC00`/`$DC01`) **before / during (held) / after**. `before==during` ⇒ the key
+never moved the matrix line (didn't reach VICE); they differ but the game didn't
+react ⇒ it scanned a different key/port, or that screen (crack/doc/trainer)
+ignores it. This is how you tell a romdev problem from a game-flow problem.
+
 **Controller-alone (playtest):** a human in `playtest` needs no keyboard — the
 pad's spare buttons map to the C64 keys (X=Space, L2=Run/Stop, R2=Return,
 right-stick=F1/F3/F5/F7, top face=F1; d-pad+Fire=joystick). The same mapping

package/src/mcp/tool-manifest.js

@@ -1,92 +0,0 @@
-// Tool manifest — the SINGLE SOURCE OF TRUTH for the consolidated tool surface.
-//
-// The 132→34 consolidation (see internal CONSOLIDATION_PLAN) merges narrow tools
-// into domain tools with a typed operation axis. This manifest records, for each
-// consolidated tool, the OLD tools it absorbs and the axis it routes on — so:
-//   1. a coverage-gate test can assert every old tool name maps to exactly one
-//      new tool (no capability silently dropped, no dupe);
-//   2. a tool-count budget test can fail the build if the surface regrows;
-//   3. docs + the rename map for downstream agents derive from one place.
-//
-// GOVERNANCE: a new capability is a new PARAMETER/op-value on an existing tool by
-// default — NOT a new top-level tool. Adding an entry here is a deliberate act the
-// budget test surfaces at PR time.
-//
-// Each MERGE_MAP entry: newTool → { absorbs:[...oldNames], axis:'op'|'as'|... }.
-// `absorbs: []` + `unchanged:true` means the tool kept its name (no merge).
-// This map grows one domain at a time as each consolidated tool lands.
-
-export const MERGE_MAP = {
-  // ── files (generic disk I/O) ──
-  files: { absorbs: ["writeAsset", "readAsset", "listAssets"], axis: "op" },
-  // ── cheats (DB lookup/search + apply/clear + make) ──
-  cheats: { absorbs: ["gameCheats", "searchCheats", "applyCheat", "clearCheats", "makeCheat"], axis: "op" },
-  // ── text (custom-font learn/encode/find for romhacking) ──
-  text: { absorbs: ["learnFontMap", "encodeTextForRom", "findEncodedText"], axis: "op" },
-  // ── symbols (name↔addr, memory map, PC→symbol). buildSourceWithDebug stays for `build`. ──
-  symbols: { absorbs: ["resolveSymbol", "lookupAddress", "getMemoryMap", "listSymbols", "addressToSymbol"], axis: "op" },
-  // ── disasm (raw bytes / ROM / project / references) ──
-  disasm: { absorbs: ["disassemble", "disassembleRom", "disassembleProject", "findReferences"], axis: "target" },
-  // ── state (save/load/list/export/dump/diff; diffState moved here from memory.js) ──
-  state: { absorbs: ["saveState", "loadState", "listStates", "exportState", "dumpState", "diffState"], axis: "op" },
-  // ── input (set/press/sequence/navigate/layout; getInputLayout folded in) ──
-  input: { absorbs: ["setInput", "pressButton", "inputSequence", "navigate", "getInputLayout"], axis: "op" },
-  // ── platform (list/resolve/toolchains/docs/doc; spans platforms.js+platform-docs.js+toolchain.js) ──
-  platform: { absorbs: ["listPlatforms", "resolvePlatform", "listToolchains", "installToolchain", "listPlatformDocs", "getPlatformDoc"], axis: "op" },
-  // ── host (unload/shutdown/reset/pause/resume FSM; loadMedia + getStatus stay separate) ──
-  host: { absorbs: ["unloadMedia", "shutdown", "reset", "pause", "resume"], axis: "op" },
-  // ── frame (step/screenshot/stepAndShot/stepInstruction; stepInstruction folded from watch-memory.js) ──
-  frame: { absorbs: ["stepFrames", "screenshot", "stepAndScreenshot", "stepInstruction"], axis: "op" },
-  // ── scaffold (project/game + snippets; patchGbHeader folded into romPatch op:'gbHeader') ──
-  scaffold: { absorbs: ["createProject", "createGame", "starterSnippets", "copyStarterSnippets"], axis: "op" },
-  // ── cart (identify/extract/wrap; identifyRom from rom-id.js, rest from cart-parts.js) ──
-  cart: { absorbs: ["identifyRom", "extractCart", "wrapRomFromParts"], axis: "op" },
-  // ── palette (live/platformMaster/lospec; spans platform-tools.js + lospec.js) ──
-  palette: { absorbs: ["inspectPalette", "getPlatformPalettePng", "getLospecPalette"], axis: "source" },
-  // ── audioDebug (inspect/record; getAudioState from platform-tools.js, recordAudio from audio.js; pcmToBrr/wavToXgm2Pcm stay) ──
-  audioDebug: { absorbs: ["getAudioState", "recordAudio"], axis: "op" },
-  // ── sprites (inspect OAM + meta-sprite pipeline; inspectSprites from platform-tools.js, rest from metasprite-tools.js; validateGenesisTiles stays for encodeArt) ──
-  sprites: { absorbs: ["inspectSprites", "groupVisibleSprites", "previewVisibleSprites", "captureMetaSprite", "renderMetaSpritePreview", "emitMetaSpriteRenderer", "extractSpriteFromScreenshot"], axis: "op" },
-  // ── background (tilemap/render-state; inspectBackgroundMap from platform-tools.js, getRenderingContext from rendering-context.js, whichTilesAreRendered from which-tiles.js) ──
-  background: { absorbs: ["inspectBackgroundMap", "getRenderingContext", "whichTilesAreRendered"], axis: "view" },
-  // ── tiles (decode/render tile bytes; inspectPatternTiles from platform-tools.js, getTile/tileFingerprints/tilesAscii from tile-inspect.js, extractSpriteSheet from rom-id.js, previewTileArt from preview-tile.js) ──
-  tiles: { absorbs: ["inspectPatternTiles", "getTile", "tileFingerprints", "tilesAscii", "extractSpriteSheet", "previewTileArt"], axis: "op" },
-  // ── encodeArt (PNG→native art; convertImageToTiles+imageToTilemap from platform-tools.js, quantizePngForPlatform+cropSpriteSheet from sprite-pipeline.js, validateGenesisTiles from metasprite-tools.js) ──
-  encodeArt: { absorbs: ["convertImageToTiles", "imageToTilemap", "quantizePngForPlatform", "cropSpriteSheet", "validateGenesisTiles"], axis: "stage" },
-  // ── importArt (editor-file/ROM → native tiles; load* from art-loaders.js, crossPlatformSpriteImport from sprite-pipeline.js as from:'rom') ──
-  importArt: { absorbs: ["loadAsepriteSheet", "loadGifAnimation", "loadSpriteSheet", "loadTilemap", "crossPlatformSpriteImport"], axis: "from" },
-  // ── memory (read/write/search; all 8 from memory.js) ──
-  memory: { absorbs: ["readMemory", "writeMemory", "readCartRom", "snapshotMemory", "diffMemory", "classifyRegion", "searchValue", "searchNext"], axis: "op" },
-  // ── cpu (read/drive; getCPUState from platform-tools.js, setRegister/callSubroutine/decompressWith from watch-memory.js) ──
-  cpu: { absorbs: ["getCPUState", "setRegister", "callSubroutine", "decompressWith"], axis: "op" },
-  // ── breakpoint (STOP-on-first; all 4 from watch-memory.js) ──
-  breakpoint: { absorbs: ["findWriter", "runUntilWrite", "runUntilPC", "runUntilRead"], axis: "on" },
-  // ── watch (LOG-ALL; watchMemory/watchRange/logPCRange + Genesis VDP-DMA trace
-  //    on:'dma' from watchDma/traceVramSource — all from watch-memory.js +
-  //    trace-vram-source.js. dmaTrace was folded in as watch({on:'dma'}).) ──
-  watch: { absorbs: ["watchMemory", "watchRange", "logPCRange", "watchDma", "traceVramSource"], axis: "on" },
-  // ── build (compile/run; buildSource/buildProject/runSource from toolchain.js, buildSourceWithDebug from symbols.js). ENTRY-TIER. ──
-  build: { absorbs: ["buildSource", "buildSourceWithDebug", "buildProject", "runSource"], axis: "output" },
-  // ── romPatch (9-op ROM-hack toolkit; patchFile/patchRom from rom-id.js, spliceCHR from splice-chr.js, relocateBlock/makeStoredBlock/findPointerTo from reinject.js, findFreeSpace from free-space.js, diffRoms from diff-roms.js, patchGbHeader as op:'gbHeader') ──
-  romPatch: { absorbs: ["patchFile", "patchRom", "spliceCHR", "relocateBlock", "makeStoredBlock", "findFreeSpace", "findPointerTo", "diffRoms", "patchGbHeader"], axis: "op" },
-  // ── catalog (orient; listCategories + getStatus, both entry-tier in index.js) ──
-  catalog: { absorbs: ["listCategories", "getStatus"], axis: "op" },
-  // ── playtest (show-a-human window FSM; all 4 from playtest.js). ENTRY-TIER. ──
-  playtest: { absorbs: ["playtestStop", "playtestStatus", "playtestFramebuffer"], axis: "op" },
-  // ── encodeAudio (external clip → native sample format; pcmToBrr + wavToXgm2Pcm from audio.js) ──
-  encodeAudio: { absorbs: ["pcmToBrr", "wavToXgm2Pcm"], axis: "target" },
-};
-
-/** Every OLD tool name that the consolidation removes (absorbed into a new tool). */
-export function absorbedToolNames() {
-  const names = [];
-  for (const entry of Object.values(MERGE_MAP)) {
-    if (entry.absorbs) names.push(...entry.absorbs);
-  }
-  return names;
-}
-
-/** The consolidated (new) tool names this manifest defines. */
-export function consolidatedToolNames() {
-  return Object.keys(MERGE_MAP);
-}