c64bridge 0.5.0

package/data/basic/basic-spec.md

@@ -0,0 +1,230 @@
+# C64 BASIC V2 Specification
+
+## Language
+
+### Overview
+
+C64 BASIC V2 is an interpreted language with line-numbered statements, tokenised keywords, and a limited variable model. Execution flows linearly unless redirected by control statements.
+
+### Variable Types
+
+| Type | Suffix | Range | Storage | Notes |
+|------|---------|--------|----------|-------|
+| **Real (Float)** | none | ±2.9×10⁻³⁸ … ±1.7×10³⁸ | 5 bytes (1 exp, 4 mantissa) | Default type. |
+| **Integer** | `%` | −32768 … 32767 | 2 bytes | Converted from float on assignment, slower. |
+| **String** | `$` | 0–255 chars | 3-byte descriptor | Holds PETSCII text. |
+
+Booleans are represented numerically: `FALSE=0`, `TRUE=−1` or any non-zero value.
+
+### Variable Naming
+
+- Only the **first two letters** of a name are significant (`CO`, `COCOS` → same variable).  
+- Type suffix (`%`, `$`) distinguishes otherwise identical names.  
+- Allowed: `A–Z`, `0–9`; must start with a letter.  
+- Keywords and system variables (`ST`, `TI`, `TI$`, `FN`) are reserved.  
+- Maximum logical name length ≈80 characters.
+
+### Arrays
+
+Declared via `DIM`, e.g. `DIM A(7)` (indices 0–7). Multi-dimensional arrays are supported (`DIM B$(4,5)`).
+
+### Operators and Precedence
+
+| Rank | Operators | Description |
+|------|------------|-------------|
+| 1 | `^` | Exponentiation |
+| 2 | unary `+` `-` | Sign |
+| 3 | `*` `/` | Multiplication, Division |
+| 4 | `+` `-` | Addition, Subtraction, String concat |
+| 5 | `<` `<=` `=` `>=` `>` `<>` | Comparison |
+| 6 | `NOT` | Logical NOT |
+| 7 | `AND` | Logical AND |
+| 8 | `OR` | Logical OR |
+
+Parentheses may nest up to 10 levels. Logical operators can also perform bitwise operations on 16‑bit integers.
+
+### Syntax Definition (EBNF)
+
+```
+program      = { line }, endmarker ;
+line         = nextptr word , lineno word , stmtlist , 0x00 ;
+stmtlist     = statement , { ":" , statement } ;
+
+statement =
+    "REM" , { <any PETSCII except CR> } |
+    "FOR" , var , "=" , expr , "TO" , expr , [ "STEP" , expr ] |
+    "NEXT" , [ var ] |
+    "IF" , expr , "THEN" , ( stmtlist | lineno ) |
+    ( "GOTO" | "GO" , "TO" ) , lineno |
+    "GOSUB" , lineno | "RETURN" |
+    "ON" , expr , ( "GOTO" | "GOSUB" ) , lineno , { "," , lineno } |
+    "DEF" , "FN" , fnname , "(" , var , ")" , "=" , expr |
+    "INPUT" , [ prompt ] , varlist | "GET" , var | "PRINT" , [ printlist ] |
+    "OPEN" , expr , "," , expr , [ "," , expr , [ "," , fnameMode ] ] |
+    "CLOSE" , expr | "CMD" , expr , [ "," , exprlist ] |
+    "LOAD" , fname [ "," , dev [ "," , secdev ] ] |
+    "SAVE" , fname [ "," , dev [ "," , secdev ] ] |
+    "VERIFY" , fname [ "," , dev [ "," , secdev ] ] |
+    "READ" , varlist | "RESTORE" | "DATA" , datalist |
+    "POKE" , expr , "," , expr | "PEEK" , "(" , expr , ")" |
+    "WAIT" , expr , "," , expr , [ "," , expr ] |
+    "SYS" , expr , { "," , expr } | var , "=" , expr |
+    "USR" , "(" , expr , ")" |
+    "RUN" , [ lineno ] | "STOP" | "END" | "CONT" |
+    "LIST" , [ listRange ] | "NEW" | "CLR" |
+    "FRE" , "(" , expr , ")" ;
+
+expr         = term , { "OR" , term } ;
+term         = factor , { "AND" , factor } ;
+factor       = [ "NOT" ] , relation ;
+relation     = sum , { ( "=" | "<" | ">" | "<=" | ">=" | "<>" ) , sum } ;
+sum          = product , { ( "+" | "-" ) , product } ;
+product      = power , { ( "*" | "/" ) , power } ;
+power        = unary , { "^" , unary } ;
+unary        = [ "+" | "-" ] , primary ;
+primary      = number | string | var | fncall | "(" , expr , ")" ;
+
+fncall       = ( "SGN" | "INT" | "ABS" | "USR" | "FRE" | "POS" | "SQR" | "RND" |
+                 "LOG" | "EXP" | "COS" | "SIN" | "TAN" | "ATN" | "PEEK" | "LEN" |
+                 "STR$" | "VAL" | "ASC" | "CHR$" | "LEFT$" | "RIGHT$" | "MID$" |
+                 "TAB" | "SPC" ), "(" , [ expr , { "," , expr } ] , ")" ;
+
+printlist    = [ expr | "#" , expr ] , { "," | ";" , [ expr | "#" , expr ] } ;
+varlist      = var , { "," , var } ;
+datalist     = datum , { "," , datum } ;
+datum        = number | string | expr ;
+
+fname        = string ; dev = expr ; secdev = expr ; fnameMode = string ;
+lineno       = 0..65535 ;
+var          = name [ "%" | "$" ] ; fnname = "FN" , name ;
+name         = letter , { letter | digit } ;
+prompt       = string , ";" ;
+listRange    = lineno | "-" , lineno | lineno , "-" ;
+number       = integer | float ; string = quoted PETSCII ;
+```
+
+### Commands and Functions
+
+- **Flow:** `FOR…TO…[STEP…]…NEXT [var]`, `IF expr THEN (stmts|line)`, `GOTO`, `GO TO`, `GOSUB`, `RETURN`, `ON expr GOTO/GOSUB`, `DEF FN name(x)=expr`  
+- **I/O:** `GET var$`, `INPUT ["prompt";] var[,var…]`, `PRINT [items]`, `SPC(n)`, `TAB(n)`, `POS(dummy)`  
+- **Files:** `LOAD`, `SAVE`, `VERIFY`, `OPEN`, `CLOSE`, `GET#`, `INPUT#`, `PRINT#`, `CMD`, `ST`  
+- **DATA:** `DATA`, `READ`, `RESTORE`  
+- **Math/Logic:** `+ - * / ^`, comparisons, `AND OR NOT`; `SGN INT ABS RND SQR LOG EXP SIN COS TAN ATN`  
+- **Strings:** `+` (concat), `LEN LEFT$ RIGHT$ MID$ STR$ VAL ASC CHR$`  
+- **Memory:** `PEEK(addr)`, `POKE addr,val`, `WAIT addr,mask[,invert]`  
+- **System:** `SYS addr[,p…]`, `USR(expr)` (fixed $0310)  
+- **Execution:** `RUN [line]`, `STOP`, `END`, `CONT`  
+- **Misc:** `REM`, `LIST`, `NEW`, `CLR`, `FRE(0)`, constants `π`, timers `TI`, `TI$`
+
+---
+
+## Tokenization
+
+### Encoding Rules
+
+- Keywords occupy **$80–$CB**; single‑byte tokens replace text during encoding.  
+- Tokenisation **skips inside** strings (`"..."`) and remarks (`REM`).  
+- Matching is **greedy**, **case‑insensitive**; e.g. `PRINT#` before `PRINT`.  
+- If a line becomes empty, insert a single space (`$20`).  
+- Characters are written as **PETSCII**, with identifiers uppercased; strings/comments unchanged.
+
+### Keyword Table
+
+| Hex | Keyword | Notes |
+|------|----------|-------|
+| 80 | END | |
+| 81 | FOR | |
+| 82 | NEXT | |
+| 83 | DATA | |
+| 84 | INPUT# | |
+| 85 | INPUT | |
+| 86 | DIM | |
+| 87 | READ | |
+| 88 | LET | Optional |
+| 89 | GOTO | |
+| 8A | RUN | |
+| 8B | IF | |
+| 8C | RESTORE | |
+| 8D | GOSUB | |
+| 8E | RETURN | |
+| 8F | REM | De-tokenises remainder |
+| 90 | STOP | |
+| 91 | ON | |
+| 92 | WAIT | |
+| 93 | LOAD | |
+| 94 | SAVE | |
+| 95 | VERIFY | |
+| 96 | DEF | |
+| 97 | POKE | |
+| 98 | PRINT# | |
+| 99 | PRINT | |
+| 9A | CONT | |
+| 9B | LIST | |
+| 9C | CLR | |
+| 9D | CMD | |
+| 9E | SYS | |
+| 9F | OPEN | |
+| A0 | CLOSE | |
+| A1 | GET | |
+| A2 | NEW | |
+| A3 | TAB( | |
+| A4 | TO | |
+| A5 | FN | |
+| A6 | SPC( | |
+| A7 | THEN | |
+| A8 | NOT | |
+| A9 | STEP | |
+| AA | + | |
+| AB | - | |
+| AC | * | |
+| AD | / | |
+| AE | ^ | |
+| AF | AND | |
+| B0 | OR | |
+| B1 | > | |
+| B2 | = | |
+| B3 | < | |
+| B4 | SGN | |
+| B5 | INT | |
+| B6 | ABS | |
+| B7 | USR | |
+| B8 | FRE | |
+| B9 | POS | |
+| BA | SQR | |
+| BB | RND | |
+| BC | LOG | |
+| BD | EXP | |
+| BE | COS | |
+| BF | SIN | |
+| C0 | TAN | |
+| C1 | ATN | |
+| C2 | PEEK | |
+| C3 | LEN | |
+| C4 | STR$ | |
+| C5 | VAL | |
+| C6 | ASC | |
+| C7 | CHR$ | |
+| C8 | LEFT$ | |
+| C9 | RIGHT$ | |
+| CA | MID$ | |
+| CB | GO | For GO TO / GO SUB |
+
+### PRG Layout
+
+Each BASIC program is stored as a contiguous memory block starting at `$0801`:
+
+1. **Load address** `$0801` (little‑endian).  
+2. Repeated **line records**:  
+   - Pointer to next line (absolute address, word LE)  
+   - Line number (word LE)  
+   - Tokenised bytes ending with `00`  
+3. Final **terminator word `0000`**.
+
+Pointers increase monotonically. The last line points to the terminator.
+
+### Validation Rules
+
+- Line numbers `0–65535` only.  
+- Final sentinel `0000` required.  
+- `ST` bits: 6 = EOF, 7 = Device not present.  
+- `RND(seed<0)` re‑initialises RNG; `RND(0)` continues sequence.

package/data/basic/examples/audio/alle-meine-entchen-expressive.bas

@@ -0,0 +1,41 @@
+10 REM ALLE MEINE ENTCHEN - MUSICAL PHRASING
+20 REM WITH PROPER EMPHASIS AND BREATHING
+30 REM USING TRIANGLE WAVE AND PROPER ADSR
+40 REM
+50 POKE 54296,15:REM VOLUME TO MAXIMUM
+60 POKE 54277,17:POKE 54278,240:REM FAST ATTACK, SLOW RELEASE
+70 REM
+80 PRINT "PLAYING ALLE MEINE ENTCHEN..."
+90 PRINT "WITH MUSICAL EXPRESSION!"
+100 REM
+110 REM ALLE MEINE ENTCHEN (C-D-E-F-G-G) - OPENING PHRASE
+120 POKE 54273,30:POKE 54274,0:POKE 54276,17:FOR I=1 TO 250:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+130 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+140 POKE 54273,38:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+150 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+160 POKE 54273,45:POKE 54274,0:POKE 54276,17:FOR I=1 TO 200:NEXT I:POKE 54276,16:FOR I=1 TO 50:NEXT I
+170 POKE 54273,45:POKE 54274,0:POKE 54276,17:FOR I=1 TO 400:NEXT I:POKE 54276,16:FOR I=1 TO 150:NEXT I
+180 REM
+190 REM SCHWIMMEN AUF DEM SEE (A-A-A-A-G) - FLOATING PHRASE
+200 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 160:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+210 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 160:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+220 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 160:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+230 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 160:NEXT I:POKE 54276,16:FOR I=1 TO 50:NEXT I
+240 POKE 54273,45:POKE 54274,0:POKE 54276,17:FOR I=1 TO 450:NEXT I:POKE 54276,16:FOR I=1 TO 200:NEXT I
+250 REM
+260 REM KOEPFCHEN IN DAS WASSER (F-F-F-F-E) - DIVING MOTION
+270 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 140:NEXT I:POKE 54276,16:FOR I=1 TO 25:NEXT I
+280 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 140:NEXT I:POKE 54276,16:FOR I=1 TO 25:NEXT I
+290 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 140:NEXT I:POKE 54276,16:FOR I=1 TO 25:NEXT I
+300 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 140:NEXT I:POKE 54276,16:FOR I=1 TO 50:NEXT I
+310 POKE 54273,38:POKE 54274,0:POKE 54276,17:FOR I=1 TO 350:NEXT I:POKE 54276,16:FOR I=1 TO 120:NEXT I
+320 REM
+330 REM SCHWAENZCHEN IN DIE HOEH (D-D-D-D-C) - TRIUMPHANT ENDING
+340 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+350 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+360 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 30:NEXT I
+370 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 200:NEXT I:POKE 54276,16:FOR I=1 TO 50:NEXT I
+380 POKE 54273,30:POKE 54274,0:POKE 54276,17:FOR I=1 TO 600:NEXT I:POKE 54276,16
+390 REM
+400 POKE 54276,0:PRINT "ALLE MEINE ENTCHEN COMPLETE!"
+410 PRINT "WITH MUSICAL EXPRESSION AND PHRASING!"

package/data/basic/examples/audio/c-major-scale-pleasant.bas

@@ -0,0 +1,29 @@
+10 REM PLEASANT C MAJOR SCALE
+20 REM USES TRIANGLE WAVE AND PROPER ADSR
+30 REM BASED ON REAL HARDWARE TESTING
+40 REM 
+50 POKE 54296,15:REM VOLUME TO MAXIMUM
+60 POKE 54277,17:POKE 54278,240:REM FAST ATTACK, SLOW RELEASE
+70 REM
+80 REM LOWER C MAJOR SCALE WITH TRIANGLE WAVE
+90 PRINT "PLAYING C MAJOR SCALE..."
+100 REM
+110 REM C (30)
+120 POKE 54273,30:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+130 REM D (34)  
+140 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+150 REM E (38)
+160 POKE 54273,38:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+170 REM F (40)
+180 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+190 REM G (45)
+200 POKE 54273,45:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+210 REM A (51)
+220 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+230 REM B (57)
+240 POKE 54273,57:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+250 REM C (60)
+260 POKE 54273,60:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16
+270 REM
+280 POKE 54276,0:PRINT "SMOOTH SCALE COMPLETE"
+290 PRINT "SID REGISTERS CLEARED"

package/data/basic/examples/io/joystick.bas

@@ -0,0 +1,5 @@
+10 PRINT "READING JOYSTICK PORT 2"
+20 J=PEEK(56320)
+30 PRINT "PORT2:";J
+40 FOR T=1 TO 200:NEXT
+50 GOTO 20

package/data/basic/examples/video/bounce.bas

@@ -0,0 +1,8 @@
+10 POKE 53280,0:POKE 53281,0
+20 X=10:DX=1
+30 PRINT CHR$(147)
+40 PRINT TAB(X);"O"
+50 X=X+DX
+60 IF X=1 OR X=38 THEN DX=-DX
+70 FOR T=1 TO 50:NEXT
+80 GOTO 30

package/data/basic/examples/video/entchen-petscii.bas

@@ -0,0 +1,16 @@
+10 REM ENTCHEN PETSCII SCENE
+20 POKE 53280,6:POKE 53281,14:REM BLUE BORDER, LIGHT BLUE BACKGROUND
+30 POKE 646,7:PRINT CHR$(147);CHR$(14):REM CLEAR SCREEN, SET YELLOW, LOWERCASE MODE
+40 PRINT "        ~~~~~     ~~~~     ~~~~"
+50 PRINT "    ~~~~    ~~~~~     ~~~~     ~~~~"
+60 PRINT "         __           __"
+70 PRINT " ___<( o)___   ___(o )>___"
+80 PRINT "   (     )       (     )"
+90 PRINT "    (_____)     (_____ )"
+100 PRINT "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
+110 POKE 646,1:PRINT
+120 PRINT "ALLE MEINE ENTCHEN"
+130 PRINT "SCHWIMMEN AUF DEM SEE"
+140 PRINT "KOPFCHEN IN DAS WASSER"
+150 PRINT "SCHWANZCHEN IN DIE HOH'"
+160 END

package/data/basic/examples/video/hello-world.bas

@@ -0,0 +1,4 @@
+10 PRINT "HELLO WORLD!"
+20 PRINT "WELCOME TO C64 PROGRAMMING"
+30 PRINT "FROM THE YEAR 2025!"
+40 END

package/data/basic/examples/video/wave.bas

@@ -0,0 +1,7 @@
+10 POKE 53280,0:POKE 53281,0
+20 PRINT CHR$(147)
+30 FOR X=0 TO 39
+40 Y=10+INT(8*SIN(X/6))
+50 PRINT TAB(X);TAB(Y);"*"
+60 NEXT X
+70 GOTO 30

package/data/context/bootstrap.md

@@ -0,0 +1,148 @@
+# C64 Knowledge Bootstrap
+
+High-level overview for C64 development. For more details, see linked spec documents.
+
+## Device & Services
+
+- MCP server controls Ultimate 64/C64 via REST: upload/run BASIC or ASM, screen/memory I/O, drives, SID music, audio analysis, local RAG.
+- Key chips: VIC-II ($D000), SID ($D400), CIA1 ($DC00), CIA2 ($DD00).
+
+## Memory Map (default RAM layout)
+
+For Full details see `../memory/memory-map.md` with focus on low-memory (pages 0-3) in `../memory/low-memory-map.md` and  KERNAL memory in `../memory/kernal-memory-map.md`.
+
+- $0000–$00FF: Zero page
+- $0100–$01FF: Stack
+- $0200–$02FF: Workspace, vectors ($0314/$0315 IRQ, $0318/$0319 BRK)
+- $0400–$07E7: Screen RAM (text 40×25)
+- $0801–: BASIC program area (defaults)
+- $A000–$BFFF: BASIC ROM (banked; RAM when LORAM/HIRAM cleared)
+- $C000–$CFFF: RAM (common for ASM)
+- $D000–$DFFF: I/O area (VIC-II $D000–$D02E; SID $D400–$D418; Color RAM $D800–$DBE7; CIA1/2 $DC00/$DD00)
+- $E000–$FFFF: KERNAL ROM (banked)
+
+Bank control (6510 at $0001):
+
+- Bits: 0 LORAM, 1 HIRAM, 2 CHAREN. Typical full RAM: %0000_0011 → clear for RAM, set for ROM.
+
+## Video (VIC-II)
+
+The VIC-II chip handles graphics and sprites. Fore more information see `data/video/vic-spec.md`.
+
+- Sprites: X ($D000..$D00E even), Y ($D001..$D00F odd), X MSBs $D010.
+- Control: $D011 (bit 7: 25th row; bit 6: RST8; bit 5: bitmap on; bits 0–2: vertical scroll).
+- Raster line: $D012 (LSB), $D011 bit 7 forms MSB; raster IRQ: mask $D01A, status $D019, vector $0314/$0315.
+- Control 2/Multicolour: $D016 (bit 4: 38/40 cols; bit 5: multicolour; bits 0–2: horizontal scroll).
+- Memory pointers: $D018 (bits 1–3: screen base; bits 4–7: charset/bitmap base).
+- Sprite enable: $D015; expand X: $D01D; expand Y: $D017; priority: $D01B; multicolour: $D01C.
+- Colors: Border $D020; background 0–3 $D021–$D023; sprite multicolour $D025–$D026; sprite colours $D027–$D02E.
+- Collisions: sprite-sprite $D01E (read/clear by write); sprite-background $D01F.
+
+Video modes:
+
+- Text: $D011 bit 5=0; $D016 bit 5=0 (hi-res); charset and screen from $D018.
+- Bitmap: $D011 bit 5=1; hi-res (single colour per 8×8) or multicolour ($D016 bit 5=1).
+- Multicolour text/bitmap: wide pixels using $D022–$D024 and colour RAM.
+
+Bitmap setup (typical):
+
+- Screen map at $0400 ($D018 bits 1–3 = 1), bitmap at $2000 ($D018 bits 4–7 = 8).
+- Enable bitmap: set $D011 bit 5; optional multicolour: set $D016 bit 5.
+
+### PETSCII, Screen & Colors
+
+- Screen at $0400 (40×25); write screen codes. Colour RAM at $D800 (nybbles). Border $D020, background $D021.
+- To draw pixels: use bitmap mode and write to bitmap memory; control colours via attributes (screen/colour RAM in text, nybbles per cell in bitmap multicolour).
+
+### PETSCII String Pitfalls
+
+- PETSCII is not ASCII: characters such as the backslash map to control codes (e.g. `$1C` toggles reverse video in the default upper/graphics set). Switch to the lower/upper character set first (`CHR$(14)` or `POKE 53272,14`) or pick alternative glyphs if you need a literal `\` on screen.
+- Commodore BASIC does not interpret `\n` as a newline. When emitting multi-line art, either print each line separately or inject carriage returns explicitly with `CHR$(13)`.
+
+Example:
+
+```basic
+10 PRINT CHR$(147);CHR$(14);" /\\_/\\"
+20 PRINT " ( o.o )"
+30 PRINT "  > ^ <"
+40 PRINT CHR$(142)
+```
+
+## Raster IRQ Setup
+
+Use this to trigger code at a specific raster line, e.g. for split-screen effects, multiplexing sprites, or scrolling in the border without screen tear.
+
+1. Disable interrupts: `SEI`.
+2. Set raster line `$D012`, configure `$D011` bit 7 accordingly.
+3. Set IRQ vector `$0314/$0315` to handler.
+4. Enable IRQ in `$D01A` and global `CLI`.
+5. In handler: do work (e.g., change colours/sprites), then `LDA $D019`/`STA $D019` to clear and `RTI`.
+
+## Image & Sprites
+
+- Bitmap (hi-res): set `$D011` bit 5=1, `$D016` bit 5=0; point `$D018` to screen/bitmap; write bits into bitmap memory.
+- Multicolour bitmap: also set `$D016` bit 5=1; use `$D022–$D024` and colour RAM per cell.
+- Sprites: define 63-byte patterns; set sprite pointers at $07F8–$07FF; position with `$D000–$D00F`, enable with `$D015`.
+
+## Audio (SID)
+
+The SID chip handles audio synthesis. For more information see `data/audio/sid-spec.md`.
+
+Per voice (1..3; base offsets +0x07 per voice):
+
+- FREQ LO/HI: $D400/$D401, $D407/$D408, $D40E/$D40F.
+- PULSE LO/HI: $D402/$D403, $D409/$D40A, $D410/$D411.
+- CONTROL: $D404, $D40B, $D412 (bit 0 GATE; 1 SYNC; 2 RING; 3 TEST; 4 TRI; 5 SAW; 6 PULSE; 7 NOISE).
+- ADSR: $D405 (A hi-nibble, D lo-nibble), $D406 (S hi-nibble, R lo-nibble).
+
+Filter/Master:
+
+- Cutoff: $D415/$D416; resonance/voice routing: $D417; volume/filter mode: $D418 (low 4 bits volume 0–15; bits 4–7 filter + third-voice mute).
+
+Making sound (basic):
+
+1. Set frequency ($D400/01).
+2. Set pulse width ($D402/03) if pulse.
+3. Set ADSR ($D405/06).
+4. Set waveform + GATE in CONTROL ($D404).
+5. Set master volume at $D418.
+
+## BASIC
+
+Basic is used for simple programs and quick prototyping. It is very slow compared to assembly. For more information see `data/basic/basic-spec.md`.
+
+- Program: numbered lines; end with `END` or stop on last line.
+- Variables: A–Z (and arrays A()(numeric), A$() string); strings end with `$`.
+- Assignment: `LET A=expr` (LET optional) | `A$="TEXT"`.
+- I/O: `PRINT expr[,;expr...]` | `INPUT var` | `GET A$` | `OPEN ch,dev,sa,"name"` | `PRINT#ch,expr` | `CLOSE ch`.
+- Control: `IF expr THEN <stmt|line>` | `GOTO n` | `GOSUB n` | `RETURN` | `FOR v=start TO end STEP s: ... : NEXT v` | `ON x GOTO l1,...` | `ON x GOSUB l1,...`.
+- Data: `DATA v1,v2,...` | `READ var` | `RESTORE`.
+- System: `POKE addr,val` | `PEEK(addr)` | `SYS addr` | `RUN` | `STOP` | `NEW`.
+- Strings: `LEFT$(s,n)` `RIGHT$(s,n)` `MID$(s,p[,n])` `CHR$(n)` `ASC(s)` `LEN(s)`.
+- Math: `+ - * / ^` | `ABS` `INT` `SGN` `SQR` `SIN` `COS` `TAN` `ATN` `RND([n])` `FRE(0)` `TI$`.
+- Relational: `= <> < > <= >=` (boolean as -1/0).
+- Remarks: `REM text` (tokens ignored till end of line).
+- Example (print to printer device 4): `OPEN 4,4:PRINT#4,"HELLO":CLOSE 4`.
+
+## 6502/6510 Assembly
+
+Assembly is used for maximum performance and control. For more information see `data/asssembly/assembly-spec.md`.
+
+- Addressing modes: `#imm, zp, zp,X, zp,Y, abs, abs,X, abs,Y, (zp), (zp,X), (zp),Y, rel`.
+- Key opcodes (full set):
+  - Load/Store: `LDA LDX LDY` / `STA STX STY`.
+  - ALU: `ADC SBC AND ORA EOR ASL LSR ROL ROR`.
+  - Inc/Dec: `INC INX INY DEC DEX DEY`.
+  - Compare/Bit: `CMP CPX CPY BIT`.
+  - Branch: `BCC BCS BEQ BMI BNE BPL BVC BVS`.
+  - Jump/Call: `JMP JSR RTS RTI`.
+  - Status: `CLC SEC CLI SEI CLD SED CLV NOP`.
+  - Stack: `PHA PHP PLA PLP TAX TXA TAY TYA TSX TXS BRK`.
+- Directives (assembler used here): `.org/*=`, `.byte`, `.word`, `.text/.ascii`, `ds` (fill), labels `name:`.
+- Interrupts: set IRQ vector at $0314/$0315 to your routine; acknowledge VIC-II IRQ by writing back bit to $D019.
+- Example (border flash): write to `$D020` inside raster IRQ (`$D012`/`$D011`), mask `$D01A`, acknowledge `$D019`.
+
+## Context & RAG
+
+- Layers: `data/context/bootstrap.md` → `AGENTS.md` → `.github/prompts/*.prompt.md` → `data/context/chat.md` → RAG docs (`doc/**/*.md`, `data/**/*.md`).
+- Retrieval returns relevant chunks with provenance comments for transparency.

package/data/context/chat.md

@@ -0,0 +1,36 @@
+# Chat Policy
+
+Behavioral norms for assistants across personas.
+
+## Style
+
+- Be concise, technically precise, and skimmable.
+- Use code blocks only for relevant snippets; include provenance comments when injecting source-derived text.
+- Use backticks for file, directory, or function names; avoid bare URLs; prefer markdown links with descriptive text.
+
+## Temperature
+
+- Default low temperature; prioritize determinism and repeatability.
+- Escalate creativity slightly for SID composition and art prompts.
+
+## Safety & Device Handling
+
+- Warn before potentially disruptive actions (reset, poweroff, drive ops) unless the action is explicitly requested by the user or clearly implied by the requested task (for example, write and run a program).
+- Prefer dry runs where possible; confirm preconditions.
+- Avoid long-lived processes; commands must terminate.
+
+## Provenance & Transparency
+
+- When injecting templates or retrieved references, add comments like:
+  <!-- Source: .github/prompts/compose-song.prompt.md | Section: Compose Song -->
+  <!-- Source: data/audio/sid-spec.md -->
+- Summarize which layers were used (primer/agent/prompt/policy/RAG) if it helps troubleshooting.
+
+## Formatting
+
+- Use headings and bullet lists; keep responses short by default.
+- Embed short code; avoid over-formatting.
+
+## Refusal Policy
+
+- Refuse unsafe or destructive requests; suggest safe alternatives.