c64bridge 0.9.1 → 0.9.3

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

@@ -246,13 +246,14 @@ Custom charsets have minimal performance impact:
 ### Using render_sprite
 
 ```javascript
-{
-  spriteData: "base64-encoded-63-bytes",
+await callTool("c64_graphics", {
+  op: "render_sprite",
+  sprite: "base64-encoded-63-bytes",
   x: 160,           // Center horizontally
   y: 100,           // Center vertically  
-  colour: 1,        // White
+  color: 1,         // White
   multicolour: false
-}
+})
 ```
 
 The tool:
@@ -270,26 +271,26 @@ When working with sprites and charsets:
 1. Use memory ranges documented in c64://memory/map
 2. Avoid BASIC program area ($0801-$9FFF) unless controlling it
 3. Preserve zero page ($0000-$00FF) and stack ($0100-$01FF)
-4. Use the `c64_memory` operations `read` and `write` for safe access
+4. Use `c64_memory` with `op: "read"` and `op: "write"` for safe access
 
 ## Example Workflows
 
 ### Simple Sprite Display
 
 1. Prepare 24×21 sprite bitmap
-2. Call `render_sprite` with sprite data
+2. Call `c64_graphics` with `op: "render_sprite"` and 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
+4. Use `c64_memory` with `op: "read_screen"` to verify appearance
+5. Optionally call `c64_memory` with `op: "write"` to adjust position/colour
 
 ### Custom Charset Installation
 
 1. Design character set (full or partial)
 2. Encode to 8-byte-per-char format
-3. Use `c64_memory` `write` to copy the charset to $2000
+3. Use `c64_memory` with `op: "write"` to copy the charset to $2000
 4. POKE $D018 to point VIC-II at new charset
-5. Use `upload_run_basic` to test character display
-6. Verify with `read_screen`
+5. Use `c64_program` with `op: "upload_run_basic"` to test character display
+6. Verify with `c64_memory` and `op: "read_screen"`
 
 ### Animated Sprite Sequence
 
@@ -297,13 +298,13 @@ When working with sprites and charsets:
 2. Upload all frames to consecutive memory locations
 3. Generate BASIC program that cycles sprite pointer
 4. Use raster timing for smooth animation
-5. Verify frame timing with `c64_memory` `read` checks
+5. Verify frame timing with `c64_memory` and `op: "read"` checks
 
 ## Best Practices Summary
 
 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 `render_sprite` and memory tools
+3. **Use Tools**: Leverage `c64_graphics` with `op: "render_sprite"` and `c64_memory` operations
 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

package/data/io/cia-spec.md

@@ -105,11 +105,11 @@ User‑port mapping for CIA2 PRB and PRA b2 is defined in `io-spec.md` (pin lett
 
 - **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`
+- **KERNAL vector/entry points:** `../kernal/rom-routines.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)
+- [Mapping the C64](https://www.zimmers.net/anonftp/pub/cbm/c64/manuals/mapping-c64_txt)

package/data/{memory/kernal-memory-map.md → kernal/rom-routines.md}

@@ -1,8 +1,9 @@
-# C64 KERNAL Memory Map — Complete ($E000–$FFFF)
+# C64 KERNAL ROM Routines 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.
+> Related memory maps: `../memory/memory-map.md`, `../memory/low-memory-map.md`, `../basic/rom-routines.md`, `../io/io-spec.md`.
 
 | Address | Decimal | Name | Function | Args | Input | Output | Notes |
 |:--------|:--------|:-----|:---------|:-----|:------|:-------|:------|
@@ -37,7 +38,7 @@
 | `$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 |
+| `$E3BA` | 58298 | 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) | — | — | — | — |

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

@@ -5,6 +5,7 @@
 > 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.
+> Related memory maps: `memory-map.md`, `../basic/rom-routines.md`, `../kernal/rom-routines.md`, `../io/io-spec.md`.
 
 ## Legend
 

package/data/memory/memory-map.md

@@ -2,6 +2,19 @@
 
 All addresses are shown as `hex` / `dec`. Group related entries to minimise token usage while keeping lookup simple.
 
+## Memory Map Reference Routing
+
+Use this quick map to select the narrowest reference before coding or patching memory.
+
+| Need | MCP resource | File |
+| --- | --- | --- |
+| Whole 64 KB layout, RAM/ROM/I/O banks, VIC/SID/CIA ranges | `c64://memory/map` | `data/memory/memory-map.md` |
+| Zero page, stack, page-2 buffers, page-3 vectors, cassette buffer | `c64://memory/zero-page-and-workspace` | `data/memory/low-memory-map.md` |
+| BASIC ROM routines, parser/evaluator helpers, variables, strings, token dispatch | `c64://basic/rom-routines` | `data/basic/rom-routines.md` |
+| KERNAL ROM routines, jump table, vectors, serial/tape/screen services | `c64://kernal/rom-routines` | `data/kernal/rom-routines.md` |
+| Hardware register map for VIC-II, SID, CIA, colour RAM, expansion I/O | `c64://io/spec` | `data/io/io-spec.md` |
+| CIA timer, keyboard, serial, TOD, IRQ/NMI register details | `c64://io/cia/spec` | `data/io/cia-spec.md` |
+
 ## Zero Page ($0000-$00FF)
 
 | Label | Address | Purpose |

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

@@ -5,12 +5,12 @@ This guide summarizes the High Voltage SID Collection (HVSC) "PSID file format"
 - 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`.
+You can play a SID file on a connected device with the MCP tool `c64_sound` and `op: "play_sid_file"`.
 
-## Quick start: play a SID via REST/MCP
+## Quick start: play a SID via MCP
 
-- Endpoint: `POST /tools/sidplay_file`
-- Body: `{ "path": "/flash/music/Example.sid", "songnr": 1 }` (optional `songnr`)
+- Tool: `c64_sound`
+- Arguments: `{ "op": "play_sid_file", "path": "/flash/music/Example.sid", "songnr": 1 }` (optional `songnr`)
 
 Refer to `doc/c64u/c64-rest-api.md` for the underlying device endpoint and options.
 
@@ -85,7 +85,7 @@ SID files do not embed duration. HVSC ships a `Songlengths.md5` database mapping
 
 ## Related API and tools
 
-- Play from device filesystem: `sidplay_file` (see generated `mcp-manifest.json` and `src/index.ts`)
+- Play from device filesystem: `c64_sound` with `op: "play_sid_file"` (see generated `mcp/tools.json` and `mcp/schemas/c64_sound.schema.json`)
 - Low-level SID register programming: see `data/sound/sid-spec.md`
 
 References for further reading: HVSC PSID v2NG file format (spec), community resources, and project notes from implementations like SIDman.

package/data/sound/sid-programming-best-practices.md

@@ -126,18 +126,18 @@ This solution was developed through:
 
 ```bash
 curl -X POST -H 'Content-Type: application/json' \
-  -d '{"program": "... BASIC program ..."}' \
-  http://localhost:8000/tools/upload_run_basic
+  -d '{"op": "upload_run_basic", "program": "... BASIC program ..."}' \
+  http://localhost:8000/tools/c64_program
 ```
 
 ### Future Audio Analysis
 
-The working scale can now be used with the `analyze_audio` tool:
+The working scale can now be used with `c64_sound` and `op: "analyze"`:
 
 ```bash
 curl -X POST -H 'Content-Type: application/json' \
-  -d '{"request": "verify the scale sounds correct"}' \
-  http://localhost:8000/tools/analyze_audio
+  -d '{"op": "analyze", "request": "verify the scale sounds correct"}' \
+  http://localhost:8000/tools/c64_sound
 ```
 
 ## Musical Expression Example: "Alle meine Entchen"

package/data/vice/vice-binary-monitor-spec.md

@@ -15,7 +15,7 @@ Recommended C64 Bridge entry points:
 | Debug registers and checkpoints | `c64_debug` | `get_registers`, `set_registers`, `create_checkpoint`, `list_checkpoints`, `step`, `step_return` |
 | Send keyboard or joystick input | `c64_input` | `write_text`, `key`, `joystick` |
 | Capture emulator display | `c64_graphics` | `capture_frame` |
-| Reset or resume execution | `c64_system` | `reset`, `resume` |
+| Reset or continue execution | `c64_system`, `c64_debug` | `reset`, `continue_execution` |
 | Read or write VICE resources | `c64_vice` | `resource_get`, `resource_set` |
 
 ---
@@ -633,7 +633,7 @@ C64 Bridge mapping:
 
 | MCP tool     | Operation |
 | ------------ | --------- |
-| `c64_system` | `resume`  |
+| `c64_debug` | `continue_execution` |
 
 ---
 
@@ -797,7 +797,7 @@ Usually emitted with `request_id = 0xffffffff`.
 | Palette Get          | `0x91` |                   `0x91` | internal display support                                                            |
 | Joyport Set          | `0xa2` |                   `0xa2` | `c64_input.joystick`                                                                |
 | Userport Set         | `0xb2` |                   `0xb2` | internal or unmapped                                                                |
-| Exit                 | `0xaa` |                   `0xaa` | `c64_system.resume`                                                                 |
+| Exit                 | `0xaa` |                   `0xaa` | `c64_debug.continue_execution`                                                       |
 | Quit                 | `0xbb` |                   `0xbb` | managed VICE lifecycle                                                              |
 | Reset                | `0xcc` |                   `0xcc` | `c64_system.reset`, `c64_system.reboot`, `c64_drive.reset`                          |
 | Autostart / Autoload | `0xdd` |                   `0xdd` | `c64_program.run_prg`, `c64_program.upload_run_basic`, `c64_program.upload_run_asm` |
@@ -827,17 +827,16 @@ Examples:
 | Read PC and A                   | `c64_debug` with `op = get_registers`     |
 | Step one instruction            | `c64_debug` with `op = step`              |
 | Step until return               | `c64_debug` with `op = step_return`       |
-| Continue execution              | `c64_system` with `op = resume`           |
+| Continue execution              | `c64_debug` with `op = continue_execution` |
 | Reset VICE                      | `c64_system` with `op = reset`            |
 | Change a VICE setting           | `c64_vice` with `op = resource_set`       |
 
 ## Backend Selection
 
-If both C64 Ultimate and VICE are configured, use `c64_select_backend` before making VICE-specific requests.
+If both C64 Ultimate and VICE are configured, call `c64_select_backend` with these arguments before making VICE-specific requests:
 
 ```json
 {
-  "tool": "c64_select_backend",
   "op": "select",
   "backend": "vice"
 }