romdevtools 0.27.0 → 0.29.0

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,27 +85,23 @@ 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.
 
 The bundled GG `sports.c` already does this — copy that pattern when
 porting other SMS multiplayer code.
 
-## "Build errors mention 'TMR SEGA' or ROM header"
+## "TMR SEGA" header / ROM boots in the wrong video mode
 
-Same magic as SMS — gpgx accepts headerless ROMs fine for development.
-For real-hardware ROM-burning include a header at $7FF0:
+The build pipeline now stamps the 16-byte header at `$7FF0` automatically
+("TMR SEGA" + checksum + the region/size byte at `$7FFF`) and pads every
+image to 32 KB — you never hand-write it for romdev builds.
 
-```
-db "TMR SEGA"
-dw 0                  ; reserved
-dw 0                  ; checksum (gpgx ignores)
-db 0x00, 0x00, 0x00   ; product code BCD
-db 0x00               ; product code high + version
-db 0x40               ; region (0x40 = GG)
-db 0x4C               ; ROM size (0x4C = 32 KB)
-```
-
-The bundled scaffolds build without a header — sufficient for the
-emulator-driven workflow. Add one before shipping to a cartridge.
+The byte that matters is `$7FFF`: **high nibble = region, low nibble = ROM
+size**. romdev writes `$7C` (GG international, 32 KB) on `.gg` builds.
+If you patch a ROM by hand and leave an SMS region nibble there (`$4C` =
+SMS export), gpgx boots the `.gg` file in **SMS compatibility mode** —
+256×192 timing, SMS palette depth — and everything renders dark and
+mis-cropped even though your code is fine. Check `$7FFF` first when a GG
+ROM suddenly looks like an SMS ROM.

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:

package/src/platforms/gg/lib/c/gg_crt0.s

@@ -37,10 +37,13 @@
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
         .org    0x0000
+        ;; ONLY 8 BYTES fit before the RST $08 vector. The old block here
+        ;; (di/im 1/ld sp/jp = 9 bytes) overflowed into .org 0x0008, whose
+        ;; `ret` stomped the jp's high target byte -> boot jumped into
+        ;; garbage. di+im 1+jp = 6 bytes; SP setup moved to _boot below.
         di                          ; interrupts off until we're ready
         im      1                   ; mode 1 — IRQs jump to $0038
-        ld      sp, #0xDFF0         ; GG/SMS stack (top of WRAM minus 16)
-        jp      gsinit              ; skip the interrupt vector table
+        jp      _boot               ; continue past the vector table
 
 ;; ─── RST handlers (default = return) ──────────────────────────────
         .org    0x0008
@@ -80,6 +83,15 @@
         .org    0x0066
         retn
 
+;; ─── Boot continuation (right after the NMI vector) ───────────────
+;; SP first, then the C runtime init. Lives in the ABS header area so
+;; it exists at a known address regardless of where _CODE is linked
+;; (_CODE must start at >= $0100 so it can't overwrite this table).
+        .org    0x0068
+_boot:
+        ld      sp, #0xDFF0         ; stack at top of WRAM minus 16
+        jp      gsinit
+
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC pattern: jump to a code area, run initializers, then
 ;; call main. The initializer area is filled by sdcc when it sees

package/src/platforms/gg/lib/c/joypad_read.c

@@ -20,3 +20,32 @@ uint8_t gg_joypad_read(void) {
   uint8_t start = ~PORT_GG_INPUT; /* GG-specific port bit 7 = START */
   return (uint8_t)((a & 0x3F) | (start & 0x80));
 }
+
+/*
+ * Player 2 read — for ALTERNATING-TURNS or 2-controller play.
+ *
+ * HONEST NOTE: a real Game Gear has only ONE controller port on the unit; its
+ * 2P story is the Gear-to-Gear LINK CABLE (a second console). But the GG VDP
+ * and I/O chip are the SMS's, and gpgx wires the SMS's full split-across-
+ * $DC/$DD second-controller layout for GG too — so a SECOND PAD does drive
+ * port B in the emulator (and on an SMS-pad adapter), which is exactly what an
+ * alternating-turns 2P platformer needs (the two players never play at once).
+ *
+ * The hardware layout is the SMS's awkward split:
+ *   PORT_JOY_A bits 6-7  = P2 UP, P2 DOWN
+ *   PORT_JOY_B bits 0-3  = P2 LEFT, P2 RIGHT, P2 B1, P2 B2
+ * Reassembled into the same bit layout P1 uses:
+ *   bit 0 = UP, 1 = DOWN, 2 = LEFT, 3 = RIGHT, 4 = B1, 5 = B2.
+ * Returns 0 when no P2 pad is present (all bits high = released after invert).
+ */
+uint8_t gg_joypad_read_p2(void) {
+  uint8_t a = ~PORT_JOY_A;          /* P2 UP in bit 6, DOWN in bit 7 */
+  uint8_t b = ~PORT_JOY_B;          /* P2 LEFT bit 0, RIGHT 1, B1 2, B2 3 */
+  uint8_t up    = (a >> 6) & 0x01;  /* bit 6 -> bit 0 */
+  uint8_t down  = (a >> 6) & 0x02;  /* bit 7 -> bit 1 */
+  uint8_t left  = (b << 2) & 0x04;  /* bit 0 -> bit 2 */
+  uint8_t right = (b << 2) & 0x08;  /* bit 1 -> bit 3 */
+  uint8_t b1    = (b << 2) & 0x10;  /* bit 2 -> bit 4 */
+  uint8_t b2    = (b << 2) & 0x20;  /* bit 3 -> bit 5 */
+  return (uint8_t)(up | down | left | right | b1 | b2);
+}

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -96,7 +96,7 @@ void main(void) {
 `tgi_updatedisplay()` is the frame heartbeat — it ping-pongs the
 double-buffered display and waits for vblank.
 
-## Drawing many rectangles in one frame (game scaffold pattern)
+## Drawing many rectangles in one frame (example-game pattern)
 
 The minimal example above draws "one rect per frame." For an actual
 game with HUD + background + sprites you'll do many tgi_bar / tgi_setcolor

package/src/platforms/lynx/TROUBLESHOOTING.md

@@ -44,7 +44,7 @@ Two things that trip agents up:
   Skipping it is the #1 "Lynx is blank" trap.
 - **Don't rely on `tgi_clear()`** to blank the screen in this
   toolchain/emulator path — use a full-screen `tgi_bar(0,0,maxx,maxy)`
-  in the background colour instead. The bundled `shmup` scaffold uses
+  in the background colour instead. The bundled `shmup` example uses
   this exact loop; copy it.
 
 ## "tgi_outtextxy renders nothing"
@@ -54,7 +54,7 @@ cc65's default TGI on Lynx ships without a font. Either:
    live in `$cc65_share/target/lynx/fonts/`.
 2. Draw your own glyphs with `tgi_bar`/`tgi_line`.
 
-The bundled scaffolds work around this by using simple rectangles
+The bundled example games work around this by using simple rectangles
 for game content + only short text strings. For game UI text, embed
 a bitmap font directly in your code.
 
@@ -93,7 +93,7 @@ cc65 is C89. No mixed declarations + code, no inline `for (uint8_t i
 = 0; ...)`, no compound literals, no // comments in some configs.
 Declare all variables at the top of each block.
 
-The bundled Lynx scaffolds are C89-clean — copy that pattern.
+The bundled Lynx example games are C89-clean — copy that pattern.
 
 ## "Compile fails: no rule to make target lynx-bll.cfg"
 

package/src/platforms/lynx/lib/c/lynx_sfx.c

@@ -103,21 +103,57 @@ static void sfx_flush_pending(void) {
       POKE(VOICE_BASE(i) + 1, 0x80);     /* feedback off */
       POKE(VOICE_BASE(i) + 4, sfx_pending_period[i]);
       POKE(VOICE_BASE(i) + 5, 0x18);     /* RELOAD + COUNT + 16us clock */
-      POKE(VOICE_BASE(i) + 0, 64);       /* volume */
+      POKE(VOICE_BASE(i) + 0, 100);      /* volume (was 64 — read as near-silent on hardware) */
     } else if (sfx_pending_kind[i] == 2) {
       /* Noise on voice 3. */
       POKE(VOICE_BASE(i) + 7, 0x01);     /* 12-bit LFSR */
       POKE(VOICE_BASE(i) + 1, 0x95);     /* classic noise feedback */
       POKE(VOICE_BASE(i) + 4, 40);
       POKE(VOICE_BASE(i) + 5, 0x18);
-      POKE(VOICE_BASE(i) + 0, 64);
+      POKE(VOICE_BASE(i) + 0, 100);
     }
     sfx_pending_kind[i] = 0;
   }
 }
 
+/* ── background music: 16-step melody loop on voice 1 ───────────────
+ * Ticked from sfx_update() through the SAME staged-write path (R57),
+ * so every scaffold that already calls sfx_init() + sfx_update() gets
+ * continuous music for free — "no sound at all" was the Lynx playtest
+ * verdict. sfx_music(0) turns it off. SFX use voice 0 (+ noise on 3).
+ * MIKEY period at the 16us clock: freq ~= 31250 / period. */
+static const uint8_t music_period[16] = {
+    119, 95, 80, 60, 80, 95, 119, 0,    /* C4 E4 G4 C5 G4 E4 C4 -  */
+    142, 119, 95, 71, 95, 119, 142, 0,  /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t music_enabled = 1;
+static uint8_t music_step, music_timer;
+
+void sfx_music(uint8_t on) {
+  music_enabled = on;
+  music_step = 0;
+  music_timer = 0;
+}
+
+static void music_tick(void) {
+  uint8_t p;
+  if (!music_enabled) return;
+  if (music_timer == 0) {
+    p = music_period[music_step & 15];
+    if (p) {
+      sfx_pending_kind[1] = 1;          /* staged like any tone (R57-safe) */
+      sfx_pending_period[1] = p;
+      sfx_remaining[1] = 8;             /* hold 8 of 9 frames — articulated */
+    }
+    music_step++;
+  }
+  music_timer++;
+  if (music_timer >= 9) music_timer = 0;
+}
+
 void sfx_update(void) {
   uint8_t i;
+  music_tick();
   /* R57: flush any sfx_tone/sfx_noise requests from THIS frame. The
    * caller is expected to have just returned from tgi_updatedisplay
    * (or wait_vblank), so the synchronous timer-event sweep that handy

package/src/platforms/lynx/lib/c/lynx_sfx.h

@@ -54,6 +54,7 @@ void sfx_init(void);
 void sfx_tone(uint8_t channel, uint8_t period, uint8_t length_frames);
 void sfx_noise(uint8_t length_frames);
 void sfx_update(void);
+void sfx_music(uint8_t on);  /* background melody on voice 1 — ON by default; 0 = off */
 void sfx_off(void);
 
 #endif

package/src/platforms/msx/MENTAL_MODEL.md

@@ -12,13 +12,13 @@ romdev ships a **hardware helper library** (`src/platforms/msx/lib/c/`:
 `msx_psg_tone()` in plain C. It uses DIRECT Z80 I/O ports (the reliable path —
 NOT fragile inline-asm BIOS wrappers).
 
-The fastest way to a working game: **`scaffold({op:'game', platform: "msx", genre:
-"shmup"})`** — or any of `platformer` / `puzzle` / `sports` / `racing`, the full
-genre set. For a smaller starting point use **`scaffold({op:'project', platform:
-"msx", template: "sprite_move"})`** (also `music_sfx`, `catch_game`). Either drops
+The fastest way to a working game: **fork the example game whose core loop is
+nearest yours — `examples({op:'fork', example:"msx/shmup", name, path})`** — or any
+of `platformer` / `puzzle` / `sports` / `racing`, the full genre set. For a smaller
+starting point fork `msx/sprite_move` (also `music_sfx`, `catch_game`). Either drops
 a complete, *building* project — a verified playable example + the helper lib +
 the cart crt0 + docs. Read the example's `main.c`, then change it. Examples live in
-`examples/msx/`. The `platformer` scaffold column-streams the SCREEN 2 name table
+`examples/msx/`. The `platformer` example column-streams the SCREEN 2 name table
 for a tile-by-tile side-scroll. **Gotcha:** read joystick **port 1**
 (`msx_read_joystick(1)`) — port 0 is the keyboard, which an emulator's gamepad
 doesn't drive.
@@ -117,6 +117,12 @@ exactly this.
   generator + the envelope (period + shape bits).
 - `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
   `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).
+- `disasm({target:'rom'|'references'|'project'})` — native binutils z80
+  `objdump`. MegaROMs (>32 KB) are handled per 16 KB bank: `references` scans
+  bank 0 at `$4000` (after the "AB" header) and banks 1+ at `$8000` (an
+  assumed ASCII16-style window), refs tagged `romBank`;
+  `disasm({target:'project'})` splits the header into its own data region and
+  emits a bank-by-bank native rebuild recipe in `BUILD.md`.
 
 ## MCP debug & inspection tooling
 

package/src/platforms/msx/TROUBLESHOOTING.md

@@ -66,3 +66,24 @@ fixed hardware colors — you choose indices, not RGB.
 The build worker pool can transiently fail. Re-run the build. If it fails
 consistently, read the `log` — SDCC's C89 parser errors are terse; common causes
 are `//` comments, mid-block declarations, or file-scope inline asm (see above).
+
+
+## PSG writes get eaten — sound code "runs" but the chip stays silent
+
+The BIOS KEYINT interrupt fires every frame and reads PSG register 14 (the
+joystick row) — and it CLOBBERS the PSGADDR latch. If an interrupt lands
+between your `PSGADDR = n` and the matching `PSGWRITE`, your byte goes into
+R14 instead of the register you selected. Symptom: the mixer looks right but
+periods/volumes stay 0 — total silence even though your code clearly ran.
+
+**Rule: wrap every PSGADDR/PSGWRITE sequence in `__asm__("di")` /
+`__asm__("ei")`.** The bundled `msx_psg_tone`/`msx_psg_off` (and the music
+ticker) already do this; copy the pattern for any direct PSG access you write.
+
+## A `static x = 5;` boots as 0 (historical — fixed in the bundled crt0)
+
+The old `msx_crt0.s` placed the SDCC `_INITIALIZER` area in RAM, so the boot
+copy duplicated uninitialised RAM onto itself: every value-initialised static
+read 0 and BSS was never zeroed. The bundled crt0 has been fixed (ROM-placed
+`_INITIALIZER` + a BSS-zero loop). If a project forked before 2026-06-09
+shows ghost zeros, refresh its `msx_crt0.s` from a freshly forked example.

package/src/platforms/msx/lib/c/msx_crt0.s

@@ -27,6 +27,8 @@
         .globl  _main
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
+        .globl  s__DATA
+        .globl  l__DATA
         .globl  s__INITIALIZED
 
 ;; ─── Cartridge ROM header at $4000 ────────────────────────────────
@@ -44,7 +46,15 @@
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC area order so the linker fills _GSINIT with the global
 ;; initializer fragments sdcc emits, then _GSFINAL.
+        ;; AREA ORDERING IS LOAD-BEARING (same bug class fixed in the SMS/GG
+        ;; crt0s 2026-06-08): `_INITIALIZER` (the ROM image of every value-
+        ;; initialised static) MUST be declared in the ROM group — otherwise
+        ;; sdld places it in RAM after `_INITIALIZED` and the init copy below
+        ;; copies uninitialised RAM onto itself, so every `static x = N;`
+        ;; boots as 0. On MSX that silenced ALL scaffold audio (the PSG
+        ;; music/sfx state booted zeroed) among other ghosts.
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -59,6 +69,23 @@
 
 ;; INIT entry — the BIOS CALLs here with interrupts on and a valid stack.
 init:
+        ;; ── Zero the BSS segment (`_DATA`) ── every uninitialised static
+        ;; must read back 0 at boot (power-on RAM is garbage).
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, bss_done
+        ldir
+bss_done:
         ;; Copy initialized-data image from ROM to RAM (SDCC global inits).
         ld      bc, #l__INITIALIZER
         ld      a, b

package/src/platforms/msx/lib/c/msx_hw.h

@@ -87,6 +87,9 @@ void    msx_clear_sprites(void);
 void    msx_vblank_wait(void);
 uint8_t msx_read_joystick(uint8_t stick);
 void    msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol);
+void    msx_psg_noise(uint8_t chan, uint8_t rate, uint8_t vol); /* vol 0 = off */
+void    msx_music(uint8_t on);   /* background melody on channel C — ON by default; 0 = off */
+void    msx_music_tick(void);    /* call once per frame (scaffolds do) */
 void    msx_psg_off(uint8_t chan);
 
 #endif /* MSX_HW_H */

package/src/platforms/msx/lib/c/msx_vdp.c

@@ -121,6 +121,13 @@ void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
     uint8_t fine = (uint8_t)(period & 0xFF);
     uint8_t coarse = (uint8_t)((period >> 8) & 0x0F);
 
+    /* DI around the whole register sequence: the BIOS KEYINT ISR reads
+     * PSG R14 (joystick row) every frame, and it CLOBBERS the PSGADDR
+     * latch — an IRQ between our PSGADDR and PSGWRITE sent the period/
+     * volume bytes into R14 instead. Symptom: mixer set, period 0,
+     * amplitude 0 → every MSX scaffold was silent. */
+    __asm__("di");
+
     /* tone period: regs 0/1 (A), 2/3 (B), 4/5 (C) */
     PSGADDR = (uint8_t)(chan << 1);       PSGWRITE = fine;
     PSGADDR = (uint8_t)((chan << 1) + 1); PSGWRITE = coarse;
@@ -136,15 +143,78 @@ void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
     mixer &= (uint8_t)~(1 << chan);        /* tone ON for this channel       */
     PSGADDR = 7;
     PSGWRITE = mixer;
+    __asm__("ei");
+}
+
+/* Play NOISE on PSG channel 0/1/2: the AY's one shared noise generator
+ * (reg 6, 5-bit period — bigger = lower rumble) routed into this channel by
+ * clearing its noise-disable mixer bit (reg 7 bits 3-5) while setting its
+ * tone-disable bit. The classic explosion/impact voice.
+ * msx_psg_noise(chan, rate, 0) silences the channel and re-masks its noise
+ * bit (msx_psg_off only re-masks TONE — it doesn't know about noise). */
+void msx_psg_noise(uint8_t chan, uint8_t rate, uint8_t vol) {
+    uint8_t mixer;
+    __asm__("di");                                /* same KEYINT race as above */
+    if (vol) {
+        PSGADDR = 6;                              /* noise period (shared)     */
+        PSGWRITE = (uint8_t)(rate & 0x1F);
+    }
+    PSGADDR = (uint8_t)(8 + chan);
+    PSGWRITE = (uint8_t)(vol & 0x0F);
+    PSGADDR = 7;
+    mixer = PSGREAD;
+    mixer |= (uint8_t)(1 << chan);                /* tone OFF for this channel */
+    if (vol) mixer &= (uint8_t)~(1 << (3 + chan)); /* noise ON  */
+    else     mixer |= (uint8_t)(1 << (3 + chan));  /* noise OFF */
+    PSGADDR = 7;
+    PSGWRITE = mixer;
+    __asm__("ei");
 }
 
 /* Silence a PSG channel: zero its volume and re-disable its tone bit. */
 void msx_psg_off(uint8_t chan) {
     uint8_t mixer;
+    __asm__("di");                                /* same KEYINT race as above */
     PSGADDR = (uint8_t)(8 + chan); PSGWRITE = 0;  /* volume 0 */
     PSGADDR = 7;
     mixer = PSGREAD;
     mixer |= (uint8_t)(1 << chan);                /* tone OFF for this channel */
     PSGADDR = 7;
     PSGWRITE = mixer;
+    __asm__("ei");
+}
+
+/* ── background music: 16-step melody loop on PSG channel C (2) ─────
+ * Call msx_music_tick() once per frame (the scaffolds wire it in after
+ * their vsync wait); msx_music(0) turns it off. SFX use channels A/B,
+ * so effects always cut through. AY period = 1789773 / (16 * freq). */
+static const uint16_t _msx_music_per[16] = {
+    427, 339, 285, 214, 285, 339, 427, 0,    /* C4 E4 G4 C5 G4 E4 C4 -  */
+    508, 427, 339, 254, 339, 427, 508, 0,    /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t _msx_music_on = 1;
+static uint8_t _msx_music_step;
+static uint8_t _msx_music_timer;
+
+void msx_music(uint8_t on) {
+    _msx_music_on = on;
+    _msx_music_step = 0;
+    _msx_music_timer = 0;
+    if (!on) msx_psg_off(2);
+}
+
+void msx_music_tick(void) {
+    uint16_t p;
+    if (!_msx_music_on) return;
+    if (_msx_music_timer == 0) {
+        p = _msx_music_per[_msx_music_step & 15];
+        if (p) {
+            msx_psg_tone(2, p, 12);            /* AY volume is ~logarithmic — 9 was a whisper */
+        } else {
+            msx_psg_off(2);                    /* rest */
+        }
+        ++_msx_music_step;
+    }
+    ++_msx_music_timer;
+    if (_msx_music_timer >= 9) _msx_music_timer = 0;
 }

package/src/platforms/nes/MENTAL_MODEL.md

@@ -207,9 +207,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.
 
-## What `scaffold({op:'project'})` copies into your project
+## What `examples({op:'fork'})` copies into your project
 
-`scaffold({op:'project', platform:"nes", template:"hello_sprite"|"tile_engine"|"default"})`
+`examples({op:'fork', example:"nes/hello_sprite"|"nes/tile_engine"|"nes/default", 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.
@@ -393,7 +393,11 @@ build({ output:'rom', platform:'nes',
         inesHeader:{ prgBanks:2, chrBanks:1, mapper:0, mirroring:"vertical" } })
 ```
 Mutually exclusive with `linkerConfig`. Works for any NROM (mapper 0, ≤2 PRG
-banks); for a banked mapper supply a linker `.cfg` that places each bank.
+banks). For a BANKED mapper you don't hand-write the glue anymore:
+`disasm({target:'project'})` emits a HEADER segment (the original 16 iNES
+bytes), a `.segment "PRGn"` wrapper per bank, and a multi-bank `nes_rebuild.cfg`
+(switchable banks at $8000, fixed top bank at $C000), all wired into
+`rebuild.json` via `linkerConfigPath` — a one-call byte-exact rebuild.
 
 **2. `linkerConfig:"chr-rom"` — for homebrew C that ships FIXED tile art.**
 A cc65-C preset (segment split + a CHARS segment in an 8 KB ROM2 bank). Put your
@@ -402,8 +406,11 @@ tiles in `.segment "CHARS"` (`.incbin "tiles.chr"`) + pass the blob via
 other bank configs, prefer `inesHeader`.
 
 **3. `disasm({target:'project'})` — disassemble → rebuild, in two calls.**
-For NES it now extracts the CHR-ROM to `chr.bin`, writes a `rebuild.json` (the
-exact `build({inesHeader})` call, with absolute paths) and a `BUILD.md`. Feed
+For NES it extracts the CHR-ROM to `chr.bin`, writes a `rebuild.json` (the
+exact `build({...})` call, with absolute paths) and a `BUILD.md`. NROM gets the
+`inesHeader` one-call form; BANKED mappers (UxROM/MMC1/MMC3…) get per-bank
+`PRGn` segment wrappers + the original-bytes HEADER segment + a generated
+multi-bank `.cfg` referenced via `linkerConfigPath`. Either way: feed
 `rebuild.json` straight back to `build` and you get a byte-identical ROM. This
 is the RE workhorse loop: `disasm({target:'project'})` → edit the `.asm` →
 rebuild → `diffRoms` to confirm your patch landed.