romdevtools 0.28.0 → 0.29.0

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -174,7 +174,7 @@ pokes the BG map "whenever the state changes" will have SOME of those pokes
 land mid-frame and vanish: stale cells, a piece that visually lags the
 logical grid, glitches that move around as code timing shifts.
 
-The robust pattern (used by the bundled puzzle scaffolds):
+The robust pattern (used by the bundled puzzle example games):
 
 1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
    pairs to a small RAM queue whenever game state changes a cell.
@@ -195,7 +195,7 @@ pokes the BG map "whenever the state changes" will have SOME of those pokes
 land mid-frame and vanish: stale cells, a piece that visually lags the
 logical grid, glitches that move around as code timing shifts.
 
-The robust pattern (used by the bundled puzzle scaffolds):
+The robust pattern (used by the bundled puzzle example games):
 
 1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
    pairs to a small RAM queue whenever game state changes a cell.
@@ -208,6 +208,60 @@ The robust pattern (used by the bundled puzzle scaffolds):
 If you must write outside that structure, turn the LCD off first (only
 acceptable during init/load screens — mid-game it flashes white).
 
+## "My HUD scrolls with the background" / "the window ate the bottom of my screen"
+
+The window layer (WX/WY + LCDC bit 5) is the GB's fixed-HUD mechanism: it has
+no scroll registers, always draws its own map from (0,0) pinned to the screen,
+on top of the BG. Three rules, all demonstrated in the shmup example
+(`examples/gb/templates/shmup.c`, "HARDWARE IDIOM: window-layer HUD"):
+
+- **WX is screen X plus 7.** `WX=7` is the left edge. WX 0-6 produces real
+  DMG pixel-pipeline glitches; WX ≥ 167 pushes the window off-screen.
+- **The window has no height register.** From the first line it covers (WY)
+  it owns EVERY line to the bottom of the frame, full width from WX. That's
+  why GB HUDs live at the BOTTOM of the screen (`WY = 128` → lines 128-143 =
+  HUD, lines 0-127 = scrolling playfield). A top HUD needs a mid-frame
+  STAT/LYC interrupt to turn LCDC bit 5 back off — a different, fragile
+  idiom; don't fall into it by accident by setting WY=0.
+- **Sprites are NOT clipped by the window** — they draw on top of it. Despawn
+  (or Y-clamp) everything before the HUD line, or your enemies fly across
+  the score bar.
+
+Use a separate map for the window (LCDC bit 6 → $9C00) so it doesn't fight
+the BG's $9800 map.
+
+## "Hi-score doesn't persist" / save_ram is empty or all $FF
+
+Battery saves need BOTH halves:
+
+1. **The header must declare a battery cart.** The bundled `gb_crt0.s` emits
+   `$0147 = $03` (MBC1+RAM+BATTERY) and `$0149 = $02` (8 KB) as real bytes,
+   and the build's post-link header fix passes them through. The emulator
+   sizes its SAVE_RAM region from those two bytes — type $00 (ROM-only)
+   means no save_ram region at all, and writes to $A000 go nowhere.
+2. **Cart RAM is gated.** It boots DISABLED; writes are silently discarded
+   until you write `$0A` to $0000-$1FFF (any address there — it's a mapper
+   register, not memory). Write `$00` to the same range after saving
+   (battery hygiene: an enabled RAM bank can corrupt at power-off on real
+   hardware).
+
+Working pattern with magic + checksum (a fresh cart is $FF garbage — never
+trust raw bytes): shmup example, "HARDWARE IDIOM: battery SRAM". Verify
+headlessly: play to a score, force game over, `memory({op:'read',
+region:"save_ram"})` shows the record, and the hi-score still shows on the
+title after a hard reset (power cycle).
+
+## "Boot takes seconds" / a screen repaint visibly stalls the game
+
+The sm83 has no divide instruction. SDCC's software `%` / `/` costs ~700
+cycles per call — one `(r*7+c*5) % 11` in a 32×32 map fill is 2048 calls
+≈ 1.5 MILLION cycles ≈ a 1.5-second frozen boot (measured, not theoretical;
+the shmup example shipped exactly that for an hour). In any per-cell or
+per-frame loop, replace modulo patterns with running counters +
+subtract-on-overflow (see `paint_starfield` in the shmup example) and
+decimal score display with power-of-ten subtraction (`u16_to_tiles` there).
+A single `%` per event — e.g. per enemy spawn — is fine.
+
 ## Debug recipes
 
 A few high-leverage tools you might not know exist:
@@ -247,14 +301,13 @@ Boot order that always works for GBC:
    }
 ```
 
-Cribbed from `examples/gbc/templates/tile_engine.c` — start a fresh
-game from that template with:
+Cribbed from `examples/gbc/templates/tile_engine.c` — fork that
+example into a fresh game with:
 
 ```js
-scaffold({
-  op: 'project',
-  platform: "gbc",
-  template: "tile_engine",
+examples({
+  op: 'fork',
+  example: "gbc/tile_engine",
   name: "mygame",
   path: "/abs/path/to/dir",
 });

package/src/platforms/gb/lib/c/README.md

@@ -1,8 +1,8 @@
 # GB / GBC C runtime + headers
 
 These are the source files that back the GB/GBC C templates. They're
-**not** auto-injected at build time — `scaffold({op:'project', platform:"gb"|"gbc",
-template:"..."})` copies them into your project directory so the
+**not** auto-injected at build time — `examples({op:'fork', example:"gb/<name>" or
+"gbc/<name>", name, path})` copies them into your project directory so the
 project is self-describing. Build calls then point at your project's
 copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
 
@@ -32,7 +32,7 @@ didn't produce, or to override a field:
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into
-  every GB project by `scaffold({op:'project'})`. Same logic, no MCP needed.
+  every GB project by `examples({op:'fork'})`. Same logic, no MCP needed.
 - `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
   RGBDS asm projects can invoke it directly.
 
@@ -46,17 +46,16 @@ didn't produce, or to override a field:
   hardware, OAM DMA timing, joypad layout. Read this before your first
   GB/GBC project.
 
-## Project templates
+## Forking an example
 
-Bootstrap a working game-loop skeleton with `scaffold({op:'project'})`:
+Bootstrap a working game-loop skeleton by forking an example with `examples({op:'fork'})`:
 
 ```js
-scaffold({
-  op:       'project',
-  platform: "gbc",
-  template: "tile_engine",   // or "hello_sprite", or "default"
-  name:     "mygame",
-  path:     "/abs/path",
+examples({
+  op:      'fork',
+  example: "gbc/tile_engine",   // or "gbc/hello_sprite", or "gbc/default"
+  name:    "mygame",
+  path:    "/abs/path",
 })
 ```
 

package/src/platforms/gb/lib/c/gb_crt0.s

@@ -86,11 +86,35 @@
         nop
         jp      init
 
-;; ─── Header bytes at $0104-$014F — host pipeline fills these ──────
+;; ─── Header bytes at $0104-$014F — host pipeline fills most of these ─
+;; The logo / title / checksums are patched post-link (rgbfix in the
+;; build pipeline, or patch-header.js when rebuilding outside romdev).
+;; The CART TYPE and RAM SIZE bytes are DECLARED HERE as real bytes so
+;; the build's header fixup can read and preserve them:
+;;
+;;   $0147 = $03  MBC1 + RAM + BATTERY
+;;   $0149 = $02  8 KB external cart RAM at $A000-$BFFF
+;;
+;; This is what makes battery saves (persistent hi-scores) work: the
+;; emulator sizes its SAVE_RAM from these two bytes. The RAM is gated —
+;; games must write $0A to $0000-$1FFF before touching $A000 and write
+;; $00 after (see the SRAM idiom in the shmup example). Games that never
+;; touch $A000 are completely unaffected by the mapper declaration: a
+;; 32 KB image fits in MBC1 banks 0-1 exactly as it does in a ROM-only
+;; cart, and the MBC registers only react to ROM-area WRITES (which
+;; normal code never performs).
+;;
+;; If you rebuild OUTSIDE romdev, keep these bytes: rgbfix flags are
+;; `-m 0x03 -r 0x02` (patch-header.js defaults to ROM-only — pass
+;; cartType/ramSize through patchGbHeader() if you script it).
         .area _HEADERe (ABS)
         .org    0x0104
-        ;; 76 bytes total: Nintendo logo (48) + title (16) + flags+checksums (12)
-        .ds     0x4C
+        .ds     0x43            ; $0104-$0146 logo/title/CGB flag/licensee/SGB (patched in)
+        .org    0x0147
+        .db     0x03            ; $0147 cart type: MBC1+RAM+BATTERY (see above)
+        .db     0x00            ; $0148 ROM size (rgbfix -p recomputes)
+        .db     0x02            ; $0149 RAM size: 8 KB
+        .ds     0x06            ; $014A-$014F dest/licensee/version/checksums (patched in)
 
 ;; ─── init: real boot code, lives in _CODE starting at $0150 ────────
         .area   _CODE

package/src/platforms/gb/lib/c/patch-header.js

@@ -13,7 +13,7 @@
 // runs a bundled rgbfix after every gb/gbc link — see the
 // "rgbfix (auto header fix)" line in build logs), so you only need this
 // script when rebuilding the project OUTSIDE romdev with stock SDCC and
-// no RGBDS installed. It's what keeps the scaffold self-contained.
+// no RGBDS installed. It's what keeps the forked project self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header
@@ -151,7 +151,17 @@ if (isCli) {
   const rom = new Uint8Array(readFileSync(inPath));
   // Auto-detect CGB based on file extension.
   const cgb = /\.gbc$/i.test(inPath) || /\.gbc$/i.test(outPath);
-  patchGbHeader(rom, { cgb });
+  // Battery-cart passthrough: the bundled gb_crt0.s emits the cart-type and
+  // RAM-size bytes EXPLICITLY ($0147=$03 MBC1+RAM+BATTERY, $0149=$02 8KB) so
+  // battery hi-score saves work. Preserve a known battery-MBC declaration
+  // instead of stomping it back to ROM-only; unknown/garbage bytes (a crt0
+  // that left the header window as a .ds gap) still get the safe defaults.
+  const BATTERY_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]);
+  const declType = rom.length > 0x149 ? rom[0x147] : 0x00;
+  const declRam = rom.length > 0x149 ? rom[0x149] : 0x00;
+  const cartType = BATTERY_TYPES.has(declType) ? declType : 0x00;
+  const ramSize = cartType !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+  patchGbHeader(rom, { cgb, cartType, ramSize });
   writeFileSync(outPath, rom);
-  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""})`);
+  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""}${cartType ? `, cart $${cartType.toString(16)}+RAM` : ""})`);
 }

package/src/platforms/gba/MENTAL_MODEL.md

@@ -129,11 +129,11 @@ Sound FIFO states. See "MCP debug & inspection tooling" below for the rest of
 the live-debug loop (sprites / palette / background / cpu / breakpoint + the
 memory regions and disasm pipeline).
 
-**For scaffold-level sfx**, the libtonc runtime ships a minimal
+**For starter-level sfx**, the libtonc runtime ships a minimal
 `gba_sfx.h` / `gba_sfx.c` pair (3 functions: `sfx_init`, `sfx_tone`,
 `sfx_noise`) that wraps the DMG-compatible APU directly. Same shape
-as the NES/GB scaffold sound API, so cross-platform game ports feel
-the same. All 5 GBA genre scaffolds (shmup/platformer/puzzle/sports/
+as the NES/GB example sound API, so cross-platform game ports feel
+the same. All 5 GBA genre example games (shmup/platformer/puzzle/sports/
 racing) use it.
 
 ## MCP debug & inspection tooling
@@ -210,7 +210,7 @@ the first call** (`irq_init(NULL)` + `irq_add(II_VBLANK, NULL)` with
 libtonc — `irqInit(NULL)` + `irqEnable(IRQ_VBLANK)` with libgba).
 Without this, the BIOS halts the CPU forever waiting for an IRQ that
 never fires. ROM appears to compile + load but freezes on frame 1 —
-single most common GBA gotcha. Every bundled scaffold does it; copy
+single most common GBA gotcha. Every bundled example does it; copy
 the pattern.
 
 ## Cart header format

package/src/platforms/gba/TROUBLESHOOTING.md

@@ -36,7 +36,7 @@ installs the master handler + `irq_add(II_VBLANK, NULL)` registers a
 no-op for vblank (just so the IRQ fires + the BIOS counter increments).
 With libgba, `irqInit()` does both steps.
 
-Every bundled R28 scaffold (`tonc_hello`, `tonc_hello_sprite`, `shmup`,
+Every bundled R28 example (`tonc_hello`, `tonc_hello_sprite`, `shmup`,
 `platformer`, `puzzle`, `sports`, `racing`) sets this up — copy the
 pattern.
 
@@ -132,10 +132,10 @@ install promise but everything else still works.
 A deferred enhancement is to port libsysbase into our build so
 iprintf "just works."
 
-## Adding sound to a scaffold
+## Adding sound to your game
 
 Both runtimes bundle `gba_sfx.h` + `gba_sfx.c` next to your `main.c`
-(courtesy of `scaffold({op:'project'})`). The shape:
+(courtesy of `examples({op:'fork'})`). The shape:
 
 ```c
 #include "gba_sfx.h"

package/src/platforms/gba/lib/c/gba_sfx.c

@@ -76,6 +76,46 @@ void sfx_noise(u8 length_frames) {
     REG_SND4FREQ = 0xC033;
 }
 
+/* ── background music: 16-step melody loop on channel 2 ─────────────
+ * Mirrors the Genesis/NES example pattern: games get continuous music
+ * for free by calling sfx_music_tick() once per frame. The melody is a
+ * gentle A-minor arpeggio at reduced envelope volume (0xA of 0xF) so
+ * one-shot SFX on channel 1 / noise on 4 read clearly over it.
+ * Note values are GBA 11-bit frequency codes: Hz = 131072/(2048-code),
+ * code = 2048 - 131072/Hz. 0 = rest. */
+static const u16 music_code[16] = {
+    1452, 1548, 1651, 1750,   /* A3 C4 E4 A4 */
+    1714, 1651, 1548, 0,      /* G4 E4 C4  - */
+    1452, 1546, 1620, 1714,   /* A3 C4 D4 G4 */
+    1651, 1548, 1452, 0,      /* E4 C4 A3  - */
+};
+static u8 music_enabled = 1;
+static u8 music_step, music_timer;
+
+void sfx_music(u8 on) {
+    music_enabled = on;
+    music_step = 0;
+    music_timer = 0;
+    if (!on) REG_SND2CNT = 0x0000;   /* zero envelope = silence now */
+}
+
+void sfx_music_tick(void) {
+    if (!music_enabled) return;
+    if (music_timer == 0) {
+        u16 code = music_code[music_step & 15];
+        if (code) {
+            /* vol 0xA, 50% duty, length 40/64 steps (~156ms) — the
+             * length-enable auto-silences before the next note so
+             * rests actually rest. */
+            REG_SND2CNT  = (u16)(0xA080 | (64 - 40));
+            REG_SND2FREQ = (u16)(0xC000 | (code & 0x07FF));
+        }
+        music_step++;
+    }
+    music_timer++;
+    if (music_timer >= 10) music_timer = 0;   /* 6 notes/sec at 60fps */
+}
+
 void sfx_off(void) {
     REG_SNDSTAT = 0x0000;
 }

package/src/platforms/gba/lib/c/gba_sfx.h

@@ -42,6 +42,16 @@ void sfx_tone(u8 channel, u16 freq_period, u8 length_frames);
  *   length_frames: 1..63 (same scaling as sfx_tone). */
 void sfx_noise(u8 length_frames);
 
+/* ── background music ────────────────────────────────────────────────
+ * A 16-step square-wave melody loop on channel 2 (so keep one-shot SFX
+ * on channel 1 + noise on 4 and nothing fights for the channel).
+ * Call sfx_music_tick() once per frame from your main loop — it steps
+ * the melody. ON by default after sfx_init(); sfx_music(0) silences it.
+ * "No sound" feedback in playtests is nearly always a missing per-frame
+ * tick, not broken registers. */
+void sfx_music(u8 on);
+void sfx_music_tick(void);
+
 /* Power down the APU. */
 void sfx_off(void);
 

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -114,7 +114,7 @@ The CGB boot ROM checks header byte **`$0143`**:
 - `$80` → CGB-enhanced mode (color works, DMG-compat fallback)
 - `$C0` → CGB-only mode (refuses to boot on a DMG)
 
-**Every bundled GBC scaffold is built with `$0143 = $80`** — `build({output:'rom'})`
+**Every bundled GBC example game is built with `$0143 = $80`** — `build({output:'rom'})`
 / `build({output:'run'})` set this automatically at build time when `platform:"gbc"`,
 so a freshly built `.gbc` boots in color with no extra step. (Build it as
 `platform:"gb"` instead and the flag stays `$00` → DMG green-shade mode,
@@ -197,12 +197,12 @@ inversion: `{a}`→A, `{b}`→B, `{start}`/`{select}`, plus the d-pad (spatial
 east→A, west→B). So `input({op:'set', a: true})` presses GBC A as expected — unlike
 the genesis_plus_gx platforms (Genesis/SMS/GG), there's no surprise here.
 
-## Scaffolds
+## Example games
 
-All GB scaffolds (`shmup`, `platformer`, `puzzle`, `sports`, `racing`,
+All GB example games (`shmup`, `platformer`, `puzzle`, `sports`, `racing`,
 `hello_sprite`, `tile_engine`) compile identically as GBC ROMs — the
 bundled GB runtime is already CGB-aware (writes OCPD/OCPS for color).
-The genre scaffolds inherit from GB via `TEMPLATES.gbc = TEMPLATES.gb`;
+The genre examples inherit from GB via `TEMPLATES.gbc = TEMPLATES.gb`;
 the only differences at build time are:
 
 - ROM extension: `.gbc` (vs `.gb`)

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -128,7 +128,7 @@ pokes the BG map "whenever the state changes" will have SOME of those pokes
 land mid-frame and vanish: stale cells, a piece that visually lags the
 logical grid, glitches that move around as code timing shifts.
 
-The robust pattern (used by the bundled puzzle scaffolds):
+The robust pattern (used by the bundled puzzle example games):
 
 1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
    pairs to a small RAM queue whenever game state changes a cell.
@@ -149,7 +149,7 @@ sound channels or extra waveforms.
 
 ## "ROM size > 32 KB needed"
 
-The bundled GBC scaffolds all fit in 32 KB (single bank, no MBC).
+The bundled GBC example games all fit in 32 KB (single bank, no MBC).
 For larger projects use an MBC (memory bank controller). MBC1 / MBC3
 work in gambatte; set the `$0147` cartridge type byte accordingly.
 romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
@@ -159,11 +159,11 @@ romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
 Default GBC speed is the same as DMG (~4 MHz Z80). Double-speed mode
 via KEY1 ($FF4D) doubles CPU but halves audio sample rate + breaks
 cycle-counted code. Most homebrew leaves it off; if you need the
-extra clocks, change the GB scaffold pattern to:
+extra clocks, change the GB example pattern to:
 
 ```c
 KEY1 = 1;            /* request speed switch */
 __asm__("stop");     /* arm the switch (compiler-specific syntax) */
 ```
 
-Not bundled in any scaffold — use only if you've measured a need.
+Not bundled in any example — use only if you've measured a need.

package/src/platforms/gbc/UPSTREAM_SOURCES.md

@@ -3,7 +3,7 @@
 GBC shares its toolchain (SDCC sm83) + emulator (gambatte) + most
 of the runtime (`gb_runtime.c`, `gb_crt0.s`, `patch-header.js`,
 hUGEDriver) with DMG. The CGB tree (`src/platforms/gbc/`) holds
-the color-aware scaffolds; everything below is in lockstep with
+the color-aware example games; everything below is in lockstep with
 the GB tree.
 
 CGB-specific:

package/src/platforms/gbc/lib/c/README.md

@@ -1,8 +1,8 @@
 # GB / GBC C runtime + headers
 
 These are the source files that back the GB/GBC C templates. They're
-**not** auto-injected at build time — `scaffold({op:'project', platform:"gb"|"gbc",
-template:"..."})` copies them into your project directory so the
+**not** auto-injected at build time — `examples({op:'fork', example:"gb/<name>" or
+"gbc/<name>", name, path})` copies them into your project directory so the
 project is self-describing. Build calls then point at your project's
 copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
 
@@ -32,7 +32,7 @@ didn't produce, or to override a field:
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into
-  every GB project by `scaffold({op:'project'})`. Same logic, no MCP needed.
+  every GB project by `examples({op:'fork'})`. Same logic, no MCP needed.
 - `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
   RGBDS asm projects can invoke it directly.
 
@@ -46,17 +46,16 @@ didn't produce, or to override a field:
   hardware, OAM DMA timing, joypad layout. Read this before your first
   GB/GBC project.
 
-## Project templates
+## Forking an example
 
-Bootstrap a working game-loop skeleton with `scaffold({op:'project'})`:
+Bootstrap a working game-loop skeleton by forking an example with `examples({op:'fork'})`:
 
 ```js
-scaffold({
-  op:       'project',
-  platform: "gbc",
-  template: "tile_engine",   // or "hello_sprite", or "default"
-  name:     "mygame",
-  path:     "/abs/path",
+examples({
+  op:      'fork',
+  example: "gbc/tile_engine",   // or "gbc/hello_sprite", or "gbc/default"
+  name:    "mygame",
+  path:    "/abs/path",
 })
 ```
 

package/src/platforms/gbc/lib/c/gb_crt0.s

@@ -86,11 +86,34 @@
         nop
         jp      init
 
-;; ─── Header bytes at $0104-$014F — host pipeline fills these ──────
+;; ─── Header bytes at $0104-$014F — host pipeline fills most of these ──
         .area _HEADERe (ABS)
         .org    0x0104
-        ;; 76 bytes total: Nintendo logo (48) + title (16) + flags+checksums (12)
-        .ds     0x4C
+        ;; Nintendo logo ($0104-$0133, 48 bytes) + title/manufacturer/CGB
+        ;; flag ($0134-$0143) + licensee/SGB ($0144-$0146): left as a gap —
+        ;; the post-link header fix (bundled rgbfix, or patch-header.js when
+        ;; rebuilding outside romdev) writes the canonical logo, the CGB
+        ;; flag, and both checksums.
+        .ds     0x43
+        ;; Cartridge TYPE + RAM size ($0147-$0149) are emitted EXPLICITLY so
+        ;; the post-link fix can preserve them (it reads these bytes and
+        ;; passes them through; unknown/garbage values fall back to ROM-only).
+        ;; This is the GB equivalent of the NES crt0's iNES BATTERY bit:
+        ;; declaring the cart in the boot file makes battery saves part of
+        ;; the project source, not a build flag someone has to remember.
+        ;;
+        ;;   $0147 = $03  MBC1 + RAM + BATTERY  → the core exposes the 8KB
+        ;;                at $A000-$BFFF as persistent SAVE_RAM (.srm).
+        ;;                Writes only stick after the $0A enable sequence —
+        ;;                see the SRAM HARDWARE IDIOM in the puzzle example.
+        ;;   $0148 = $00  32 KB ROM (2 banks — no banking needed)
+        ;;   $0149 = $02  8 KB cart RAM (one bank at $A000)
+        .org    0x0147
+        .db     0x03            ; cart type: MBC1+RAM+BATTERY
+        .db     0x00            ; ROM size: 32 KB
+        .db     0x02            ; RAM size: 8 KB
+        ;; $014A-$014F (destination/licensee/version/checksums): host fills.
+        .ds     0x06
 
 ;; ─── init: real boot code, lives in _CODE starting at $0150 ────────
         .area   _CODE

package/src/platforms/gbc/lib/c/patch-header.js

@@ -13,7 +13,7 @@
 // runs a bundled rgbfix after every gb/gbc link — see the
 // "rgbfix (auto header fix)" line in build logs), so you only need this
 // script when rebuilding the project OUTSIDE romdev with stock SDCC and
-// no RGBDS installed. It's what keeps the scaffold self-contained.
+// no RGBDS installed. It's what keeps the forked project self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header
@@ -151,7 +151,17 @@ if (isCli) {
   const rom = new Uint8Array(readFileSync(inPath));
   // Auto-detect CGB based on file extension.
   const cgb = /\.gbc$/i.test(inPath) || /\.gbc$/i.test(outPath);
-  patchGbHeader(rom, { cgb });
+  // Battery-cart passthrough: the bundled gb_crt0.s emits the cart-type and
+  // RAM-size bytes EXPLICITLY ($0147=$03 MBC1+RAM+BATTERY, $0149=$02 8KB) so
+  // battery hi-score saves work. Preserve a known battery-MBC declaration
+  // instead of stomping it back to ROM-only; unknown/garbage bytes (a crt0
+  // that left the header window as a .ds gap) still get the safe defaults.
+  const BATTERY_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]);
+  const declType = rom.length > 0x149 ? rom[0x147] : 0x00;
+  const declRam = rom.length > 0x149 ? rom[0x149] : 0x00;
+  const cartType = BATTERY_TYPES.has(declType) ? declType : 0x00;
+  const ramSize = cartType !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+  patchGbHeader(rom, { cgb, cartType, ramSize });
   writeFileSync(outPath, rom);
-  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""})`);
+  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""}${cartType ? `, cart $${cartType.toString(16)}+RAM` : ""})`);
 }

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -178,7 +178,7 @@ software mistake, not a hardware limit:
 > burst or a per-frame DMA), you overrun vblank, drop frames, and the
 > scroll judders. **Paint the planes ONCE at setup; the loop only nudges
 > scroll registers and re-stages sprites.** Use the
-> `template:"two_plane_parallax"` scaffold as the known-good shape.
+> `two_plane_parallax` example as the known-good shape.
 
 ### Hardware scroll, the whole loop
 
@@ -241,7 +241,7 @@ if (newTileCol != lastTileCol) {
 ```
 
 That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
-The `template:"platformer"` scaffold scrolls within one plane (no
+The `platformer` example scrolls within one plane (no
 streaming); add the column-stream above to go wider. (Real Sonic also
 splits the screen with H-blank raster effects for independent strips —
 that's an IRQ/raster topic, see the `asm` template.)
@@ -481,7 +481,7 @@ build pipeline computes the checksum on link.
 
 ## Where the SDK lives (and how to read it)
 
-`scaffold({op:'project', platform:"genesis"})` ships the full SGDK include
+`examples({op:'fork'})` (any Genesis example) ships the full SGDK include
 tree into the new project at `vendor/sgdk/`. So when your code does
 `#include <genesis.h>`, those headers come from
 `vendor/sgdk/include/`:

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -239,8 +239,8 @@ Genesis scrolls in HARDWARE — moving the world is two register writes
 plane every frame (a `VDP_fillTileMapRect` / `VDP_loadTileMap` / big
 `DMA_*` each frame), you overrun the vblank DMA budget and drop frames →
 judder. Fix: paint the planes ONCE at setup; the loop only nudges scroll
-registers + re-stages sprites. The `template:"two_plane_parallax"`
-scaffold is the known-good shape.
+registers + re-stages sprites. The `two_plane_parallax`
+example is the known-good shape.
 
 Diagnose it without guessing (no core rebuild):
 

package/src/platforms/gg/MENTAL_MODEL.md

@@ -14,7 +14,7 @@ $E000-$FFFB  Work RAM mirror
 $FFFC-$FFFF  Mapper control registers
 ```
 
-Most 32 KB scaffolds fit in banks 0+1 and never touch the mapper.
+Most 32 KB example games fit in banks 0+1 and never touch the mapper.
 
 ## VDP (display)
 
@@ -36,7 +36,7 @@ GG VDP = SMS VDP in Mode 4, smaller visible viewport.
   OR draw the text via the BG name table (no per-line limit).
 
 **Always render gameplay content inside (48, 24)..(207, 167)** so it's
-visible on real hardware. The bundled scaffolds work without this
+visible on real hardware. The bundled example games work without this
 because gpgx shows the full framebuffer.
 
 ### Sprite coords are hardware-space, NOT visible-space
@@ -78,9 +78,9 @@ on its own anymore.
 `gg_vdp_init()` sets R6 = 0xFF. R6 bit 2 is the SA13 select for
 sprite tile data — bit 2 is **SET** in 0xFF, so sprite tiles read
 from `$2000-$3FFF`, in their **own bank** separate from BG tiles at
-$0000. This is the baseline because every bundled scaffold uploads
+$0000. This is the baseline because every bundled example uploads
 its sprite tiles to `$2000` (`gg_load_tiles(0x2000, …)`) — the
-default and the scaffolds match, so sprites Just Show Up.
+default and the examples match, so sprites Just Show Up.
 
 Watch the bit: 0xFB has SA13 **CLEAR** = sprite tiles at $0000
 (sharing the BG bank). If you ever set R6=0xFB you MUST also upload

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -16,7 +16,7 @@ Anything you draw outside `(48, 24)..(207, 167)` is in the border —
 visible in headless emulator screenshots (gpgx shows the whole frame)
 but invisible on real hardware.
 
-The bundled scaffolds are direct ports of the SMS scaffolds and target
+The bundled example games are direct ports of the SMS examples and target
 the full 256×192 area. Works fine for development under gpgx; for
 shipping to a real GG, reposition sprite + tilemap content to the
 visible center.
@@ -28,7 +28,7 @@ active low), separate from the D-pad/A/B which are on `$DC` like
 SMS. `gg_joypad_read()` already merges them — START shows up in bit 7
 of the returned byte (`JOY_START` mask).
 
-If you copied an SMS scaffold that uses PAUSE-as-START semantics
+If you copied an SMS example that uses PAUSE-as-START semantics
 (SMS pause button is at port $DD bit 4 IIRC), it won't work on GG;
 swap to JOY_START.
 
@@ -85,7 +85,7 @@ two-byte little-endian CRAM entry.
 
 ## "Linking error: undefined reference to sms_joypad_read_p2"
 
-GG only has one controller. The SMS scaffolds use `sms_joypad_read_p2`
+GG only has one controller. The SMS examples use `sms_joypad_read_p2`
 for the two-controller patterns (Pong, 2P shmup). When porting, drop
 the P2 read + force `p2 = 0` so the AI fallback always engages.
 

package/src/platforms/gg/UPSTREAM_SOURCES.md

@@ -3,7 +3,7 @@
 GG shares its toolchain (SDCC z80) + emulator (genesis_plus_gx) +
 most of the runtime with SMS (`sms_crt0.s` ≡ `gg_crt0.s` byte-for-
 byte; PSG protocol identical). The GG tree at `src/platforms/gg/`
-holds the GG-specific scaffolds and runtime helpers; SMS docs apply
+holds the GG-specific example games and runtime helpers; SMS docs apply
 for everything else.
 
 GG-specific: