c64bridge 0.8.1 → 0.9.0

package/.github/prompts/steer.prompt.md

@@ -0,0 +1,55 @@
+ROLE
+
+You are an execution-focused engineering agent operating inside an active repository with an existing PLANS.md and WORKLOG.md.
+
+You are in a live execution session. Your primary responsibility is to maintain forward progress while applying tightly scoped steering changes without disrupting the current plan.
+
+OBJECTIVE
+
+Apply a small, well-defined refinement to the system while preserving momentum and respecting the current execution state.
+
+PROCESS
+
+1. Read the current PLANS.md and identify the active execution context.
+2. Do NOT replace, rewrite, or restructure the plan.
+3. Append a new TODO item to PLANS.md that captures the steering instruction provided after `/steer`.
+4. Treat this TODO as part of the current plan, not a separate phase.
+5. Execute the TODO immediately after appending it.
+6. Continue executing the remaining plan without interruption.
+
+CONSTRAINTS
+
+- Treat the steering input as a minimal refinement, not a redesign.
+- Prefer the smallest possible change set.
+- Do not introduce unrelated changes.
+- Do not refactor broadly unless explicitly required by the steering input.
+- Preserve all existing behavior unless the steering explicitly requires a change.
+- Do not rename commands, files, or interfaces unless explicitly instructed.
+- Do not reset context or restart the implementation.
+
+VALIDATION
+
+- Ensure no regressions are introduced.
+- Verify that existing commands and workflows behave as before unless explicitly changed.
+- If the change affects user-facing behavior, ensure it remains consistent with intent.
+
+STATE TRACKING
+
+- Append a concise entry to WORKLOG.md including:
+  - what was changed
+  - why it was changed
+  - confirmation of validation
+
+EXECUTION RULES
+
+- Do not stop at analysis. Execute the change.
+- Do not expand scope beyond the steering instruction.
+- Do not declare completion if any part of the appended TODO remains incomplete.
+- Maintain deterministic, verifiable progress.
+
+TERMINATION CONDITION
+
+- The appended TODO has been fully implemented
+- Validation has been performed
+- WORKLOG.md has been updated
+- Execution has resumed on the existing plan

package/AGENTS.md

@@ -74,6 +74,7 @@ If a workflow description starts listing tool calls outside `.github/skills`, tr
 - Discover resources and prompts with ListResources and ListPrompts.
 - Use the matching skill in `.github/skills/` to decide the actual tool sequence, validation, and safety behavior.
 - After discovery has already happened for the active session, prefer execution over repeated rediscovery for unambiguous requests.
+- When the request targets the `vice` backend, read `c64://vice/binary-monitor-spec` before executing so Binary Monitor framing, single-client limits, and trap/resume side effects are in scope.
 - Treat `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, `c64_system`, `c64_config`, `c64_rag`, `c64_extract`, and similar grouped MCP tools as discriminated unions: every direct call must include `op`.
 - Never call a grouped tool with `{}` or with only secondary arguments. Choose the sub-operation first, then send `{ op: "...", ... }`.
 - When a skill tells you to execute a grouped tool, copy the exact `op` string from the skill instead of inferring it from the tool name.
@@ -113,13 +114,14 @@ Tools and parameters are listed dynamically via ListTools.
 
 Use ListResources to discover built-in knowledge, then read specific URIs to enrich context before coding:
 
-- `c64://specs/basic` — BASIC v2 tokens, syntax, device I/O
-- `c64://specs/assembly` — 6510 opcodes, addressing, zero-page strategy
-- `c64://specs/vic` — raster timing, sprites, colour RAM, bitmap modes
-- `c64://specs/sid` — SID registers, waveforms, ADSR
-- `c64://specs/memory-map` — full 64 KB address map
-- `c64://docs/basic/pitfalls` — quoting, line length, token pitfalls
-- `c64://docs/petscii-style` — readable PETSCII, colour/dither guidance
+- `c64://basic/spec` — BASIC v2 tokens, syntax, device I/O
+- `c64://assembly/6510-spec` — 6510 opcodes, addressing, zero-page strategy
+- `c64://graphics/vic/spec` — raster timing, sprites, colour RAM, bitmap modes
+- `c64://sound/sid/spec` — SID registers, waveforms, ADSR
+- `c64://memory/map` — full 64 KB address map
+- `c64://vice/binary-monitor-spec` — mandatory reference when targeting VICE; covers Binary Monitor transport, command framing, and debugger side effects
+- `c64://basic/pitfalls` — quoting, line length, token pitfalls
+- `c64://graphics/petscii/style-guide` — readable PETSCII, colour/dither guidance
 
 Pull RAG snippets via `c64_rag` (ops `basic`/`asm`) for targeted examples.
 

package/README.md

@@ -10,10 +10,20 @@ Your AI Command Bridge for the Commodore 64.
 [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
 [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-forestgreen)](doc/developer.md)
 
-C64 Bridge is a Model Context Protocol ([MCP](https://modelcontextprotocol.io/docs/getting-started/intro)) server for controlling a real Commodore 64 Ultimate or Ultimate 64, and for switching into a VICE emulator session when you want emulator-backed workflows in the same MCP conversation.
+[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=io.github.chrisgleissner%2Fc64bridge&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=io.github.chrisgleissner%2Fc64bridge&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D&quality=insiders)
+[![Install in Visual Studio](https://img.shields.io/badge/Install_in-Visual_Studio-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D)
+[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=io.github.chrisgleissner%2Fc64bridge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImM2NGJyaWRnZSJdLCJlbnYiOnsiQzY0X01PREUiOiJjNjR1IiwiQzY0VV9IT1NUIjoiYzY0dSIsIlZJQ0VfQklOQVJZIjoiL3Vzci9sb2NhbC9iaW4veDY0c2MiLCJWSUNFX0RJUkVDVE9SWSI6Ii91c3IvbG9jYWwvc2hhcmUvdmljZSIsIlZJQ0VfVklTSUJMRSI6InRydWUiLCJWSUNFX1dBUlAiOiJmYWxzZSJ9fQ==)
+[![Use with Claude Code](https://img.shields.io/badge/Use_with-Claude_Code-D97757?style=flat-square&logo=anthropic&logoColor=white)](#claude-code)
+
+C64 Bridge is an MCP server for controlling and working with a Commodore 64 from an AI client.
+
+It lets you run programs, read and write memory, render graphics, and play sound on a real [Commodore 64 Ultimate](https://www.commodore.net/) or [Ultimate 64](https://ultimate64.com/). You can also switch to a [VICE](https://vice-emu.sourceforge.io/) emulator session at any time, so the same MCP conversation works with both hardware and emulator.
 
 It is built on the official TypeScript `@modelcontextprotocol/sdk` and supports both `stdio` for local AI integration and an optional HTTP bridge for manual inspection.
 
+C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io/?q=c64bridge).
+
 ## Contents
 
 - [C64 Bridge](#c64-bridge)
@@ -43,6 +53,7 @@ It is built on the official TypeScript `@modelcontextprotocol/sdk` and supports
       - [SID Playback](#sid-playback)
       - [RAG](#rag)
       - [Testing](#testing)
+  - [Claude Code](#claude-code)
   - [Example Workflow](#example-workflow)
   - [HTTP Invocation](#http-invocation)
   - [Build and Test](#build-and-test)
@@ -182,9 +193,14 @@ The detailed lookup order, merge rules, backend examples, and override model are
 
 ### 4. Connect from an MCP Client
 
-If you use VS Code, follow the [VS Code MCP Setup](#vs-code-mcp-setup) section below.
+C64 Bridge ships a single canonical `stdio` entry point that every MCP client uses:
 
-If you use another MCP client, point it at the `stdio` server entry point and pass any required environment variables exactly as documented in this README and in [mcp.json](./mcp.json).
+- **VS Code (GitHub Copilot)** — see [VS Code MCP Setup](#vs-code-mcp-setup).
+- **Claude Code (CLI and VS Code plugin)** — see [Claude Code](#claude-code).
+- **Cursor, Visual Studio, VS Code Insiders** — use the install badges at the top of this README.
+- **Any other MCP client** — point it at the same `stdio` server, with the environment variables documented in [Runtime Environment Variable Reference](#runtime-environment-variable-reference) and the registry manifest in [mcp.json](./mcp.json).
+
+The startup command is the same across clients: `npx -y c64bridge@latest` for the published package, or `node scripts/start.mjs` from a local checkout. Backend selection (`c64u` vs `vice`) and credentials live in the shared [Configuration](#configuration) files and environment variables — clients only need to know the command.
 
 ## Configuration
 
@@ -235,8 +251,8 @@ Use this for managed VICE launches:
 }
 ```
 
-- `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.
+- `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.
 - 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]
@@ -268,6 +284,8 @@ The screenshots below were captured from actual backend bitmap responses after t
 
 ## VS Code MCP Setup
 
+This section covers the GitHub Copilot integration that ships with VS Code. For the Claude Code VS Code plugin, see [Claude Code](#claude-code) — it reads `.mcp.json`, not `.vscode/mcp.json`.
+
 If this repository is checked out locally, open the prepared [.vscode/mcp.json](./.vscode/mcp.json).
 
 Otherwise, put the following into your own `.vscode/mcp.json`:
@@ -430,8 +448,8 @@ Every runtime environment variable documented in `mcp.json` can be set in your M
 | `DISABLE_XVFB` | 0 | — | Set to 1 to disable Xvfb fallback and use the current display only |
 | `FORCE_XVFB` | 0 | — | Set to 1 to force managed VICE launches to run under Xvfb |
 | `VICE_ARGS` |  | vice.args | Extra command-line arguments forwarded to managed VICE launches |
-| `VICE_BINARY` | x64sc | vice.exe | VICE binary to launch for managed emulator sessions and audio capture |
-| `VICE_DIRECTORY` | auto-detect | vice.directory | Override the VICE resource directory used for ROM and UI asset discovery |
+| `VICE_BINARY` | x64sc | vice.exe | VICE binary to launch for managed emulator sessions and audio capture; automatic search is used only when this override is missing or invalid |
+| `VICE_DIRECTORY` | auto-detect | vice.directory | Override the VICE resource directory used for ROM and UI asset discovery; automatic search is used only when this override is missing or invalid |
 | `VICE_HOST` | 127.0.0.1 | vice.host | Override the VICE Binary Monitor host |
 | `VICE_PORT` | 6502 | vice.port | Override the VICE Binary Monitor port |
 | `VICE_VISIBLE` | true | vice.visible | Launch VICE visibly on the desktop instead of headless/Xvfb when possible |
@@ -474,6 +492,24 @@ Every runtime environment variable documented in `mcp.json` can be set in your M
 
 <!-- AUTO-GENERATED:ENV-VARS-END -->
 
+## Claude Code
+
+[Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) is supported as a first-class MCP client. It uses the same canonical start command and the same backend [Configuration](#configuration) files and environment variables as every other client — only the discovery file differs.
+
+**Claude Code CLI** — register the published server in one command:
+
+```bash
+claude mcp add c64bridge -- npx -y c64bridge@latest
+```
+
+Use `--scope user` to make it available across all your projects, or `--scope project` to write a `.mcp.json` next to the current repo. Backend selection (`c64u` vs `vice`), host, port, and password come from the same files documented in [Configuration](#configuration); per-shell overrides come from the variables in [Runtime Environment Variable Reference](#runtime-environment-variable-reference).
+
+**Project-scoped discovery** — this repository ships a checked-in [.mcp.json](./.mcp.json) that points Claude Code at the local source via `node scripts/start.mjs`. When you open the repo with `claude` (CLI or VS Code plugin), Claude Code prompts to enable the project-scoped server on first run. Approve it once and the `c64_*` tools become discoverable in that workspace.
+
+**Claude Code VS Code plugin** — the plugin reads the same `.mcp.json` and the same user-scope `claude mcp add` registrations as the CLI. No extra setup is required beyond installing the plugin and approving the project server prompt. The existing [.vscode/mcp.json](./.vscode/mcp.json) is read by GitHub Copilot, not by Claude Code; the two files coexist without conflict because they target different clients with different config schemas.
+
+**Verify it works** — after registration, run `claude mcp list` (CLI) or open the MCP panel (plugin) and look for `c64bridge`. Then ask Claude Code something like *“use vice: write a small BASIC program that clears the screen and prints HELLO CLAUDE”* — it should call `c64_select_backend` and `c64_program` directly. If tools do not appear, confirm Node 24+ is on `PATH`, that the server was approved at the requested scope, and that the backend is reachable per the [Configuration](#configuration) section.
+
 ## Example Workflow
 
 Compose a children’s song with ChatGPT and VS Code:
@@ -525,14 +561,22 @@ 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
@@ -563,20 +607,20 @@ 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. | `path` | — | ✅ | ✅ |
-| `get` | Read a configuration category or specific item. | `category` | — | ✅ | ✅ |
+| `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. | `path` | — | ✅ | ✅ |
+| `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. | `category`, `item`, `value` | — | ✅ | ✅ |
+| `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. | `path` | — | ✅ | ✅ |
+| `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). | `value` | — | ✅ |  |
+| `write_debugreg` | Write a hex value to the Ultimate debug register ($D7FF). | — | — | ✅ |  |
 
 #### c64_debug
 
@@ -584,17 +628,17 @@ Grouped entry point for VICE debugger operations (breakpoints, registers, steppi
 
 | Operation | Description | Required Inputs | Notes | C64U | VICE |
 | --- | --- | --- | --- | --- | --- |
-| `create_checkpoint` | Create a new checkpoint (breakpoint) in VICE. | `address` | — |  | ✅ |
-| `delete_checkpoint` | Remove a checkpoint by id. | `id` | — |  | ✅ |
-| `get_checkpoint` | Fetch a single checkpoint by id. | `id` | — |  | ✅ |
+| `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. | `id`, `expression` | — |  | ✅ |
-| `set_registers` | Write register values. | `writes` | — |  | ✅ |
+| `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. | `id`, `enabled` | — |  | ✅ |
+| `toggle_checkpoint` | Enable or disable a checkpoint by id. | — | — |  | ✅ |
 
 #### c64_disk
 
@@ -602,12 +646,12 @@ Grouped entry point for disk mounts, listings, image creation, and program disco
 
 | Operation | Description | Required Inputs | Notes | C64U | VICE |
 | --- | --- | --- | --- | --- | --- |
-| `create_image` | Create a blank disk image of the specified format. | `format`, `path` | — | ✅ |  |
-| `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` | — | ✅ |  |
-| `list_drives` | List Ultimate drive slots and their mounted images. | — | — | ✅ | ✅ |
-| `mount` | Mount a disk image with optional verification and retries. | `drive`, `image` | supports verify | ✅ | ✅ |
-| `unmount` | Remove the mounted image from an Ultimate drive slot. | `drive` | — | ✅ | ✅ |
+| `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 | ✅ | ✅ |
 
 #### c64_drive
 
@@ -615,11 +659,11 @@ 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. | `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` | — | ✅ | ✅ |
+| `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). | — | — | ✅ | ✅ |
 
 #### c64_extract
 
@@ -630,8 +674,8 @@ Grouped entry point for sprite/charset extraction, memory dumps, filesystem stat
 | `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. | `address`, `length`, `outputPath` | — | ✅ |  |
-| `sprites` | Scan RAM for sprites and optionally export .spr files. | `address`, `length` | — | ✅ |  |
+| `memory_dump` | Dump a RAM range to hex or binary files with manifest metadata. | — | — | ✅ |  |
+| `sprites` | Scan RAM for sprites and optionally export .spr files. | — | — | ✅ |  |
 
 #### c64_graphics
 
@@ -640,10 +684,10 @@ 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. | `imagePath`, `format` | — | ✅ | ✅ |
+| `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. | `text` | — | ✅ | ✅ |
-| `render_sprite` | Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. | `sprite` | — | ✅ | ✅ |
+| `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. | — | — | ✅ | ✅ |
 
 #### c64_memory
 
@@ -651,10 +695,10 @@ 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. | `address` | — | ✅ | ✅ |
-| `read_screen` | Return the current 40x25 text screen converted to ASCII. | — | — | ✅ | ✅ |
-| `wait_for_text` | Poll the screen until a substring or regex appears, or timeout elapses. | `pattern` | — | ✅ | ✅ |
-| `write` | Write a hexadecimal byte sequence into RAM. | `address`, `bytes` | supports verify | ✅ | ✅ |
+| `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 | ✅ | ✅ |
 
 #### c64_printer
 
@@ -662,9 +706,9 @@ 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). | `firstChar`, `chars` | — | ✅ |  |
-| `print_bitmap` | Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows. | `printer`, `columns` | — | ✅ |  |
-| `print_text` | Generate BASIC that prints text to device 4. | `text` | — | ✅ |  |
+| `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. | — | — | ✅ |  |
 
 #### c64_program
 
@@ -672,14 +716,14 @@ 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. | `programs` | — | ✅ | ✅ |
-| `bundle_run` | Capture screen, memory, and debug registers into an artifact bundle. | `runId`, `outputPath` | — | ✅ |  |
+| `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. | `path` | — | ✅ |  |
-| `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` | — | ✅ | ✅ |
-| `upload_run_asm` | Assemble 6502/6510 source, upload the PRG, and execute it. | `program` | supports verify | ✅ | ✅ |
-| `upload_run_basic` | Upload Commodore BASIC v2 source and execute it immediately. | `program` | 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 | ✅ | ✅ |
 
 #### c64_rag
 
@@ -687,8 +731,8 @@ 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. | `q` | — | ✅ | ✅ |
-| `basic` | Retrieve BASIC references and snippets from the local knowledge base. | `q` | — | ✅ | ✅ |
+| `asm` | Retrieve 6502/6510 assembly references from the local knowledge base. | — | — | ✅ | ✅ |
+| `basic` | Retrieve BASIC references and snippets from the local knowledge base. | — | — | ✅ | ✅ |
 
 #### c64_select_backend
 
@@ -696,7 +740,7 @@ 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. | `backend` | — | ✅ | ✅ |
+| `select` | Switch the active runtime backend without restarting the MCP server. | — | — | ✅ | ✅ |
 
 #### c64_sound
 
@@ -704,19 +748,19 @@ Grouped entry point for SID control, playback, composition, and analysis workflo
 
 | Operation | Description | Required Inputs | Notes | C64U | VICE |
 | --- | --- | --- | --- | --- | --- |
-| `analyze` | Automatically analyze SID playback when verification is requested. | `request` | — | ✅ |  |
-| `capture_samples` | Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. | — | — | ✅ |  |
-| `compile_play` | Compile SIDWAVE or CPG source and optionally play it immediately. | — | — | ✅ | ✅ |
-| `generate` | Generate a lightweight SID arpeggio playback sequence. | — | — | ✅ | ✅ |
-| `note_off` | Release a SID voice by clearing its gate bit. | `voice` | — | ✅ | ✅ |
-| `note_on` | Trigger a SID voice with configurable waveform, ADSR, and pitch. | — | — | ✅ | ✅ |
+| `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. | `path` | — | ✅ |  |
+| `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. | `path` | — | ✅ |  |
-| `record_analyze` | Record audio for a fixed duration and return SID analysis metrics. | `durationSeconds` | — | ✅ |  |
-| `reset` | Soft or hard reset of SID registers to clear glitches. | — | — | ✅ | ✅ |
-| `set_volume` | Set the SID master volume register at $D418 (0-15). | `volume` | — | ✅ | ✅ |
+| `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 | ✅ | ✅ |
 
 #### c64_stream
@@ -725,8 +769,8 @@ 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. | `stream`, `target` | — | ✅ |  |
-| `stop` | Stop an active Ultimate streaming session. | `stream` | — | ✅ |  |
+| `start` | Start an Ultimate streaming session toward a host:port target. | — | — | ✅ |  |
+| `stop` | Stop an active Ultimate streaming session. | — | — | ✅ |  |
 
 #### c64_system
 
@@ -742,9 +786,9 @@ Grouped entry point for power, reset, menu, and background task control.
 | `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` | — | ✅ | ✅ |
+| `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. | `name` | — | ✅ | ✅ |
+| `stop_task` | Stop a specific background task and clear its timer. | — | — | ✅ | ✅ |
 
 #### c64_vice
 
@@ -752,39 +796,39 @@ 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). | `name` | — |  | ✅ |
-| `resource_set` | Write a VICE configuration resource (safe prefixes only). | `name`, `value` | — |  | ✅ |
+| `resource_get` | Read a VICE configuration resource (safe prefixes only). | — | — |  | ✅ |
+| `resource_set` | Write a VICE configuration resource (safe prefixes only). | — | — |  | ✅ |
 
 ### Resources
 
 | Name | Summary |
 | --- | --- |
-| `c64://docs/index` | Explains how to approach each knowledge bundle and when to consult it. |
-| `c64://context/bootstrap` | Step-by-step rules for safe automation, verification, and rollback on the C64. |
-| `c64://context/fast-paths` | Condensed routing guide for one-call demos, backend switching, and when to prefer orchestration over manual tool composition. |
-| `c64://specs/basic` | Token definitions, syntax rules, and device I/O guidance for BASIC v2. |
-| `c64://docs/basic/pitfalls` | Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps. |
-| `c64://specs/assembly` | Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU. |
-| `c64://specs/sid` | Register map, waveform behaviour, and ADSR envelopes for expressive SID playback. |
-| `c64://specs/sidwave` | Defines the SIDWAVE interchange format used by the SID composer workflow. |
-| `c64://docs/sid/file-structure` | Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music. |
-| `c64://docs/sid/best-practices` | Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music. |
-| `c64://specs/vic` | Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II. |
-| `c64://specs/charset` | Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input. |
-| `c64://docs/petscii-style` | Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays. |
-| `c64://docs/sprite-charset-workflows` | Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics. |
-| `c64://specs/memory-map` | Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions. |
-| `c64://specs/memory-low` | Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses. |
-| `c64://specs/memory-kernal` | Lists KERNAL ROM vectors and service routines for OS-level functionality. |
-| `c64://specs/io` | Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes. |
-| `c64://specs/cia` | Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout. |
-| `c64://specs/printer` | Covers device setup, control codes, and Ultimate 64 integration for printers. |
-| `c64://docs/printer/guide` | Quick-look workflow covering setup, troubleshooting, and sample jobs for both printer families. |
-| `c64://docs/printer/commodore-text` | Character sets, control codes, and formatting for Commodore MPS text output. |
-| `c64://docs/printer/commodore-bitmap` | Details bitmap modes, graphics commands, and data layout for MPS bitmap printing. |
-| `c64://docs/printer/epson-text` | Lists ESC/P control codes and formatting advice for Epson FX text output. |
-| `c64://docs/printer/epson-bitmap` | Explains bit-image modes, density options, and data packing for Epson bitmap jobs. |
-| `c64://docs/printer/prompts` | Reusable prompt templates that drive complex printer jobs through the MCP server. |
+| `c64://guide/index` | Explains how to approach each knowledge bundle and when to consult it. |
+| `c64://guide/bootstrap` | Step-by-step rules for safe automation, verification, and rollback on the C64. |
+| `c64://guide/fast-paths` | Condensed routing guide for one-call demos, backend switching, and when to prefer orchestration over manual tool composition. |
+| `c64://vice/binary-monitor-spec` | Transport framing, single-client constraints, command semantics, and monitor side effects that shape all VICE-backed operations. |
+| `c64://basic/spec` | Token definitions, syntax rules, and device I/O guidance for BASIC v2. |
+| `c64://basic/pitfalls` | Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps. |
+| `c64://assembly/6510-spec` | Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU. |
+| `c64://sound/sid/spec` | Register map, waveform behaviour, and ADSR envelopes for expressive SID playback. |
+| `c64://sound/sidwave/spec` | Defines the SIDWAVE interchange format used by the SID composer workflow. |
+| `c64://sound/sid/file-format` | Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music. |
+| `c64://sound/sid/best-practices` | Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music. |
+| `c64://graphics/vic/spec` | Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II. |
+| `c64://graphics/character-set` | Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input. |
+| `c64://graphics/petscii/style-guide` | Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays. |
+| `c64://graphics/sprite-charset/best-practices` | Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics. |
+| `c64://memory/map` | Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions. |
+| `c64://memory/zero-page-and-workspace` | Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses. |
+| `c64://kernal/rom-routines` | Lists KERNAL ROM vectors and service routines for OS-level functionality. |
+| `c64://io/spec` | Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes. |
+| `c64://io/cia/spec` | Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout. |
+| `c64://printer/spec` | Covers device setup, control codes, and Ultimate 64 integration for printers. |
+| `c64://printer/commodore/text` | Character sets, control codes, and formatting for Commodore MPS text output. |
+| `c64://printer/commodore/bitmap` | Details bitmap modes, graphics commands, and data layout for MPS bitmap printing. |
+| `c64://printer/epson/text` | Lists ESC/P control codes and formatting advice for Epson FX text output. |
+| `c64://printer/epson/bitmap` | Explains bit-image modes, density options, and data packing for Epson bitmap jobs. |
+| `c64://printer/prompt-guide` | Reusable prompt templates that drive complex printer jobs through the MCP server. |
 
 ### Prompts