c64bridge 0.9.0 → 0.9.2

package/README.md

@@ -61,12 +61,14 @@ C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontex
   - [Static MCP Interface](#static-mcp-interface)
   - [MCP API Reference](#mcp-api-reference)
     - [Tools](#tools)
+      - [c64\_batch](#c64_batch)
       - [c64\_config](#c64_config)
       - [c64\_debug](#c64_debug)
       - [c64\_disk](#c64_disk)
       - [c64\_drive](#c64_drive)
       - [c64\_extract](#c64_extract)
       - [c64\_graphics](#c64_graphics)
+      - [c64\_input](#c64_input)
       - [c64\_memory](#c64_memory)
       - [c64\_printer](#c64_printer)
       - [c64\_program](#c64_program)
@@ -251,8 +253,8 @@ Use this for managed VICE launches:
 }
 ```
 
-- `directory` is optional. When omitted, or when the configured path is invalid, C64 Bridge auto-detects a VICE resource directory by looking for the standard C64 ROM set near the selected emulator binary and in common system locations.
-- `VICE_BINARY`, `VICE_DIRECTORY`, `VICE_HOST`, `VICE_PORT`, `VICE_VISIBLE`, `VICE_WARP`, and `VICE_ARGS` override managed VICE startup without editing config files. Valid explicit `VICE_BINARY` and `VICE_DIRECTORY` values are used as-is; automatic search only fills in missing or invalid values.
+- `directory` is optional. When omitted, C64 Bridge auto-detects a VICE resource directory by looking for the standard C64 ROM set near the emulator binary and in common system locations.
+- `VICE_BINARY`, `VICE_DIRECTORY`, `VICE_HOST`, `VICE_PORT`, `VICE_VISIBLE`, `VICE_WARP`, and `VICE_ARGS` override managed VICE startup without editing config files.
 - If no explicit binary is configured, the runtime prefers `/usr/local/bin/x64sc` when present, then falls back to `x64sc` or `x64` on `PATH` so the same setup remains portable across operating systems.
 
 > [!NOTE]
@@ -272,6 +274,9 @@ Prompt illustration (issued via Copilot in VS Code, using GPT 5.4 Medium):
 
 ```text
 c64u: write a small BASIC program that clears the screen and prints HELLO C64U
+```
+
+```text
 vice: write a small BASIC program that clears the screen and prints HELLO VICE
 ```
 
@@ -561,22 +566,14 @@ The [`./build`](./build) script at the project root wraps all development tasks
 ./build test                                         # integration tests (mock backend)
 ./build test --real                                  # test against real hardware
 ./build test --platform vice --target mock           # single test leg
-./build test:vice:mock                               # curated VICE mock matrix (feature-matrix coverage)
-./build test:vice:device                             # curated real-VICE validation (device backend + smoke, headless/Xvfb by default)
 ./build test:matrix                                  # full matrix (c64u/mock · vice/mock · vice/device)
 ./build coverage                                     # merged coverage report
 ./build coverage:single --platform c64u --target mock
-npm run vice:smoke                                   # direct VICE binary-monitor smoke test
-npm run vice:smoke:visible                           # human-visible VICE boot + HELLO demo (keeps window open)
 ./build check                                        # build + test matrix (no install)
 ./build rag:rebuild                                  # rebuild RAG embeddings
 ./build release --version 1.2.3                      # prepare a release
 ```
 
-The visible smoke demo accepts `true`/`false`, `on`/`off`, and `1`/`0` for `VICE_VISIBLE`, `VICE_WARP`, and `VICE_KEEP_OPEN`. `npm run vice:smoke:visible` forces a visible, warp-off session, waits for a stable `READY.` screen, then injects `HELLO` and keeps the window open for inspection.
-
-Automation note: `npm run test:vice:device` and `./build` force the real-VICE validation leg into headless/Xvfb mode so the CI-style matrix does not open a confusing local emulator window.
-
 > **Starting the MCP server** is not managed by `./build`. Use `npm start` (from source) or `npx -y c64bridge@latest` (published package) as shown in the [Quick Start](#quick-start) section above.
 
 ## Documentation
@@ -596,208 +593,237 @@ This allows agents to inspect the available tools, resources, prompts, and schem
 
 <!-- AUTO-GENERATED:MCP-DOCS-START -->
 
-This MCP server exposes **15 tools**, **26 resources**, and **10 prompts** for controlling your Commodore 64.
+This MCP server exposes **17 tools**, **26 resources**, and **10 prompts** for controlling your Commodore 64.
 
 ### Tools
 
+_Address range convention: `address` + `length` means start address plus byte count; `startAddress` + `endAddress` means inclusive bounds._
+
+#### c64_batch
+
+Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.
+
+_No operations defined._
+
 #### c64_config
 
 Grouped entry point for configuration reads/writes, diagnostics, and snapshots.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `batch_update` | Apply multiple configuration updates in a single request. | — | — | ✅ | ✅ |
-| `diff` | Compare the current configuration with a snapshot. | — | — | ✅ | ✅ |
-| `get` | Read a configuration category or specific item. | — | — | ✅ | ✅ |
-| `info` | Retrieve Ultimate hardware information and status. | — | — | ✅ | ✅ |
-| `list` | List configuration categories reported by the firmware. | — | — | ✅ | ✅ |
-| `load_flash` | Load configuration from flash storage. | — | — | ✅ |  |
-| `read_debugreg` | Read the Ultimate debug register ($D7FF). | — | — | ✅ |  |
-| `reset_defaults` | Reset firmware configuration to factory defaults. | — | — | ✅ |  |
-| `restore` | Restore configuration from a snapshot file. | — | — | ✅ | ✅ |
-| `save_flash` | Persist the current configuration to flash storage. | — | — | ✅ |  |
-| `set` | Write a configuration value in the selected category. | — | — | ✅ | ✅ |
-| `shuffle` | Discover PRG/CRT files and run each with optional screen capture. | — | — | ✅ |  |
-| `snapshot` | Snapshot configuration to disk for later restore or diff. | — | — | ✅ | ✅ |
-| `version` | Fetch firmware version details. | — | — | ✅ | ✅ |
-| `write_debugreg` | Write a hex value to the Ultimate debug register ($D7FF). | — | — | ✅ |  |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `batch_update` | Apply multiple configuration updates in a single request. | — | — | — | ✅ | ✅ |
+| `diff` | Compare the current configuration with a snapshot. | `path` | — | — | ✅ | ✅ |
+| `get` | Read a configuration category or specific item. | `category` | `item` | — | ✅ | ✅ |
+| `info` | Retrieve Ultimate hardware information and status. | — | — | — | ✅ | ✅ |
+| `list` | List configuration categories reported by the firmware. | — | — | — | ✅ | ✅ |
+| `load_flash` | Load configuration from flash storage. | — | — | — | ✅ |  |
+| `read_debugreg` | Read the Ultimate debug register ($D7FF). | — | — | — | ✅ |  |
+| `reset_defaults` | Reset firmware configuration to factory defaults. | — | — | — | ✅ |  |
+| `restore` | Restore configuration from a snapshot file. | `path` | `applyToFlash=false` | — | ✅ | ✅ |
+| `save_flash` | Persist the current configuration to flash storage. | — | — | — | ✅ |  |
+| `set` | Write a configuration value in the selected category. | `category`, `item`, `value` | — | — | ✅ | ✅ |
+| `shuffle` | Discover PRG/CRT files and run each with optional screen capture. | — | `root="/"`, `extensions=["prg","crt"]`, `durationMs=5000`, `captureScreen=true`, `maxPrograms=10`, `outputPath`, `resetDelayMs=100` | — | ✅ |  |
+| `snapshot` | Snapshot configuration to disk for later restore or diff. | `path` | — | — | ✅ | ✅ |
+| `version` | Fetch firmware version details. | — | — | — | ✅ | ✅ |
+| `write_debugreg` | Write a hex value to the Ultimate debug register ($D7FF). | `value` | — | — | ✅ |  |
 
 #### c64_debug
 
 Grouped entry point for VICE debugger operations (breakpoints, registers, stepping).
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `create_checkpoint` | Create a new checkpoint (breakpoint) in VICE. | — | — |  | ✅ |
-| `delete_checkpoint` | Remove a checkpoint by id. | — | — |  | ✅ |
-| `get_checkpoint` | Fetch a single checkpoint by id. | — | — |  | ✅ |
-| `get_registers` | Read register values, optionally filtered by name or id. | — | — |  | ✅ |
-| `list_checkpoints` | List all active VICE checkpoints (breakpoints). | — | — |  | ✅ |
-| `list_registers` | List available registers (metadata). | — | — |  | ✅ |
-| `set_condition` | Attach a conditional expression to a checkpoint. | — | — |  | ✅ |
-| `set_registers` | Write register values. | — | — |  | ✅ |
-| `step` | Single-step CPU execution. | — | — |  | ✅ |
-| `step_return` | Continue execution until the current routine returns. | — | — |  | ✅ |
-| `toggle_checkpoint` | Enable or disable a checkpoint by id. | — | — |  | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `continue_execution` | Exit the Binary Monitor and resume CPU execution (BM 0xAA Exit). | — | — | — |  | ✅ |
+| `create_checkpoint` | Create a new checkpoint (breakpoint) in VICE. | `address` | `endAddress`, `stopOnHit=true`, `enabled=true`, `temporary=false`, `label`, `operations`, `memspace` | — |  | ✅ |
+| `delete_checkpoint` | Remove a checkpoint by id. | `id` | — | — |  | ✅ |
+| `get_checkpoint` | Fetch a single checkpoint by id. | `id` | — | — |  | ✅ |
+| `get_monitor_state` | Read CPU registers and return the current monitor state. | — | `memspace` | — |  | ✅ |
+| `get_registers` | Read register values, optionally filtered by name or id. | — | `memspace`, `registers` | — |  | ✅ |
+| `list_checkpoints` | List all active VICE checkpoints (breakpoints). | — | — | — |  | ✅ |
+| `list_registers` | List available registers (metadata). | — | `memspace` | — |  | ✅ |
+| `nuclear_reset` | Kill and restart the VICE process (managed instances only). | — | — | — |  | ✅ |
+| `set_condition` | Attach a conditional expression to a checkpoint. | `id`, `expression` | — | — |  | ✅ |
+| `set_registers` | Write register values. | `writes` | `memspace` | — |  | ✅ |
+| `step` | Single-step CPU execution. | — | `count=1`, `mode` | — |  | ✅ |
+| `step_return` | Continue execution until the current routine returns. | — | — | — |  | ✅ |
+| `toggle_checkpoint` | Enable or disable a checkpoint by id. | `id`, `enabled` | — | — |  | ✅ |
+| `wait_for_state` | Poll CPU registers until PC equals expectedPC or timeout elapses. | — | `expectedPC`, `timeoutMs=5000`, `pollMs=100` | — |  | ✅ |
 
 #### c64_disk
 
 Grouped entry point for disk mounts, listings, image creation, and program discovery.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `create_image` | Create a blank disk image of the specified format. | — | supports verify | ✅ |  |
-| `file_info` | Inspect metadata for a file on the Ultimate filesystem. | — | supports verify | ✅ |  |
-| `find_and_run` | Search for a PRG/CRT by name substring and run the first match. | — | supports verify | ✅ |  |
-| `list_drives` | List Ultimate drive slots and their mounted images. | — | supports verify | ✅ | ✅ |
-| `mount` | Mount a disk image with optional verification and retries. | — | supports verify | ✅ | ✅ |
-| `unmount` | Remove the mounted image from an Ultimate drive slot. | — | supports verify | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `create_image` | Create a blank disk image of the specified format. | `format`, `path` | `diskname`, `tracks` | — | ✅ |  |
+| `file_info` | Inspect metadata for a file on the Ultimate filesystem. | `path` | — | — | ✅ |  |
+| `find_and_run` | Search for a PRG/CRT by name substring and run the first match. | `nameContains` | `root="/"`, `extensions`, `caseInsensitive=true`, `sort="discovered"`, `waitMs=0`, `captureCandidates=10` | — | ✅ |  |
+| `list_drives` | List Ultimate drive slots and their mounted images. | — | — | — | ✅ | ✅ |
+| `mount` | Mount a disk image with optional verification and retries. | `drive`, `image` | `type`, `attachmentMode`, `driveMode`, `verify=false`, `powerOnIfNeeded=true`, `resetAfterMount=true`, `maxRetries=2`, `retryDelayMs=500` | supports verify | ✅ | ✅ |
+| `unmount` | Remove the mounted image from an Ultimate drive slot. | `drive` | — | — | ✅ | ✅ |
 
 #### c64_drive
 
 Grouped entry point for drive power, mode, reset, and ROM operations.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `load_rom` | Temporarily load a custom ROM into an Ultimate drive slot. | — | — | ✅ |  |
-| `power_off` | Power off a specific Ultimate drive slot. | — | — | ✅ | ✅ |
-| `power_on` | Power on a specific Ultimate drive slot. | — | — | ✅ | ✅ |
-| `reset` | Issue an IEC reset for the selected drive slot. | — | — | ✅ | ✅ |
-| `set_mode` | Set the emulation mode for a drive slot (1541/1571/1581). | — | — | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `load_rom` | Temporarily load a custom ROM into an Ultimate drive slot. | `drive`, `path` | — | — | ✅ |  |
+| `power_off` | Power off a specific Ultimate drive slot. | `drive` | — | — | ✅ | ✅ |
+| `power_on` | Power on a specific Ultimate drive slot. | `drive` | — | — | ✅ | ✅ |
+| `reset` | Issue an IEC reset for the selected drive slot. | `drive` | — | — | ✅ | ✅ |
+| `set_mode` | Set the emulation mode for a drive slot (1541/1571/1581). | `drive`, `mode` | — | — | ✅ | ✅ |
 
 #### c64_extract
 
 Grouped entry point for sprite/charset extraction, memory dumps, filesystem stats, and firmware health checks.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `charset` | Locate and extract 2KB character sets from RAM. | — | — | ✅ |  |
-| `firmware_health` | Run firmware readiness checks and report status metrics. | — | — | ✅ |  |
-| `fs_stats` | Walk the filesystem and aggregate counts/bytes by extension. | — | — | ✅ |  |
-| `memory_dump` | Dump a RAM range to hex or binary files with manifest metadata. | — | — | ✅ |  |
-| `sprites` | Scan RAM for sprites and optionally export .spr files. | — | — | ✅ |  |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `charset` | Locate and extract 2KB character sets from RAM. | — | `address`, `scanRange="common"`, `outputPath`, `pauseDuringRead=true`, `minNonEmptyChars=32`, `minEntropy=0.3` | — | ✅ |  |
+| `firmware_health` | Run firmware readiness checks and report status metrics. | — | — | — | ✅ |  |
+| `fs_stats` | Walk the filesystem and aggregate counts/bytes by extension. | — | `root="/"`, `extensions`, `includeContainers=true`, `maxSamplesPerExtension=3` | — | ✅ |  |
+| `memory_dump` | Dump a RAM range to hex or binary files with manifest metadata. | `address`, `length`, `outputPath` | `format="hex"`, `chunkSize=512`, `pauseDuringRead=true`, `retries=1` | — | ✅ |  |
+| `sprites` | Scan RAM for sprites and optionally export .spr files. | `address`, `length` | `stride=64`, `maxSprites=16`, `minNonZeroRows=4`, `minSetBits=12`, `includeBase64=true`, `outputDir`, `pauseDuringRead=true` | — | ✅ |  |
 
 #### c64_graphics
 
 Grouped entry point for frame capture and graphics rendering workflows.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `capture_frame` | Capture one or more complete video frames from the active backend. | — | — | ✅ | ✅ |
-| `render_bitmap` | Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. | — | — | ✅ | ✅ |
-| `render_petscii_art` | Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. | — | — | ✅ | ✅ |
-| `render_petscii_text` | Display PETSCII text with optional border and background colours. | — | — | ✅ | ✅ |
-| `render_sprite` | Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. | — | — | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `capture_frame` | Capture one or more complete video frames from the active backend. | — | `count=1`, `includePixels=true`, `encoding="base64"` | — | ✅ | ✅ |
+| `get_display_state` | Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical. | — | — | — | ✅ | ✅ |
+| `render_bitmap` | Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. | `imagePath`, `format` | `bitmapAddress=8192`, `screenAddress=1024`, `borderColor=0`, `backgroundColor=0`, `preserveAspect=true` | — | ✅ | ✅ |
+| `render_petscii_art` | Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. | — | `prompt`, `text`, `maxWidth`, `maxHeight`, `borderColor`, `backgroundColor`, `foregroundColor`, `dryRun=false`, `bitmap` | — | ✅ | ✅ |
+| `render_petscii_text` | Display PETSCII text with optional border and background colours. | `text` | `borderColor`, `backgroundColor` | — | ✅ | ✅ |
+| `render_sprite` | Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. | `sprite` | `index=0`, `x=100`, `y=100`, `color=1`, `multicolour=false` | — | ✅ | ✅ |
+
+#### c64_input
+
+Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).
+
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `joystick` | Simulate joystick input by writing directly to CIA1 Port A/B registers. | `port`, `controls`, `action` | `durationMs=80` | — |  | ✅ |
+| `key` | Tap a single key or hold it for a duration. | `key` | `durationMs=0`, `count=1` | — | ✅ | ✅ |
+| `write_text` | Send a text string to the keyboard buffer, with PETSCII token expansion. | `text` | `delayMs=0` | — | ✅ | ✅ |
 
 #### c64_memory
 
 Grouped entry point for memory I/O, screen reads, and screen polling.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `read` | Read a range of bytes and return a hex dump with address metadata. | — | supports verify | ✅ | ✅ |
-| `read_screen` | Return the current 40x25 text screen converted to ASCII. | — | supports verify | ✅ | ✅ |
-| `wait_for_text` | Poll the screen until a substring or regex appears, or timeout elapses. | — | supports verify | ✅ | ✅ |
-| `write` | Write a hexadecimal byte sequence into RAM. | — | supports verify | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `compare_memory` | Compare two memory regions byte-by-byte and report differences. | `address1`, `address2`, `length` | `maxDiffs=10` | — | ✅ | ✅ |
+| `copy_memory` | Copy a RAM region to another address. | `source`, `dest`, `length` | — | — | ✅ | ✅ |
+| `disassemble` | Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE. | `address` | `length=64`, `instructionCount` | — | ✅ | ✅ |
+| `fill_memory` | Fill a memory range with a repeating byte pattern. | `address`, `length`, `pattern` | — | — | ✅ | ✅ |
+| `read` | Read a range of bytes and return a hex dump with address metadata. | `address` | `length=256` | — | ✅ | ✅ |
+| `read_screen` | Return the current 40x25 text screen converted to ASCII. | — | — | — | ✅ | ✅ |
+| `save_memory` | Dump a memory range to a local file, with an optional PRG load-address header. | `startAddress`, `endAddress`, `filePath` | `asPrg=true` | — | ✅ | ✅ |
+| `search_memory` | Search for a byte pattern within a memory range and return matching addresses. | `startAddress`, `endAddress`, `pattern` | `maxResults=10` | — | ✅ | ✅ |
+| `wait_for_text` | Poll the screen until a substring or regex appears, or timeout elapses. | `pattern` | `isRegex=false`, `caseInsensitive=true`, `timeoutMs=3000`, `intervalMs=100` | — | ✅ | ✅ |
+| `write` | Write a hexadecimal byte sequence into RAM. | `address`, `bytes` | `verify=false`, `expected`, `mask`, `abortOnMismatch=true` | supports verify | ✅ | ✅ |
 
 #### c64_printer
 
 Grouped entry point for Commodore and Epson printing helpers.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `define_chars` | Define custom printer characters (Commodore DLL mode). | — | — | ✅ |  |
-| `print_bitmap` | Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows. | — | — | ✅ |  |
-| `print_text` | Generate BASIC that prints text to device 4. | — | — | ✅ |  |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `define_chars` | Define custom printer characters (Commodore DLL mode). | `firstChar`, `chars` | `secondaryAddress` | — | ✅ |  |
+| `print_bitmap` | Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows. | `printer="commodore"`, `columns` | `repeats`, `useSubRepeat`, `secondaryAddress`, `ensureMsb=true`, `mode`, `density`, `timesPerLine` | — | ✅ |  |
+| `print_text` | Generate BASIC that prints text to device 4. | `text` | `target="commodore"`, `secondaryAddress`, `formFeed=false` | — | ✅ |  |
 
 #### c64_program
 
 Grouped entry point for program upload, execution, and batch workflows.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `batch_run` | Run multiple PRG/CRT programs with post-run assertions. | — | supports verify | ✅ | ✅ |
-| `bundle_run` | Capture screen, memory, and debug registers into an artifact bundle. | — | supports verify | ✅ |  |
-| `cross_platform_greeting` | Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. | — | supports verify | ✅ | ✅ |
-| `load_prg` | Load a PRG from Ultimate storage without executing it. | — | supports verify | ✅ |  |
-| `run_crt` | Mount and run a CRT cartridge image. | — | supports verify | ✅ |  |
-| `run_prg` | Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE. | — | supports verify | ✅ | ✅ |
-| `upload_run_asm` | Assemble 6502/6510 source, upload the PRG, and execute it. | — | supports verify | ✅ | ✅ |
-| `upload_run_basic` | Upload Commodore BASIC v2 source and execute it immediately. | — | supports verify | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `batch_run` | Run multiple PRG/CRT programs with post-run assertions. | `programs` | `continueOnError=false`, `durationMs=2000`, `outputPath`, `resetDelayMs=100` | — | ✅ | ✅ |
+| `bundle_run` | Capture screen, memory, and debug registers into an artifact bundle. | `runId`, `outputPath` | `captureScreen=true`, `memoryRanges`, `captureDebugReg=true` | — | ✅ |  |
+| `cross_platform_greeting` | Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. | — | `platforms=["vice","c64u"]`, `messageTemplate="HAVE A GREAT DAY, {PLATFORM}!"`, `verify=true`, `captureScreenshot=true`, `outputPath`, `restoreActiveBackend=true`, `timeoutMs=1500`, `pollIntervalMs=100` | supports verify | ✅ | ✅ |
+| `load_prg` | Load a PRG from Ultimate storage without executing it. | `path` | `symbolsFile` | — | ✅ |  |
+| `run_crt` | Mount and run a CRT cartridge image. | `path` | — | — | ✅ |  |
+| `run_prg` | Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE. | `path` | `symbolsFile` | — | ✅ | ✅ |
+| `upload_run_asm` | Assemble 6502/6510 source, upload the PRG, and execute it. | `program` | `verify=false` | supports verify | ✅ | ✅ |
+| `upload_run_basic` | Upload Commodore BASIC v2 source and execute it immediately. | `program` | `verify=false` | supports verify | ✅ | ✅ |
 
 #### c64_rag
 
 Grouped entry point for BASIC and assembly RAG lookups.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `asm` | Retrieve 6502/6510 assembly references from the local knowledge base. | — | — | ✅ | ✅ |
-| `basic` | Retrieve BASIC references and snippets from the local knowledge base. | — | — | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `asm` | Retrieve 6502/6510 assembly references from the local knowledge base. | `q` | `k=3` | — | ✅ | ✅ |
+| `basic` | Retrieve BASIC references and snippets from the local knowledge base. | `q` | `k=3` | — | ✅ | ✅ |
 
 #### c64_select_backend
 
 Switch the active backend between C64U hardware and the VICE emulator at runtime.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `select` | Switch the active runtime backend without restarting the MCP server. | — | — | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `select` | Switch the active runtime backend without restarting the MCP server. | `backend` | — | — | ✅ | ✅ |
 
 #### c64_sound
 
 Grouped entry point for SID control, playback, composition, and analysis workflows.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `analyze` | Automatically analyze SID playback when verification is requested. | — | supports verify | ✅ |  |
-| `capture_samples` | Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. | — | supports verify | ✅ |  |
-| `compile_play` | Compile SIDWAVE or CPG source and optionally play it immediately. | — | supports verify | ✅ | ✅ |
-| `generate` | Generate a lightweight SID arpeggio playback sequence. | — | supports verify | ✅ | ✅ |
-| `note_off` | Release a SID voice by clearing its gate bit. | — | supports verify | ✅ | ✅ |
-| `note_on` | Trigger a SID voice with configurable waveform, ADSR, and pitch. | — | supports verify | ✅ | ✅ |
-| `pipeline` | Compile a SIDWAVE score, play it, and analyze the recording. | — | supports verify | ✅ |  |
-| `play_mod_file` | Play a MOD tracker module via the Ultimate SID player. | — | supports verify | ✅ |  |
-| `play_preset` | Compile and play a built-in SID preset such as Für Elise by Beethoven. | — | supports verify | ✅ | ✅ |
-| `play_sid_file` | Play a SID file stored on the Ultimate filesystem. | — | supports verify | ✅ |  |
-| `record_analyze` | Record audio for a fixed duration and return SID analysis metrics. | — | supports verify | ✅ |  |
-| `reset` | Soft or hard reset of SID registers to clear glitches. | — | supports verify | ✅ | ✅ |
-| `set_volume` | Set the SID master volume register at $D418 (0-15). | — | supports verify | ✅ | ✅ |
-| `silence_all` | Silence all SID voices with optional audio verification. | — | supports verify | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `analyze` | Automatically analyze SID playback when verification is requested. | `request` | `durationSeconds`, `expectedSidwave` | — | ✅ |  |
+| `capture_samples` | Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. | — | `count=256`, `encoding="base64"` | — | ✅ |  |
+| `compile_play` | Compile SIDWAVE or CPG source and optionally play it immediately. | — | `sidwave`, `cpg`, `format`, `output="prg"`, `dryRun=false` | — | ✅ | ✅ |
+| `generate` | Generate a lightweight SID arpeggio playback sequence. | — | `root="C4"`, `pattern="0,4,7"`, `steps=16`, `tempoMs=120`, `waveform="tri"`, `preset="classic"` | — | ✅ | ✅ |
+| `note_off` | Release a SID voice by clearing its gate bit. | `voice` | — | — | ✅ | ✅ |
+| `note_on` | Trigger a SID voice with configurable waveform, ADSR, and pitch. | — | `voice=1`, `note`, `frequencyHz`, `system="PAL"`, `waveform="pulse"`, `pulseWidth=2048`, `attack=1`, `decay=1`, `sustain=15`, `release=3` | — | ✅ | ✅ |
+| `pipeline` | Compile a SIDWAVE score, play it, and analyze the recording. | — | `sidwave`, `cpg`, `output="prg"`, `waitBeforeCaptureMs=500`, `analysisDurationSeconds=3`, `expectedSidwave`, `verifySilenceBefore=true`, `verifySilenceAfter=true`, `silenceDurationSeconds=1.5`, `silenceRmsThreshold=0.02`, `postSilenceWaitMs=200`, `silenceWaitMs=150` | supports verify | ✅ |  |
+| `play_mod_file` | Play a MOD tracker module via the Ultimate SID player. | `path` | — | — | ✅ |  |
+| `play_preset` | Compile and play a built-in SID preset such as Für Elise by Beethoven. | — | `preset="fuer_elise"`, `platforms`, `verify=true`, `analysisDurationSeconds=4`, `waitBeforeCaptureMs=400`, `restoreActiveBackend=true` | supports verify | ✅ | ✅ |
+| `play_sid_file` | Play a SID file stored on the Ultimate filesystem. | `path` | `songnr` | — | ✅ |  |
+| `record_analyze` | Record audio for a fixed duration and return SID analysis metrics. | `durationSeconds` | `expectedSidwave` | — | ✅ |  |
+| `reset` | Soft or hard reset of SID registers to clear glitches. | — | `hard=false` | — | ✅ | ✅ |
+| `set_volume` | Set the SID master volume register at $D418 (0-15). | `volume` | — | — | ✅ | ✅ |
+| `silence_all` | Silence all SID voices with optional audio verification. | — | `verify=false` | supports verify | ✅ | ✅ |
 
 #### c64_stream
 
 Grouped entry point for starting and stopping Ultimate streaming sessions.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `start` | Start an Ultimate streaming session toward a host:port target. | — | — | ✅ |  |
-| `stop` | Stop an active Ultimate streaming session. | — | — | ✅ |  |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `start` | Start an Ultimate streaming session toward a host:port target. | `stream`, `target` | — | — | ✅ |  |
+| `stop` | Stop an active Ultimate streaming session. | `stream` | — | — | ✅ |  |
 
 #### c64_system
 
 Grouped entry point for power, reset, menu, and background task control.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `list_tasks` | List known background tasks with status metadata. | — | — | ✅ | ✅ |
-| `menu` | Toggle the Ultimate menu button for navigation. | — | — | ✅ |  |
-| `pause` | Pause the machine until resumed. | — | — | ✅ |  |
-| `performance_report` | Summarize diagnostics spans and tool latencies from the current or latest MCP session. | — | — | ✅ | ✅ |
-| `poweroff` | Request a controlled shutdown via the Ultimate firmware. | — | — | ✅ | ✅ |
-| `reboot` | Trigger a firmware reboot to recover from faults. | — | — | ✅ | ✅ |
-| `reset` | Issue a soft reset without cutting power. | — | — | ✅ | ✅ |
-| `resume` | Resume CPU execution after a pause. | — | — | ✅ |  |
-| `start_task` | Start a named background task that runs on an interval. | — | — | ✅ | ✅ |
-| `stop_all_tasks` | Stop every running background task and persist state. | — | — | ✅ | ✅ |
-| `stop_task` | Stop a specific background task and clear its timer. | — | — | ✅ | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `list_tasks` | List known background tasks with status metadata. | — | — | — | ✅ | ✅ |
+| `menu` | Toggle the Ultimate menu button for navigation. | — | — | — | ✅ |  |
+| `pause` | Pause the machine until resumed. | — | — | — | ✅ |  |
+| `performance_report` | Summarize diagnostics spans and tool latencies from the current or latest MCP session. | — | `scope="current"`, `includeTimeline=true`, `maxEntries=25` | — | ✅ | ✅ |
+| `poweroff` | Request a controlled shutdown via the Ultimate firmware. | — | — | — | ✅ | ✅ |
+| `reboot` | Trigger a firmware reboot to recover from faults. | — | — | — | ✅ | ✅ |
+| `reset` | Issue a soft reset without cutting power. | — | — | — | ✅ | ✅ |
+| `resume` | Resume CPU execution after a pause. | — | — | — | ✅ |  |
+| `start_task` | Start a named background task that runs on an interval. | `name`, `operation` | `arguments={}`, `intervalMs=1000`, `maxIterations` | — | ✅ | ✅ |
+| `stop_all_tasks` | Stop every running background task and persist state. | — | — | — | ✅ | ✅ |
+| `stop_task` | Stop a specific background task and clear its timer. | `name` | — | — | ✅ | ✅ |
 
 #### c64_vice
 
 Grouped entry point for reading and updating selected VICE resources.
 
-| Operation | Description | Required Inputs | Notes | C64U | VICE |
-| --- | --- | --- | --- | --- | --- |
-| `resource_get` | Read a VICE configuration resource (safe prefixes only). | — | — |  | ✅ |
-| `resource_set` | Write a VICE configuration resource (safe prefixes only). | — | — |  | ✅ |
+| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
+| --- | --- | --- | --- | --- | --- | --- |
+| `resource_get` | Read a VICE configuration resource (safe prefixes only). | `name` | — | — |  | ✅ |
+| `resource_set` | Write a VICE configuration resource (safe prefixes only). | `name`, `value` | — | — |  | ✅ |
 
 ### Resources
 

package/data/assembly/assembly-spec.md

@@ -506,4 +506,4 @@ Screen-code conversion
 
 - If input is ASCII uppercase 'A'..'Z', convert: screen = PETSCII - $40 (e.g. $41→$01). Implement in a small loop if needed.
 
-This file is intentionally minimal: use `basicConverter` / `assemblyConverter` in `src/` for tokenization/PRG building and `data/graphics/character-set.csv` for exact screen-code mappings.
+This file is intentionally minimal: use `src/tools/basicTokenizer.ts` / `src/tools/assembler.ts` for tokenization/PRG building and `data/graphics/character-set.csv` for exact screen-code mappings.

package/data/context/bootstrap.md

@@ -17,12 +17,12 @@ Do not assume the current backend is correct without checking
 
 ## 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" }`.
+- Grouped MCP tools are never called bare. For tools such as `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, and `c64_system`, call the tool with flat arguments that include `op`.
+- Wrong: `c64_program {}` or `{ "c64_program": { "op": "cross_platform_greeting" } }`. Correct: call tool `c64_program` with `{ "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.
+- Use manual `c64_select_backend` with `op: "select"` plus `c64_program` with `op: "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.
 

package/data/context/fast-paths.md

@@ -27,6 +27,8 @@ Use these routing shortcuts when the user wants a quick visible or audible resul
 
 Example:
 
+Call tool `c64_sound` with:
+
 ```json
 {
   "op": "play_preset",
@@ -41,4 +43,4 @@ Example:
 ## 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.
+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

@@ -63,7 +63,7 @@ Conversion: Screen code ≠ PETSCII code. Use charset reference (c64://graphics/
 
 - BASIC/printing: Use PETSCII codes with CHR$() or PRINT
 - Direct screen memory: Use screen codes with POKE to $0400+offset
-- Tools: `c64_graphics` (`render_petscii_art`) returns both `petsciiCodes` array and screen memory data
+- Tools: `c64_graphics` with `op: "render_petscii_art"` returns both `petsciiCodes` array and screen memory data
 
 ## Essential PETSCII Symbols
 

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/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"