c64bridge 0.7.4 → 0.8.0

package/data/assembly/assembly-spec.md

@@ -1,4 +1,4 @@
-# Language
+# 6510 Assembly Language
 
 ## Overview
 
@@ -184,6 +184,295 @@ Modes (columns): `A  #  ZP ZPX ZPY ABS ABSX ABSY IND IZX IZY REL IMP`
 | TXS | | | | | | | | | | | | |✓|
 | TYA | | | | | | | | | | | | |✓|
 
+### Opcode Decode Table
+
+#### Scope
+
+- Table order is strictly ascending by opcode from `00` to `FF`.
+- `IMM` is the canonical mode token for **immediate** addressing.
+- Elsewhere in the spec, immediate operands may be written with `#`, e.g. `LDA #$01`.
+- `cycles` is the base cycle count.
+- `page_cross_penalty` is only populated where an extra cycle can occur due to page crossing or branch flow.
+- `KIL` does not complete normal execution; `cycles=halt`.
+
+#### Semantic Conventions
+
+- `M` = operand value after address resolution
+- `[EA]` = memory at effective address
+- `EA.hi` = high byte of effective address
+- `push(x)` / `pop` / `pop16` = stack operations
+- `set(...)` = update listed flags from result
+- `ROL(x)` / `ROR(x)` = rotate through carry
+- `rel` = signed relative branch displacement
+- Unofficial unstable opcodes are marked explicitly with `unstable;`
+
+#### Table Format
+
+```text
+opcode mnemonic mode flags cycles page_cross_penalty semantics
+```
+
+#### Table
+
+```text
+00 BRK IMP O 7 - interrupt; push(PC+2,P|B); I←1; PC←[FFFE]
+01 ORA IZX O 6 - A←A|M; set(Z,N)
+02 KIL IMP U,H halt - halt
+03 SLO IZX U 8 - M←M<<1; A←A|M; set(C,Z,N)
+04 NOP ZP U 3 - no-op
+05 ORA ZP O 3 - A←A|M; set(Z,N)
+06 ASL ZP O 5 - M←M<<1; set(C,Z,N)
+07 SLO ZP U 5 - M←M<<1; A←A|M; set(C,Z,N)
+08 PHP IMP O 3 - push(P|B)
+09 ORA IMM O 2 - A←A|M; set(Z,N)
+0A ASL A O 2 - A←A<<1; set(C,Z,N)
+0B ANC IMM U 2 - A←A&#; C←bit7(A); set(Z,N)
+0C NOP ABS U 4 - no-op
+0D ORA ABS O 4 - A←A|M; set(Z,N)
+0E ASL ABS O 6 - M←M<<1; set(C,Z,N)
+0F SLO ABS U 6 - M←M<<1; A←A|M; set(C,Z,N)
+10 BPL REL O 2 +1 if branch taken; +1 more if page-cross if N=0 then PC←PC+rel
+11 ORA IZY O 5 +1 if page-cross A←A|M; set(Z,N)
+12 KIL IMP U,H halt - halt
+13 SLO IZY U 8 - M←M<<1; A←A|M; set(C,Z,N)
+14 NOP ZPX U 4 - no-op
+15 ORA ZPX O 4 - A←A|M; set(Z,N)
+16 ASL ZPX O 6 - M←M<<1; set(C,Z,N)
+17 SLO ZPX U 6 - M←M<<1; A←A|M; set(C,Z,N)
+18 CLC IMP O 2 - C←0
+19 ORA ABSY O 4 +1 if page-cross A←A|M; set(Z,N)
+1A NOP IMP U 2 - no-op
+1B SLO ABSY U 7 - M←M<<1; A←A|M; set(C,Z,N)
+1C NOP ABSX U 4 +1 if page-cross no-op
+1D ORA ABSX O 4 +1 if page-cross A←A|M; set(Z,N)
+1E ASL ABSX O 7 - M←M<<1; set(C,Z,N)
+1F SLO ABSX U 7 - M←M<<1; A←A|M; set(C,Z,N)
+20 JSR ABS O 6 - push(PC-1); PC←EA
+21 AND IZX O 6 - A←A&M; set(Z,N)
+22 KIL IMP U,H halt - halt
+23 RLA IZX U 8 - M←ROL(M); A←A&M; set(C,Z,N)
+24 BIT ZP O 3 - Z←(A&M)=0; N←bit7(M); V←bit6(M)
+25 AND ZP O 3 - A←A&M; set(Z,N)
+26 ROL ZP O 5 - M←ROL(M); set(C,Z,N)
+27 RLA ZP U 5 - M←ROL(M); A←A&M; set(C,Z,N)
+28 PLP IMP O 4 - P←pop
+29 AND IMM O 2 - A←A&#; set(Z,N)
+2A ROL A O 2 - A←ROL(A); set(C,Z,N)
+2B ANC IMM U 2 - A←A&#; C←bit7(A); set(Z,N)
+2C BIT ABS O 4 - Z←(A&M)=0; N←bit7(M); V←bit6(M)
+2D AND ABS O 4 - A←A&M; set(Z,N)
+2E ROL ABS O 6 - M←ROL(M); set(C,Z,N)
+2F RLA ABS U 6 - M←ROL(M); A←A&M; set(C,Z,N)
+30 BMI REL O 2 +1 if branch taken; +1 more if page-cross if N=1 then PC←PC+rel
+31 AND IZY O 5 +1 if page-cross A←A&M; set(Z,N)
+32 KIL IMP U,H halt - halt
+33 RLA IZY U 8 - M←ROL(M); A←A&M; set(C,Z,N)
+34 NOP ZPX U 4 - no-op
+35 AND ZPX O 4 - A←A&M; set(Z,N)
+36 ROL ZPX O 6 - M←ROL(M); set(C,Z,N)
+37 RLA ZPX U 6 - M←ROL(M); A←A&M; set(C,Z,N)
+38 SEC IMP O 2 - C←1
+39 AND ABSY O 4 +1 if page-cross A←A&M; set(Z,N)
+3A NOP IMP U 2 - no-op
+3B RLA ABSY U 7 - M←ROL(M); A←A&M; set(C,Z,N)
+3C NOP ABSX U 4 +1 if page-cross no-op
+3D AND ABSX O 4 +1 if page-cross A←A&M; set(Z,N)
+3E ROL ABSX O 7 - M←ROL(M); set(C,Z,N)
+3F RLA ABSX U 7 - M←ROL(M); A←A&M; set(C,Z,N)
+40 RTI IMP O 6 - P←pop; PC←pop16
+41 EOR IZX O 6 - A←A^M; set(Z,N)
+42 KIL IMP U,H halt - halt
+43 SRE IZX U 8 - M←M>>1; A←A^M; set(C,Z,N)
+44 NOP ZP U 3 - no-op
+45 EOR ZP O 3 - A←A^M; set(Z,N)
+46 LSR ZP O 5 - M←M>>1; set(C,Z,N)
+47 SRE ZP U 5 - M←M>>1; A←A^M; set(C,Z,N)
+48 PHA IMP O 3 - push(A)
+49 EOR IMM O 2 - A←A^M; set(Z,N)
+4A LSR A O 2 - A←A>>1; set(C,Z,N)
+4B ALR IMM U 2 - A←(A&#)>>1; set(C,Z,N)
+4C JMP ABS O 3 - PC←EA
+4D EOR ABS O 4 - A←A^M; set(Z,N)
+4E LSR ABS O 6 - M←M>>1; set(C,Z,N)
+4F SRE ABS U 6 - M←M>>1; A←A^M; set(C,Z,N)
+50 BVC REL O 2 +1 if branch taken; +1 more if page-cross if V=0 then PC←PC+rel
+51 EOR IZY O 5 +1 if page-cross A←A^M; set(Z,N)
+52 KIL IMP U,H halt - halt
+53 SRE IZY U 8 - M←M>>1; A←A^M; set(C,Z,N)
+54 NOP ZPX U 4 - no-op
+55 EOR ZPX O 4 - A←A^M; set(Z,N)
+56 LSR ZPX O 6 - M←M>>1; set(C,Z,N)
+57 SRE ZPX U 6 - M←M>>1; A←A^M; set(C,Z,N)
+58 CLI IMP O 2 - I←0
+59 EOR ABSY O 4 +1 if page-cross A←A^M; set(Z,N)
+5A NOP IMP U 2 - no-op
+5B SRE ABSY U 7 - M←M>>1; A←A^M; set(C,Z,N)
+5C NOP ABSX U 4 +1 if page-cross no-op
+5D EOR ABSX O 4 +1 if page-cross A←A^M; set(Z,N)
+5E LSR ABSX O 7 - M←M>>1; set(C,Z,N)
+5F SRE ABSX U 7 - M←M>>1; A←A^M; set(C,Z,N)
+60 RTS IMP O 6 - PC←pop16+1
+61 ADC IZX O 6 - A←A+M+C; set(C,Z,N,V)
+62 KIL IMP U,H halt - halt
+63 RRA IZX U 8 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+64 NOP ZP U 3 - no-op
+65 ADC ZP O 3 - A←A+M+C; set(C,Z,N,V)
+66 ROR ZP O 5 - M←ROR(M); set(C,Z,N)
+67 RRA ZP U 5 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+68 PLA IMP O 4 - A←pop; set(Z,N)
+69 ADC IMM O 2 - A←A+#+C; set(C,Z,N,V)
+6A ROR A O 2 - A←ROR(A); set(C,Z,N)
+6B ARR IMM U 2 - A←ROR(A&#); C←bit6(A); V←bit6(A)^bit5(A); set(Z,N)
+6C JMP IND O 5 - PC←EA
+6D ADC ABS O 4 - A←A+M+C; set(C,Z,N,V)
+6E ROR ABS O 6 - M←ROR(M); set(C,Z,N)
+6F RRA ABS U 6 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+70 BVS REL O 2 +1 if branch taken; +1 more if page-cross if V=1 then PC←PC+rel
+71 ADC IZY O 5 +1 if page-cross A←A+M+C; set(C,Z,N,V)
+72 KIL IMP U,H halt - halt
+73 RRA IZY U 8 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+74 NOP ZPX U 4 - no-op
+75 ADC ZPX O 4 - A←A+M+C; set(C,Z,N,V)
+76 ROR ZPX O 6 - M←ROR(M); set(C,Z,N)
+77 RRA ZPX U 6 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+78 SEI IMP O 2 - I←1
+79 ADC ABSY O 4 +1 if page-cross A←A+M+C; set(C,Z,N,V)
+7A NOP IMP U 2 - no-op
+7B RRA ABSY U 7 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+7C NOP ABSX U 4 +1 if page-cross no-op
+7D ADC ABSX O 4 +1 if page-cross A←A+M+C; set(C,Z,N,V)
+7E ROR ABSX O 7 - M←ROR(M); set(C,Z,N)
+7F RRA ABSX U 7 - M←ROR(M); A←A+M+C; set(C,Z,N,V)
+80 NOP IMM U 2 - no-op
+81 STA IZX O 6 - [EA]←A
+82 NOP IMM U 2 - no-op
+83 SAX IZX U 6 - [EA]←A&X
+84 STY ZP O 3 - [EA]←Y
+85 STA ZP O 3 - [EA]←A
+86 STX ZP O 3 - [EA]←X
+87 SAX ZP U 3 - [EA]←A&X
+88 DEY IMP O 2 - Y←Y-1; set(Z,N)
+89 NOP IMM U 2 - no-op
+8A TXA IMP O 2 - A←X; set(Z,N)
+8B XAA IMM U 2 - unstable; A←X&#; set(Z,N)
+8C STY ABS O 4 - [EA]←Y
+8D STA ABS O 4 - [EA]←A
+8E STX ABS O 4 - [EA]←X
+8F SAX ABS U 4 - [EA]←A&X
+90 BCC REL O 2 +1 if branch taken; +1 more if page-cross if C=0 then PC←PC+rel
+91 STA IZY O 6 - [EA]←A
+92 KIL IMP U,H halt - halt
+93 AHX IZY U,S 6 - unstable; [EA]←A&X&(EA.hi+1)
+94 STY ZPX O 4 - [EA]←Y
+95 STA ZPX O 4 - [EA]←A
+96 STX ZPY O 4 - [EA]←X
+97 SAX ZPY U 4 - [EA]←A&X
+98 TYA IMP O 2 - A←Y; set(Z,N)
+99 STA ABSY O 5 - [EA]←A
+9A TXS IMP O 2 - SP←X
+9B TAS ABSY U,S 5 - unstable; SP←A&X; [EA]←SP&(EA.hi+1)
+9C SHY ABSX U,S 5 - unstable; [EA]←Y&(EA.hi+1)
+9D STA ABSX O 5 - [EA]←A
+9E SHX ABSY U,S 5 - unstable; [EA]←X&(EA.hi+1)
+9F AHX ABSY U,S 5 - unstable; [EA]←A&X&(EA.hi+1)
+A0 LDY IMM O 2 - Y←#; set(Z,N)
+A1 LDA IZX O 6 - A←M; set(Z,N)
+A2 LDX IMM O 2 - X←#; set(Z,N)
+A3 LAX IZX U 6 - A←M; X←M; set(Z,N)
+A4 LDY ZP O 3 - Y←M; set(Z,N)
+A5 LDA ZP O 3 - A←M; set(Z,N)
+A6 LDX ZP O 3 - X←M; set(Z,N)
+A7 LAX ZP U 3 - A←M; X←M; set(Z,N)
+A8 TAY IMP O 2 - Y←A; set(Z,N)
+A9 LDA IMM O 2 - A←#; set(Z,N)
+AA TAX IMP O 2 - X←A; set(Z,N)
+AB LAX IMM U 2 - A←#; X←#; set(Z,N)
+AC LDY ABS O 4 - Y←M; set(Z,N)
+AD LDA ABS O 4 - A←M; set(Z,N)
+AE LDX ABS O 4 - X←M; set(Z,N)
+AF LAX ABS U 4 - A←M; X←M; set(Z,N)
+B0 BCS REL O 2 +1 if branch taken; +1 more if page-cross if C=1 then PC←PC+rel
+B1 LDA IZY O 5 +1 if page-cross A←M; set(Z,N)
+B2 KIL IMP U,H halt - halt
+B3 LAX IZY U 5 +1 if page-cross A←M; X←M; set(Z,N)
+B4 LDY ZPX O 4 - Y←M; set(Z,N)
+B5 LDA ZPX O 4 - A←M; set(Z,N)
+B6 LDX ZPY O 4 - X←M; set(Z,N)
+B7 LAX ZPY U 4 - A←M; X←M; set(Z,N)
+B8 CLV IMP O 2 - V←0
+B9 LDA ABSY O 4 +1 if page-cross A←M; set(Z,N)
+BA TSX IMP O 2 - X←SP; set(Z,N)
+BB LAS ABSY U 4 +1 if page-cross unstable; A←M&SP; X←A; SP←A; set(Z,N)
+BC LDY ABSX O 4 +1 if page-cross Y←M; set(Z,N)
+BD LDA ABSX O 4 +1 if page-cross A←M; set(Z,N)
+BE LDX ABSY O 4 +1 if page-cross X←M; set(Z,N)
+BF LAX ABSY U 4 +1 if page-cross A←M; X←M; set(Z,N)
+C0 CPY IMM O 2 - tmp←Y-#; set(C,Z,N)
+C1 CMP IZX O 6 - tmp←A-M; set(C,Z,N)
+C2 NOP IMM U 2 - no-op
+C3 DCP IZX U 8 - M←M-1; tmp←A-M; set(C,Z,N)
+C4 CPY ZP O 3 - tmp←Y-M; set(C,Z,N)
+C5 CMP ZP O 3 - tmp←A-M; set(C,Z,N)
+C6 DEC ZP O 5 - M←M-1; set(Z,N)
+C7 DCP ZP U 5 - M←M-1; tmp←A-M; set(C,Z,N)
+C8 INY IMP O 2 - Y←Y+1; set(Z,N)
+C9 CMP IMM O 2 - tmp←A-#; set(C,Z,N)
+CA DEX IMP O 2 - X←X-1; set(Z,N)
+CB AXS IMM U 2 - X←(A&X)-#; set(C,Z,N)
+CC CPY ABS O 4 - tmp←Y-M; set(C,Z,N)
+CD CMP ABS O 4 - tmp←A-M; set(C,Z,N)
+CE DEC ABS O 6 - M←M-1; set(Z,N)
+CF DCP ABS U 6 - M←M-1; tmp←A-M; set(C,Z,N)
+D0 BNE REL O 2 +1 if branch taken; +1 more if page-cross if Z=0 then PC←PC+rel
+D1 CMP IZY O 5 +1 if page-cross tmp←A-M; set(C,Z,N)
+D2 KIL IMP U,H halt - halt
+D3 DCP IZY U 8 - M←M-1; tmp←A-M; set(C,Z,N)
+D4 NOP ZPX U 4 - no-op
+D5 CMP ZPX O 4 - tmp←A-M; set(C,Z,N)
+D6 DEC ZPX O 6 - M←M-1; set(Z,N)
+D7 DCP ZPX U 6 - M←M-1; tmp←A-M; set(C,Z,N)
+D8 CLD IMP O 2 - D←0
+D9 CMP ABSY O 4 +1 if page-cross tmp←A-M; set(C,Z,N)
+DA NOP IMP U 2 - no-op
+DB DCP ABSY U 7 - M←M-1; tmp←A-M; set(C,Z,N)
+DC NOP ABSX U 4 +1 if page-cross no-op
+DD CMP ABSX O 4 +1 if page-cross tmp←A-M; set(C,Z,N)
+DE DEC ABSX O 7 - M←M-1; set(Z,N)
+DF DCP ABSX U 7 - M←M-1; tmp←A-M; set(C,Z,N)
+E0 CPX IMM O 2 - tmp←X-#; set(C,Z,N)
+E1 SBC IZX O 6 - A←A-M-(1-C); set(C,Z,N,V)
+E2 NOP IMM U 2 - no-op
+E3 ISC IZX U 8 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+E4 CPX ZP O 3 - tmp←X-M; set(C,Z,N)
+E5 SBC ZP O 3 - A←A-M-(1-C); set(C,Z,N,V)
+E6 INC ZP O 5 - M←M+1; set(Z,N)
+E7 ISC ZP U 5 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+E8 INX IMP O 2 - X←X+1; set(Z,N)
+E9 SBC IMM O 2 - A←A-#-(1-C); set(C,Z,N,V)
+EA NOP IMP O 2 - no-op
+EB SBC IMM U 2 - A←A-#-(1-C); set(C,Z,N,V)
+EC CPX ABS O 4 - tmp←X-M; set(C,Z,N)
+ED SBC ABS O 4 - A←A-M-(1-C); set(C,Z,N,V)
+EE INC ABS O 6 - M←M+1; set(Z,N)
+EF ISC ABS U 6 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+F0 BEQ REL O 2 +1 if branch taken; +1 more if page-cross if Z=1 then PC←PC+rel
+F1 SBC IZY O 5 +1 if page-cross A←A-M-(1-C); set(C,Z,N,V)
+F2 KIL IMP U,H halt - halt
+F3 ISC IZY U 8 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+F4 NOP ZPX U 4 - no-op
+F5 SBC ZPX O 4 - A←A-M-(1-C); set(C,Z,N,V)
+F6 INC ZPX O 6 - M←M+1; set(Z,N)
+F7 ISC ZPX U 6 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+F8 SED IMP O 2 - D←1
+F9 SBC ABSY O 4 +1 if page-cross A←A-M-(1-C); set(C,Z,N,V)
+FA NOP IMP U 2 - no-op
+FB ISC ABSY U 7 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+FC NOP ABSX U 4 +1 if page-cross no-op
+FD SBC ABSX O 4 +1 if page-cross A←A-M-(1-C); set(C,Z,N,V)
+FE INC ABSX O 7 - M←M+1; set(Z,N)
+FF ISC ABSX U 7 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
+```
+
 ### Vector Entry Points (C64)
 
 - NMI `$FFFA/B`, RESET `$FFFC/D`, IRQ/BRK `$FFFE/F`. After RESET, execution starts at vector `$FFFC` (KERNAL init).

package/data/context/bootstrap.md

@@ -2,6 +2,30 @@
 
 High-level overview for C64 development. For more details, see linked spec documents.
 
+## Backend Selection
+
+Two backends may be available: `c64u` (physical C64 Ultimate hardware) and `vice`
+(VICE emulator). Use `c64_select_backend` to switch.
+
+**Routing rules — call `c64_select_backend` first when the user:**
+- Says "use vice", "on vice", "in the emulator", "via vice", or similar
+- Says "use c64u", "on hardware", "on the Ultimate", "on the real machine", or similar
+- Prefixes a request with a backend name, e.g. "vice: run this program"
+
+Do not assume the current backend is correct without checking
+`c64://platform/status` if the user has expressed a preference.
+
+## Fast Paths
+
+- Grouped MCP tools are never called bare. For tools such as `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, and `c64_system`, always send an object with `op` first.
+- Wrong: `c64_program {}`. Correct: `c64_program { op: "cross_platform_greeting" }`.
+- For simple visible confirmation on `vice`, `c64u`, or both, prefer `c64_program` with `op: "cross_platform_greeting"`.
+- For trivial hello-world and smoke-test requests, route to `.github/skills/hello-world/SKILL.md` and let that skill use the shortest greeting workflow.
+- That workflow switches backends internally, writes a platform-customized BASIC greeting, captures screenshots, and verifies the rendered text without extra tool composition.
+- Use manual `c64_select_backend` plus `upload_run_basic` only when the user needs custom program logic beyond a quick greeting or text demo.
+- On local machines with a graphical session, assume VICE should be visible by default. Only expect Xvfb or other headless fallback in CI or when no framebuffer/display session exists.
+- For manual visible VICE BASIC runs, avoid immediate `read_screen` or `wait_for_text` calls, because Binary Monitor traffic traps execution while servicing requests.
+
 ## 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.
@@ -126,7 +150,7 @@ Basic is used for simple programs and quick prototyping. It is very slow compare
 
 ## 6502/6510 Assembly
 
-Assembly is used for maximum performance and control. For more information see `data/asssembly/assembly-spec.md`.
+Assembly is used for maximum performance and control. For more information see `data/assembly/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):
@@ -144,5 +168,5 @@ Assembly is used for maximum performance and control. For more information see `
 
 ## Context & RAG
 
-- Layers: `data/context/bootstrap.md` → `AGENTS.md` → `.github/prompts/*.prompt.md` → `data/context/chat.md` → RAG docs (`doc/**/*.md`, `data/**/*.md`).
+- Layers: `data/context/bootstrap.md` → `AGENTS.md` / `CLAUDE.md` / `.github/copilot-instructions.md` → `.github/prompts/*.prompt.md` → `.github/skills/*/SKILL.md` → `data/context/chat.md` → RAG docs (`doc/**/*.md`, `data/**/*.md`).
 - Retrieval returns relevant chunks with provenance comments for transparency.

package/data/context/fast-paths.md

@@ -0,0 +1,44 @@
+# Fast Path Workflows
+
+Use these routing shortcuts when the user wants a quick visible or audible result and does not need a bespoke workflow.
+
+## Quick Visible Demo
+
+- Route quick greetings, smoke tests, and visible backend confirmation to `.github/skills/cross-platform-demo/SKILL.md`.
+- Use the custom BASIC path only when the user needs logic beyond a simple demo.
+
+## Ultra-Fast Hello World
+
+- Route trivial hello-world, greeting, and smoke-test requests to `.github/skills/hello-world/SKILL.md`.
+- On local machines with a graphical session, assume VICE should render visibly in a real emulator window.
+- Only expect Xvfb or other headless fallback in CI or when no framebuffer/display session exists.
+
+## Backend-Pinned BASIC Fast Path
+
+- When the prompt already pins the backend with prefixes such as `vice:` or `c64u:` and asks for a tiny static greeting or hello-world style BASIC output, route directly to `.github/skills/hello-world/SKILL.md`.
+- Treat requests such as `vice: write a small BASIC program that clears the screen and prints HELLO VICE` as unambiguous; do not spend extra turns re-reading README sections, MCP manifests, or BASIC references before executing.
+- Fall back to `.github/skills/basic-program/SKILL.md` only when the user asks for custom program logic, hardware-specific behavior, or deeper debugging.
+
+## Quick Music Demo
+
+- Route recognizable demo-tune requests to `.github/skills/sid-music/SKILL.md`.
+- The canonical built-in preset is `fuer_elise`.
+- Legacy preset callers should still normalize to the same playback path rather than failing.
+
+Example:
+
+```json
+{
+  "op": "play_preset",
+  "preset": "fuer_elise"
+}
+```
+
+## Longer Interactive Sessions
+
+- Use the dedicated skill for the underlying task when the user needs a pinned backend, custom program logic, or deeper debugging.
+
+## Verification Order
+
+1. Trust the verification defined by the selected skill first.
+2. Use captured artifacts or follow-up inspection only when the selected skill indicates that extra verification is needed.

package/data/graphics/petscii-style-guide.md

@@ -37,13 +37,16 @@ Colour presets and character codes for C64 PETSCII art. Target: LLM optimization
 ## Contrast Guidelines
 
 **Readable combinations** (luminance difference ≥3):
+
 - 0/1 (Black/White), 0/7 (Black/Yellow), 0/13 (Black/Lt.Green)
 - 6/1 (Blue/White), 6/7 (Blue/Yellow), 11/1 (Dk.Grey/White)
 
 **Marginal** (luminance difference 2):
+
 - 0/3 (Black/Cyan), 6/14 (Blue/Lt.Blue), 12/1 (Grey/White)
 
 **Unreadable** (insufficient contrast):
+
 - 12/15 (Grey/Lt.Grey), 11/12 (Dk.Grey/Grey), 2/4 (Red/Purple)
 - 6/11 (Blue/Dk.Grey), 9/11 (Brown/Dk.Grey)
 
@@ -57,9 +60,10 @@ Border matching: Set border=background for seamless look.
 Conversion: Screen code ≠ PETSCII code. Use charset reference (c64://specs/charset) for mapping.
 
 **Usage**:
+
 - BASIC/printing: Use PETSCII codes with CHR$() or PRINT
 - Direct screen memory: Use screen codes with POKE to $0400+offset
-- Tools: `c64_graphics` (`create_petscii`) returns both `petsciiCodes` array and screen memory data
+- Tools: `c64_graphics` (`render_petscii_art`) returns both `petsciiCodes` array and screen memory data
 
 ## Essential PETSCII Symbols
 
@@ -89,7 +93,7 @@ Conversion: Screen code ≠ PETSCII code. Use charset reference (c64://specs/cha
 
 ```javascript
 await callTool("c64_graphics", {
-  op: "create_petscii",
+  op: "render_petscii_art",
   prompt: "cat",
   borderColor: 0,
   backgroundColor: 6,

package/data/graphics/sprite-charset-best-practices.md

@@ -243,7 +243,7 @@ Custom charsets have minimal performance impact:
 
 ## Tool Integration
 
-### Using generate_sprite_prg
+### Using render_sprite
 
 ```javascript
 {
@@ -258,7 +258,7 @@ Custom charsets have minimal performance impact:
 The tool:
 
 - Validates 63-byte sprite format
-- Generates BASIC program to display sprite
+- Writes sprite data directly into RAM
 - Handles sprite pointer and VIC-II register setup
 - Returns structured metadata for follow-up operations
 
@@ -277,8 +277,8 @@ When working with sprites and charsets:
 ### Simple Sprite Display
 
 1. Prepare 24×21 sprite bitmap
-2. Call `generate_sprite_prg` with sprite data
-3. Tool returns PRG that sets up sprite automatically
+2. Call `render_sprite` with sprite data
+3. Tool writes sprite data and patches VIC-II state automatically
 4. Use `read_screen` to verify appearance
 5. Optionally call `c64_memory` `write` to adjust position/colour
 
@@ -303,7 +303,7 @@ When working with sprites and charsets:
 
 1. **Plan Memory Layout**: Map out sprite and charset locations before coding
 2. **Test Incrementally**: Display one sprite/char before adding more
-3. **Use Tools**: Leverage `generate_sprite_prg` and memory tools
+3. **Use Tools**: Leverage `render_sprite` and memory tools
 4. **Document State**: Note which sprites/chars are active
 5. **Handle Errors**: Check return values and screen output
 6. **Optimize Last**: Get it working, then optimize if needed