romdevtools 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,361 @@ 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.29.0 — 2026-06-11
+
+### Examples — the complete-game library, finished & made honest
+- **The 14×5 grid is complete (70 games).** Every platform now ships all five
+  canonical genres. The last gap, the Atari 2600 puzzle, ships as **TILE TWINS**
+  — a memory match-pairs game (a real puzzle: a static, turn-based board drawn
+  as full-width COLUPF bands, the honest TIA fit — not a colored match-3 grid the
+  TIA can't render). Forkable via `examples({op:'fork', example:'atari2600/puzzle'})`.
+- **C64 games now SAVE for real — 1541 disk save.** The honest C64 medium is the
+  floppy (no battery SRAM). All 5 C64 games write a hi-score/record to a SEQ file
+  on drive 8 via the KERNAL; run from a `.d64` it commits to the live disk and
+  `state({op:'exportDisk'})` captures it (reload restores it). As a bare `.prg`
+  there's no mounted disk, so it's an honest in-session no-op. (Replaces the old
+  gated no-op seams — the VICE core already supported writable-disk write-back.)
+- **C64 two-player now works.** The VICE core drove only one control port per
+  RetroPad; host port-1 (P2) input never reached the game. Now both standard
+  control ports are live (host port 0 = P1, host port 1 = P2) — verified by
+  driving both paddles independently in the versus games.
+- **PCE save claim corrected (honesty).** A bare HuCard cannot save — BRAM is
+  peripheral-only (CD-ROM² / Tennokoe Bank / Memory Base 128) on real hardware.
+  The 5 PCE games no longer claim a battery save; they keep an honest in-session
+  hi-score, with the BRAM mapping documented in-file as the real-hardware path.
+- **Honest framing.** The examples are described as SCAFFOLDING, not showcases:
+  the gameplay is intentionally thin — their value is the working boot sequence,
+  APIs, and syntax to fork from. Superlatives dropped from the `examples` tool
+  doctrine and the generated project README.
+
+### Added — livestream frame coverage: see what the agent is doing
+- **Most state-changing tools now emit the post-call frame to /livestream**,
+  at zero cost to the agent (deferred PNG encode after the response goes
+  out): `frame({op:'step'})`, `input` set/press/sequence/navigate,
+  `state({op:'load'})`, `loadMedia`, `host({op:'reset'})` (soft + hard),
+  `runUntil`, `cheats({op:'apply'})`, and `cpu({op:'call'})` — joining the
+  breakpoint/watch hits, verify, and stepInstruction that already emitted.
+- **Throttled to one frame per 2s per (session, tool)**, trailing-edge: a
+  frame-step loop can't flood the stream and its LAST frame always lands;
+  different tools back-to-back all show; multiple agents on one server
+  never throttle each other.
+- **`call_frame` events carry a caption** (`step ×30`, `press start`,
+  `state load boss`, `loaded game.nes`) and the livestream UI shows it on
+  the image card — the stream reads as a narrative.
+- **To-disk renders now reach the stream too**: `tiles({op:'preview'})`,
+  `extractSpriteSheet`-style file renders, and `encodeArt` quantize/crop
+  attach the PNG as an observer sideband when routed to `outputPath` — the
+  human sees the render even though the agent only gets a path.
+
+## 0.28.0
+
+The reverse-engineering release: the three RE primitives — break-instant
+`registersAtHit`, interference-free `pure` CPU calls, and the
+`watch({on:'copy'})` graphics source-trace — now work on ALL 14 platforms
+(every emulator core rebuilt; upstream pins unchanged, everything carried by
+the patches in `scripts/patches/`). Plus the full scaffold overhaul from real
+RetroDECK playtesting, banked-cart parity for disasm/rebuild, the value-search
+upgrades, and the playtest co-drive detection. Details per section below.
+
+
+### Added — pure calls + the generic copy trace on ALL 14 platforms (primitives #2 and #3)
+The other two primitives from the all-platforms RE proposal, completing the
+set (registersAtHit was #1):
+- **`cpu({op:'call', pure:true})` works everywhere.** The guarantee is the
+  same on every platform — the game's own NMI/IRQ/VBlank logic CANNOT run
+  during the call and stomp the routine's output buffer — with the mechanism
+  reported as `pureMode`: Genesis/SMS/GG step ONLY the CPU (`'cpu-only'`,
+  the gpgx separable-loop path); every other core suppresses interrupt
+  DELIVERY for the duration (`'irq-blocked'` via a new `romdev_irqblock_set`
+  export — pending lines stay pending, video/timers advance harmlessly, no
+  game handler executes); the 2600's 6507 has no interrupt lines at all
+  (`'no-interrupts'`). Proven live on NES: NMI delivery verified firing,
+  then silent under the block, then a planted routine pure-called
+  end-to-end with its write landing.
+- **`watch({on:'copy'})` — the generic "where does this graphic come
+  from?".** Logs every write landing in a VRAM/dest address window with the
+  EXECUTING instruction's PC. Port-based video memory is hooked INSIDE the
+  cores — NES $2007, SNES $2118/19 (BOTH CPU port writes and the DMA path —
+  the PC is the DMA-triggering instruction), PCE VWR, MSX VDP data port,
+  SMS/GG/Genesis VDP data port (the CPU-port complement of the Genesis DMA
+  watch). Direct-mapped platforms (GB/GBC, GBA, C64, Lynx, 7800) route
+  through the CPU-address range log automatically. Follow a hit with
+  breakpoint({on:'pc', address: pc}) for registersAtHit at the uploader.
+- Cores rebuilt again (same pins; the scripts/patches/ diffs carry
+  everything — all 11 verified to apply clean to pristine checkouts).
+- `test/pure-copy-primitives.test.js`: the 13-core irq-block/run-pure
+  feature matrix, NES NMI-delivery proof + end-to-end pure call, MSX
+  block-safety, and copy traces on NES (port), SNES (port+DMA), GB (mapped).
+
+### Fixed/Added — registersAtHit + freeze-after-hit on ALL 14 platforms (every core rebuilt)
+The gpgx round's break-instant fixes, extended to every other core — the same
+three guarantees now hold across the whole platform matrix:
+- **`registersAtHit` everywhere** — every breakpoint hit (pc-break, watchdog,
+  write-watch, read-watch) on every platform freezes the FULL register file at
+  the hit instant inside the core hook, exported via `romdev_regsnap_get` and
+  surfaced in the breakpoint hit response. Per-CPU register sets: 6502 family
+  (NES/2600/7800/C64/Lynx/PCE) A/X/Y/P/S/PC; 65816 (SNES) +DB/D; sm83 (GB/GBC)
+  A/F/B/C/D/E/H/L/SP; Z80 (SMS/GG/MSX) +IX/IY; m68k (Genesis) D0-7/A0-7/SR;
+  ARM7 (GBA) r0-r15/CPSR. NES previously snapshotted pc-breaks only — its
+  write/read hits now snapshot too.
+- **Freeze-after-hit everywhere** — once a hit fires, the CPU run loop stays
+  frozen (across re-entries and frames) until the host clears the hit, so even
+  live register reads agree with the snapshot. Previously each core resumed on
+  the next loop re-entry and the registers drifted.
+- **Executing-instruction PC everywhere** — write/read watchpoints and range
+  logs report the EXECUTING instruction's first byte, latched at dispatch
+  (sm83/Z80/65816/6502 PCs advance past operands mid-instruction — the same
+  off-by-one class the gpgx round fixed for m68k; GBA reports the pipeline PC,
+  matching its breakpoint-address convention).
+- Cores rebuilt: fceumm, snes9x, gambatte, mGBA, handy, vice, stella2014,
+  prosystem, geargrafx, bluemsx (pins unchanged; the romdev patches in
+  scripts/patches/ carry all of it — the whole stack reproduces from a clean
+  clone). `cpu({op:'call', pure:true})` remains gpgx-only (the other systems'
+  CPU/video loops are not separable without deeper core surgery); their calls
+  carry the ⚠ frame-logic caveat instead.
+- `test/regsnap-all-cores.test.js`: live single-step snapshot + freeze proof
+  on 10 platforms (plus the existing gpgx suite for Genesis/SMS/GG).
+
+### Fixed/Added — gpgx core round (the NBA-Jam-both-consoles feedback): break-instant truth on Genesis/SMS/GG
+The first core rebuild in this release (gpgx only; pins unchanged, patch extended).
+- **`registersAtHit` on Genesis/SMS/GG** — `breakpoint({on:'pc'|'write'|'read'})`
+  hits now carry the FULL register file (m68k d0-d7/a0-a7/pc/sr/sp; z80
+  a/f/b/c/d/e/h/l/ix/iy/pc/sp) frozen by the core AT the hit instant. gpgx
+  schedules CPUs per scanline, so the live register file used to drift
+  hundreds of instructions past a hit before the host could read it — the
+  "wrong-pointer chases" that cost a real RE session ~2h. On a pc-break the
+  CPU now also stays FROZEN for the remainder of the frame (and across
+  frames until the hit is cleared), so even live reads agree.
+- **Write/read watchpoint PC is the EXECUTING instruction** — the hooks now
+  record the instruction's first-byte address latched at dispatch, not the
+  post-prefetch PC (the orb-at-$2A7216-reported-as-$2A721C off-by-one).
+  `breakpoint({on:'write'})` also renames `value`→`valueByte` (it's the one
+  byte that landed, not the operand) and explains its `hits` semantics.
+- **`cpu({op:'call', pure:true})`** — steps ONLY the active CPU (new
+  `romdev_run_pure` export): no VDP line processing, no co-CPU, no interrupts
+  raised — so the game's own VBlank logic can NOT run "concurrently" and
+  stomp the driven routine's output buffer (a real session diffed a correct
+  codec reimplementation against that poisoned output for ~1.5h). Non-pure
+  calls that spanned frames now carry a loud ⚠ caveat naming the risk and
+  the fix.
+- **Genesis `system_ram` normalized to CPU byte order** — gpgx stores 68k
+  work RAM host-LE word-swapped (`work_ram[A^1]`); the raw layout leaked
+  through every byte-granular tool. Self-consistent within search→write
+  loops (which is why it hid — even a test had the swapped bytes baked in as
+  the expected value), but off-by-XOR-1 the moment an offset crossed to/from
+  disassembly addresses or cheat-DB maps. Offset X now IS the byte the 68k
+  sees at $FF0000+X; words read big-endian as documented. This also fixes
+  `cpu({op:'call'})` sentinel pushes / `presetMemory` writes for any non-zero
+  sentinel address (the default $0 sentinel was swap-invariant, hiding it).
+- breakpoint hit responses normalize `hits` (a watchdog stop no longer
+  reports the contradictory `hit:true, hits:0`).
+- Docs: the held-input menu trick (when a `pressDuring` schedule never
+  registers on a menu screen, hold via `input({op:'set'})` and omit
+  pressDuring — runs inherit held input) is now in the breakpoint/watch tool
+  docs; the server banner prints a one-line headless note when no display is
+  available (so an agent knows before promising a playtest window).
+- `test/gpgx-registers-at-hit.test.js`: live-core coverage for all of it,
+  including a per-platform Genesis memory-read smoke (the earlier
+  "info is not defined" regression was invisible to a fake-host-only suite).
+
+
+### Fixed/Added — value-search upgrades (from the locate-value skill review)
+- **Relative compares work as the FIRST `searchNext`.** `op:'search'` now
+  baselines every candidate at seed time, so `compare:'inc'/'dec'/'changed'/
+  'unchanged'` no longer silently return 0 candidates on the first narrow
+  (the footgun a real session burned rounds on and a skill had to document —
+  the "do one eq round first" workaround is obsolete).
+- **Representation-aware search** — `memory({op:'search', as:'bcd'|'digits'})`
+  for the stored≠displayed cases: `'bcd'` matches packed-BCD values (2 decimal
+  digits/byte, region endianness — classic NES scores); `'digits'` matches one
+  byte per ON-SCREEN digit at ANY constant tile base (HUD digit/tile-index
+  buffers; the base is auto-detected per candidate and reported; single-digit
+  seeds only accept base 0/0x30 to avoid matching everything). `searchNext`
+  narrows in the seed's representation automatically, including numeric
+  `inc`/`dec` on decoded values. Works on all platforms/regions (endianness
+  per region, big-endian m68k included).
+- **search/searchNext response notes fixed** — they recommended the dead
+  `searchValue` name and a `writeMemory({bytes})` form that op:'write'
+  REJECTS; now they name the live ops with a `hex` payload, mention the
+  scene-changed-mid-step empty-round trap, and point input-driven values at
+  `diffRuns`. Same stale-name fix in two `watch` tool notes.
+- `test/search-representations.test.js` covers all of it.
+
+
+### Added — banked-cart parity across ALL platforms (per-bank references + rebuild glue)
+The 0.27.0 feedback round fixed per-bank reference scanning and one-call banked
+rebuild glue for NES only. Every other banked-cart platform now gets the same
+treatment:
+- **`disasm({target:'references'})` scans EVERY bank on every banked format** —
+  SNES multi-bank LoROM (was: only the first 32KB bank), GB/GBC MBC and SMS/GG
+  Sega-mapper and MSX megaROM (was: only the first 32KB), Atari 2600 F8/F6/F4
+  (was: only the boot bank), Atari 7800 (was: only the top 16KB — flat carts now
+  scan the WHOLE image, SuperGame carts per-bank), and >32KB HuCards (was: a
+  wrapped, garbage start address). Non-NES refs carry a `romBank` tag (NES keeps
+  `prgBank`). Very large carts scan the first 64 banks and SAY SO in `notes`.
+- **`disasm({target:'project'})` splits every banked format per-bank** so
+  instructions never straddle a bank edge: Sega-mapper SMS/GG (16KB banks),
+  MSX megaROMs (16KB banks + the "AB" header as its own data region), banked
+  2600 (4KB banks), 7800 SuperGame (16KB banks + the .a78 header split out),
+  >32KB HuCards (8KB pages + optional copier header split out).
+- **Atari 7800 SuperGame and PC Engine HuCards (flat AND banked) get one-call
+  byte-identical `build()` rebuilds** — their asm toolchain is cc65/ca65, the
+  same match that made NES one-call. NES-style glue: HEADER segment carrying
+  the original header bytes, per-bank segment wrappers, generated multi-bank
+  `.cfg` via `linkerConfigPath`. **PCE was previously the one honestly-LOSSY
+  case** (planRegions trimmed real $FF padding and didn't strip copier
+  headers) — both fixed, `verifiable:true` now.
+- **SMS/GG, MSX, and 2600 banked carts get per-bank native rebuild recipes**
+  (their `build()` is SDCC/DASM — can't consume the disasm syntax): per-bank
+  wrappers + cfg blobs (2600), bank-by-bank `as`/`objcopy`/`dd`/`cat` recipes
+  in `BUILD.md` (SMS/GG/MSX), all byte-exact.
+- Proven by `test/banked-parity.test.js`: synthetic banked carts on 7 platforms;
+  byte-identical one-call rebuilds verified end-to-end for 7800 SuperGame,
+  banked PCE, and flat-PCE-with-real-padding.
+
+
+### Fixed — scaffold overhaul from real RetroDECK/Bazzite playtesting (all 14 platforms)
+A full human playtest of every genre scaffold on real hardware surfaced clusters
+of repeated logic errors. The big ones:
+- **SMS/GG: every `build({output:'project'})` ROM black-screened** — the project
+  recipe skipped the dir's `*_crt0.s` believing `buildForPlatform` auto-injects
+  the bundled crt0 (it doesn't; only the rom/run handlers do), so SDCC's stock
+  z80 crt0 linked instead and `main()` never ran. Also: the bundled crt0's reset
+  block was 9 bytes (overflowed into the `.org 0x0008` RST slot, corrupting
+  `jp gsinit`), `_CODE` linked at `$0000` ON TOP of the vector table, and `.gg`
+  ROMs got an SMS region nibble (`$4C`) that flips Genesis-Plus-GX into SMS-compat
+  mode. Project builds now route/fall back to the bundled crt0, `_CODE` sits at
+  `$0100`, GG ROMs get region `$7C`, ROMs pad to 32KB before the TMR SEGA header,
+  and a regression test pins the boot byte + header. The SMS scaffold now ships
+  `sms_crt0.s` like GG/MSX.
+- **"All enemies spawn on the left"** (18 shmup/racing templates): spawn X/lane
+  came from `spawn_timer`, which the caller resets to 0 immediately before
+  `spawn()` — a constant. Each template now has a Galois-LFSR `rand8()`.
+- **Puzzle genre**: the gbc template is now the polished falling-jewel reference
+  game (4-direction matches, gravity + cascade chains, magic piece, SFX + music,
+  collect/flush vblank rendering, dataLoc `$C200` via the gb/gbc project recipe);
+  the DMG gb template is rebuilt around the same core; and the
+  mark/clear/gravity/cascade core is ported to all 10 other platforms (PCE: H+V
+  in its 8KB boot bank). Replaces a horizontal-only scan that missed vertical/
+  diagonal matches, half-cleared 4+ runs, and never dropped survivors.
+- **Atari 2600**: SWCHA ASL carry-chains clobbered A between shifts (pressing
+  RIGHT also "pressed" LEFT — the stuck-to-the-left-edge bug) in three templates;
+  the platformer's terminal-velocity clamp caught POSITIVE velocities (unsigned
+  CMP), killing every jump within one frame; sports' paddle axis was inverted vs
+  the kernel's Y convention and RESBL was never strobed (the ball NEVER moved
+  horizontally — per-frame div-15 + HMBL positioning added); racing re-randomizes
+  both lanes on crash; shmup aliens reaching the cannon reset the wave.
+- **Atari 7800**: the SWCHA joystick bit defines were exactly REVERSED on every
+  template (up/down steered left/right; sports' left/right moved the paddle
+  vertically). Plus speed tuning (platformer movement + jump, puzzle fall rate,
+  sports serve).
+- **Platformers**: GBA fell through every platform (the `blocked_below` gate
+  only matched a 1px window at 20px/frame fall speeds); SNES platforms are now
+  visibly drawn on the scrolled text layer (were invisible collision rects);
+  Lynx landing uses a crossing test (exact-equality check tunnelled); C64
+  `render_view` rewritten ~20x faster (a per-CELL platform scan + 16-bit modulo
+  cost ~2s per 8px scroll step at 1MHz — froze the game and ate jump presses);
+  NES player is red (was sky-blue on sky-blue) and moves 2px/frame; GB/GBC jump
+  height tamed.
+- **GBA sports "never starts"**: `tte_printf` (broken in this libtonc — the
+  documented GBA-1 issue) ran every frame and crashed with an undefined-
+  instruction exception on iteration 1. Replaced with the `tte_write` digit path
+  the other templates already use.
+- **SNES**: each genre now gets a distinct backdrop tint (every scaffold shipped
+  the same blue checkered wallpaper).
+- **Sound everywhere**: every scaffold now has a continuous background-music
+  loop plus audible SFX, verified per platform by recording + RMS analysis.
+  Genesis/Lynx tick a melody inside `sfx_update()` (no template wiring; Lynx
+  voices 64→100), NES adds a triangle-channel melody to `nes_runtime`, PCE a
+  ch5 melody with corrected volume (the 5-bit field is ~-1.5dB/step from 31 —
+  the old 13 was -27dB, near-silence; the shmup SFX are maxed), and the SMS/GG
+  3-voice tracker that already shipped is now actually STARTED by all 11
+  templates. **MSX root cause**: `msx_crt0.s` had the same `_INITIALIZER`-in-RAM
+  bug fixed for SMS/GG (every `static x = N` booted 0) plus a BIOS-KEYINT
+  PSGADDR-latch race (PSG writes now DI/EI-guarded) — both fixed; this likely
+  also explains the reported MSX sprite flakiness.
+- **GB/GBC sports scanline tear**: the OAM DMA now fires at the vblank leading
+  edge (45 staged `oam_set` calls used to push it a third of the frame into
+  active display — the "horizontal line a 3rd of the way down" glitch).
+- Misc per-genre polish: PCE gameplay speeds, C64 racing clears the BASIC
+  startup text, C64 sports court widened to the 9-bit sprite range, MSX/Lynx
+  sports contrast, GBA puzzle well border.
+- **Verification**: all 69 existing platform×genre scaffolds were swept —
+  scaffold → project build → boot → render-health green, all 14 platforms
+  respond to input, and each platform's audio was captured and RMS-checked.
+  (Atari 2600 has no puzzle genre by design.)
+
+### Fixed/Added — the 0.27.0 Zanac RE feedback round (banked-NES rebuilds, A/B diff, token cuts)
+- **Banked NES `disasm({target:'project'})` now emits COMPLETE, working rebuild
+  glue** (the headline ask): a `HEADER` segment with the original 16 iNES bytes,
+  a per-bank `PRGn` segment wrapper for every bank, a multi-bank `nes_rebuild.cfg`
+  (switchable banks at `$8000`, fixed top bank at `$C000`, CHR wired when
+  present), and a `rebuild.json` `build()` call referencing all of it. Proven
+  byte-identical on a synthetic 4-bank mapper-2 ROM fed straight back to
+  `build()` — what previously took an hour of hand-written segments + cfg is
+  now zero glue. (NROM keeps the existing proven `inesHeader` one-call path.)
+- **`build({linkerConfigPath})`** reads the `.cfg` from disk so a large
+  multi-bank config never streams through context (and `rebuild.json` uses it).
+- **`disasm({target:'references'})` scans every PRG bank on banked NES** —
+  the old flat-blob-at-`$8000` disassembly returned `refsFound:0` on >32KB
+  ROMs. Refs now carry a `prgBank` tag, and `#$nn` immediates no longer count
+  as references (they're values, not addresses).
+- **`memory({op:'diffRuns'})`** — the A/B input-diff primitive: runs the same
+  start state twice under two different held inputs (savestate restore in
+  between) and returns only the divergent bytes, with run-A/run-B values for
+  small clusters. Replaces the save/run/dump/restore/run/dump/python-diff loop
+  (~6 calls + a 4KB context hit) with one call; live-verified isolating an NES
+  player-X byte.
+- **`memory({op:'read'/'readCart', outputPath, echo:false})`** returns just
+  `{path, bytes}` — no more ~4KB hex echo on a 2KB dump that was explicitly
+  routed to disk.
+- **`memory({op:'diff'})`**: summary clusters ≤8 bytes now include
+  `before`/`after` hex (no more falling back to `view:'raw'` for the values),
+  and `minDelta` filters RNG/counter wiggle.
+- **`input({op:'press'})` guarantees a released→pressed edge** (one released
+  frame first), so edge-triggered handlers (START pause) can't miss the press
+  when the button was already held.
+- **`breakpoint({on:'pc'})` misses now diagnose**: report `pcNow`, stop
+  suggesting `pressDuring` when input WAS supplied (wrong-address is then the
+  likely story), and point at `watch({on:'pc'})` coverage tracing.
+
+### Added — human co-drive detection: agents now KNOW when a human is playing in the playtest window
+The long-standing confusion ("they get confused when I try to play while they're
+coding") had a real mechanism: the playtest window shares the session's ONE
+emulator host with the agent, and its 60fps tick wrote the human's pad state —
+including all-zeros when nobody was pressing — over the agent's `input({op:'set'})`
+every frame. The agent had no signal a human was co-driving and no warning that
+its input was being clobbered. Now:
+- **The window only writes input while the human is actually pressing** (pad,
+  keyboard, or rewind-scrub), plus one release write after they let go. An idle
+  window no longer silently clobbers the agent's held input. The human still wins
+  the instant they press.
+- **The window tracks human activity** ("pressed within the last ~2 s" ≈ 120
+  ticks) and exposes it: `catalog({op:'status'})` reports `playtestWindowOpen` +
+  `humanInputActive` (+ `framesSinceHumanInput`), and `playtest({op:'status'})`
+  reports the same.
+- **`frame({op:'step'/'stepAndShot'})` and `input(set/press/sequence/navigate)`
+  responses carry a `humanCoDriveWarning`** while the human is actively playing,
+  telling the agent the conflict is happening NOW and pointing at the escape
+  hatches: `host({op:'pause'})` to inspect frozen, or a second session
+  (different `x-romdev-session` = fully isolated emulator) for deterministic work.
+- The playtest tool's FOOTGUN doc now describes the real contract (real-time
+  stepping always races; input only clobbered while the human presses).
+
+### Changed — `screenshot` scale docs: native is the accurate default, upscale adds no detail
+The `scale` param's docs oversold integer UPscaling as making tiny handheld shots
+"legible." That was misleading: nearest-neighbor upscale just duplicates pixels —
+it adds **no information** the native frame doesn't already have, costs more image
+tokens, and since VLM vision encoders resize every input to their own fixed
+resolution it may not change what the model sees (and can slightly degrade it via a
+bicubic downscale of stretched pixels). Reworded the param + tool description to
+lead with **native (`scale:1`, the default) = perfect pixels = the accurate
+representation**, keep the genuinely-useful DOWNscale (`<1`, fewer tokens for
+"did it change?" checks), and frame upscale honestly as a last resort for clients
+that can't zoom a small image. (No behavior change — `scale` was already opt-in and
+defaulted to native; this is the docs telling the truth about it.)
+(Committed during the 0.27.0 cycle but AFTER 0.27.0 published — ships in 0.28.0.)
+
 ## 0.27.0
 
 ### Added — `breakpoint(on:'pc', captureMemory:[…])` reads named RAM at the hit

package/README.md

@@ -12,7 +12,7 @@ That's it — one command starts the local romdev **tool server** (no global ins
 - **Agent Skill** — `GET /skills/romdev/SKILL.md` (the [Agent Skills](https://agentskills.io) standard; save it to your skills dir as `skills/romdev/SKILL.md`; ~100 tokens until invoked).
 - **MCP** — it's also a [Model Context Protocol](https://modelcontextprotocol.io/) server at `/mcp` for clients that want it.
 
-This package contains all the JavaScript — the tool surface, the WASM emulator host, the per-platform scaffolds, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages it depends on, loaded on demand the first time you build or run a given platform.
+This package contains all the JavaScript — the tool surface, the WASM emulator host, the per-platform example games, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages it depends on, loaded on demand the first time you build or run a given platform.
 
 > For the full project — what romdev is, the supported-platform matrix, how the pieces fit together, and how to develop on it — see the [repository README](https://github.com/monteslu/romdev#readme).
 
@@ -21,8 +21,8 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 - **`bin`**
   - `romdevtools` → the tool server (`src/mcp/server.js`). Serves the HTTP tool routes, `/documentation`, `/skills/romdev/SKILL.md`, and an MCP endpoint on `http://127.0.0.1:7331` by default (`PORT` / `HOST` to override). `romdev-mcp` is kept as an alias of the same command.
   - `romdevtools-cli` → a smoke/utility CLI, incl. `romdevtools-cli play <rom>` (SDL window, hot-plug controllers).
-- **`src/`** — the server, MCP tools, WASM host, core/toolchain resolvers, per-platform memory interpretation, and bundled library/runtime source (cc65 libs, PVSnesLib, SGDK, libtonc/libgba, hUGEDriver, …) that scaffolded projects link against.
-- **`examples/`** — per-platform starter projects and genre scaffolds.
+- **`src/`** — the server, MCP tools, WASM host, core/toolchain resolvers, per-platform memory interpretation, and bundled library/runtime source (cc65 libs, PVSnesLib, SGDK, libtonc/libgba, hUGEDriver, …) that forked projects link against.
+- **`examples/`** — per-platform example games (complete, working, forkable) and minimal references.
 
 ## Dependencies
 
@@ -45,7 +45,7 @@ claude mcp add --transport http romdev http://127.0.0.1:7331/mcp
 
 It's a standard **streamable-HTTP** MCP server at `http://127.0.0.1:7331/mcp`. For opencode, Codex CLI, and other clients, see **[Connect](https://github.com/monteslu/romdev#connect)** in the repository README. An optional human observer (live tool-call view) is at `/livestream`.
 
-Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instructions — the workflow guide for the full tool surface. Or just connect your agent and call `catalog({op:'categories'})` to explore the tools live (and `catalog({op:'whatsNew'})` for the recent CHANGELOG + a rename table if you're resuming work against an older version).
+Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instructions — the workflow guide for the full tool surface. Or just connect your agent and call `catalog({op:'categories'})` to explore the tools live, and `catalog({op:'status'})` for the running version + session snapshot.
 
 ## Prefer not to use MCP? Use HTTP or a Skill
 

package/examples/README.md

@@ -1,6 +1,6 @@
 # Examples
 
-Minimal "hello" projects for every platform romdev's bundled toolchains can build. Each one is the simplest thing that's still a real ROM — an agent forks from these instead of starting from a blank file.
+Working example games — one buildable, rendering starting point per platform×genre (plus minimal references) for every platform romdev's bundled toolchains can build. These are **scaffolding, not showcases**: the gameplay is intentionally thin (treat it as placeholder and reshape it). Their value is that each already carries the platform's boot sequence, hardware init, APIs, and syntax wired up and WORKING, so you change 2 things while 13 keep working instead of getting 15 right from a blank file. **Never start from a blank file: fork the example whose CORE LOOP is nearest your game (even for a very different game) with `examples({op:'fork', example:'<platform>/<name>', name, path})`, then modify one thing at a time, re-running `build({output:'run'})` after each.** Read OTHER examples with `examples({op:'show'})` for techniques to graft. Rationale: retro bring-up is a long chain of fragile hardware init with zero partial credit; a working game is a regression oracle.
 
 Each example fits the convention:
 - A `main.c` or `main.asm`/`main.s` as the entry point.
@@ -14,18 +14,18 @@ Each example fits the convention:
 | nes (full game) | `nes/space-shooter/` | cc65   | Canonical complete-game reference — a generic fixed-shooter showing "NES-shaped C": bit-packed alien state, 5-col formation for the 8-sprite/scanline limit, correct OAM-staging order, shields/HUD as BG tiles, CHR-RAM upload, APU SFX. Build with `linkerConfig: "chr-ram-runtime"` + `nes_runtime.c`. See its README. |
 | c64          | `c64/main.c`         | cc65      | Direct VIC-II + screen-RAM demo: paints background, writes screen codes for "HELLO ROM-DEV-MCP" into screen RAM with white-on-blue color, cycles the border color. C89 (cc65) — no mixed decl/code. |
 | atari2600    | `atari2600/main.asm` | dasm      | Standard NTSC kernel (3 vsync + 37 vblank + 192 visible + 30 overscan) with a single GRP0 sprite, joystick-driven movement, and the vector table at $FFFA. |
-| atari2600 (gallery shooter) | `atari2600/templates/mini_invaders.asm` | dasm | Fixed-shooter 2600 game using the RIGHT TIA objects (not playfield "barcode" bars): P0 double-width cannon, P1 + NUSIZ1=%011 = a row of 3 hardware-replicated invaders, M0 = shot. Aliens march + drop at edges; button fires. The honest 2600-idiomatic genre layout. `scaffold({op:'project', platform:"atari2600", template:"mini_invaders"})`. |
+| atari2600 (gallery shooter) | `atari2600/templates/mini_invaders.asm` | dasm | Fixed-shooter 2600 game using the RIGHT TIA objects (not playfield "barcode" bars): P0 double-width cannon, P1 + NUSIZ1=%011 = a row of 3 hardware-replicated invaders, M0 = shot. Aliens march + drop at edges; button fires. The honest 2600-idiomatic genre layout. `examples({op:'fork', example:"atari2600/mini_invaders", name, path})`. |
 | atari7800    | `atari7800/main.c`   | cc65      | Minimal MARIA bring-up: DLL pointing at a single-zone DL, palette load, CHARBASE = 0. cc65 can't constant-fold pointer→int for static initializers, so the DL/DLL addresses are patched in at runtime in `main()`. |
 | lynx         | `lynx/main.c`        | cc65      |                                      |
 | snes         | `snes/main.asm`      | asar      |                                      |
 | genesis      | `genesis/main.s`     | vasm68k   |                                      |
 | gb           | `gb/main.c` (default) or `gb/main.asm` (`language:"asm"`) | sdcc sm83 port (C, default) / rgbds (asm) | C example cycles the BG palette every 32 frames. Asm example shows yellow 'H' on light BG, scrollable with A. SDCC GB hardware-register headers under `src/platforms/gb/lib/c/gb_hardware.h`. |
 | gbc          | `gbc/main.asm`       | rgbds (asm) / sdcc sm83 (C) | The bundled example is an asm CGB-color demo (yellow 'H' on a true-blue BG, only possible on GBC). C is also supported via SDCC sm83 — same as GB. |
-| sms          | `sms/main.c` (or `sms/templates/*.c`) | sdcc | Pair with `src/platforms/sms/lib/c/sms_crt0.s` (passed via `crt0` arg) — boots into a real cartridge with vector table + SP=$DFF0 + IM 1. Yellow 'H' on blue, scrollable with P1-B1. The 9 templates under `sms/templates/` (default, hello_sprite, tile_engine, shmup, shmup_2p, platformer, puzzle, sports, racing, music_demo) all use this crt0 — `scaffold({op:'project'})` copies it in automatically. |
-| gg           | `gg/templates/default.c` (or any other template) | sdcc | R53: GG now ships `src/platforms/gg/lib/c/gg_crt0.s` (byte-identical to SMS's). Real visible-and-runnable default: VDP Mode 4 init + palette + yellow 'H' centered in the 160×144 visible viewport + B1 scroll loop. The 9 templates (default, hello_sprite, tile_engine, shmup, platformer, puzzle, sports, racing, music_demo) all link the GG runtime + crt0 via `scaffold({op:'project', platform:"gg"})`. |
-| gba          | `gba/templates/*.c`  | arm-none-eabi-gcc | Default runtime = **libtonc** (`#include <tonc.h>`). 9 scaffolds incl. `tonc_hello`, `tonc_hello_sprite`, the 5 genre scaffolds, and `maxmod_demo` (music). Pass `runtime:"libgba"` for the devkitPro API, `runtime:"none"` for bare newlib. **Always call `irq_init(NULL); irq_add(II_VBLANK, NULL);` before `VBlankIntrWait()`** — otherwise the BIOS halts forever. |
-| pce          | `pce/<template>/main.c` | cc65 (HuC6280) | HuCard homebrew, no BIOS. Ships a direct-register VDC/PSG helper lib (`pce.h` + `pce.lib`) — cc65 has no PCE sprite/sound library. Templates: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre scaffolds (shmup/platformer/puzzle/sports/racing). **`#include <stdint.h>`** for int8/16/32_t — `pce.h` only typedefs u8/u16. Genre scaffolds fill the BAT (32×32 virtual screen); the platformer smooth-scrolls via the VDC BXR register. |
-| msx          | `msx/<template>/main.c` | sdcc (z80) | Boots cartridge homebrew on the open C-BIOS (no proprietary ROM). Ships an AY-3-8910 + TMS9918/V9938 VDP helper lib (`msx_hw.h` + `msx_vdp.c`). Templates: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre scaffolds. The bundled `msx_crt0.s` (applied by the dir-build recipe automatically) emits the `"AB"` cartridge header at $4000 + INIT pointer — **C-BIOS shows its logo for ~2-3 s, then CALLs INIT**, so run ≥240 frames before screenshotting. The platformer column-streams the SCREEN 2 name table for a tile-by-tile scroll. |
+| sms          | `sms/main.c` (or `sms/templates/*.c`) | sdcc | Pair with `src/platforms/sms/lib/c/sms_crt0.s` (passed via `crt0` arg) — boots into a real cartridge with vector table + SP=$DFF0 + IM 1. Yellow 'H' on blue, scrollable with P1-B1. The 10 examples under `sms/templates/` (default, hello_sprite, tile_engine, shmup, shmup_2p, platformer, puzzle, sports, racing, music_demo) all use this crt0 — `examples({op:'fork'})` copies it in automatically. |
+| gg           | `gg/templates/default.c` (or any other example) | sdcc | R53: GG now ships `src/platforms/gg/lib/c/gg_crt0.s` (byte-identical to SMS's). Real visible-and-runnable default: VDP Mode 4 init + palette + yellow 'H' centered in the 160×144 visible viewport + B1 scroll loop. The 9 examples (default, hello_sprite, tile_engine, shmup, platformer, puzzle, sports, racing, music_demo) all link the GG runtime + crt0 via `examples({op:'fork', example:"gg/<name>", name, path})`. |
+| gba          | `gba/templates/*.c`  | arm-none-eabi-gcc | Default runtime = **libtonc** (`#include <tonc.h>`). 9 examples incl. `tonc_hello`, `tonc_hello_sprite`, the 5 genre games, and `maxmod_demo` (music). Pass `runtime:"libgba"` for the devkitPro API, `runtime:"none"` for bare newlib. **Always call `irq_init(NULL); irq_add(II_VBLANK, NULL);` before `VBlankIntrWait()`** — otherwise the BIOS halts forever. |
+| pce          | `pce/<template>/main.c` | cc65 (HuC6280) | HuCard homebrew, no BIOS. Ships a direct-register VDC/PSG helper lib (`pce.h` + `pce.lib`) — cc65 has no PCE sprite/sound library. Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games (shmup/platformer/puzzle/sports/racing). **`#include <stdint.h>`** for int8/16/32_t — `pce.h` only typedefs u8/u16. The genre games fill the BAT (32×32 virtual screen); the platformer smooth-scrolls via the VDC BXR register. |
+| msx          | `msx/<template>/main.c` | sdcc (z80) | Boots cartridge homebrew on the open C-BIOS (no proprietary ROM). Ships an AY-3-8910 + TMS9918/V9938 VDP helper lib (`msx_hw.h` + `msx_vdp.c`). Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games. The bundled `msx_crt0.s` (applied by the dir-build recipe automatically) emits the `"AB"` cartridge header at $4000 + INIT pointer — **C-BIOS shows its logo for ~2-3 s, then CALLs INIT**, so run ≥240 frames before screenshotting. The platformer column-streams the SCREEN 2 name table for a tile-by-tile scroll. |
 
 ## Guides