0.2.5 dev

AGENTS.md

@@ -1,5 +1,9 @@
 # Local Agent Notes
 
+- C64 Ultimate REST/FTP access from Codex must be run from a separate
+  Terminal-owned/background bash, for example via `osascript` opening Terminal
+  and writing logs/status files. Plain foreground `exec_command` curls can fail
+  with false "no route"/connection errors even when the C64U is reachable.
 - REL file access debugging: do **not** use `src/apps/dizzy/dizzy.c` as a reference implementation for REL open/position/read/write behavior.
 - For CAL26 REL work, use the `xrelchk` harness and proven CAL26-specific test results as the source of truth.
 
@@ -14,7 +18,7 @@
 ## ReadyOS Architecture Rules
 
 - App working region is `$1000-$C5FF` (`$B600` bytes); REU save/restore also targets this range.
-- Shim jump table/data is resident at `$C800-$C9FF`; never place app data/code assumptions there unless intentionally using shim ABI.
+- The full resident shim region is `$C600-$C9FF` (1 KB). `$C600-$C7FF` is reserved expansion space and the public jump-table/data ABI remains at `$C800-$C9FF`; never place app data/code assumptions anywhere in this region.
 - Assume KERNAL/disk I/O can clobber app memory in the active region; keep persistent control state in defined safe areas only.
 - ReadyBASIC module packages are generated SEQ files named `rbm.<name>`; preserve/restore disk-image logic must treat names beginning with `rbm.` as build-owned artifacts, not user files to restore from an older disk image.
 - ReadyBASIC refactors must follow `src/apps/readybasic/readyBASICrefactorguidelines.md`. In particular, do not replace BASIC ROM expression/assignment helpers with ReadyBASIC command evaluators unless the normal BASIC cases are proven unchanged; the module-refactor regression broke `I%=I%+1` by doing this and caused `REPEAT`/`UNTIL` failures.
@@ -23,6 +27,21 @@
 - Never call `run.sh` with a specific app name such as `launcher`, `editor`, or any other single-app mode; those paths are not valid for normal ReadyOS verification.
 - Avoid ad-hoc `make`, direct artifact launches, and single-app run modes so all generated assets and preserved D71 user files are included and restored correctly.
 
+### ReadyOS Launch Cookbook
+
+- `run.sh` is not guaranteed to be executable in this checkout; invoke it as `/bin/bash ./run.sh ...`, not `./run.sh ...`.
+- Interactive regular D81, current built artifacts, fast disk mode: `/bin/bash ./run.sh --profile precog-d81 --vice-fast --skipbuild`.
+- Interactive regular D81 with rebuild first: `/bin/bash ./run.sh --profile precog-d81 --vice-fast`.
+- Interactive default profile, current artifacts: `/bin/bash ./run.sh --skipbuild`; add `--vice-fast` for fast disk mode.
+- Do **not** use `kff2-fast` unless the user explicitly asks for the Kung Fu Flash 2 D81 SKU; it is not the regular D81 build.
+- To leave a visible VICE window open from Codex, run the interactive command in a long-running background shell/session and do not run any VICE cleanup or harness prelaunch cleanup afterward.
+- Headless ReadyBASIC regular automation: `make readybasic-vice-suites`; focused hotkey probe: `/bin/bash build_support/run_readybasic_hotkey_probe.sh`.
+- Headless ReadyBASIC cartridge automation: `make easyflash-readybasic-vice-suites`.
+- Harness scripts close VICE by default; only use their `KEEP_VICE`/non-headless options when deliberately debugging automation, not for normal interactive launch.
+- C64 Ultimate hardware automation must be launched from a long-running/background
+  bash shell. One-shot foreground shell calls from Codex may not reach the C64U
+  REST/FTP endpoints even when the device is reachable.
+
 ## CAL26 REL Debugging Discipline
 
 - Use `xrelchk` first; prove behavior in harness before porting to `cal26`.

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.2.5 (development)
+
+### ReadyBASIC Graphics/Sound, C64 Ultimate DMA, Documentation
+
+- Expanded ReadyBASIC through five graphics phases and Sound Phase 1. The
+  built-in module set now covers modes, pixels and primitives, REU surfaces,
+  sprites/input, polygon buffers, display lists, tiles/tilemaps, multicolor
+  bitmap operations, and immediate SID voice/filter commands, accompanied by
+  32 graphics demos and 6 sound demos plus regular/EasyFlash probes.
+- Added the opt-in regular-launcher C64 Ultimate DOS/UCI direct-to-REU loader.
+  It obtains exact PRG payload sizes, supports packed ReadyShell resources,
+  reuses a mounted D81 when possible, exposes `DMA:YES`/`DMA:ON`/`DMA:NO`
+  launcher state, and falls back to KERNAL/disk loading on unavailable or
+  failed DMA paths. The default `LAUNCHER_DMA_LOAD=0` build remains portable.
+- Added focused UCI protocol/timing probes, C64 Ultimate launcher and
+  ReadyShell hardware smoke coverage, valid/empty/bad-path acceptance fixtures,
+  and preserved hardware investigation evidence.
+- Reconciled current public/private documentation with dynamic REU allocation,
+  ReadyOS-bank schema 5, shim token lookup, the nine-overlay ReadyShell layout,
+  current ReadyBASIC memory/modules/examples, the 21-app EasyFlash layout, and
+  opt-in DMA behavior. Historical release and dated evidence documents remain
+  preserved as snapshots.
+- Combined the launcher snapshot and authoritative operating-system metadata in
+  physical `Skip`, now named the ReadyOS bank. Physical `Skip+1` becomes the
+  first dynamic allocation bank. The app snapshot remains `$1000-$C5FF`
+  (`$B600`), while `$C600-$C9FF` is restored as a 1 KB resident shim region;
+  its stable 512-byte ABI resolves nonzero tokens through the ReadyOS `$B740`
+  map instead of arithmetic placement or a resident bitmap.
+- Reduced launcher warm-resume duplication to a compact `RSM1` UI record. The
+  launcher reconstructs banks, drives, hotkeys, resources, loaded state, and
+  sizes from the ReadyOS `LS` settings and 64-app registry. Runtime testing
+  also fixed catalog scratch-pointer invalidation during first allocation and
+  delayed menu-selection validation until after registry restoration.
+
 ## 0.2.4
 
 ### ReadyBASIC, REU Control Bank, Dynamic Resources, Cartridge, Apps