c64bridge 0.5.0

package/data/api/basic-api-spec.md

@@ -0,0 +1,154 @@
+# C64 BASIC API — Callable Routines & Token Dispatch (ROM $A000–$BFFF)
+
+> Purpose: Minimal, deduplicated interface spec for **callable** BASIC API entry points and token dispatch.  
+> Format: Markdown table (one row per routine). Addresses shown in **hex** and **decimal**. **Bold** Name = callable/public API.  
+> Conventions: A=Accumulator, X,Y=Index registers, C=Carry; Token shown where a BASIC token invokes the routine; “—” if not applicable.
+
+## Use of Low Memory ($0000–$03FF)
+
+BASIC uses the [low memory area](./memory/low-memory-map.md) for program management, variable tracking, and floating-point math, with temporary overlap of certain KERNAL variables. It shares this space with the Kernal.
+
+| Range | Purpose | Key Variables / Pointers |
+|:------|:---------|:-------------------------|
+| `$002B–$0030` | Core pointers defining BASIC memory layout | TXTTAB, VARTAB, ARYTAB |
+| `$0031–$0038` | Free-space and string pool boundaries | STREND, FREETOP, MEMSIZ |
+| `$0039–$0042` | Current/previous line context and DATA pointer | CURLIN, OLDLIN, DATPTR |
+| `$0061–$006E` | Floating point accumulators (FAC1/FAC2) | FP math workspace |
+| `$0073–$007A` | Inline copy of CHRGET/CHRGOT tokenizer entry | BASIC text reader |
+| `$0099–$009A` | Default I/O device numbers | DFLTN (input), DFLTO (output) |
+| `$0200–$0258` | Input buffer for keyboard and direct statements | INBUF |
+| `$0281–$0284` | BASIC start and end addresses after memory test | BASBOT, BASTOP |
+| `$0300–$030B` | **BASIC RAM vectors** (redirectable entry points) | e.g. LIST, NEW, RUN |
+| `$033C–$03FB` | Cassette buffer reused by BASIC LOAD/SAVE | TBUFFER |
+
+BASIC and KERNAL share portions of this map; modifying these variables directly  
+allows the relocation of program text, redefining top-of-memory, or injecting custom LOAD/SAVE behavior.
+
+## Callable Routines
+
+| Address | Decimal | Token | Name | Function | Args | Input | Output | Notes |
+|:--------|:--------|:------|:-----|:---------|:-----|:------|:-------|:------|
+| `$A000` | 40960 | — | **COLDV** | Cold start vector target (BASIC init) | — | Entry via OS after power-on | — | Prints banner/bytes free; see `$E394` |
+| `$A002` | 40962 | — | **WARMV** | Warm start vector target (STOP/RESTORE) | — | Entry via BRK/STOP | — | Preserves program; see `$E37B` |
+| `$A00C` | 40972 | — | **STMDSP** | Statement dispatch table (addr-1 entries) | — | NEWSTT preloads return to CHRGET | — | Maps tokens 128–162 to handlers |
+| `$A052` | 41042 | — | **FUNDSP** | Function dispatch table | — | FRMEVAL evals arg; jumps by token | — | Maps tokens 180–202 to handlers |
+| `$A080` | 41088 | — | **OPTAB** | Operator dispatch table (addr-1 + precedence) | — | Expression parsing | — | Maps tokens 170–179 |
+| `$A19E` | 41374 | — | **ERRTAB** | BASIC error message texts | — | — | — | Indexed via vector table `$A328` |
+| `$A328` | 41768 | — | **ERRVEC** | Error message vector table | — | X=err# (in ERROR) | — | 30 entries; BREAK msg in misc |
+| `$A365` | 41829 | — | **MSGTBL** | Misc messages (OK, ERROR, READY., BREAK) | — | — | — | Zero-terminated strings |
+| `$A38A` | 41866 | — | **FNDFOR** | Find FOR block on stack | — | Stack contains FOR frames | — | Used by NEXT/LOOP control |
+| `$A3B8` | 41912 | — | **BLTU** | Open space for new line/variable | — | Requested insert size | — | Moves text/vars; checks space |
+| `$A3FB` | 41979 | — | **GETSTK** | Check stack space | — | Needed bytes in A? | — | Errors on overflow |
+| `$A408` | 41992 | — | **REASON** | Check free memory; GC if needed | — | Requested bytes | — | Calls GARBAG `$B526` then error |
+| `$A435` | 42037 | — | **OMERR** | OUT OF MEMORY handler | X=err# | — | — | Falls through to ERROR |
+| `$A437` | 42039 | — | **ERROR** | General error handler | X=err# | — | — | Vectored via RAM $0300 for trapping |
+| `$A474` | 42089 | — | **READY** | Print READY and enter main loop | — | — | — | Sets KERNAL message flag |
+| `$A480` | 42112 | — | **MAIN** | Main loop: read line, exec/store | — | Via RAM vector $0302 | — | Keyboard via CHRIN `$F157` |
+| `$A49C` | 42140 | — | **MAIN1** | Add/replace program line | — | Line in input buffer | — | Tokenizes; updates links; CLR |
+| `$A533` | 42291 | — | **LINKPRG** | Relink tokenized program lines | — | Program text | — | Rewrites next-line pointers |
+| `$A560` | 42336 | — | **INLIN** | Read input line to buffer ($0200) | — | From current input (keyboard) | — | Max 80 chars; error if >80 |
+| `$A579` | 42361 | — | **CRUNCH** | Tokenize input buffer line | — | Buffer @ $0200 | — | Vectored via RAM $0304 |
+| `$A613` | 42515 | — | **FINDLN** | Find line number (target in $14/$15) | — | Program text | C=1 if found; $5F/$60=ptr | C=0 if not found |
+| `$A642` | 42562 | 162 ($A2) | **NEW** | NEW: clear program to zero link | — | — | — | Falls through CLR |
+| `$A65E` | 42590 | 156 ($9C) | **CLR** | CLR: close files; reset var areas | — | — | — | Calls KERNAL CLALL `$F32F` |
+| `$A68E` | 42638 | — | **RUNC** | Reset text pointer to start | — | — | — | Sets TXTPTR $7A/$7B |
+| `$A69C` | 42652 | 155 ($9B) | **LIST** | LIST: print lines in range | — | Start/end in $5F/$60 and $14/$15 | — | Uses QPLOP for tokens |
+| `$A717` | 42775 | — | **QPLOP** | Convert tokens → ASCII for LIST | — | Vectored via RAM $0306 | — | Supports custom keywords |
+| `$A742` | 42818 | 129 ($81) | **FOR** | Save FOR frame on stack | — | TO expr eval once; STEP default 1 | — | Non-array FP loop var |
+| `$A7AE` | 42926 | — | **NEWSTT** | Prepare next statement execution | — | — | — | Tests STOP; advances pointers |
+| `$A7E4` | 42980 | — | **GONE** | Fetch next token and execute | — | Vectored via RAM $0308 | — | PUSH (addr-1) from STMDSP; CHRGET |
+| `$A81D` | 43037 | 140 ($8C) | **RESTORE** | RESET DATA pointer | — | — | — | DATA ptr $41/$42 ← start $2B/$2C |
+| `$A82C` | 43052 | — | **STOPTST** | Test STOP key and branch | — | Calls KERNAL STOP `$F6ED` | — | |
+| `$A82F` | 43055 | 144 ($90) | **STOP** | STOP: break program | — | STOP pressed | — | Prints BREAK then READY |
+| `$A831` | 43057 | 128 ($80) | **END** | END: terminate program | — | — | — | Preserves CONT pointers |
+| `$A857` | 43095 | 154 ($9A) | **CONT** | CONT: resume after STOP/END | — | Saved CONT pointers | — | Errors if missing |
+| `$A871` | 43121 | 138 ($8A) | **RUN** | RUN: SETMSG, CLR, optional GOTO | — | Optional line# | — | SETMSG `$FE18` |
+| `$A883` | 43139 | 141 ($8D) | **GOSUB** | Push return context; then GOTO | — | — | — | Marks stack frame (0x8D) |
+| `$A8A0` | 43168 | 137 ($89) | **GOTO** | Branch to target line | — | Scans program for line | — | Adjusts pointers to target |
+| `$A8D2` | 43218 | 142 ($8E) | **RETURN** | Pop GOSUB frame; resume | — | Stack contains frame | — | Restores line/char pointers |
+| `$A8F8` | 43256 | 131 ($83) | **DATA** | Skip DATA text | — | — | — | Skips to next stmt (like REM) |
+| `$A906` | 43270 | — | **DATAN** | Find end of current statement | — | — | — | Stops at 0 or colon (outside quotes) |
+| `$A928` | 43304 | 139 ($8B) | **IF** | Eval expr; if nonzero do THEN-part | — | Uses FRMEVAL `$AD9E` | — | Else falls through to REM |
+| `$A93B` | 43323 | 143 ($8F) | **REM** | Skip to next statement | — | — | — | Shares code path with IF |
+| `$A94B` | 43339 | 145 ($91) | **ON** | ON GOTO/GOSUB list dispatch | — | Arg → integer; select target | — | No-op if out-of-range |
+| `$A96B` | 43371 | — | **LINGET** | Parse decimal → 2-byte line# | — | Range 0–63999 | $14/$15=line# | |
+| `$A9A5` | 43429 | 136 ($88) | **LET** | Evaluate/assign var (all types) | — | Var ref and expr | — | Type-checked assign/create |
+| `$AA80` | 43648 | 152 ($98) | **PRINT#** | PRINT# (to device) | — | Calls CMD then CLRCHN `$F333` | — | |
+| `$AA86` | 43654 | 157 ($9D) | **CMD** | Route output to device; keep open | — | CHKOUT `$F250`; PRINT text | — | Leaves channel open |
+| `$AAA0` | 43680 | 153 ($99) | **PRINT** | PRINT with TAB/SPC/;/, variables | — | Converts to strings; CHROUT | — | Handles TI, TI$, ST |
+| `$AB1E` | 43806 | — | **STROUT** | Print zero-terminated string at (A,Y) | A=lo,Y=hi | Points to string | — | |
+| `$AB4D` | 43853 | — | **DOAGIN** | Input error formatting (GET/INPUT/READ) | — | — | — | |
+| `$AB7B` | 43899 | 161 ($A1) | **GET** | GET/GET#: get single char | — | Optional CHKIN/CLRCHN | A=char | Uses READ common I/O |
+| `$ABA5` | 43941 | 132 ($84) | **INPUT#** | INPUT# from device | — | CHKIN; then INPUT; CHKOUT | — | Discards excess silently |
+| `$ABBF` | 43967 | 133 ($85) | **INPUT** | Prompt; read; assign to vars | — | Not allowed in direct mode | — | Uses READ common code |
+| `$AC06` | 44038 | 135 ($87) | **READ** | Read from DATA; assign | — | DATA pointer | — | Shared I/O for GET/INPUT |
+| `$ACFC` | 44284 | — | **EXIGNT** | Input error message texts | — | — | — | “?EXTRA IGNORED”, “?REDO FROM START” |
+| `$AD1E` | 44318 | 130 ($82) | **NEXT** | Increment FOR var; loop test | — | FOR frame on stack | — | Removes frame when complete |
+| `$AD8A` | 44426 | — | **FRMNUM** | Type check (string vs numeric) | — | Desired type | — | TYPE MISMATCH on mismatch |
+| `$AD9E` | 44446 | — | **FRMEVAL** | Evaluate expression | — | Text pointer at term start | Result→FAC1/desc | Sets flags at $0D/$0E |
+| `$AE83` | 44675 | — | **EVAL** | Parse single numeric term → FAC1 | — | Constant/variable/PI | FAC1 | Vectored via RAM $030A |
+| `$AEF1` | 44785 | — | **PARCHK** | Evaluate expression in parentheses | — | — | — | Calls FRMEVAL |
+| `$AEFF` | 44799 | — | **SYNCHR** | Syntax helper: expect & skip char | A=expected | — | — | For comma/parens checks |
+| `$AF08` | 44808 | — | **SNERR** | Print SYNTAX ERROR | — | — | — | |
+| `$AF2B` | 44843 | — | **ISVAR** | Fetch variable value | — | — | Result in FAC1/desc | |
+| `$AFA7` | 44967 | — | **ISFUN** | Dispatch and evaluate function | — | Token in current text | — | Uses FUNDSP |
+| `$AFE6` | 45030 | 176 ($B0) | **OR** | Logical OR | — | Operands coerced to 16-bit ints | FAC1=0/−1 | Shares code with AND |
+| `$AFE9` | 45033 | 175 ($AF) | **AND** | Logical AND | — | Operands coerced to 16-bit ints | FAC1=0/−1 | — |
+| `$B016` | 45078 | 177 ($B1) | **REL** | Comparisons (>,<,=) | — | Strings or floats | FAC1=0/−1 | Used by tokens 177/178/179 |
+| `$B081` | 45185 | 134 ($86) | **DIM** | Create array(s) | — | Variables list | — | Default size 11 elements if missing |
+| `$B08B` | 45195 | — | **PTRGET** | Find/create variable descriptor | — | Name in text | Ptr→$47/$48 | |
+| `$B113` | 45331 | — | **ISALPHA** | Test A for alphabetic | A=char | — | Z/N set | Part of var-name check |
+| `$B11D` | 45341 | — | **NOTFNS** | Create new variable descriptor | — | — | — | Moves storage up 7 bytes |
+| `$B185` | 45445 | — | **FINPTR** | Return address of variable | — | — | Ptr→$47/$48 | |
+| `$B194` | 45460 | — | **ARYGET** | Allocate array descriptor | — | Dims parsed | — | 5 + 2*ndim bytes |
+| `$B1AA` | 45482 | — | **FTOI_AY** | Float→signed int in A(high)/Y(low) | — | FAC1 | A,Y=int | Also writes $64/$65 |
+| `$B1B2` | 45490 | — | **INTIDX** | Subscript to positive integer | — | FAC1 | — | Range check |
+| `$B1BF` | 45503 | — | **AYINT** | Float→signed int @ $64/$65 | — | FAC1 in range | — | Errors if out of range |
+| `$B245` | 45637 | — | **BSERR** | BAD SUBSCRIPT error | — | — | — | |
+| `$B248` | 45640 | — | **FCERR** | ILLEGAL QUANTITY error | — | — | — | |
+| `$B34C` | 45900 | — | **UMULT** | Size of multidimensional array | — | Dims | — | Multiply dims |
+| `$B37D` | 45949 | 184 ($B8) | **FRE** | Return free memory (fix sign) | — | Calls GARBAG `$B526` | FAC1 | Use `FRE(0)-65536*(FRE(0)<0)` |
+| `$B391` | 45969 | — | **GIVAYF** | 16-bit signed int (A,Y) → float | A,Y=int | — | FAC1 | RAM vector at 5–6 |
+| `$B39E` | 45982 | 185 ($B9) | **POS** | Cursor position (logical) | — | Calls PLOT `$E50A` | FAC1 | Equivalent to PEEK(211) |
+| `$B3B3` | 46003 | 150 ($96) | **DEF** | Define FN | — | Syntax checks; push frame | — | Nested functions allowed |
+| `$B3E1` | 46049 | — | **GETFNM** | Check DEF/FN syntax | — | — | — | Finds/creates dep. var |
+| `$B3F4` | 46068 | — | **FNDOER** | Evaluate FN(...) | — | — | FAC1 | Uses definition text |
+| `$B465` | 46181 | 196 ($C4) | **STR$** | Number → string | — | Number required | String desc | |
+| `$B487` | 46215 | — | **STRLIT** | Scan string literal; set pointers | — | — | — | Allocates/copies as needed |
+| `$B4F4` | 46324 | — | **GETSPA** | Allocate string space (may GC) | — | Length in A? | — | Calls GARBAG on shortage |
+| `$B526` | 46374 | — | **GARBAG** | String garbage collection | — | — | — | Compacts live strings; moves bottom ptr |
+| `$B63D` | 46653 | — | **CAT** | Concatenate strings | — | A$+B$ | New string desc | Allocates & builds |
+| `$B67A` | 46714 | — | **MOVINS** | Move string text | — | — | — | Utility |
+| `$B6A3` | 46755 | — | **FRESTR** | Discard temporary string | — | — | — | Updates bottom if topmost |
+| `$B6DB` | 46811 | — | **FRETMS** | Remove entry from temp string stack | — | — | — | |
+| `$B6EC` | 46828 | 199 ($C7) | **CHR$** | Create one-byte string | — | Byte value | String desc | |
+| `$B700` | 46848 | 200 ($C8) | **LEFT$** | Left substring | — | String, count | String desc | |
+| `$B72C` | 46892 | 201 ($C9) | **RIGHT$** | Right substring | — | String, count | String desc | |
+| `$B737` | 46903 | 202 ($CA) | **MID$** | Mid substring | — | String, pos[,len] | String desc | |
+| `$B761` | 46945 | — | **PREAM** | Pull params for LEFT$/RIGHT$/MID$ | — | — | — | Helper |
+| `$B77C` | 46972 | 195 ($C3) | **LEN** | String length → number | — | String desc | FAC1 | |
+| `$B78B` | 46987 | 198 ($C6) | **ASC** | First char code → number | — | String | FAC1 | |
+| `$B79B` | 47003 | — | **GETBYTC** | Read byte parameter (0–255) | — | — | X=byte | For USR/new commands |
+| `$B7AD` | 47021 | 197 ($C5) | **VAL** | Parse number in string | — | String | FAC1 | |
+| `$B7EB` | 47083 | — | **GETNUM** | Get 16-bit address and 8-bit byte | — | Parses next numeric; range-checks | $14/$15=addr, X=byte | For POKE/WAIT |
+| `$B7F7` | 47095 | — | **GETADR** | Float→unsigned 16-bit address | — | FAC1 in range | $14/$15 | For PEEK |
+| `$B80D` | 47117 | 194 ($C2) | **PEEK** | Read byte at address | — | Addr via GETADR | FAC1 | Reads via Y then float |
+| `$B824` | 47140 | 151 ($97) | **POKE** | Write byte to address | — | GETNUM (addr,byte) | — | |
+| `$B82D` | 47149 | 146 ($92) | **WAIT** | Wait on (addr XOR pat) AND mask | — | Addr, mask[,pattern] | — | Poll loop until nonzero |
+| `$BC39` | 48185 | 180 ($B4) | **SGN** | Sign of number | — | FAC1 | FAC1 | |
+| `$BC58` | 48216 | 182 ($B6) | **ABS** | Absolute value | — | FAC1 | FAC1 | |
+| `$BCCC` | 48332 | 181 ($B5) | **INT** | Truncate to integer | — | FAC1 | FAC1 | |
+| `$BDDD` | 48605 | — | **FOUT** | Float → ASCII string | — | FAC1 | A,Y→string | Used by PRINT/STR$ |
+| `$BF71` | 49009 | 186 ($BA) | **SQR** | Square root | — | FAC1 | FAC1 | |
+| `$BF7B` | 49019 | 174 ($AE) | **^** | Exponentiation | — | FAC2^FAC1 | FAC1 | |
+| `$BFB4` | 49076 | 168 ($A8) | **NOT / >** | Logical NOT (also helper for >) | — | FAC1 | FAC1 | NOT X = -(X+1) |
+| `$BFED` | 49133 | 189 ($BD) | **EXP** | e^X | — | FAC1 | FAC1 | Jumps into KERNAL continuation |
+| `$B86A` | 47210 | 170 ($AA) | **+** | Addition | — | FAC1,FAC2 | FAC1 | |
+| `$B853` | 47187 | 171 ($AB) | **-** | Subtraction | — | FAC1,FAC2 | FAC1 | |
+| `$BA2B` | 47659 | 172 ($AC) | **\*** | Multiplication | — | FAC1,FAC2 | FAC1 | |
+| `$BB12` | 47890 | 173 ($AD) | **/** | Division | — | FAC2/FAC1 | FAC1 | |
+| `$AFE6` | 45030 | 176 ($B0) | **AND** | Logical AND | — | ints | FAC1 | duplicate entry for clarity |
+| `$AFE9` | 45033 | 175 ($AF) | **OR** | Logical OR | — | ints | FAC1 | duplicate entry for clarity |
+| `$AED4` | 44756 | 178 ($B2) | **=** | Equal comparison | — | — | FAC1=0/−1 | Uses REL |
+| `$BFB4` | 49076 | 177 ($B1) | **>** | Greater than comparison | — | — | FAC1=0/−1 | Uses REL/NEGOP |
+| `$B016` | 45078 | 179 ($B3) | **<** | Less than comparison | — | — | FAC1=0/−1 | Uses REL |

package/data/api/kernal-api-spec.md

@@ -0,0 +1,68 @@
+# C64 KERNAL API — Callable Routines (ROM $E000–$FFFF)
+
+> Purpose: Minimal, deduplicated interface spec for **callable** KERNAL API routines.  
+> Format: Markdown table (one row per routine). Addresses shown in **hex** and **decimal** for BASIC friendliness.  
+> Conventions: A=Accumulator, X,Y=Index registers, C=Carry; “—” means not applicable. **Bold** Name = callable/public API.
+
+## Use of Low Memory ($0000–$03FF)
+
+The KERNAL relies on the [low memory region](./memory/low-memory-map.md) for all I/O and interrupt control. It shares this space with BASIC.
+
+| Range | Purpose | Key Variables / Vectors |
+|:------|:---------|:------------------------|
+| `$0000–$0001` | 6510 I/O registers controlling memory banking and cassette motor | D6510, R6510 |
+| `$0090` | I/O **status byte** updated by KERNAL routines | STATUS |
+| `$009B–$00A2` | System clock and **TIME** variables for RDTIM/SETTIM | TI, TI$ |
+| `$00B8–$00BC` | File/device association (LFN, SA, FA) | LA, SA, FA, FNADR |
+| `$00C6` | Keyboard buffer count | NDX |
+| `$00F3–$00F6` | Vectors to color RAM and keyboard decode tables | USER, KEYTAB |
+| `$0314–$0333` | **Interrupt and I/O vectors** (modifiable by user) | CINV, CBINV, IRQ, BRK, NMI, etc. |
+| `$033C–$03FB` | **Cassette buffer** (192 bytes, reusable for ML code if no tape is used) | TBUFFER |
+| `$03FC–$03FF` | Unused bytes (safe for temporary data) | — |
+
+The KERNAL modifies `$0001` to switch ROM/RAM banks, writes device status to `$0090`,  
+and maintains IRQ/NMI linkage through `$0314–$0318`. Avoid overwriting these unless intercepting system vectors.
+
+## Callable Routines
+
+| Address | Decimal | Name | Function | Args | Input | Output | Notes |
+|:--------|:--------|:-----|:---------|:-----|:------|:-------|:------|
+| `$FF81` | 65409 | **CINT** | Init screen editor; clear/home; cursor state | — | Call after IOINIT/RAMTAS/RESTOR | — | Sets screen/keyboard defaults |
+| `$FF84` | 65412 | **IOINIT** | Init CIAs; SID volume off; set IRQ @ 60 Hz | — | Power‑up or RESTORE flow | — | Sets CIA1 Timer A, bus lines |
+| `$FF87` | 65415 | **RAMTAS** | RAM test; set MEMBOT/MEMTOP; zp/pages clear | — | Power‑up | MEMBOT=`$0281/2`, MEMTOP=`$0283/4` | Sets screen base via `$0288` |
+| `$FF8A` | 65418 | **RESTOR** | Restore default RAM vectors | — | — | Vectors at `$0314–$0333` reset | Uses ROM table at `$FD30` |
+| `$FF8D` | 65421 | **VECTOR** | Read/Write RAM vector table | C=1 read; C=0 write; X/Y=table addr | SEI recommended | Vectors copied to/from (X,Y) | Affects IRQ/NMI; use SEI/CLI |
+| `$FF90` | 65424 | **SETMSG** | Enable/disable control & error messages | A: bit6=control, bit7=errors | — | — | Does not suppress cassette prompts |
+| `$FF93` | 65427 | **SECOND** | Send secondary addr after LISTEN (serial) | A=sec addr | Device is LISTENing | — | For serial LISTEN path |
+| `$FF96` | 65430 | **TKSA** | Send secondary addr after TALK (serial) | A=sec addr | Device is TALKing | — | For serial TALK path |
+| `$FF99` | 65433 | **MEMTOP** | Get/Set top of BASIC RAM pointer | C=1 get; C=0 set; (get→X/Y; set: X/Y=in) | — | On get: X=lo,Y=hi | Pointer at `$0283/4` |
+| `$FF9C` | 65436 | **MEMBOT** | Get/Set bottom of BASIC RAM pointer | C=1 get; C=0 set; (get→X/Y; set: X/Y=in) | — | On get: X=lo,Y=hi | Pointer at `$0281/2` |
+| `$FF9F` | 65439 | **SCNKEY** | Scan keyboard; buffer PETSCII | — | IRQ normally handles; call if IRQ off | — | Keycode→`$CB`; buffer at `$0277` |
+| `$FFA2` | 65442 | **SETTMO** | Set IEEE/serial timeout flag | A bit7=0 enable; bit7=1 disable | — | — | Rarely used |
+| `$FFA5` | 65445 | **ACPTR** | Read byte from current TALKer (serial) | — | Device TALK/TKSA set | A=byte | Use READST for status |
+| `$FFA8` | 65448 | **CIOUT** | Send byte to current LISTENer (serial) | A=byte | Device LISTEN/SECOND set | — | Buffers until next/UNLSN |
+| `$FFAB` | 65451 | **UNTLK** | Send UNTALK on serial bus | — | — | — | Ends TALK state |
+| `$FFAE` | 65454 | **UNLSN** | Send UNLISTEN on serial bus | — | — | — | Ends LISTEN state |
+| `$FFB1` | 65457 | **LISTEN** | Send LISTEN+dev | A=device# | — | — | — |
+| `$FFB4` | 65460 | **TALK** | Send TALK+dev | A=device# | — | — | — |
+| `$FFB7` | 65463 | **READST** | Read & clear I/O status | — | — | A=status | RS‑232 clears its own |
+| `$FFBA` | 65466 | **SETLFS** | Set logical file#, device#, secondary | A=file#, X=device#, Y=secondary or `$FF` | — | — | Required before OPEN/LOAD/SAVE |
+| `$FFBD` | 65469 | **SETNAM** | Set filename pointer & length | A=len, X=lo, Y=hi | — | — | Points to PETSCII name |
+| `$FFC0` | 65472 | **OPEN** | Open channel to device | — | After SETLFS/SETNAM | C=1 on error | Entry uses vector `$031A` |
+| `$FFC3` | 65475 | **CLOSE** | Close logical file | A=file# | File was OPENed | — | Frees resources; sends UNLSN |
+| `$FFC6` | 65478 | **CHKIN** | Select input channel (logical file) | X=file# | After OPEN | — | For CHRIN/GETIN |
+| `$FFC9` | 65481 | **CHKOUT** | Select output channel (logical file) | X=file# | After OPEN | — | For CHROUT |
+| `$FFCC` | 65484 | **CLRCHN** | Restore default I/O devices | — | — | — | Keyboard/screen; sends UNTALK/UNLSN if needed |
+| `$FFCF` | 65487 | **CHRIN** | Read byte from current input device | — | After CHKIN (or default keyboard) | A=byte | Keyboard path echoes & line-buffers |
+| `$FFD2` | 65490 | **CHROUT** | Write byte to current output device | A=byte | After CHKOUT (or default screen) | — | Screen path handles control codes |
+| `$FFD5` | 65493 | **LOAD** | Load/Verify to RAM | A=0 load, A=1 verify; X/Y=start | SETLFS/SETNAM done | X/Y=end addr loaded | SA=1 uses header address |
+| `$FFD8` | 65496 | **SAVE** | Save RAM to device | A=zp ptr offset; X/Y=end addr | SETLFS/SETNAM done; ZP ptr→start | — | Cassette buffers; disk writes file |
+| `$FFDB` | 65499 | **SETTIM** | Set software clock | A=lo, X=mid, Y=hi | — | Clock `$00A0–$00A2` set | Disables IRQ during set |
+| `$FFDE` | 65502 | **RDTIM** | Read software clock | — | — | A=lo, X=mid, Y=hi | From `$00A0–$00A2` |
+| `$FFE1` | 65505 | **STOP** | Test STOP key | — | UDTIM updates key state | Z=1 if STOP pressed | Also clears I/O channels on stop |
+| `$FFE4` | 65508 | **GETIN** | Get next char (unbuffered if possible) | — | Device selected; keyboard uses buffer | A=byte | Via vector `$032A` |
+| `$FFE7` | 65511 | **CLALL** | Close all files | — | — | — | Resets open-file index; restores I/O |
+| `$FFEA` | 65514 | **UDTIM** | Jiffy clock tick; STOP key scan | — | IRQ calls every 1/60 s | `$00A0–$00A2`++ | Part of standard IRQ |
+| `$FFED` | 65517 | **SCREEN** | Return screen size | — | — | X=cols(40), Y=rows(25) | For cross‑platform compatibility |
+| `$FFF0` | 65520 | **PLOT** | Read/Set cursor | C=1 read; C=0 set; Y=row, X=col | — | On read: X=col, Y=row | Uses PNTR `$00D3`/TBLX `$00D6` |
+| `$FFF3` | 65523 | **IOBASE** | Return I/O base address | — | — | X=lo, Y=hi | Present value `$DC00` (CIA1) |

package/data/assembly/assembly-spec.md

@@ -0,0 +1,196 @@
+# Language
+
+## Overview
+
+MOS 6510 (C64 CPU) is a NMOS 6502 core with an 8‑bit data path and a 16‑bit address space (64 KiB). Registers: `A`, `X`, `Y` (8‑bit), `PC` (16‑bit), `SP` (8‑bit, stack at `$0100..$01FF`), `P` status `[N V - B D I Z C]`. The stack grows downward; pushes write to `$0100+SP` then decrement `SP`.
+
+## Lexical Conventions
+
+- **Numbers:** decimal `42`, hexadecimal `$2A`, binary `%00101010`. Immediate prefix `#`.
+- **Identifiers:** `[A–Z_][A–Z0–9_]*` (case‑insensitive).  
+- **Labels:** an identifier followed by `:` defines the current address. Reference with the bare identifier (optionally signed offsets in expressions).
+- **Comments:** `;` to end of line. Whitespace is insignificant except as separator.
+- **Expressions:** integers with `+ - * / & | ^ ~ << >>` and parentheses (assembler‑dependent), may refer to labels and the current location counter `*`.
+
+## Addressing Modes (names and syntax)
+
+| Abbrev | Name | Operand Syntax | Example |
+|---|---|---|---|
+| `A` | Accumulator | `A` or omitted | `ASL A` / `ASL` |
+| `#` | Immediate | `#byte` | `LDA #$0F` |
+| `ZP` | Zeropage | `$LL` | `LDA $00` |
+| `ZPX` | Zeropage,X | `$LL,X` | `LDA $10,X` |
+| `ZPY` | Zeropage,Y | `$LL,Y` | `LDX $10,Y` |
+| `ABS` | Absolute | `$HHLL` | `LDA $C000` |
+| `ABSX` | Absolute,X | `$HHLL,X` | `LDA $D000,X` |
+| `ABSY` | Absolute,Y | `$HHLL,Y` | `LDA $D000,Y` |
+| `IND` | Indirect | `($HHLL)` | `JMP ($FFFC)` |
+| `IZX` | (ZP,X) | `($LL,X)` | `LDA ($40,X)` |
+| `IZY` | (ZP),Y | `($LL),Y` | `LDA ($40),Y` |
+| `REL` | Relative | label | `BEQ done` |
+| `IMP` | Implied | — | `CLC` |
+
+*6510 `JMP (addr)` has the classic page‑wrap bug at `$xxFF → $xx00`.*
+
+## Labels and Symbol Rules
+
+- **Definition:** `label:` binds `label` to the current address (`*`). Multiple labels may precede an instruction.
+- **Use:** Any place an absolute/relative/address expression is expected (`LDA label`, `BEQ loop`).
+- **Forward refs:** allowed; assembler resolves in a second pass.
+- **Constants:** `name = expr` or `.equ name, expr` (assembler‑specific). Location counter may be set with `.org expr`. Data directives: `.byte`, `.word`, `.fill`, `.align` (names may vary).
+
+## Instruction Semantics (brief)
+
+- **Load/Store:** `LDA/LDX/LDY` load; `STA/STX/STY` store. Affect `N,Z` (stores don’t).
+- **ALU:** `ADC/SBC` (use `CLC`/`SEC` before add/sub), `AND/ORA/EOR`, `INC/DEC` (memory), `INX/INY/DEX/DEY` (registers). Flags as per 6502.
+- **Shifts/Rotates:** `ASL/LSR/ROL/ROR` on `A` or memory. Shifted‑out bit enters `C`.
+- **Compare:** `CMP/CPX/CPY` set `C` for ≥, `Z` for =, `N` for sign of result (no writeback).
+- **Branch:** `BPL/BMI/BVC/BVS/BCC/BCS/BNE/BEQ` use signed 8‑bit `REL` offset (−128..+127 from `PC+2`). Taken branch +1 cycle; +1 more if page crosses.
+- **Jumps/Calls:** `JMP` `ABS|IND`, `JSR ABS`, `RTS`, `BRK`/`RTI`.
+- **Stack/Flags/Xfer:** `PHA/PLA`, `PHP/PLP`, `TAX/TAY/TXA/TYA`, `TSX/TXS`, `CLC/SEC/CLI/SEI/CLD/SED/CLV`, `NOP`.
+- **Decimal mode:** C64 typically keeps `D=0` (`CLD`). Use BCD only if intentional.
+
+## EBNF (assembly source)
+
+```
+program     = { line } ;
+line        = [ label ] , [ instruction | directive ] , [ comment ] , EOL ;
+label       = identifier , ":" ;
+instruction = mnemonic , [ operand ] ;
+directive   = "." , ident , [ operandlist ] ;
+
+operand     = expr
+            | "#" , byte
+            | "(" , expr , ")"                          (* IND for JMP *)
+            | "(" , zp , "," , "X" , ")"                (* IZX *)
+            | "(" , zp , ")" , "," , "Y"                (* IZY *)
+            | expr , "," , "X"                          (* ABSX or ZPX *)
+            | expr , "," , "Y"                          (* ABSY or ZPY *)
+            ;
+operandlist = expr , { "," , expr } ;
+
+expr        = term , { ("+"|"-"|"|"|"^") , term } ;
+term        = factor , { ("*"|"/"|"&") , factor } ;
+factor      = ["+"|"-"|"~"] , primary ;
+primary     = number | identifier | "(" , expr , ")" | "*" ;
+
+mnemonic    = "ADC"|"AND"|"ASL"|"BCC"|"BCS"|"BEQ"|"BIT"|"BMI"|"BNE"|"BPL"|
+              "BRK"|"BVC"|"BVS"|"CLC"|"CLD"|"CLI"|"CLV"|"CMP"|"CPX"|"CPY"|
+              "DEC"|"DEX"|"DEY"|"EOR"|"INC"|"INX"|"INY"|"JMP"|"JSR"|"LDA"|
+              "LDX"|"LDY"|"LSR"|"NOP"|"ORA"|"PHA"|"PHP"|"PLA"|"PLP"|"ROL"|
+              "ROR"|"RTI"|"RTS"|"SBC"|"SEC"|"SED"|"SEI"|"STA"|"STX"|"STY"|
+              "TAX"|"TAY"|"TSX"|"TXA"|"TXS"|"TYA" ;
+
+identifier  = ( "A".."Z" | "_" ) , { "A".."Z" | "0".."9" | "_" } ;
+number      = dec | "$" hex | "%" bin ;
+dec         = "0".."9" , { "0".."9" } ;
+hex         = hexDigit , { hexDigit } ;
+bin         = "0"|"1" , { "0"|"1" } ;
+hexDigit    = "0".."9" | "A".."F" ;
+byte        = number ;      (* assembler validates range *)
+zp          = number ;      (* assembler may restrict to 0..255 for ZP *)
+comment     = ";" , { any-not-EOL } ;
+EOL         = "\n" ;
+```
+
+---
+
+## Tokenization
+
+### Addressing‑Mode Profiles (bytes/cycles)
+
+Unless noted, page cross on `ABSX/ABSY/IZY` adds **+1** cycle.
+
+| Group | Mode → bytes/cycles | Notes |
+|---|---|---|
+| **ALU (ADC,AND,CMP,EOR,LDA,ORA,SBC)** | `#` 2/2 · `ZP` 2/3 · `ZPX` 2/4 · `ABS` 3/4 · `ABSX` 3/4+ · `ABSY` 3/4+ · `IZX` 2/6 · `IZY` 2/5+ | CMP shares counts; LDA as listed. |
+| **STA** | `ZP` 2/3 · `ZPX` 2/4 · `ABS` 3/4 · `ABSX` 3/5 · `ABSY` 3/5 · `IZX` 2/6 · `IZY` 2/6 | Store does **not** set `N,Z`. |
+| **STX** | `ZP` 2/3 · `ZPY` 2/4 · `ABS` 3/4 | |
+| **STY** | `ZP` 2/3 · `ZPX` 2/4 · `ABS` 3/4 | |
+| **LDX** | `#` 2/2 · `ZP` 2/3 · `ZPY` 2/4 · `ABS` 3/4 · `ABSY` 3/4+ | |
+| **LDY** | `#` 2/2 · `ZP` 2/3 · `ZPX` 2/4 · `ABS` 3/4 · `ABSX` 3/4+ | |
+| **INC/DEC (mem)** | `ZP` 2/5 · `ZPX` 2/6 · `ABS` 3/6 · `ABSX` 3/7 | |
+| **INX/INY/DEX/DEY** | `IMP` 1/2 | |
+| **ASL/LSR/ROL/ROR** | `A` 1/2 · `ZP` 2/5 · `ZPX` 2/6 · `ABS` 3/6 · `ABSX` 3/7 | |
+| **BIT** | `ZP` 2/3 · `ABS` 3/4 | On 6510 only ZP/ABS. |
+| **JMP** | `ABS` 3/3 · `IND` 3/5 | Buggy wrap on `IND`. |
+| **JSR/RTS/RTI/BRK** | `JSR ABS` 3/6 · `RTS` 1/6 · `RTI` 1/6 · `BRK` 1/7 | |
+| **Branches (Bcc)** | `REL` 2/2(+1 taken, +1 xpage) | |
+| **Flag ops** | `IMP` 1/2 | `CLC,CLD,CLI,CLV,SEC,SED,SEI` |
+| **Stack ops** | `PHA,PHP` 1/3 · `PLA,PLP` 1/4 | |
+| **Transfers** | `TAX,TAY,TXA,TYA,TSX,TXS` 1/2 | |
+| **NOP** | `IMP` 1/2 | Documented form only. |
+
+### Opcode × Addressing‑Mode Matrix (✓ = supported on 6510)
+
+Modes (columns): `A  #  ZP ZPX ZPY ABS ABSX ABSY IND IZX IZY REL IMP`
+
+| Mnemonic |A|#|ZP|ZPX|ZPY|ABS|ABSX|ABSY|IND|IZX|IZY|REL|IMP|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| ADC | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| AND | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| ASL |✓| |✓|✓| |✓|✓| | | | | | |
+| BCC | | | | | | | | | | | |✓| |
+| BCS | | | | | | | | | | | |✓| |
+| BEQ | | | | | | | | | | | |✓| |
+| BIT | | |✓| | |✓| | | | | | | |
+| BMI | | | | | | | | | | | |✓| |
+| BNE | | | | | | | | | | | |✓| |
+| BPL | | | | | | | | | | | |✓| |
+| BRK | | | | | | | | | | | | |✓|
+| BVC | | | | | | | | | | | |✓| |
+| BVS | | | | | | | | | | | |✓| |
+| CLC | | | | | | | | | | | | |✓|
+| CLD | | | | | | | | | | | | |✓|
+| CLI | | | | | | | | | | | | |✓|
+| CLV | | | | | | | | | | | | |✓|
+| CMP | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| CPX | |✓|✓| | |✓| | | | | | | |
+| CPY | |✓|✓| | |✓| | | | | | | |
+| DEC | | |✓|✓| |✓|✓| | | | | | |
+| DEX | | | | | | | | | | | | |✓|
+| DEY | | | | | | | | | | | | |✓|
+| EOR | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| INC | | |✓|✓| |✓|✓| | | | | | |
+| INX | | | | | | | | | | | | |✓|
+| INY | | | | | | | | | | | | |✓|
+| JMP | | | | | |✓| |✓|✓| | | | |
+| JSR | | | | | |✓| | | | | | | |
+| LDA | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| LDX | |✓|✓| |✓|✓| |✓| | | | | |
+| LDY | |✓|✓|✓| |✓|✓| | | | | | |
+| LSR |✓| |✓|✓| |✓|✓| | | | | | |
+| NOP | | | | | | | | | | | | |✓|
+| ORA | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| PHA | | | | | | | | | | | | |✓|
+| PHP | | | | | | | | | | | | |✓|
+| PLA | | | | | | | | | | | | |✓|
+| PLP | | | | | | | | | | | | |✓|
+| ROL |✓| |✓|✓| |✓|✓| | | | | | |
+| ROR |✓| |✓|✓| |✓|✓| | | | | | |
+| RTI | | | | | | | | | | | | |✓|
+| RTS | | | | | | | | | | | | |✓|
+| SBC | |✓|✓|✓| |✓|✓|✓| |✓|✓| | |
+| SEC | | | | | | | | | | | | |✓|
+| SED | | | | | | | | | | | | |✓|
+| SEI | | | | | | | | | | | | |✓|
+| STA | | |✓|✓| |✓|✓|✓| |✓|✓| | |
+| STX | | |✓| |✓|✓| | | | | | | |
+| STY | | |✓|✓| |✓| | | | | | | |
+| TAX | | | | | | | | | | | | |✓|
+| TAY | | | | | | | | | | | | |✓|
+| TSX | | | | | | | | | | | | |✓|
+| TXA | | | | | | | | | | | | |✓|
+| TXS | | | | | | | | | | | | |✓|
+| TYA | | | | | | | | | | | | |✓|
+
+### Vector Entry Points (C64)
+
+- NMI `$FFFA/B`, RESET `$FFFC/D`, IRQ/BRK `$FFFE/F`. After RESET, execution starts at vector `$FFFC` (KERNAL init).
+
+### Minimal Directives (common)
+
+- Location: `.org addr` / `* = addr`  
+- Data: `.byte expr[,…]`, `.word expr[,…]`  
+- Symbols: `name = expr` / `.equ name, expr`  
+- Alignment/fill (assembler‑specific): `.align n`, `.fill count, value`

package/data/assembly/examples/effects/sinewave.asm

@@ -0,0 +1,5 @@
+        *= $0801
+        LDA #$00
+LOOP    STA $D020
+        ADC #$01
+        JMP LOOP

package/data/assembly/examples/graphics/sprite/mover.asm

@@ -0,0 +1,15 @@
+        *= $0801
+        SEI
+        LDA #$01
+        STA $D015          ; enable sprite 0
+        LDA #$00
+        STA $D001          ; sprite 0 Y
+        LDA #$18
+        STA $D000          ; sprite 0 X
+LOOP    INC $D000          ; move right
+        LDA $D000
+        CMP #$F0
+        BNE LOOP
+        LDA #$18
+        STA $D000
+        JMP LOOP

package/data/assembly/examples/sid-file-structure.md

@@ -0,0 +1,8 @@
+# SID File Structure Reference (for RAG)
+
+See `data/audio/sid-file-structure.md` for the complete explanation of PSID/RSID headers, fields, and playback behavior. This stub ensures the RAG index includes this topic and can surface it when generating or playing songs.
+
+- Magic: `PSID` or `RSID`
+- Key fields: version, dataOffset, loadAddress, initAddress, playAddress, songs, startSong, speed
+- v2–v4 extras: flags (PAL/NTSC, 6581/8580), startPage/pageLength, second/third SID base
+- Song length lookup: HVSC `Songlengths.md5` by MD5 of full file

package/data/assembly/examples/sid-overview.md

@@ -0,0 +1,11 @@
+# SID Quick Reference (for RAG)
+
+See `data/audio/sid-spec.md` for the full guide. This stub ensures the RAG index includes SID guidance.
+
+- Base address: $D400
+- Voice control: $D404/$D40B/$D412 (bits: NOISE PULSE SAW TRI TEST RING SYNC GATE)
+- Play note: set FREQ LO/HI, PW LO/HI, AD, SR; set CTRL with waveform|GATE
+- Stop note: clear GATE bit in CTRL
+- Volume/filter: $D418 (bits 0..3 volume, 4..6 LP/BP/HP)
+- Filter cutoff: $D415/$D416 (11 bits)
+- Useful effects: arpeggio (rewrite FREQ), vibrato (modulate FREQ), PWM (modulate PW), filter sweeps ($D415/$D416)

package/data/audio/sid-file-structure.md

@@ -0,0 +1,91 @@
+# SID File Structure (PSID/RSID) — Concise Overview
+
+This guide summarizes the High Voltage SID Collection (HVSC) "PSID file format" header used by classic SID tunes. A SID file consists of:
+
+- A header containing metadata and playback parameters
+- The actual 6502 machine code and data that the player runs on the C64
+
+You can play a SID file on a connected device using the REST API via the MCP tool `sidplay_file`.
+
+## Quick start: play a SID via REST/MCP
+
+- Endpoint: `POST /tools/sidplay_file`
+- Body: `{ "path": "/flash/music/Example.sid", "songnr": 1 }` (optional `songnr`)
+
+Refer to `doc/rest/c64-rest-api.md` for the underlying device endpoint and options.
+
+## Header layout (common fields)
+
+Offsets are from the start of the file. All multi-byte fields are big-endian.
+
+- +00 — magic (4 bytes): ASCII `PSID` or `RSID`
+  - `PSID`: C64-compatible files (player-friendly subset); `RSID`: more strict C64 requirements (no BASIC SYS stubs, tighter hardware expectations)
+- +04 — version (uint16): 1..4
+  - Higher versions extend the header with more fields (see below)
+- +06 — dataOffset (uint16): byte offset where the code/data block begins
+  - Typically static per version; points to the start of the machine code region
+- +08 — loadAddress (uint16): target RAM address for the data block
+  - If 0, the first two bytes of the data block contain the load address
+- +0A — initAddress (uint16): address to call once at start
+  - Accumulator selects the sub-song number when calling init
+  - If 0, use `loadAddress` as the init routine address
+- +0C — playAddress (uint16): address to call repeatedly to advance playback
+  - Usually invoked by the IRQ handler at 50/60 Hz
+  - If 0, the code is expected to install its own ISR during init
+- +0E — songs (uint16): number of available sub-songs (>= 1)
+- +10 — startSong (uint16): default sub-song to start with (1-based)
+- +12 — speed (uint32): per-song timing bits (bit i = song i)
+  - Bit = 0: use vertical blank (VIC raster; PAL/NTSC rate)
+  - Bit = 1: use CIA1 timer-driven playback (~60 Hz)
+
+For version 1, the header ends here and the data begins at `+76` (decimal) unless `dataOffset` states otherwise.
+
+## Extended header (versions 2–4)
+
+These versions append more detail for environment and chip configuration.
+
+- +76 — flags (uint32): bitfield
+  - b0: 0 = built-in player, 1 = Compute! player
+  - b1: 0 = C64-compatible PSID, 1 = PlaySID-specific/C64 BASIC
+  - b2–b3 (video): `01`=PAL, `10`=NTSC, `11`=Both, `00`=Unknown
+  - b4–b5 (primary SID model): `00`=unknown, `01`=6581, `10`=8580, `11`=both
+  - b6–b7 (second SID model): same encoding (v3+)
+  - b8–b9 (third SID model): same encoding (v4)
+  - Remaining bits reserved (set to 0)
+- +78 — startPage (uint8): high byte of a free memory page for a music driver; `0` means free outside data block, `0xFF` means none
+- +79 — pageLength (uint8): number of contiguous pages available starting at `startPage`
+- +7A — secondSIDAddress (uint8): `0x2x` → second SID at `$D2x0`, etc. (v3+)
+- +7B — thirdSIDAddress (uint8): third SID address like above (v4)
+- +7C — data start (beginning of machine code and data)
+
+Notes:
+
+- Version number loosely correlates with multi-SID usage: v2 single-SID, v3 dual-SID, v4 triple-SID.
+- PAL vs NTSC differences and SID model (6581/8580) materially affect sound; consult `flags`.
+
+## Timing and interrupts
+
+- `speed` determines whether playback uses VBlank (VIC raster IRQ) or CIA1 timer.
+- In RSID, VIC raster is generally not to be assumed; rely on the player-installed timing per header hints.
+
+## Song length database (Songlengths.md5)
+
+SID files do not embed duration. HVSC ships a `Songlengths.md5` database mapping each file’s MD5 to a track length:
+
+- Format: INI-like: a header line `[database]`, then repeated groups of a commented filename line (starts with `;`) and a line with `MD5 = mm:ss[.ms]`.
+- To obtain a length: compute MD5 of the full SID file (header + data), look up the matching entry, parse minutes/seconds (and optional milliseconds).
+
+## Practical playback flow
+
+1) Read header (verify `PSID`/`RSID`).
+2) Resolve `dataOffset` and `loadAddress`; if `loadAddress=0`, fetch it from first two data bytes.
+3) Load data to RAM and call `initAddress` (or `loadAddress` if `initAddress=0`), passing the desired sub-song in `A`.
+4) Repeatedly call `playAddress` (or let the player’s ISR drive it) at the cadence implied by `speed`.
+5) Select sub-songs via re-invoking `init` with accumulator set to song number.
+
+## Related API and tools
+
+- Play from device filesystem: `sidplay_file` (see generated `mcp-manifest.json` and `src/index.ts`)
+- Low-level SID register programming: see `data/audio/sid-spec.md`
+
+References for further reading: HVSC PSID v2NG file format (spec), community resources, and project notes from implementations like SIDman.