romdevtools 0.28.0 → 0.29.0

package/src/mcp/tools/rom-id.js

@@ -305,13 +305,17 @@ export async function extractSpriteSheetCore({ platform, path: romPath, offset,
         const path = await import("node:path");
         await mkdir(path.dirname(outputPath), { recursive: true });
         await writeFile(outputPath, png);
-        return jsonContent({
+        // Livestream sideband: show the rendered sheet even though the agent
+        // only gets the path.
+        const out = jsonContent({
           path: outputPath,
           intent: d.intent,
           bytes: png.length,
           paletteSource,
           note,
         });
+        out._observerImages = [{ kind: "image", mimeType: "image/png", base64: png.toString("base64") }];
+        return out;
       }
       return {
         content: [

package/src/mcp/tools/run-until.js

@@ -10,6 +10,7 @@
 
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
+import { attachObserverFrame } from "./watch-memory.js";
 
 export function registerRunUntilTools(server, z, sessionKey) {
   const memoryCondition = z.object({
@@ -75,11 +76,12 @@ export function registerRunUntilTools(server, z, sessionKey) {
         }
       }
 
-      return jsonContent({
+      // Livestream: the frame where the condition was met (or where we gave up).
+      return attachObserverFrame(jsonContent({
         conditionMet: met,
         framesStepped,
         finalValue,
-      });
+      }), host, met ? "runUntil: condition met" : "runUntil: gave up");
     }),
   );
 }

package/src/mcp/tools/snippets.js

@@ -97,11 +97,11 @@ export function registerSnippetTools(_server, _z) {
       platform, languages, snippets: filtered,
       note: filtered.length === 0
         ? `No snippets matched for '${platform}'${language ? ` (language=${language})` : ""}.`
-        : `Fetch one with starterSnippets({ platform, mode:'get', name${language ? ", language" : ""} }), or all with mode:'getAll'.`,
+        : `Fetch one with examples({ op:'snippets', platform, mode:'get', snippetName${language ? ", language" : ""} }), or all with mode:'getAll'.`,
     });
   }
   async function snippetsGet(platform, name, language) {
-    if (!name) throw new Error("starterSnippets mode:'get' requires `name`.");
+    if (!name) throw new Error("examples({op:'snippets'}) mode:'get' requires `snippetName`.");
     if (name.includes("..") || (name.includes("/") && !/^[a-z]+\/[\w.-]+$/i.test(name))) {
       throw new Error("snippet name must not contain '..' or arbitrary path separators");
     }
@@ -124,7 +124,7 @@ export function registerSnippetTools(_server, _z) {
       return textContent(`No snippets available for '${platform}'${language ? ` (language=${language})` : ""}.`);
     }
     if (!inline && !outputPath) {
-      throw new Error("starterSnippets mode:'getAll': pass outputPath (write the joined snippets to disk, returns {path}) or inline:true (return `combined` in the response). Or use copyStarterSnippets to write each snippet as its own file.");
+      throw new Error("examples({op:'snippets'}) mode:'getAll': pass outputPath (write the joined snippets to disk, returns {path}) or inline:true (return `combined` in the response). Or use examples({op:'copySnippets'}) to write each snippet as its own file.");
     }
     const parts = [];
     for (const s of filtered) {
@@ -161,7 +161,7 @@ export function registerSnippetTools(_server, _z) {
       if (filtered.length === 0) {
         const langPart = language ? ` (language=${language})` : "";
         const includePart = include ? ` (include=${JSON.stringify(include)})` : "";
-        throw new Error(`copyStarterSnippets: no snippets matched for platform '${platform}'${langPart}${includePart}.`);
+        throw new Error(`examples({op:'copySnippets'}): no snippets matched for platform '${platform}'${langPart}${includePart}.`);
       }
       await mkdir(destinationDir, { recursive: true });
       const written = [];
@@ -201,9 +201,9 @@ export function registerSnippetTools(_server, _z) {
   };
 }
 
-// starterSnippets/copyStarterSnippets folded into the `scaffold` tool. The cores
+// starterSnippets/copyStarterSnippets folded into the `examples` tool. The cores
 // are assigned inside registerSnippetTools (they close over the local helpers);
-// scaffold imports these and calls them. registerSnippetTools registers NO tools
+// examples imports these and calls them. registerSnippetTools registers NO tools
 // now — it just wires the cores.
 export let starterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };
 export let copyStarterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };

package/src/mcp/tools/sprite-pipeline.js

@@ -143,6 +143,7 @@ async function cropSpriteSheetImpl({ path, tileX, tileY, tileW, tileH, tileSize
   }
   await writeFile(outputPath, outBuf);
   return {
+    _observerImages: [{ kind: "image", mimeType: "image/png", base64: outBuf.toString("base64") }],
     path: outputPath,
     intent: d.intent,
     width: pxW,
@@ -157,6 +158,16 @@ async function cropSpriteSheetImpl({ path, tileX, tileY, tileW, tileH, tileSize
   };
 }
 
+// Lift a plain core result's livestream sideband OUT of the JSON body and
+// onto the MCP result object (it must never serialize into agent-visible text).
+function liftObserverImages(r) {
+  const sideband = r._observerImages;
+  delete r._observerImages;
+  const out = jsonContent(r);
+  if (sideband) out._observerImages = sideband;
+  return out;
+}
+
 // ── quantizePngForPlatform ──────────────────────────────────────────
 
 /**
@@ -247,6 +258,7 @@ async function quantizePngForPlatformImpl({ path, platform, outputPath, intent,
   const outBuf = writeIndexedPng(png.width, png.height, indices, palette);
   await writeFile(outputPath, outBuf);
   return {
+    _observerImages: [{ kind: "image", mimeType: "image/png", base64: outBuf.toString("base64") }],
     path: outputPath,
     intent: d.intent,
     width: png.width,
@@ -596,12 +608,12 @@ export function registerSpritePipelineTools(server, z, _sessionKey) {
         case "quantize": {
           if (!args.platform) throw new Error("encodeArt({stage:'quantize'}): `platform` is required.");
           if (!args.path || !args.outputPath) throw new Error("encodeArt({stage:'quantize'}): `path` and `outputPath` are required.");
-          return jsonContent(await quantizePngForPlatformImpl(args));
+          return liftObserverImages(await quantizePngForPlatformImpl(args));
         }
         case "crop": {
           if (!args.path || !args.outputPath) throw new Error("encodeArt({stage:'crop'}): `path` and `outputPath` are required.");
           if (args.tileX == null || args.tileY == null || args.tileW == null || args.tileH == null) throw new Error("encodeArt({stage:'crop'}): `tileX`, `tileY`, `tileW`, `tileH` are required.");
-          return jsonContent(await cropSpriteSheetImpl(args));
+          return liftObserverImages(await cropSpriteSheetImpl(args));
         }
         case "tiles": {
           if (!args.platform) throw new Error("encodeArt({stage:'tiles'}): `platform` is required.");

package/src/mcp/tools/state.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile, readFile } from "node:fs/promises";
 import path from "node:path";
 import { getHost } from "../state.js";
+import { attachObserverFrame } from "./watch-memory.js";
 import { jsonContent, safeTool } from "../util.js";
 
 // Resolve a state-file `path`. An ABSOLUTE path is used as-is. A RELATIVE path
@@ -342,7 +343,7 @@ export function registerStateTools(server, z, sessionKey) {
     safeTool(async (args) => {
       switch (args.op) {
         case "save":   return jsonContent(await saveStateCore(args, sessionKey));
-        case "load":   return jsonContent(await loadStateCore(args, sessionKey));
+        case "load":   return attachObserverFrame(jsonContent(await loadStateCore(args, sessionKey)), getHost(sessionKey), `state load ${args.name ?? args.path ?? ""}`.trim());
         case "list":   return jsonContent(listStatesCore(args, sessionKey));
         case "export": {
           if (!args.fromSlot) throw new Error("state({op:'export'}): `fromSlot` is required.");

package/src/mcp/tools/tile-inspect.js

@@ -284,7 +284,14 @@ export function registerTileInspectTools(server, z, sessionKey) {
           if (r.pngBase64) {
             return { content: [imageContent(r.pngBase64), textContent(JSON.stringify({ ...r, pngBase64: undefined }))] };
           }
-          return jsonContent(r);
+          // Lift the livestream sideband OUT of the core's plain result before
+          // it's serialized — it must ride on the MCP result object, never in
+          // the agent-visible JSON text.
+          const sideband = r._observerImages;
+          delete r._observerImages;
+          const out = jsonContent(r);
+          if (sideband) out._observerImages = sideband;
+          return out;
         }
         default: throw new Error(`tiles: unknown op '${args.op}'`);
       }

package/src/mcp/tools/toolchain.js

@@ -703,7 +703,7 @@ export function registerToolchainTools(server, z, sessionKey) {
     "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
     "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`). **`resolveSymbols:['grid','score']` folds those names' addresses ({resolvedSymbols:{grid:{address,hex,region?,ramOffset?}}}) straight into the result — the cheap way to a WRAM variable's address without loading the whole map (or round-tripping it through `symbols`).**\n" +
     "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
-    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for a scaffold({op:'project'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a scaffolded project.**",
+    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for an examples({op:'fork'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a forked project.**",
     {
       output: z.enum(["rom", "romWithDebug", "run", "project"])
         .describe("rom=produce a ROM (default); romWithDebug=ROM + .dbg/.map debug files; run=build+load+run+screenshot; project=build a project directory."),
@@ -838,6 +838,17 @@ export function projectBuildRecipe(platform, names) {
     // commercial ROMs boot in the same host; only our scaffolds failed). Routing
     // msx_crt0.s through crt0 makes ITS header + init the cartridge entry.
     if (has("msx_crt0.s")) { r.crt0File = "msx_crt0.s"; r.codeLoc = 0x4010; }
+  } else if (platform === "pce") {
+    // PCE example projects (they ship pce_hw.h) build on the 'rom32k' preset:
+    // a 32KB HuCard with bank 0 (STARTUP/VECTORS) FIRST in the file at $E000
+    // and banks 1-3 (CODE/RODATA) at $8000-$DFFF, where cc65's pce crt0 TAMs
+    // them before main(). cc65's stock pce.cfg is an 8KB boot bank — too small
+    // for a complete example game — and its documented 32K variant places the
+    // vectors in the LAST file bank, which a HuCard never maps at reset
+    // (verified black screen on geargrafx). An 8KB-sized program still links
+    // and boots identically under this preset, so it's safe for every
+    // pce_hw.h-style project. Bare hand-rolled dirs are left alone.
+    if (has("pce_hw.h")) r.linkerConfig = "rom32k";
   } else if (platform === "sms" || platform === "gg") {
     // SMS/GG: route the project's *_crt0.s through the crt0 channel (like
     // GB/MSX), NOT as a plain source TU. The OLD recipe skipped it on the

package/src/mcp/tools/watch-memory.js

@@ -56,7 +56,7 @@ async function maybeRestoreState(host, fromState, fromStatePath) {
 // observer wrapper encodes it ASYNCHRONOUSLY, after the agent's response has
 // already gone out. The provider is stripped from the agent-visible result. The
 // frame is captured by reference now (correct frozen state) but rasterized later.
-export function attachObserverFrame(json, host) {
+export function attachObserverFrame(json, host, caption) {
   json._observerFrameProvider = () => {
     try {
       const shot = host.screenshot(); // { pngBase64, width, height }
@@ -65,6 +65,7 @@ export function attachObserverFrame(json, host) {
         : null;
     } catch { return null; }
   };
+  if (caption) json._observerFrameCaption = String(caption);
   return json;
 }
 
@@ -927,7 +928,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
             ? `Stopped at ${r.stoppedAtPC} (your stopAtPC) with PARTIAL output — readMemory the dst to see what's been written so far.`
             : "Did not return within maxFrames AND the watchdog didn't trip — this usually means the entry FELL BACK INTO THE GAME (a wrapper PC with a wrong source, so it never reaches the sentinel) and the game is just free-running. finalPC is inside the main loop, not your routine. Re-check the entry PC (use the routine body, not a wrapper) and the source regs; or lower maxInstructions to fail fast while probing. Bump maxFrames/maxInstructions only if you're sure it's a legitimately huge decompress.")
         + frameLogicCaveat;
-      return jsonContent({
+      return attachObserverFrame(jsonContent({
         returned: r.returned, framesRun: r.framesRun, sandbox,
         ...(r.pure ? { pure: true, pureMode: r.pureMode } : {}),
         ...(r.watchdog ? { watchdog: true, reason: r.reason } : {}),
@@ -935,7 +936,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         ...(r.finalPC ? { finalPC: r.finalPC } : {}),
         ...(r.finalRegs ? { finalRegs: r.finalRegs } : {}),
         note,
-      });
+      }), host, "cpu call");
   }
 
   async function cpuDecompress({ entryPC, sourceAddress, destAddress, maxFrames = 600 }) {

package/src/observer/bus.js

@@ -80,6 +80,79 @@ class ObserverBus extends EventEmitter {
 
 export const observer = new ObserverBus();
 
+// ── Throttled deferred-frame emission ───────────────────────────────────────
+// `call_frame` events carry a freshly-rasterized framebuffer PNG for the
+// human's livestream. Tools attach a PROVIDER thunk (attachObserverFrame) and
+// both transports route it here. Two guarantees:
+//   1. The PNG encode NEVER runs on the agent's critical path (deferred via
+//      setImmediate / the trailing timer).
+//   2. Rate-limited to one frame per FRAME_MIN_INTERVAL_MS **per
+//      (session, tool)** — frame({op:'step'}) called 120× in a narrowing loop
+//      emits at most every 2s, but a step followed immediately by a DIFFERENT
+//      tool's frame (input, state load, …) still shows: distinct tools don't
+//      throttle each other. Trailing-edge: the LAST suppressed frame in a
+//      burst always lands when the window reopens (rendered at fire time =
+//      the current screen, which is exactly what the human wants to converge
+//      on).
+let FRAME_MIN_INTERVAL_MS = 2000;
+export function _setFrameThrottleForTest(ms) { FRAME_MIN_INTERVAL_MS = ms; }
+
+/** @type {Map<string, {lastTs: number, timer: any, pending: null | {provider: Function, meta: object}}>} */
+const _frameThrottle = new Map();
+
+function _emitFrame(provider, meta) {
+  try {
+    const img = provider();
+    if (img) {
+      observer.push({
+        type: "call_frame",
+        sessionKey: meta.sessionKey ?? "http",
+        platform: typeof meta.resolvePlatform === "function" ? (meta.resolvePlatform() ?? meta.platform ?? null) : (meta.platform ?? null),
+        ts: meta.ts ?? Date.now(),
+        tool: meta.tool,
+        ...(meta.caption ? { caption: meta.caption } : {}),
+        images: [img],
+      });
+    }
+  } catch { /* livestream is best-effort; never affects the agent */ }
+}
+
+/**
+ * Queue a deferred framebuffer for the livestream, throttled per
+ * (session, tool). `meta`: { sessionKey, tool, ts?, platform?,
+ * resolvePlatform?, caption? } — resolvePlatform (a thunk) is preferred so
+ * the platform label reflects post-call state (loadMedia sets it DURING the
+ * call). `provider` returns {kind:'image', mimeType, base64} or null; it is
+ * invoked OFF the agent's critical path.
+ */
+export function pushObserverFrame(meta, provider) {
+  const key = `${meta.sessionKey ?? "http"}|${meta.tool ?? "?"}`;
+  let st = _frameThrottle.get(key);
+  if (!st) { st = { lastTs: 0, timer: null, pending: null }; _frameThrottle.set(key, st); }
+  const now = Date.now();
+  if (!st.timer && now - st.lastTs >= FRAME_MIN_INTERVAL_MS) {
+    st.lastTs = now;
+    setImmediate(() => _emitFrame(provider, meta));
+    return;
+  }
+  // Inside the window: stash as the pending trailing frame (latest wins) and
+  // arm the trailing timer once.
+  st.pending = { provider, meta };
+  if (!st.timer) {
+    const delay = Math.max(1, st.lastTs + FRAME_MIN_INTERVAL_MS - now);
+    st.timer = setTimeout(() => {
+      st.timer = null;
+      const p = st.pending;
+      st.pending = null;
+      if (p) {
+        st.lastTs = Date.now();
+        _emitFrame(p.provider, p.meta);
+      }
+    }, delay);
+    if (st.timer.unref) st.timer.unref();   // never hold the process open
+  }
+}
+
 /**
  * Extract image payloads from an MCP tool result. MCP tool results have
  * `content: [{type:'text'|'image', ...}]`. We pull out images so the UI

package/src/observer/livestream.html

@@ -305,7 +305,8 @@
           // One latest image per "tool" (kind = tool name); ev.tool
           // identifies which inspect call produced it.
           s.latestByKind[ev.tool] = { ts: ev.ts, base64: img.base64,
-                                      mimeType: img.mimeType, tool: ev.tool, platform: ev.platform ?? null };
+                                      mimeType: img.mimeType, tool: ev.tool, platform: ev.platform ?? null,
+                                      caption: ev.caption ?? null };
         }
       }
       // screenshotAscii pushes both the PNG (above) AND the raw ANSI
@@ -416,7 +417,8 @@
       card.className = "image-card";
       const dt = new Date(img.ts).toLocaleTimeString();
       const platBadge = img.platform ? `<span class="plat">${escapeHtml(img.platform)}</span> ` : "";
-      card.innerHTML = `<div class="meta"><span>${platBadge}${escapeHtml(img.tool)}</span><span>${dt}</span></div>`;
+      const label = img.caption ? `${img.tool} — ${img.caption}` : img.tool;
+      card.innerHTML = `<div class="meta"><span>${platBadge}${escapeHtml(label)}</span><span>${dt}</span></div>`;
       const el = document.createElement("img");
       el.src = `data:${img.mimeType};base64,${img.base64}`;
       el.alt = img.tool;

package/src/observer/tool-wrap.js

@@ -5,7 +5,7 @@
 //
 // Idempotent per server instance — installs once, repeats are no-ops.
 
-import { observer, extractImages, summarizeForLog } from "./bus.js";
+import { observer, extractImages, summarizeForLog, pushObserverFrame } from "./bus.js";
 import { getHostOrNull } from "../mcp/state.js";
 
 const INSTALLED = Symbol.for("romdev.observer-installed");
@@ -54,6 +54,7 @@ export function installObserverMiddleware(server, sessionKey) {
       const platform = sessionPlatform(sessionKey); // which console this call drives
       let event;
       let frameProvider = null; // deferred framebuffer thunk (encoded async below)
+      let frameCaption = null;  // optional human label for the call_frame event
       if (thrown) {
         event = {
           type: "call",
@@ -98,6 +99,10 @@ export function installObserverMiddleware(server, sessionKey) {
           frameProvider = result._observerFrameProvider;
           delete result._observerFrameProvider;
         }
+        if (result && typeof result === "object" && typeof result._observerFrameCaption === "string") {
+          frameCaption = result._observerFrameCaption;
+          delete result._observerFrameCaption;
+        }
         const inlineImages = extractImages(result);
         const images = inlineImages.length > 0 ? inlineImages : sidebandImages;
         const resultSummary = summarizeForLog(result);
@@ -121,20 +126,18 @@ export function installObserverMiddleware(server, sessionKey) {
       // tool response on observer delivery.
       try { observer.push(event); } catch { /* never let observer kill the tool */ }
 
-      // Deferred frame: encode + push the PNG AFTER the agent's response goes
-      // out, so the (expensive) rasterize never delays the tool. setImmediate
-      // yields the response first; a separate `call_frame` event carries the
-      // image for the human's livestream. Best-effort — never throws into the
-      // tool path. (Only breakpoint/watch tools set a provider.)
+      // Deferred frame: encoded + pushed AFTER the agent's response goes out,
+      // throttled to one per 2s PER (session, tool) with a trailing-edge
+      // emit (bus.js pushObserverFrame) — frame-step loops can't flood the
+      // stream, distinct tools never throttle each other, and the last frame
+      // of a burst always lands. Best-effort — never throws into the tool
+      // path.
       if (frameProvider) {
-        setImmediate(() => {
-          try {
-            const img = frameProvider();
-            if (img) {
-              observer.push({ type: "call_frame", sessionKey, platform, ts: startedAt, tool: name, images: [img] });
-            }
-          } catch { /* livestream is best-effort; never affects the agent */ }
-        });
+        pushObserverFrame({
+          sessionKey, tool: name, ts: startedAt, platform,
+          resolvePlatform: () => sessionPlatform(sessionKey),
+          ...(frameCaption ? { caption: frameCaption } : {}),
+        }, frameProvider);
       }
 
       if (thrown) throw thrown;

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -58,7 +58,7 @@ and DLL; you do NOT poke pixels into a framebuffer.**
   and (worse) burns enough cycles that the CPU stops getting time.
 - **Y position = which zone the object lives in.** Each zone covers
   N scanlines. To move an object up/down, you move it between
-  zones. (Or — in our scaffolds — you stamp the same sprite at
+  zones. (Or — in our example games — you stamp the same sprite at
   different row offsets within ONE zone's data block, which fakes
   Y movement.)
 - **Each DL header can pick a palette per object** (one of 8
@@ -136,7 +136,7 @@ The "loop continues" mask is `0x5F` (bits 0-4 + bit 6). Bit 5
 (indirect flag) and bit 7 (write-mode) do NOT keep the loop going
 by themselves.
 
-### 5-byte extended form (the bundled scaffolds use this)
+### 5-byte extended form (the bundled example games use this)
 
 ```
 +0  pixel-data LOW byte
@@ -195,7 +195,7 @@ scanlines for the ENTIRE display area (243 scanlines on NTSC,
 including 10 lines of top overscan before the visible area).
 
 If your DLL is shorter than 243 entries, MARIA reads past the end
-into random memory and renders garbage zones. The bundled scaffold
+into random memory and renders garbage zones. The bundled example
 allocates 243 entries × 3 bytes = 729 bytes (fits easily in 4 KB
 internal RAM) and points every zone with no objects at a shared
 `dl_empty[2] = {0, 0}` terminator.
@@ -213,11 +213,11 @@ for an 8-row sprite) unless you pack many sprites per page.
 **Easy work-around:** make every zone 1 scanline tall (offset=0)
 and use one DL entry per sprite ROW. Then `offset` is always 0, the
 address quirk goes away, and you can store sprite rows back-to-back.
-The bundled scaffold uses this pattern.
+The bundled example uses this pattern.
 
 The cost is more DLL entries (one per scanline), but at 3 bytes each
 across 243 lines = 729 bytes total — trivial RAM cost. Worth it for
-the simpler mental model on a starter scaffold.
+the simpler mental model on a starter example.
 
 ## Colour bytes (Atari NTSC palette)
 

package/src/platforms/atari7800/TROUBLESHOOTING.md

@@ -56,14 +56,14 @@ you have to:
 2. Place the sprite's DL entry into the zone covering its Y range.
 3. Per-frame, move the entry's bytes from old-zone DL → new-zone DL.
 
-Our scaffolds use a single-zone DLL for simplicity. Vertical
+Our example games use a single-zone DLL for simplicity. Vertical
 movement is faked by stamping the sprite at different row offsets
 within the canvas data — only works if the canvas is tall enough.
 
 ## "Memory overflow during link (RAM1 by N bytes)"
 
 The 7800 has **4 KB of RAM**. The `default.c` and `hello_sprite.c`
-scaffolds use very little; the `shmup.c` puzzle (and the older
+example games use very little; the `shmup.c` puzzle (and the older
 canvas-buffer approach) easily blow past it.
 
 Symptoms:
@@ -77,7 +77,7 @@ Fixes:
 - Use ROM constants (`const uint8_t` at file scope) instead of
   RAM globals.
 - Replace canvas-buffer rendering with per-object DLs (see
-  `shmup.c` scaffold for the canonical pattern).
+  `shmup.c` example for the canonical pattern).
 - Avoid per-frame `memset(canvas, 0, ...)` — instead, only stamp
   changed cells.
 
@@ -126,7 +126,7 @@ DL during active rendering; safe modification windows:
 Build a "next-frame" DL during the game-state update phase and
 swap pointers (DPPL/DPPH) at vblank — double-buffered.
 
-Our scaffolds rebuild the DL during vblank, which works for small
+Our example games rebuild the DL during vblank, which works for small
 DLs (< ~100 bytes). Large DLs that take ~1 ms to rebuild may
 exceed vblank time and start corrupting the active frame.
 
@@ -197,5 +197,5 @@ Fix options (in order of how much they shrink BSS):
   if you only need one sprite at a time — see `default.c` and
   `hello_sprite.c`. No per-scanline pool needed.
 
-The bundled scaffolds size their pools to fit; if you scale up
+The bundled example games size their pools to fit; if you scale up
 (more objects, taller play area), watch the build log.

package/src/platforms/c64/MENTAL_MODEL.md

@@ -115,9 +115,16 @@ which is what the KERNAL's IRQ uses to update key state every
 
 **Joystick.** One fire button. Press it with `input({op:'set', b: true})` (or
 spatial `south`) — both clear `$DC00` bit 4 (verified live). `a` is a **no-op**
-(no second button). Drive fire with `b`/`south` + the d-pad. The joystick reads
-**port 2** by default; switch with `input({op:'joyport', joyport:1})` /
-`input({op:'joyport'})` to read it.
+(no second button). Drive fire with `b`/`south` + the d-pad.
+
+**Two players.** BOTH C64 control ports are live at once, so 2P games just work:
+**host port 0 = player 1** (control port 2, `$DC00`) and **host port 1 = player
+2** (control port 1, `$DC01`) — the universal "port 0 = P1" convention. Pass two
+port entries: `input({op:'set', ports:[{up:true}, {down:true}]})` moves P1 up and
+P2 down independently. (Under the hood the host enables the VICE userport-adapter
+mapping so both ports route, and swaps them so P1 lands on control port 2 where
+the games read it.) The legacy `input({op:'joyport', joyport:1|2})` still selects
+which single port a ONE-stick setup drives, but you rarely need it now.
 
 **Keyboard (the C64-specific part — many games NEED it).** Unlike consoles, most
 C64 games (and cracktros) gate gameplay behind a KEYBOARD setup screen — **F1**
@@ -311,7 +318,7 @@ loads games, wrap the `.prg` into a `.d64`: `cart({op:'packDisk', prgPath})`
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. C64 scrolling is the fiddliest of
+The `platformer` example is single-screen. C64 scrolling is the fiddliest of
 the platforms because the VIC-II only does a 0-7 px *fine* scroll in hardware;
 moving further is a software char-cell shift.
 

package/src/platforms/c64/TROUBLESHOOTING.md

@@ -83,6 +83,19 @@ KERNAL last selected. Result: ghost input.
 
 **Use port 2 (CIA1_PRA) by default.** All bundled C64 templates do.
 
+## "Player 2 input does nothing"
+
+Both C64 control ports ARE live over MCP, so 2P works — the mapping is just
+non-obvious: **host port 0 → control port 2 ($DC00) = player 1**, **host port 1
+→ control port 1 ($DC01) = player 2** (the universal "port 0 = P1" convention).
+So a 2P game reads P1 from $DC00 and P2 from $DC01, and you drive them with two
+port entries: `input({op:'set', ports:[{up:true},{down:true}]})` moves P1 up,
+P2 down. If P2 seems dead, check you passed a SECOND `ports` entry (not just
+port 0) and that the game actually entered 2P mode (its title pick, e.g. "PORT 1
+FIRE = 2P"). The host enables the VICE userport-adapter mapping + swaps the two
+RetroPad ports under the hood so this convention holds — you don't configure
+anything.
+
 ## "Audio is silent / SID doesn't play"
 
 Three things to check:

package/src/platforms/gb/MENTAL_MODEL.md

@@ -280,9 +280,9 @@ names also resolve (east→A, west→B). So `input({op:'set', a: true})` presses
 expected — unlike the genesis_plus_gx platforms (Genesis/SMS/GG), there's no
 surprise here. (Same for **GBC** — it shares the gambatte core.)
 
-## What `scaffold({op:'project'})` copies into your project
+## What `examples({op:'fork'})` copies into your project
 
-`scaffold({op:'project', platform:"gb"|"gbc", template:...})` writes these files
+`examples({op:'fork', example:"gb/..."|"gbc/...", name, path})` writes these files
 into your project directory. **They're yours** — every byte that compiles
 is in the repo. Edit, fork, replace; nothing is auto-injected at build time.
 
@@ -340,7 +340,7 @@ Most game patterns DON'T need any of this. Try the C path first.
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. To make it a side-scroller:
+The `platformer` example is single-screen. To make it a side-scroller:
 
 - **Hardware scroll:** write `SCX` (`$FF43`) each frame = camera X mod 256.
   The BG is a 32×32 tile map (256×256 px) that wraps, so `SCX` alone scrolls