c64bridge 0.5.0

package/data/io/cia-spec.md

@@ -0,0 +1,115 @@
+# Commodore 64 CIA Specification
+
+> Purpose: Single source of truth for CIA hardware on the C64 (LLM/MCP).  
+> Companion specs: `io-spec.md` (system I/O topology, IEC/tape/ports), `data/printer/printer-spec.md` (printers).  
+> Notes: Do **not** duplicate I/O details here—refer to `io-spec.md`. This file defines *exact CIA semantics*. Where sources disagree, this merged spec defers to the attached “Mapping the C64 CIA” and the C64 Programmer’s Reference Guide.
+
+## Overview
+
+- **Chips:** 2× MOS **6526/6526A/8521** (functionally equivalent for C64 use).  
+- **Address blocks:** **CIA1** `$DC00–$DC0F` (mirrored every 16 bytes to `$DCFF`), **CIA2** `$DD00–$DD0F` (mirrored to `$DDFF`).  
+- **Core units:** Ports **PA/PB (8+8)**, **Timers A/B (16‑bit)**, **TOD clock+alarm (BCD)**, **Serial shift (SDR)**, **ICR**.  
+- **System wiring:** CIA1 → **/IRQ**; CIA2 → **/NMI**. `FLAG` inputs: **CIA1** (cassette READ), **CIA2** (user port pin B).  
+- **Electrical:** Port bits are open‑collector with pull‑ups; CMOS‑compatible; CNT/SP serial pins present on user port.  
+- **Defaults after init:** CIA1 `DDRA=$FF` (PA out), `DDRB=$00` (PB in); CIA2 `DDRA=$3F` (bits 6–7 in), `DDRB=$00` (in).  
+- **Cross‑refs:** IEC bus, user port pins, datasette lines, VIC bank select, joystick/paddles/key scan → see `io-spec.md`.
+
+## CIA #1 Registers (`$DC00–$DC0F`) — Keyboard/Joysticks/Paddles/Lightpen/IRQ
+
+| Address | Decimal | Name | Function / Bits (compact) |
+|:-------:|:-------:|:-----|:---------------------------|
+| `$DC00` | 56320 | **PRA** | Keyboard **column select** (write), **joy2** read, paddle mux/fire. **b7..b0** column sel; **b7/b6** paddle mux (`01`=Port1, `10`=Port2); **b4** joy2 fire (0=pressed); **b3..b0** joy2 dir; **b3..b2** paddle fires. |
+| `$DC01` | 56321 | **PRB** | Keyboard **row read**, **joy1** read, timer outputs. **b7..b0** rows; **b7** Timer B out (toggle/pulse); **b6** Timer A out; **b4** joy1 fire (0=pressed); **b3..b0** joy1 dir; **b3..b2** paddle fires. |
+| `$DC02` | 56322 | **DDRA** | Port A direction (0=in, 1=out). Default `$FF`. |
+| `$DC03` | 56323 | **DDRB** | Port B direction (0=in, 1=out). Default `$00`. |
+| `$DC04` | 56324 | **TALO** | Timer A **low**. **R:** counter; **W:** latch low. |
+| `$DC05` | 56325 | **TAHI** | Timer A **high**. **R:** counter; **W:** latch high (if stopped, also loads). |
+| `$DC06` | 56326 | **TBLO** | Timer B **low**. **R/W** as above. |
+| `$DC07` | 56327 | **TBHI** | Timer B **high**. **R/W** as above. |
+| `$DC08` | 56328 | **TOD10TH** | TOD tenths BCD (0–9). **CRB7=0:** writes set **time**; **=1:** set **alarm**. |
+| `$DC09` | 56329 | **TODSEC** | TOD seconds BCD. |
+| `$DC0A` | 56330 | **TODMIN** | TOD minutes BCD. |
+| `$DC0B` | 56331 | **TODHR** | TOD hours BCD; **b7 AM/PM** (1=PM). **Write halts** TOD until `$DC08` read. |
+| `$DC0C` | 56332 | **SDR** | Serial shift data. **CRA6:** 0=input (SP→SDR on CNT↑); 1=output (SDR→SP, CNT strobes). |
+| `$DC0D` | 56333 | **ICR** | **R:** b0 TA UF, b1 TB UF, b2 TOD=ALARM, b3 serial byte, b4 FLAG; **b7**=any pending. **W:** b7=1 set mask bits0–4; b7=0 clear them. **Read clears** status bits. |
+| `$DC0E` | 56334 | **CRA** | **Timer A ctrl**/**serial/TOD**: **b0** start; **b1** PB6 enable; **b2** PB6 mode (1 toggle / 0 pulse); **b3** one‑shot; **b4** force load; **b5** count src (1=CNT / 0=Φ2); **b6** SDR dir (1 out); **b7** TOD freq (1=50 Hz/0=60 Hz). |
+| `$DC0F` | 56335 | **CRB** | **Timer B ctrl/TOD sel**: **b0** start; **b1** PB7 enable; **b2** PB7 mode; **b3** one‑shot; **b4** force load; **b6..b5** mode: `00`=Φ2, `01`=CNT, `10`=TA underflow, `11`=TA underflow gated by CNT; **b7** TOD write target (1=ALARM/0=TIME). |
+
+**Notes (CIA1):** Keyboard matrix via column write (PRA) + row read (PRB), active‑low. Joystick‑keyboard contention on **Port 1** (PRB) exists; avoid or gate scanning accordingly. Paddle select uses **PRA b7/b6**; paddle *positions* read via SID POTX/POTY; paddle buttons via CIA (bits 2–3). Lightpen appears as fire on PRA b4 and via VIC `/LP`.
+
+## CIA #2 Registers (`$DD00–$DD0F`) — IEC/User Port/RS‑232/VIC Bank/NMI
+
+| Address | Decimal | Name | Function / Bits (compact) |
+|:-------:|:-------:|:-----|:---------------------------|
+| `$DD00` | 56576 | **PRA** | **IEC** + **VIC bank** + RS‑232 TXD. **b7** DATA IN, **b6** CLOCK IN, **b5** DATA OUT, **b4** CLOCK OUT, **b3** ATN OUT (bus lines active‑low via drivers); **b2** RS‑232 TXD (user M); **b1..b0** VIC 16 KiB bank: `00=$C000–FFFF`, `01=$8000–BFFF`, `10=$4000–7FFF`, `11=$0000–3FFF` (power‑on `11`). |
+| `$DD01` | 56577 | **PRB** | **User Port/RS‑232** lines (TTL). **b7** DSR (L), **b6** CTS (K), **b5** User‑J, **b4** DCD (H), **b3** RI (F), **b2** DTR (E), **b1** RTS (D), **b0** RXD (C). **Also:** PB7/PB6 timer outputs when enabled. |
+| `$DD02` | 56578 | **DDRA** | Port A direction. Default `$3F` (b6–b7 in). |
+| `$DD03` | 56579 | **DDRB** | Port B direction. Default `$00`; RS‑232 may set b1–b2 out when opened. |
+| `$DD04` | 56580 | **TALO** | Timer A low (R counter / W latch low). |
+| `$DD05` | 56581 | **TAHI** | Timer A high (R counter / W latch high). |
+| `$DD06` | 56582 | **TBLO** | Timer B low. |
+| `$DD07` | 56583 | **TBHI** | Timer B high. |
+| `$DD08` | 56584 | **TOD10TH** | TOD tenths BCD. (OS typically unused here.) |
+| `$DD09` | 56585 | **TODSEC** | TOD seconds BCD. |
+| `$DD0A` | 56586 | **TODMIN** | TOD minutes BCD. |
+| `$DD0B` | 56587 | **TODHR** | TOD hours BCD + AM/PM (b7). |
+| `$DD0C` | 56588 | **SDR** | Serial shift data (rarely used by OS; available via user port SP2/CNT2). |
+| `$DD0D` | 56589 | **ICR** | As CIA1, but flags drive **/NMI**. **b4**=FLAG (user‑port pin B). |
+| `$DD0E` | 56590 | **CRA** | As CIA1 `$DC0E`. |
+| `$DD0F` | 56591 | **CRB** | As CIA1 `$DC0F`. |
+
+**Notes (CIA2):** Provides **IEC** master control (ATN/CLOCK/DATA), **User Port** digital I/O and RS‑232 signals, and **VIC bank** selection via `PRA[1:0]`. `/PC2` (handshake) pulses low for one cycle after **PRB** access—available on user port for external strobing.
+
+## Timers (A/B) — Operation
+
+- **16‑bit down‑counters** with separate **latches** (write low→high). **Start** or **CRA/CRB b4** forces latch→counter.  
+- **Clock sources:** Φ2 (system cycles) or **CNT** pulses; **Timer B** can count **Timer A underflows**, gated by CNT if mode `11`.  
+- **Underflow:** Sets ICR bit (and asserts IRQ/NMI). Optional **PB6/PB7** **pulse** (b2=0) or **toggle** (b2=1). **b3=1** one‑shot; else auto‑reload.  
+- **Readback:** Reads return current counter; device internally manages proper two‑byte read behavior.  
+- **Typical OS setup:** CIA1 Timer A ≈ 1/60 s IRQ; tape I/O repurposes CIA1 timers; CIA2 timers often used by RS‑232.  
+
+## Time‑of‑Day (TOD) Clock — BCD + Alarm
+
+- **Regs:** `$xx08–$xx0B` (10th, sec, min, hr). **Hours b7**=AM/PM.  
+- **Write target:** **CRB7=0** write **time**; **CRB7=1** write **alarm**.  
+- **Halt rule:** Writing **TODHR** halts update until **TOD10TH** is read (for read‑latch/write‑latch coherency).  
+- **Tick source:** **CRA7** selects 60 Hz/50 Hz. **Alarm match** sets ICR bit2 (IRQ/NMI by CIA).  
+
+## Serial Shift (SDR) — SP/CNT
+
+- **Direction:** **CRA6** (0=in, 1=out).  
+- **Input:** On **CNT↑**, bit from **SP** shifts into SDR; byte complete → **ICR b3**.  
+- **Output:** With Timer A running (cont.), SDR shifts MSB→LSB out **SP** with **CNT** strobes; byte complete → **ICR b3**.  
+- **System:** OS uses port‑bit IEC more than SDR; SDR remains available on user port **SP1/CNT1** (CIA1) and **SP2/CNT2** (CIA2).  
+
+## Interrupts (ICR) — Mask/Status
+
+- **Status read (clears):** b0 TA UF, b1 TB UF, b2 TOD alarm, b3 serial, b4 FLAG; **b7**=any pending (ANDed with mask).  
+- **Mask write:** **b7=1** sets bits 0–4; **b7=0** clears bits 0–4; bits written as 0 are unchanged.  
+- **Wiring:** CIA1 ICR → **/IRQ**; CIA2 ICR → **/NMI** (not maskable by SEI).  
+
+## Pinout (logical summary)
+
+`PA0–PA7`, `PB0–PB7` (parallel I/O); `/PC` (handshake pulse after PB access; only CIA2 connected externally); `SP` (serial data), `CNT` (count/serial clock); `FLAG` (neg‑edge IRQ/NMI input); `/IRQ` (CIA1), `/NMI` (CIA2); `RS0–RS3` (reg select); `DB0–DB7`; `R/W`; `/CS`; `/RES`; `Φ2`; `Vcc`; `Vss`.  
+User‑port mapping for CIA2 PRB and PRA b2 is defined in `io-spec.md` (pin letters C..N).  
+
+## Behavior Notes / Gotchas (LLM hints)
+
+- **Keyboard scan vs Joystick 1:** Shared on **PRB**; keyscan can misread joystick state and vice‑versa. Gate scan or prefer **Port 2** for games.  
+- **Paddles:** Buttons via CIA **bits 2–3**; *positions* via **SID** POTX/POTY; select port with **PRA b7/b6**.  
+- **Mirroring:** Access any `$xx00–$xx0F` alias in the `$xx10–$xxFF` window; use base addresses for clarity.  
+- **VIC bank:** Use **CIA2 PRA[1:0]**; update VIC `$D018` pointers accordingly (see `io-spec.md`).  
+- **Datasette:** READ→CIA1 **FLAG** (ICR b4); MOTOR/WRITE/SENSE via CPU `$0001` (see `io-spec.md`).  
+
+## Cross‑References
+
+- **System I/O (IEC, tape, user/expansion ports, keyboard algorithm):** `io-spec.md`  
+- **Printers:** `data/printer/printer-spec.md`  
+- **KERNAL vector/entry points:** `data/memory/kernal-api-spec.md`
+
+---
+
+**Provenance:**
+
+- [C64 Programmer’s Reference Guide](https://www.zimmers.net/cbmpics/cbm/c64/c64prg.txt)
+- [Mapping the C64](https://www.zimmers.net/anonftp/pub/cbm/c64/manuals/mapping-c64.txt)

package/data/io/io-spec.md

@@ -0,0 +1,124 @@
+# Commodore 64 I/O Specification
+
+**Scope:** Single source of truth for C64 I/O architecture and programmer interfaces.  
+
+**Companion docs:** 
+
+- `data/io/cia-spec.md` (CIA registers/semantics)
+- `data/drive/drive-spec.md` (printer details)
+- `data/printer/printer-spec.md` (printer details)
+
+---
+
+## 1. I/O Topology (What connects where)
+
+- **CIA1 (@ $DC00)** → Keyboard matrix, Joystick Port 1, Joystick Port 2 (via matrix), Paddles select, Lightpen flag, Datasette read IRQ flag, IRQ output.  
+- **CIA2 (@ $DD00)** → Serial IEC bus (ATN/CLOCK/DATA), User Port (PB0–PB7; RS‑232 lines), VIC bank select (PRA[1:0]), NMI output.  
+- **6510 CPU Port ($0000/$0001)** → Memory map control; **Datasette motor, sense, write** lines. Datasette **read** goes to **CIA1 FLAG**.  
+- **Expansion Port** → Direct 6510 bus (A/D/R/W/Φ2/IRQ/NMI/RESET); cartridges/REUs map registers/ROM, **bypassing CIAs**.  
+- **SID** → Paddles (analog) POTX/POTY; audio; not covered here.
+- **VIC-II** → Lightpen latch; video; not covered here.
+
+(For CIA registers and bit meanings, see `cia-spec.md`.)
+
+---
+
+## 2. Device Addressing & KERNAL I/O
+
+- **Device numbers (IEC):** Printers **4–7** (convention: 4), Storage **8–30** (convention: first disk **8**). Keyboard=0, Tape=1, RS‑232=2, Screen=3. Secondary addresses distinguish channels on same device.
+- **Bus role:** C64 is IEC **master**; commands: **LISTEN**, **TALK**, **UNLISTEN**, **UNTALK**, **OPEN/CLOSE channel**, with **ATN** controlling command vs data phases.
+- **Key KERNAL entry points:** `OPEN`, `CLOSE`, `CHKIN`, `CHKOUT`, `CLRCHN`, `CHRIN`, `CHROUT`, `LOAD`, `SAVE` (see pagetable KERNAL reference for exact call vectors/regs).
+
+---
+
+## 3. Serial IEC Bus (Disk, Printers)
+
+**Physical lines (on CIA2 PRA):**  
+
+- **b3 ATN OUT**, **b4 CLOCK OUT**, **b5 DATA OUT** (active‑low drivers via 7406), **b6 CLOCK IN**, **b7 DATA IN**. Use open‑collector semantics (0V=true/active). Bytes shift **LSB first**, valid on **CLK rising**.
+
+**Protocol sketch:**  
+
+1) Master asserts **ATN**, sends device **TALK/LISTEN** + (optional) **secondary address**.  
+2) Data phase with **ATN released**; talker drives DATA, listeners ack. **EOI** marks last byte.  
+3) Master sends **UNLISTEN/UNTALK** to end.
+
+> Use KERNAL calls where possible; custom fastloaders may bit‑bang CIA2 lines for speed.
+
+---
+
+## 4. Datasette (Tape) I/O
+
+- **CPU Port ($0001):** **bit5 MOTOR** (0=on), **bit4 SENSE** (0=key pressed), **bit3 WRITE** (tape out). Direction via $0000.
+- **Read:** Cassette **READ → CIA1 /FLAG** (edge‑sensitive, falling only). **ICR bit4** set on edge; enable IRQ via ICR mask.
+- **Implication:** Can **toggle** write/motor; **cannot level‑poll** read—only edges—so loaders measure inter‑edge timing (often with CIA timers).
+
+---
+
+## 5. Keyboard (Matrix Scan) — Detailed
+
+**Hardware:** 8×8 matrix via **CIA1**: write **PRA ($DC00)** to select **column**, read **PRB ($DC01)** to sense **rows** (active‑low). Configure **DDRA=$FF**, **DDRB=$00**. Typical scan masks: `$FE,$FD,$FB,$F7,$EF,$DF,$BF,$7F`.
+**Algorithm (debounce omitted):**  
+
+```text
+init:  DDRA=$FF, DDRB=$00
+for col in 0..7:
+  PRA = ~(1<<col)            ; one column low, others high
+  rows = ~PRB & $7F/$FF      ; read active rows (0=pressed)
+  record (col, rows)         ; map to keys
+```
+
+**Notes:**  
+
+- Joystick **Port 1** shares PRB bits; pressed directions can alias key bits: e.g. Right = “2” key. Prefer **Port 2** for games.
+- **Shift/Ctrl/Commodore** are matrix keys; handle modifiers in lookup.  
+- KERNAL scan routine entry in ROM; custom code may be faster/leaner.
+
+---
+
+## 6. Joysticks, Lightpen, Paddles
+
+- **Joysticks:** Digital switches, active‑low. **Port 1 → CIA1 PRB[0..4]**, **Port 2 → CIA1 PRA[0..4]** (see `cia-spec.md` mapping). Joystick‑keyboard contention exists on Port 1.
+- **Lightpen:** Routed via VIC /LP; also appears as “fire” on CIA1. Use VIC registers for position latch. (Mapping note: see `cia-spec.md`.)
+- **Paddles:** Analog via **SID POTX/POTY**; channel selection via **CIA1 PRA[6:7]** to choose control port.
+
+---
+
+## 7. User Port (Rear Edge Connector)
+
+- **Logical:** **CIA2 PRB (PB0–PB7)** as general‑purpose digital I/O; configure with **DDRB**; read/write via **PRB**. KERNAL also provides RS‑232 routines mapping PB pins.
+- **RS‑232:** TTL‑level via User Port; needs level shifting (e.g., MAX232). High‑speed bit‑bangers (e.g., UP9600) leverage CIA timing/interrupts.
+
+---
+
+## 8. Expansion Port (Cartridges/REU/Fastloaders)
+
+- **Direct 6510 bus exposure:** A[15:0], D[7:0], R/W, Φ2, /IRQ, /NMI, /RESET, chip selects. Devices can map ROM/RAM/I/O and trap vectors. **No CIA mediation.**
+
+---
+
+## 9. VIC Bank Select (Memory Windows)
+
+- **CIA2 PRA[1:0]:** **00=$C000–FFFF**, **01=$8000–BFFF**, **10=$4000–7FFF**, **11=$0000–3FFF (default)**. Controls VIC’s addressable 16 KiB bank. (Use with VIC memory pointers).
+
+---
+
+## 10. Recommended Access Patterns (Summary)
+
+- **Prefer KERNAL** for disk/printer where compatibility matters; switch to custom IEC only for speed‑critical paths.
+- **Keyboard:** CIA1 column‑by‑column scan; handle Port‑1 joystick aliasing.
+- **Tape:** Control motor/write via $0001; measure **FLAG** edges via CIA1 ICR.
+- **User Port:** Set DDRB and use PRB; add RS‑232 level shifting if interfacing to standard serial.
+- **Expansion Port:** Memory‑mapped by cartridge; coordinate with bank switching and KERNAL vectors.
+
+---
+
+## 11. External References
+
+- **CIA details:** `cia-spec.md` (this repo).  
+- **Printers:** `data/printer/printer-spec.md` (this repo).  
+- **KERNAL API (official lookup):** pagetable.com C64 KERNAL reference.
+- **IEC protocol (electrical & byte‑level):** Derogee “IEC dissected”; pagetable Standard Serial overview; Wikipedia Commodore bus.
+- **Keyboard matrix & scan masks:** C64 OS deep‑dive. citeturn0search0
+- **Datasette lines:** C64‑Wiki Cassette Port; Luigi Di Fraia on FLAG edge; 6510 port overview.
+- **User Port/RS‑232:** C64‑Wiki Serial Port; pagetable UP9600.

package/data/memory/kernal-memory-map.md

@@ -0,0 +1,227 @@
+# C64 KERNAL Memory Map — Complete ($E000–$FFFF)
+
+> Purpose: Exhaustive sequential map of KERNAL ROM: callable routines, internal subroutines, constants, tables, IRQ/NMI handlers, and vectors.  
+> Format: One table row per symbol; **bold** names indicate callable/public API (also present in `data/api/kernal-api-spec.md`).  
+> Conventions: A=Accumulator, X,Y=Index, C=Carry; “—” not applicable.
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--------|:--------|:-----|:---------|:-----|:------|:-------|:------|
+| `$E000` | 57344 | EXP cont. | Continuation of BASIC EXP evaluation | — | Entered via BASIC JMP | — | Cross‑ROM linkage |
+| `$E043` | 57411 | POLY1 | FP series evaluation helper 1 | — | FAC1 set | — | Calls POLY2 |
+| `$E059` | 57433 | POLY2 | FP series evaluation helper 2 | — | FAC1 | FAC1 | Uses constant tables |
+| `$E08D` | 57485 | RMULC | FP const for RND multiply (5‑byte) | — | — | — | Constant |
+| `$E092` | 57490 | RADDC | FP const for RND add (5‑byte) | — | — | — | Constant |
+| `$E097` | 57495 | RND | RND(X): seed ops / scramble | A=mode in FAC | X>0 next; X<0 seed; X=0 CIA/ToD mix | FAC1 | See CIA/BCD caveats |
+| `$E0F9` | 57593 | BASIC↔KERNAL I/O | Bridge to CHRIN/CHROUT/CHKx/GETIN | — | — | — | Handles RS‑232 buffer |
+| `$E12A` | 57642 | SYS | Perform SYS; register save/restore | — | Uses `$030C–$030F` | Stores back post‑RTS | JSR target from SYS |
+| `$E156` | 57686 | SAVE (BASIC) | Prepare range; call KERNAL SAVE | — | Uses `$002B/$002D` | — | Can save arbitrary by ptr tweak |
+| `$E165` | 57701 | VERIFY (BASIC) | Set verify flag then LOAD | — | — | — | Falls through LOAD |
+| `$E168` | 57704 | LOAD (BASIC) | Prepare start; call KERNAL LOAD | — | Adjusts BASIC links | — | Retains variables; relinks |
+| `$E1BE` | 57790 | OPEN (BASIC) | BASIC OPEN → KERNAL OPEN | — | — | — | — |
+| `$E1C7` | 57799 | CLOSE (BASIC) | BASIC CLOSE → KERNAL CLOSE | — | — | — | — |
+| `$E1D4` | 57812 | Param setup L/V/S | Set filename/LFN/dev/sec | — | Prior to LOAD/SAVE/VERIFY | — | — |
+| `$E200` | 57856 | Get int to X | Comma skip, parse integer to X | — | Parsing context | X=integer | — |
+| `$E206` | 57862 | Fetch/Endline | Fetch char; if 0, unwind caller | — | — | — | Control‑flow helper |
+| `$E20E` | 57870 | Check comma | Require comma; advance text ptr | — | — | — | Error on missing comma |
+| `$E219` | 57881 | Param setup O/C | Set filename/LFN/dev/sec for O/C | — | Before OPEN/CLOSE | — | — |
+| `$E264` | 57956 | COS | COS(FAC1) via SIN | — | FAC1 | FAC1 | Adds PI/2 then SIN |
+| `$E268` | 57960 | SIN | SIN(FAC1) | — | FAC1 | FAC1 | — |
+| `$E2B4` | 58036 | TAN | TAN(FAC1)=SIN/COS | — | FAC1 | FAC1 | — |
+| `$E2E0` | 58080 | PI2 | Const PI/2 (5‑byte) | — | — | — | Constant |
+| `$E2E5` | 58085 | TWOPI | Const 2*PI (5‑byte) | — | — | — | Constant |
+| `$E2EA` | 58090 | FR4 | Const 1/4 (5‑byte) | — | — | — | Constant |
+| `$E2EF` | 58095 | SINCON | SIN/COS/TAN constants table | — | — | — | 6×5‑byte, count=5 |
+| `$E30E` | 58126 | ATN | ATN(FAC1) | — | FAC1 | FAC1 | Uses table |
+| `$E33E` | 58174 | ATNCON | ATN constants table | — | — | — | 12×5‑byte, count=11 |
+| `$E37B` | 58235 | Warm BASIC | Warm start; CLRCHN; READY vector | — | From BRK | — | Vector `$0300` |
+| `$E38B` | 58251 | Error msg | BASIC error/READY printing | X=index | Vector `$0302` next | — | — |
+| `$E394` | 58260 | Cold BASIC | Power‑on BASIC init | — | — | — | Copies vectors to RAM |
+| `$E3A2` | 58274 | INITAT | CHRGET text (to $0073) | — | — | — | Moved to ZP |
+| `$E3BA` | 59298 | RND seed | Initial RND seed (5‑byte) | — | — | — | Constant |
+| `$E3BF` | 58303 | INIT | BASIC ZP init; copy CHRGET | — | — | — | — |
+| `$E422` | 58402 | Startup msgs | Print banner & BYTES FREE | — | — | — | — |
+| `$E447` | 58439 | BASIC vec tbl | ROM vector table (→RAM $0300) | — | — | — | — |
+| `$E453` | 58451 | Copy vec | Copy BASIC vectors to RAM | — | — | — | — |
+| `$E460` | 58464 | WORDS | Text constants | — | — | — | — |
+| `$E4AD` | 58541 | CHKOUT patch | Preserve A on BASIC→KERNAL CHKOUT | — | — | — | Later KERNAL patch |
+| `$E4B7` | 58551 | Unused | 35 bytes of $AA | — | — | — | — |
+| `$E4DA` | 58586 | Color RAM clr | Clear line color to background | — | Called by `$E9FF` | — | Patch; changes old behavior |
+| `$E4E0` | 58592 | Tape pause | Pause after FOUND; auto‑continue | — | Cassette find | — | Newer KERNAL |
+| `$E4EC` | 58604 | PAL baud tbl | PAL RS‑232 prescalers | — | — | — | Matches NTSC at `$FEC2` |
+| `$E500` | 58624 | **IOBASE** | Return I/O base | — | — | X=lo,Y=hi | Default `$DC00` |
+| `$E505` | 58629 | **SCREEN** | Return screen cols/rows | — | — | X=40,Y=25 | For compat layouts |
+| `$E50A` | 58634 | **PLOT** | Read/Set cursor | C=1 read; C=0 set; Y=row,X=col | — | Read→X/Y | Uses PNTR/TBLX |
+| `$E518` | 58648 | CINT (part) | Init screen/keyboard (orig) | — | — | — | Falls through |
+| `$E544` | 58692 | Screen links | Init line link table; clear screen | — | — | — | — |
+| `$E566` | 58726 | Home | Home cursor | — | — | — | Sets PNTR/TBLX=0 |
+| `$E56C` | 58732 | PNT set | Pointer to current line | — | Uses links | `$00D1/$00D2` | — |
+| `$E5A0` | 58784 | Defaults | Set default I/O; init VIC regs | — | — | — | Writes table at `$ECB9` |
+| `$E5B4` | 58804 | LP2 | Pop from keyboard buffer | — | Buffer `$0277` | A=char | — |
+| `$E5CA` | 58826 | KBD line | Line input; echo; handles SHIFT‑RUN/STOP | — | Keyboard CHKIN path | A=bytes of line | — |
+| `$E632` | 58930 | CHRIN (kbd/scr) | Device handler for keyboard/screen | — | From CHRIN/GETIN | A=byte | — |
+| `$E684` | 59012 | Quote test | Toggle quote flag | — | — | — | `$00D4` |
+| `$E691` | 59025 | Add char | Put printable to screen | A=PETSCII | — | — | — |
+| `$E6A8` | 59048 | Exit print | Common exit of screen output | — | — | — | — |
+| `$E6B6` | 59062 | Advance cur | Advance cursor; scroll/insert as needed | — | — | — | — |
+| `$E701` | 59137 | Back 40 | Move cursor back across 40‑col boundary | — | — | — | — |
+| `$E716` | 59158 | Screen out | CHROUT screen device path | A=byte | — | — | Prints/control‑codes |
+| `$E87C` | 59516 | Next line | Cursor to next line / scroll | — | — | — | — |
+| `$E891` | 59537 | CR | Carriage return behavior | — | — | — | Reset modes; move line |
+| `$E8A1` | 59553 | BOF prev | If at start of line, move up | — | — | — | — |
+| `$E8B3` | 59571 | EOF next | If at end of line, move down | — | — | — | — |
+| `$E8CB` | 59595 | Color chk | Detect color control | A=code | — | — | — |
+| `$E8D1` | 59601 | Color tbl | PETSCII→color control map | — | — | — | 16 entries listed |
+| `$E8EA` | 59626 | Scroll | Scroll screen | — | CTRL pauses | — | — |
+| `$E965` | 59749 | Insert line | Insert blank physical line | — | — | — | — |
+| `$E9C8` | 59848 | Move line | Move screen line (and color) | — | — | — | — |
+| `$E9E0` | 59872 | Set color ptr | Temp color pointer for scrolling | — | — | `$00AE/$00AF` | — |
+| `$E9F0` | 59888 | Set line start | Pointer to start of line by X | X=line# | — | `$00D1/$00D2` | — |
+| `$E9FF` | 59903 | Clear line | Clear screen line & color | — | — | — | Uses `$E4DA` patch |
+| `$EA13` | 59923 | Blink & color | Cursor blink timer & color RAM base | — | — | — | — |
+| `$EA1C` | 59932 | Store to screen | Store A to screen, X to color | A=char,X=color | `$00D1`/`$00F3` set | — | — |
+| `$EA24` | 59940 | Sync color ptr | Sync color ptr to screen line | — | `$00D1` | `$00F3` | — |
+| `$EA31` | 59953 | IRQ | Standard IRQ entry | — | Via `$0314` | Updates jiffy clock; SCNKEY | Every 1/60 s |
+| `$EA87` | 60039 | **SCNKEY** | Keyboard scan; buffer char | — | IRQ context | Keycode→`$00CB` | Sets shift/control flags |
+| `$EAE0` | 60128 | Decode→buffer | Decode key; handle repeat; buf put | — | Keycode | Adds to `$0277` | — |
+| `$EB48` | 60232 | Set decode tbl | Choose PETSCII table (shift/ctrl/logo) | — | Flags at `$028D` | `$00F5` ptr | Handles char set toggle |
+| `$EB79` | 60281 | Tbl vectors | Addresses of decode tables | — | — | — | — |
+| `$EB81` | 60289 | Std decode | Standard key decode table | — | — | — | 64+1 entries |
+| `$EBC2` | 60354 | Shift decode | Shifted key decode table | — | — | — | 64+1 entries |
+| `$EC03` | 60419 | Logo decode | Commodore‑logo decode table | — | — | — | 64+1 entries |
+| `$EC44` | 60484 | Charset switch | Handle CHR$(14)/CHR$(142) | — | — | — | Writes `$D018` |
+| `$EC5E` | 60510 | Toggle enable | Enable/disable charset toggle | — | — | — | Uses `$0291` |
+| `$EC78` | 60536 | Ctrl decode | Control key decode table | — | — | — | 64+1 entries |
+| `$ECB9` | 60601 | VIC defaults | VIC‑II register default table | — | — | — | 47 regs |
+| `$ECE7` | 60647 | Shift‑RUN text | "LOAD\rRUN\r" buffer text | — | — | — | Injected on SHIFT‑RUN |
+| `$ECF0` | 60656 | Screen low tbl | Low bytes of line addresses | — | — | — | High from links/`$0288` |
+| `$ED09` | 60681 | **TALK** | Send TALK+dev | A=dev | — | — | — |
+| `$ED0C` | 60684 | **LISTEN** | Send LISTEN+dev | A=dev | — | — | — |
+| `$ED11` | 60689 | Serial cmd | Send serial command in A | A=cmd | — | — | Helper |
+| `$ED40` | 60736 | Serial out | Send byte on serial bus | A=byte | `$0095` buffer used | — | — |
+| `$EDB0` | 60848 | Serial timeout | TIMEOUT handler | — | — | Sets status | — |
+| `$EDB9` | 60857 | **SECOND** | Send secondary after LISTEN | A=sec | LISTEN sent | — | — |
+| `$EDC7` | 60871 | **TKSA** | Send secondary after TALK | A=sec | TALK sent | — | — |
+| `$EDDD` | 60893 | **CIOUT** | Serial write byte | A=byte | LISTEN path active | — | Buffers until UNLSN |
+| `$EDEF` | 60911 | **UNTLK** | Send UNTALK | — | — | — | — |
+| `$EDFE` | 60926 | **UNLSN** | Send UNLISTEN | — | — | — | — |
+| `$EE13` | 60947 | **ACPTR** | Serial read byte | — | TALK path active | A=byte | — |
+| `$EE85` | 61061 | SCLK low | Serial clock low | — | — | — | CIA2 `$DD00`.4 |
+| `$EE8E` | 61070 | SCLK high | Serial clock high | — | — | — | CIA2 `$DD00`.4 |
+| `$EE97` | 61079 | SDATA low | Serial data low | — | — | — | CIA2 `$DD00`.5 |
+| `$EEA9` | 61097 | Read SDATA/SCLK | Read serial input bits | — | — | C=data, N=clock | CIA2 `$DD00`.7/.6 |
+| `$EEB3` | 61107 | Delay 1ms | Busy wait ~1 ms | — | — | — | Timing helper |
+| `$EEBB` | 61115 | RS232 send bit | NMI bit‑send routine | — | NMI context | — | — |
+| `$EF2E` | 61230 | RS232 errors | Set RS‑232 status bits | — | — | Status at `$0297` | — |
+| `$EF4A` | 61258 | RS232 wordlen | Word length to X | — | Control reg | X=len | — |
+| `$EF59` | 61273 | RS232 recv bit | NMI bit‑receive routine | — | NMI context | — | — |
+| `$EF7E` | 61310 | RS232 setup rx | Setup to receive new byte | — | — | — | — |
+| `$EF90` | 61328 | RS232 start? | Test start bit | — | — | — | — |
+| `$EF97` | 61335 | RS232 store | Store received byte; check errors | — | — | — | Manage overrun/parity etc. |
+| `$EFE1` | 61409 | RS232 CHKOUT | Device‑specific CHKOUT | — | After OPEN | — | — |
+| `$F014` | 61460 | RS232 CHROUT | Device‑specific CHROUT | A=byte | After CHKOUT | — | — |
+| `$F04D` | 61517 | RS232 CHKIN | Device‑specific CHKIN | — | After OPEN | — | — |
+| `$F086` | 61574 | RS232 GETIN | Device‑specific GETIN | — | — | A=byte | Checks buffer empty |
+| `$F0A4` | 61604 | Stop RS232 NMIs | Disable RS‑232 NMIs for tape/serial | — | Before cassette/serial ops | — | Timing safety |
+| `$F0BD` | 61629 | Ctrl messages | Text: I/O ERROR, SEARCHING, … | — | — | — | High bit set on last char |
+| `$F12B` | 61739 | Print error | Print KERNAL error if direct | Y=index | Message flag `$009D` | — | — |
+| `$F13E` | 61758 | **GETIN** | Get next char | — | Device selected | A=byte | Vector `$032A` |
+| `$F157` | 61783 | **CHRIN** | Read from current input | — | After CHKIN | A=byte | Keyboard path does line read |
+| `$F1CA` | 61898 | **CHROUT** | Output to current device | A=byte | After CHKOUT | — | Screen handler at `$E716` |
+| `$F20E` | 61966 | **CHKIN** | Select input channel | X=file# | After OPEN | — | Sends TALK/SA as needed |
+| `$F250` | 62032 | **CHKOUT** | Select output channel | X=file# | After OPEN | — | Sends LISTEN/SA as needed |
+| `$F291` | 62097 | **CLOSE** | Close logical file | A=file# | File open | — | Frees buffers; UNLSN |
+| `$F30F` | 62223 | Find LFN | Find file in LFN table | A=file# | Tables at `$0259/$0263/$026D` | X=index | Helper |
+| `$F31F` | 62239 | Set current | Set current LFN/dev/SA | — | — | `$00B8–$00BA` | Helper |
+| `$F32F` | 62255 | **CLALL** | Close all channels | — | — | — | Vector `$032C` |
+| `$F333` | 62259 | **CLRCHN** | Restore default I/O | — | — | — | Keyboard/screen |
+| `$F34A` | 62282 | **OPEN** | Open logical file | — | After SETLFS/SETNAM | C=1 on error | Vector `$031A` |
+| `$F49E` | 62622 | **LOAD** | Load/Verify RAM | A=0/1; X/Y=start | After SETLFS/SETNAM | X/Y=end addr | SA=1 uses header |
+| `$F5A5` | 62885 | SEARCHING | Print SEARCHING (direct mode) | — | Direct mode | — | — |
+| `$F5D2` | 62930 | LOAD/VERIFY msg | Print LOADING/VERIFYING | — | — | — | — |
+| `$F5DD` | 62941 | **SAVE** | Save RAM to device | A=ZP ptr; X/Y=end addr | After SETLFS/SETNAM | — | Vector `$0332` |
+| `$F68F` | 63119 | SAVING msg | Print SAVING and filename | — | Direct mode | — | — |
+| `$F69B` | 63131 | **UDTIM** | Update clock; STOP scan | — | IRQ 60 Hz | `$00A0–$00A2`++ | STOP key to `$0091` |
+| `$F6DD` | 63197 | **RDTIM** | Read clock | — | — | A=lo,X=mid,Y=hi | From `$00A0–$00A2` |
+| `$F6E4` | 63204 | **SETTIM** | Set clock | A=lo,X=mid,Y=hi | — | Clock set | Disables IRQ during set |
+| `$F6ED` | 63213 | **STOP** | Test STOP key | — | — | Z=1 if pressed | Also CLRCHN & clear queue |
+| `$F6FB` | 63227 | I/O error | Handle KERNAL I/O errors | — | — | C=1, A=code | Prints if enabled |
+| `$F72C` | 63276 | Tape: next header | Find next tape header; print FOUND | — | Cassette | — | — |
+| `$F76A` | 63338 | Tape: write hdr | Write tape header block | — | — | — | — |
+| `$F7D0` | 63440 | Tape: ptr→X/Y | Pointer to tape buffer | — | — | X/Y | — |
+| `$F7D7` | 63447 | Tape: set IO area | I/O start/end to tape buffer | — | — | — | — |
+| `$F7EA` | 63466 | Tape: search name | Search tape for filename | — | — | — | — |
+| `$F817` | 63511 | Tape: buttons read | Press PLAY msg; wait / OK | — | Direct mode unaffected | — | — |
+| `$F82E` | 63534 | Cassette sense | Check cassette switch | — | — | — | — |
+| `$F838` | 63544 | Tape: buttons write | Press PLAY & RECORD msg; wait / OK | — | — | — | — |
+| `$F841` | 63553 | Tape: start read | Init flags; start read | — | — | — | — |
+| `$F864` | 63588 | Tape: start write | Init flags; start write | — | — | — | — |
+| `$F875` | 63605 | Tape: common | Setup IRQ, blank screen, save/replace IRQ | — | — | — | Uses CIA1 Timer B |
+| `$F8D0` | 63696 | Tape: STOP test | Test STOP during tape I/O | — | — | — | — |
+| `$F8E2` | 63714 | Tape: TimerA tune | Adjust CIA1 Timer A for bit timing | — | — | — | — |
+| `$F92C` | 63788 | Tape: read IRQ | IRQ handler for tape read | — | IRQ | — | Restores IRQ at end |
+| `$FA60` | 64096 | Tape: get byte | Receive/store next cassette byte | — | IRQ | — | — |
+| `$FB8E` | 64398 | Tape: addr→172 | Copy save/load address to `$00AC` | — | — | — | — |
+| `$FB97` | 64407 | Tape: reset counters | For new byte R/W | — | — | — | — |
+| `$FBA6` | 64422 | Tape: toggle out | Toggle 6510 port bit 3 for data | — | — | — | `$0001`.3 |
+| `$FBC8` | 64456 | Tape: write IRQ 2 | Cassette write (part 2) | — | IRQ | — | — |
+| `$FC6A` | 64618 | Tape: write IRQ 1 | Cassette write (part 1) | — | IRQ | — | — |
+| `$FC93` | 64659 | IRQ restore | Restore default IRQ; stop motor | — | — | — | Re‑enable 60 Hz IRQ |
+| `$FCB8` | 64696 | Tape I/O end | Terminate cassette I/O | — | — | — | RTS from IRQ |
+| `$FCCA` | 64714 | Tape motor off | Turn off cassette motor | — | — | — | — |
+| `$FCD1` | 64721 | Tape ptr chk | Compare R/W ptr vs end | — | — | — | — |
+| `$FCDB` | 64731 | Tape ptr adv | Advance R/W pointer | — | — | — | — |
+| `$FCE2` | 64738 | RESET | Power‑on reset entry | — | HW reset | — | Checks cartridge; calls IOINIT,RAMTAS,RESTOR,CINT |
+| `$FD02` | 64770 | Cart detect | Check autostart cartridge | — | — | Z set on match | Compares `$8004–$8008` |
+| `$FD10` | 64784 | Cart text | CBM+“80” text for detect (hi‑bit set) | — | — | — | — |
+| `$FD15` | 64789 | **RESTOR** | Restore RAM vectors | — | — | — | Uses ROM table `$FD30` |
+| `$FD1A` | 64794 | **VECTOR** | Read/Write vectors | C=1 read; C=0 write; X/Y=table | — | Copy vectors | Affect IRQ/NMI; SEI |
+| `$FD30` | 64816 | Default vectors | ROM vector table (to `$0314–$0333`) | — | — | — | — |
+| `$FD50` | 64848 | **RAMTAS** | RAM test; set pointers | — | — | `$0281–$0284` | Clears ZP, pages 2–3 |
+| `$FD9B` | 64923 | IRQ vector tbl | Pointers to IRQ routines | — | — | — | Tape write1/2, standard IRQ, tape read |
+| `$FDA3` | 64931 | **IOINIT** | Initialize CIAs/SID | — | — | — | Sets CIA1 Timer A |
+| `$FDF9` | 65017 | **SETNAM** | Set filename pointer/len | A=len, X=lo, Y=hi | — | — | For OPEN/LOAD/SAVE |
+| `$FE00` | 65024 | **SETLFS** | Set LFN/dev/SA | A=lfn, X=dev, Y=sa or `$FF` | — | — | For OPEN/LOAD/SAVE |
+| `$FE07` | 65031 | **READST** | Read I/O status word | — | — | A=status | RS‑232 clears own |
+| `$FE18` | 65048 | **SETMSG** | Control/error messages | A bits6–7 | — | — | — |
+| `$FF81` | 65409 | **CINT** | Init screen/keyboard | — | — | — | Jump table |
+| `$FF84` | 65412 | **IOINIT** | Initialize I/O | — | — | — | Jump table |
+| `$FF87` | 65415 | **RAMTAS** | RAM test/setup | — | — | — | Jump table |
+| `$FF8A` | 65418 | **RESTOR** | Restore vectors | — | — | — | Jump table |
+| `$FF8D` | 65421 | **VECTOR** | Vectors R/W | C,X,Y | — | — | Jump table |
+| `$FF90` | 65424 | **SETMSG** | Message flags | A | — | — | Jump table |
+| `$FF93` | 65427 | **SECOND** | Serial SA after LISTEN | A | — | — | Jump table |
+| `$FF96` | 65430 | **TKSA** | Serial SA after TALK | A | — | — | Jump table |
+| `$FF99` | 65433 | **MEMTOP** | Get/Set top of RAM | C,X,Y | — | X/Y | Jump table |
+| `$FF9C` | 65436 | **MEMBOT** | Get/Set bottom of RAM | C,X,Y | — | X/Y | Jump table |
+| `$FF9F` | 65439 | **SCNKEY** | Keyboard scan | — | — | — | Jump table |
+| `$FFA2` | 65442 | **SETTMO** | Timeout control | A | — | — | Jump table |
+| `$FFA5` | 65445 | **ACPTR** | Serial read | — | — | A | Jump table |
+| `$FFA8` | 65448 | **CIOUT** | Serial write | A | — | — | Jump table |
+| `$FFAB` | 65451 | **UNTLK** | Serial UNTALK | — | — | — | Jump table |
+| `$FFAE` | 65454 | **UNLSN** | Serial UNLISTEN | — | — | — | Jump table |
+| `$FFB1` | 65457 | **LISTEN** | Serial LISTEN | A | — | — | Jump table |
+| `$FFB4` | 65460 | **TALK** | Serial TALK | A | — | — | Jump table |
+| `$FFB7` | 65463 | **READST** | Read status | — | — | A | Jump table |
+| `$FFBA` | 65466 | **SETLFS** | Set LFN/dev/SA | A,X,Y | — | — | Jump table |
+| `$FFBD` | 65469 | **SETNAM** | Set filename | A,X,Y | — | — | Jump table |
+| `$FFC0` | 65472 | **OPEN** | Open | — | — | C on error | Jump table |
+| `$FFC3` | 65475 | **CLOSE** | Close | A | — | — | Jump table |
+| `$FFC6` | 65478 | **CHKIN** | Select input | X | — | — | Jump table |
+| `$FFC9` | 65481 | **CHKOUT** | Select output | X | — | — | Jump table |
+| `$FFCC` | 65484 | **CLRCHN** | Restore default I/O | — | — | — | Jump table |
+| `$FFCF` | 65487 | **CHRIN** | Read byte | — | — | A | Jump table |
+| `$FFD2` | 65490 | **CHROUT** | Write byte | A | — | — | Jump table |
+| `$FFD5` | 65493 | **LOAD** | Load/Verify | A,X,Y | — | X/Y=end | Jump table |
+| `$FFD8` | 65496 | **SAVE** | Save | A,X,Y | — | — | Jump table |
+| `$FFDB` | 65499 | **SETTIM** | Set clock | A,X,Y | — | — | Jump table |
+| `$FFDE` | 65502 | **RDTIM** | Read clock | — | — | A,X,Y | Jump table |
+| `$FFE1` | 65505 | **STOP** | Test STOP | — | — | Z flag | Jump table |
+| `$FFE4` | 65508 | **GETIN** | Get char | — | — | A | Jump table |
+| `$FFE7` | 65511 | **CLALL** | Close all | — | — | — | Jump table |
+| `$FFEA` | 65514 | **UDTIM** | Jiffy tick | — | — | — | Jump table |
+| `$FFED` | 65517 | **SCREEN** | Screen size | — | — | X,Y | Jump table |
+| `$FFF0` | 65520 | **PLOT** | Cursor read/set | C,X,Y | — | X,Y | Jump table |
+| `$FFF3` | 65523 | **IOBASE** | I/O base | — | — | X,Y | Jump table |
+| `$FFFA` | 65530 | NMI vec | NMI vector | — | HW | — | RAM at `$0318/9` |
+| `$FFFC` | 65532 | RESET vec | RESET vector | — | HW | — | Points to `$FCE2` |
+| `$FFFE` | 65534 | IRQ/BRK vec | IRQ/BRK vector | — | HW | — | RAM at `$0314/5` |

package/data/memory/low-memory-map.md

@@ -0,0 +1,133 @@
+# Low Memory Pages 0–3 (Zero Page, Stack, System Work Areas)
+
+> Scope: **$0000–$03FF (0–1023)**: Zero page (BASIC + KERNAL vars), page-1 stack, page-2 system buffers/tables, page-3 vectors + **cassette (tape) buffer**.  
+
+> Style: Same compact table schema used in your KERNAL/BASIC specs. **Hex + decimal** addresses. **Bold** = key/callable vectors.  
+
+> Hints: Zero page gives **1‑byte addressing** → faster code; keep ML temporaries in $FB–$FE. If **tape is unused**, the **cassette buffer $033C–$03FB (828–1019)** is ideal for **small ML helpers** or even **sprite/char data** (e.g., sprite blocks 13 @ $0340–$037F, 14 @ $0380–$03BF). Keyboard buffering enables **“dynamic keyboard”** input injection. Adjust **LORAM/HIRAM/CHAREN** via $0001 for ROM/RAM banking.
+
+## Legend
+
+A=Accumulator, X,Y=index, C=Carry; “—” = not applicable. Pointers are little‑endian unless noted.
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--|:--|:--|:--|:--|:--|:--|:--|
+| `$0000` | 0 | **D6510** | 6510 on‑chip I/O **Data Direction** | bitmask | — | — | Bits0–5 valid; default `$EF`. Configure port at $0001. |
+| `$0001` | 1 | **R6510** | 6510 on‑chip **I/O Port** (banking + cassette) | bitmask | — | — | Bit0=LORAM,1=HIRAM,2=CHAREN; 3=data out; 4=switch sense; 5=motor. |
+| `$0002` | 2 | — | Unused | — | — | — | Free (zero page). |
+| `$0003–$0004` | 3–4 | **ADRAY1** | Vector: FP→signed **int** | — | FAC1 | A,Y or $64/65 | Points to `$B1AA`. |
+| `$0005–$0006` | 5–6 | **ADRAY2** | Vector: **int→FP** | — | A,Y or $64/65 | FAC1 | Points to `$B391`. |
+| `$0007` | 7 | CHARAC | Scanner work byte | — | — | — | Search char for tokeniser. |
+| `$0008` | 8 | ENDCHR | Scanner work byte | — | — | — | Often 0 or 34 ("). |
+| `$0009` | 9 | TRMPOS | Cursor col before TAB/SPC | — | — | — | 0–79 logical col. |
+| `$000A` | 10 | VERCK | LOAD(0)/VERIFY(1) flag → KERNAL | — | — | — | Also copied to $0093. |
+| `$000B` | 11 | COUNT | Input buffer index/array subscripts | — | — | — | Tokeniser & DIM/array helper. |
+| `$000C` | 12 | DIMFLG | Array build/reference flags | — | — | — | Array state. |
+| `$000D` | 13 | VALTYP | Type flag | — | — | — | 0=numeric, $FF=string. |
+| `$000E` | 14 | INTFLG | Numeric kind flag | — | — | — | $80=int, 0=float. |
+| `$000F` | 15 | GARBFL | LIST/GC/tokenize flag | — | — | — | GC tried; LIST in quotes. |
+| `$0010` | 16 | SUBFLG | “(” seen → array/FN | — | — | — | PTRGET helper. |
+| `$0011` | 17 | INPFLG | GET/READ/INPUT kind | — | — | — | 0=INPUT, $40=GET, $98=READ. |
+| `$0012` | 18 | TANSGN | Sign/compare mask | — | — | — | Also holds compare result flags. |
+| `$0013` | 19 | CHANNL | Current I/O **channel** (CMD LFN) | — | device state | — | 0=screen/keyboard; ≠0 alters prompts/tabs. |
+| `$0014–$0015` | 20–21 | LINNUM | Target/line number | — | — | — | Also PEEK/POKE/WAIT/SYS address temp. |
+| `$0016` | 22 | TEMPPT | Temp string stack ptr | — | — | — | 3 slots @ $19–$21; FORMULA TOO COMPLEX if full. |
+| `$0017–$0018` | 23–24 | LASTPT | Temp string stack last | — | — | — | =TEMPPT−3. |
+| `$0019–$0021` | 25–33 | TEMPST | Temp string descriptors | — | — | — | length/addr triples. |
+| `$0022–$0025` | 34–37 | INDEX | Misc temp/save | — | — | — | Scratch. |
+| `$0026–$002A` | 38–42 | RESHO | FP mult/div work | — | — | — | Also array-size calc. |
+| `$002B–$002C` | 43–44 | **TXTTAB** | Ptr: start of BASIC text | — | — | — | Usually $0801; changing relocates program base. |
+| `$002D–$002E` | 45–46 | **VARTAB** | Ptr: start of variables | — | — | — | 7‑byte descriptors; type via high bit(s). |
+| `$002F–$0030` | 47–48 | **ARYTAB** | Ptr: start of arrays | — | — | — | Array header + dims + data. |
+| `$0031–$0032` | 49–50 | **STREND** | Ptr: end of arrays (=start free RAM) | — | — | — | Moves up as vars grow. |
+| `$0033–$0034` | 51–52 | **FREETOP** | Ptr: bottom of string text | — | — | — | CLR sets to MEMSIZ; strings grow downward. |
+| `$0035–$0036` | 53–54 | FRESPC | Temp string ptr | — | — | — | Recent string. |
+| `$0037–$0038` | 55–56 | **MEMSIZ** | Ptr: BASIC top (limit) | — | — | — | User‑lowerable to reserve safe area. |
+| `$0039–$003A` | 57–58 | **CURLIN** | Current BASIC line # | — | — | — | $FF in $3A = immediate mode. |
+| `$003B–$003C` | 59–60 | OLDLIN | Previous line # | — | — | — | For CONT. |
+| `$003D–$003E` | 61–62 | OLDTXT | Ptr: current stmt text | — | — | — | Saved/restored by STOP/CONT. |
+| `$003F–$0040` | 63–64 | DATLIN | DATA line # | — | — | — | Error context. |
+| `$0041–$0042` | 65–66 | **DATPTR** | Ptr: current DATA item | — | — | — | RESTORE resets to TXTTAB. |
+| `$0043–$0044` | 67–68 | INPPTR | Ptr: GET/READ/INPUT source | — | — | — | DATA or $0200 buffer. |
+| `$0045–$0046` | 69–70 | VARNAM | Current var name (2 bytes) | — | — | — | High‑bit type tagging. |
+| `$0047–$0048` | 71–72 | VARPNT | Ptr: current var value | — | — | — | Points past name bytes. |
+| `$0049–$004A` | 73–74 | FORPNT | Temp FOR var ptr | — | — | — | Pushed to stack. |
+| `$004B–$004C` | 75–76 | OPPTR | Operator table offset | — | — | — | Also text save. |
+| `$004D` | 77 | OPMASK | Compare mask | — | — | — | 1/2/4 for </=/>. |
+| `$004E–$004F` | 78–79 | DEFPNT | Ptr: current FN descriptor | — | — | — | DEF/FN. |
+| `$0050–$0052` | 80–82 | DSCPNT | Temp string desc ptr/len | — | — | — | — |
+| `$0053` | 83 | FOUR6 | GC format constant | — | — | — | 3 vs 7‑byte desc. |
+| `$0054–$0056` | 84–86 | JMPER | `JMP` + addr for FN | — | — | — | Table @ $A052. |
+| `$0057–$0060` | 87–96 | — | BASIC numeric work area | — | — | — | — |
+| `$0061–$0066` | 97–102 | **FAC1** | FP accumulator #1 | — | — | FAC1 | Exp @ $61; mant $62–$65; sign $66. |
+| `$0067–$0068` | 103–104 | SGNFLG/BITS | Series count/overflow | — | — | — | FP helper. |
+| `$0069–$006E` | 105–110 | **FAC2** | FP accumulator #2 | — | — | FAC2 | Exp/mant/sign. |
+| `$006F–$0072` | 111–114 | ARISGN/FACOV | Sign compare/rounding | — | — | — | — |
+| `$0071–$0072` | 113–114 | FBUFPT | Series eval ptr | — | — | — | Multi‑use scratch. |
+| `$0073–$008A` | 115–138 | **CHRGET** | Get/peek next BASIC char | — | TXTPTR | A=char; flags | Copied from ROM @ $E3A2 for speed. Entry **CHRGOT**=$0079. |
+| `$008B–$008F` | 139–143 | RNDX | RND seed (5‑byte FP) | — | — | — | Init from ROM seed. |
+| `$0090` | 144 | STATUS | **KERNAL ST** (I/O status) | — | device | — | Bits vary (EOF=bit6). |
+| `$0091` | 145 | STKEY | STOP/row readback | — | keyboard | — | $7F when STOP pressed. |
+| `$0092` | 146 | SVXT | Tape timing const | — | — | — | Adjustable. |
+| `$0093` | 147 | VERCK | LOAD/VERIFY flag | — | — | — | Mirrors $000A usage. |
+| `$0094–$0097` | 148–151 | C3PO/BSOUR/SYNO/XSAV | Serial/tape temporaries | — | — | — | Buffered char, etc. |
+| `$0098` | 152 | LDTND | Open files count / table end | — | OPEN/CLOSE | — | Drives LAT/FAT/SAT mgmt. |
+| `$0099` | 153 | DFLTN | Default input device | — | — | — | 0=keyboard; set by CHKIN. |
+| `$009A` | 154 | DFLTO | Default output (CMD) | — | — | — | 3=screen; set by CHKOUT. |
+| `$009B–$00A2` | 155–162 | Tape/serial state + **TIME** | — | IRQ | TIME ticks | TI/TI$ use RDTIM/SETTIM. |
+| `$00A3–$00AD` | 163–173 | Temp + **SAL** | Load start (work) | — | — | — | Screen routines reuse. |
+| `$00AE–$00AF` | 174–175 | **EAL** | Load end | — | — | — | Also SAVE limit. |
+| `$00B0–$00B3` | 176–179 | CMP0/**TAPE1** | Tape timing / **tape buffer start ptr** | — | — | — | TAPE1→$033C. |
+| `$00B4–$00B7` | 180–183 | BITTS/NXTBIT/RODATA/FNLEN | RS‑232/tape/fname len | — | — | — | Tape names up to 187 bytes. |
+| `$00B8–$00BC` | 184–188 | **LA/SA/FA/FNADR** | LFN/SA/device/fname ptr | — | — | — | Device ids: 0,1,2,3,4–5,8–11. |
+| `$00BD–$00C2` | 189–194 | ROPRTY/FSBLK/MYCH/**STAL** | RS‑232/tape start | — | — | — | STAL used by LOAD/SAVE. |
+| `$00C5` | 197 | LSTX | Last key matrix code | — | — | — | 64 if none. |
+| `$00C6` | 198 | NDX | Keyboard buffer count | — | — | — | Set to 0 to flush. |
+| `$00C7` | 199 | RVS | Reverse‑video flag | — | — | — | CHR$(18)/CHR$(146) toggle; clears on CR. |
+| `$00C8–$00CA` | 200–202 | INDX/LXSP | Input line end / start X,Y | — | — | — | Logical lines. |
+| `$00CB` | 203 | SFDX | Current key matrix code | — | keyboard | — | Used with KEYTAB tables. |
+| `$00D1` | 209 | — | Ptr: current screen line | — | — | — | USER ($F3) follows color RAM. |
+| `$00D9` | 217 | SCRLLN | **Screen line link table index** | — | — | — | Logical line topology (hi‑bit marks head). |
+| `$00F3–$00F6` | 243–246 | **USER/KEYTAB** | Color RAM ptr / keyboard table vector | — | — | — | KEYTAB→tables at $EB81/$EBC2/$EC03/$EC78. |
+| `$00F7–$00FA` | 247–250 | **RIBUF/ROBUF** | RS‑232 input/output buffer ptrs | — | — | — | 256‑byte rings at top of RAM. |
+| `$00FB–$00FE` | 251–254 | **FREEZP** | **Free zero‑page bytes** | — | — | — | Safe for ML use. |
+| `$00FF` | 255 | BASZPT | FP→ASCII temp | — | — | — | — |
+
+### Page 1 — Stack / Tape Log
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--|:--|:--|:--|:--|:--|:--|:--|
+| `$0100–$01FF` | 256–511 | **STACK** | 6510 **hardware stack** | pushes/pulls | JSR/IRQ | return addr/reg saves | BASIC also uses as work area; keep ≥62 bytes free; FOR frame = 18 bytes. |
+| `$0100–$010A` | 256–266 | — | FP→string and scan work | — | — | — | — |
+| `$0100–$013E` | 256–318 | **BAD** | Tape input error log | — | tape pass 1 | — | 62 bytes. |
+
+### Page 2 — Input Buffer, File Tables, Keyboard Queue
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--|:--|:--|:--|:--|:--|:--|:--|
+| `$0200–$0258` | 512–600 | **INBUF** | Keyboard/direct‑mode & GET/INPUT/READ buffer | — | KERNAL CHRIN | — | 89 bytes; last ~8 free on C64. |
+| `$0259–$0262` | 601–610 | **LAT** | Table: active **logical file #s** | — | OPEN/CLOSE | — | 10 entries. |
+| `$0263–$026C` | 611–620 | **FAT** | Table: device # per LFN | — | — | — | 10 entries. |
+| `$026D–$0276` | 621–630 | **SAT** | Table: secondary address per LFN | — | — | — | 10 entries. |
+| `$0277–$0280` | 631–640 | **KEYD** | **Keyboard buffer (FIFO)** | — | IRQ keyboard | dequeued chars | Max length set by $0289 (649). Supports “dynamic keyboard”. |
+| `$0281–$0284` | 641–644 | **BASBOT/BASTOP** | BASIC bottom/top pointers | — | RAMTAS | — | Set by RAM test; RS‑232 lowers by 512 for buffers. |
+| `$0288–$0289` | 648–649 | SCRNPAGE/KEYMAX | Screen page base / max KEYD size | — | — | — | Screen base page used with $ECF0 low‑byte table. |
+
+### Page 3 — KERNAL/BASIC Vectors & **Cassette Buffer**
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--|:--|:--|:--|:--|:--|:--|:--|
+| `$0300–$030B` | 768–779 | **BASIC RAM vectors** | Pointers to BASIC core routines (editable) | — | — | — | Copied from ROM @ $E447; used for wedges/overrides. |
+| `$0314–$0333` | 788–819 | **KERNAL RAM vectors** | CHRIN/CHROUT/STOP/GETIN/etc. | — | — | — | IOPEN/ICLOSE/ICHKIN/ICKOUT/ICLRCH/IBASIN/IBSOUT/ISTOP/IGETIN/ICLALL/USRCMD/ILOAD/ISAVE. |
+| `$0334–$033B` | 820–827 | — | Free vector slots | — | — | — | 8 bytes free. |
+| `$033C–$03FB` | 828–1019 | **TBUFFER** | **Cassette buffer** (192 bytes) | — | tape I/O | — | Reusable if **no tape**: ML stash or VIC‑II data (sprites **13** @ $0340–$037F, **14** @ $0380–$03BF). Header/data block formats; id byte at $033C. |
+| `$03FC–$03FF` | 1020–1023 | — | Unused | — | — | — | 4 free bytes. |
+
+---
+
+## Practical Tips (LLM prompts → actions)
+
+- **Reserve safe RAM** above BASIC: lower `MEMSIZ` ($37/$38) then `CLR` to keep ML/sprite/charset. RS‑232 OPEN auto‑lowers top by 512 for 2×256‑byte buffers.  
+- **Dynamic keyboard**: preload KEYD ($0277–$0280), set NDX ($00C6), characters are consumed in order; handy for quoted INPUT.  
+- **ROM banking** via $0001: temporarily map out BASIC/KERNAL/CHAR for patching or ROM reads; remember to **disable IRQs** before switching out KERNAL.  
+- **Cassette buffer reuse**: if device 1 not active, use $033C–$03FB for short ML stubs or graphics data; keep header semantics in mind; **do not** run tape I/O concurrently.