c64bridge 0.9.1 → 0.9.3

package/AGENTS.md

@@ -115,12 +115,17 @@ 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://basic/spec` — BASIC v2 tokens, syntax, device I/O
+- `c64://basic/rom-routines` — BASIC ROM routines, parser/evaluator helpers, numeric/string machinery
 - `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://memory/zero-page-and-workspace` — zero page, stack, page-2 buffers, page-3 vectors
 - `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://kernal/rom-routines` — KERNAL ROM routines, jump table, vectors, serial/tape/screen services
+- `c64://io/spec` — memory-mapped VIC-II, SID, CIA, colour RAM, and expansion I/O registers
+- `c64://io/cia/spec` — CIA timers, keyboard matrix, serial bus, TOD, IRQ/NMI details
 - `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

@@ -14,6 +14,7 @@ Your AI Command Bridge for the Commodore 64.
 [![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.
 
@@ -39,6 +40,8 @@ C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontex
     - [Configuration Merge Rules](#configuration-merge-rules)
     - [Backend Configuration: C64 Ultimate](#backend-configuration-c64-ultimate)
     - [Backend Configuration: VICE](#backend-configuration-vice)
+      - [VICE Window Modes](#vice-window-modes)
+      - [Recommended VICE Configurations](#recommended-vice-configurations)
     - [Runtime Backend Switching](#runtime-backend-switching)
   - [VS Code MCP Setup](#vs-code-mcp-setup)
     - [Enable the C64 Agent](#enable-the-c64-agent)
@@ -52,6 +55,7 @@ C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontex
       - [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)
@@ -59,12 +63,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)
@@ -191,9 +197,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
 
@@ -233,7 +244,7 @@ Use this for a C64 Ultimate or Ultimate 64:
 
 ### Backend Configuration: VICE
 
-Use this for managed VICE launches:
+C64 Bridge can either connect to an already running VICE Binary Monitor or manage a local VICE process for you. The usual managed setup only needs the emulator binary and, when auto-detection cannot find it, the VICE resource directory:
 
 ```json
 {
@@ -244,9 +255,69 @@ Use this for managed VICE launches:
 }
 ```
 
+- `exe` is optional when `x64sc` or `x64` is on `PATH`. If no explicit binary is configured, the runtime prefers `/usr/local/bin/x64sc` when present, then falls back to `x64sc` or `x64` on `PATH`.
 - `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.
+- `host` and `port` are optional and default to `127.0.0.1:6502`, the Binary Monitor endpoint C64 Bridge starts for managed local sessions. On local endpoints, C64 Bridge first tries to reuse an already running monitor before starting its own process.
+- `visible`, `warp`, and `args` are optional runtime controls. They can live in JSON config, but most users set their environment-variable equivalents from the MCP client because they are per-session preferences.
+- By default, VICE is started lazily on first access. When setting the environment variable `VICE_PREWARM=1`, C64 Bridge starts or connects VICE in the background during MCP startup.
+- `VICE_BINARY`, `VICE_DIRECTORY`, `VICE_HOST`, `VICE_PORT`, `VICE_VISIBLE`, `VICE_WARP`, `VICE_ARGS`, and `VICE_PREWARM` override the JSON values without editing config files.
+
+#### VICE Window Modes
+
+Choose the window mode based on where the MCP server runs:
+
+| Mode | Configuration | What happens | Use when |
+| --- | --- | --- | --- |
+| Visible | `VICE_VISIBLE=true` | VICE opens a normal desktop window. Warp defaults to off. | You are developing locally and want to watch or interact with the emulator. |
+| Minimized | `VICE_VISIBLE=true`, `VICE_ARGS="-minimized"` | VICE still runs as a normal desktop app, but its window starts iconified. Binary Monitor operations, screen reads, frame capture, and keyboard input continue to work. | You are using an agent locally and do not want the emulator stealing focus, but still want the option to restore the window. |
+| Headless/Xvfb | `VICE_VISIBLE=false` | C64 Bridge launches VICE without a user-facing desktop window, using Xvfb unless disabled. Warp defaults to on. | CI, unattended tests, servers, or any session where no one needs to inspect the emulator window. |
+
+Minimized and headless are not the same thing. Minimized is still a visible desktop session with a real VICE window; it is simply hidden by the window manager at startup. Headless/Xvfb has no user-facing window, so it is better for automation but less convenient when you need to debug by looking at the emulator.
+
+For normal local MCP use, prefer minimized VICE. It avoids focus stealing while preserving the ability to restore the window for visual inspection. Prefer headless/Xvfb for CI and remote or display-less environments.
+
+`FORCE_XVFB=1` forces the Xvfb path even if a graphical session is available. `DISABLE_XVFB=1` disables that fallback and uses the current display, which is mainly useful for troubleshooting display detection.
+
+#### Recommended VICE Configurations
+
+Local agent session, VICE starts minimized:
+
+```json
+{
+  "servers": {
+    "c64bridge": {
+      "command": "npx",
+      "args": ["-y", "c64bridge@latest"],
+      "env": {
+        "C64_MODE": "vice",
+        "VICE_VISIBLE": "true",
+        "VICE_ARGS": "-minimized",
+        "VICE_WARP": "false"
+      }
+    }
+  }
+}
+```
+
+Headless automation, VICE runs without a visible desktop window:
+
+```json
+{
+  "servers": {
+    "c64bridge": {
+      "command": "npx",
+      "args": ["-y", "c64bridge@latest"],
+      "env": {
+        "C64_MODE": "vice",
+        "VICE_VISIBLE": "false",
+        "VICE_WARP": "true"
+      }
+    }
+  }
+}
+```
+
+If VICE is installed outside the usual search paths, add `VICE_BINARY` and, if ROM/resource auto-detection fails, `VICE_DIRECTORY` to either example.
 
 > [!NOTE]
 > VICE supports only the operations marked with a VICE checkmark in the [MCP API Reference](#mcp-api-reference). Unsupported operations return `unsupported_platform`.
@@ -265,6 +336,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
 ```
 
@@ -277,6 +351,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`:
@@ -342,6 +418,8 @@ You can add `env` entries in `.vscode/mcp.json` to select a config file, overrid
 - `C64_MODE` forces the initial backend to `c64u` or `vice`
 - `LOG_LEVEL=debug` enables verbose logging
 
+For VICE-specific overrides such as `VICE_ARGS=-minimized`, `VICE_VISIBLE=false`, or custom VICE paths, use the patterns in [Backend Configuration: VICE](#backend-configuration-vice).
+
 ### Environment Variables in MCP Client Configs
 
 Every runtime environment variable documented in the root [mcp.json](./mcp.json) can be supplied by your MCP client configuration, including `.vscode/mcp.json` under `servers.c64bridge.env`.
@@ -359,7 +437,7 @@ When an environment variable has no JSON config equivalent, the order is:
 
 That rule applies uniformly across the documented runtime environment variables below.
 
-Example: visible VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:
+Example: start on minimized VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:
 
 ```json
 {
@@ -375,6 +453,7 @@ Example: visible VICE with a specific ROM or resource directory, plus a hardware
         "VICE_BINARY": "/usr/local/bin/x64sc",
         "VICE_DIRECTORY": "/usr/local/share/vice",
         "VICE_VISIBLE": "true",
+        "VICE_ARGS": "-minimized",
         "VICE_WARP": "false"
       }
     }
@@ -437,13 +516,14 @@ Every runtime environment variable documented in `mcp.json` can be set in your M
 | Variable | Default | JSON Config Key | Description |
 | --- | --- | --- | --- |
 | `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 |
+| `FORCE_XVFB` | 0 | — | Set to 1 to force managed VICE launches to use Xvfb even when a graphical session is detected |
+| `VICE_ARGS` |  | vice.args | Extra command-line arguments forwarded to managed VICE launches, such as -minimized for a visible window that starts iconified |
 | `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 |
+| `VICE_PREWARM` | 0 | vice.prewarm | Set to 1 to start/connect VICE in the background during MCP startup; disabled by default so VICE starts lazily on first use |
+| `VICE_VISIBLE` | true | vice.visible | Launch VICE as a desktop window when true; use headless/Xvfb managed launch when false |
 | `VICE_WARP` | false when visible, true when headless | vice.warp | Enable warp mode for managed VICE sessions |
 | `VICE_XVFB_DISPLAY` | :99 | — | Display number to use when managed VICE launches under Xvfb |
 
@@ -483,6 +563,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:
@@ -546,10 +644,11 @@ The [`./build`](./build) script at the project root wraps all development tasks
 
 ## Documentation
 
-- [doc/developer.md](doc/developer.md) — development workflow and RAG details
-- [data/context/bootstrap.md](data/context/bootstrap.md) — primer injected ahead of prompts
-- [doc/c64u/c64-openapi.yaml](doc/c64u/c64-openapi.yaml) — REST surface (OpenAPI 3.1)
-- [AGENTS.md](AGENTS.md) — LLM-facing quick setup, usage, and personas
+- [DeepWiki](https://deepwiki.com/chrisgleissner/c64bridge) - architecture and implementation overview
+- [doc/developer.md](doc/developer.md) - development workflow and RAG details
+- [data/context/bootstrap.md](data/context/bootstrap.md) - primer injected ahead of prompts
+- [doc/c64u/c64-openapi.yaml](doc/c64u/c64-openapi.yaml) - REST surface (OpenAPI 3.1)
+- [AGENTS.md](AGENTS.md) - LLM-facing quick setup, usage, and personas
 
 ## Static MCP Interface
 
@@ -561,7 +660,7 @@ This allows agents to inspect the available tools, resources, prompts, and schem
 
 <!-- AUTO-GENERATED:MCP-DOCS-START -->
 
-This MCP server exposes **17 tools**, **26 resources**, and **10 prompts** for controlling your Commodore 64.
+This MCP server exposes **17 tools**, **27 resources**, and **10 prompts** for controlling your Commodore 64.
 
 ### Tools
 
@@ -814,7 +913,8 @@ Grouped entry point for reading and updating selected VICE resources.
 | `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://basic/rom-routines` | Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries. |
+| `c64://kernal/rom-routines` | Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers. |
 | `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. |

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/basic/rom-routines.md

@@ -0,0 +1,269 @@
+# C64 BASIC ROM Routines Memory Map — Compact ($A000-$BFFF, $E000-$E4D2)
+
+> Purpose: Token-efficient reference for Commodore 64 BASIC V2 ROM routines, tables, parser/evaluator helpers, numeric/string machinery, statement/function dispatch, and C64-specific BASIC continuation code.  
+> Format: Address-first tables; **bold** names indicate the most reusable entry points for machine-language or MCP tooling.  
+> Conventions: A=Accumulator, X,Y=Index, C=Carry; “—” = not applicable.
+> Related memory maps: `../memory/memory-map.md`, `../memory/low-memory-map.md`, `../kernal/rom-routines.md`, `../io/io-spec.md`.
+
+## Legend
+
+Class: A=safe helper, B=usable with guardrails, C=interpreter-coupled, D=non-returning/control-flow, data=table/constant.
+
+## Direct-Use Rules
+
+- BASIC ROM must be banked in (`$0001` LORAM+HIRAM set). KERNAL ROM must also be visible for I/O and error reporting.
+- Many failures jump to `$A437` (`ERROR`) rather than returning a status code.
+- Prefer KERNAL APIs for files/devices and dynamic keyboard or tokenized program install for statements.
+- Best reusable BASIC targets: `FRMEVL`, `FRMNUM`, `GETBYT`, `GETADR`, `PTRGET`, `FOUT`, `MOVFM`, `MOVMF`, `LNKPRG`, `CLR`.
+- Avoid direct statement entries unless a wrapper controls `TXTPTR`, stack, BASIC vectors, error recovery, and runtime pointers.
+
+## Essential BASIC State
+
+| Address | Decimal | Name | Function | Notes |
+|:--|:--|:--|:--|:--|
+| `$000C` | 12 | DIMFLG | Array allocation/reference flag | Used by `PTRGET`. |
+| `$000D` | 13 | VALTYP | Current type | `$00` numeric, `$FF` string. |
+| `$000E` | 14 | INTFLG | Numeric subtype | `$00` float, `$80` integer. |
+| `$0014–$0015` | 20–21 | LINNUM | Line/address/number temp | Used by `PEEK`, `POKE`, `WAIT`, `SYS`. |
+| `$0016–$0021` | 22–33 | TEMPPT/TEMPST | Temporary string descriptor stack | Three 3-byte descriptors. |
+| `$002B–$002C` | 43–44 | **TXTTAB** | BASIC program start | Normally `$0801`. |
+| `$002D–$002E` | 45–46 | **VARTAB** | Scalar variable table start | Updated after program changes. |
+| `$002F–$0030` | 47–48 | **ARYTAB** | Array table start | Follows scalars. |
+| `$0031–$0032` | 49–50 | **STREND** | End of arrays / free RAM start | Moves upward. |
+| `$0033–$0034` | 51–52 | **FREETOP** | Bottom of string heap | Strings grow downward. |
+| `$0037–$0038` | 55–56 | **MEMSIZ** | BASIC memory top | Lower then `CLR` to reserve RAM. |
+| `$0039–$003A` | 57–58 | CURLIN | Current BASIC line | High byte `$FF` = direct mode. |
+| `$0041–$0042` | 65–66 | DATPTR | Current DATA item pointer | Reset by `RESTORE`. |
+| `$0045–$0048` | 69–72 | VARNAM/VARPNT | Current variable name/value pointer | Set by `PTRGET`. |
+| `$0050–$0052` | 80–82 | DSCPNT | String descriptor pointer/temp | String functions. |
+| `$0061–$0066` | 97–102 | **FAC1** | Primary floating-point accumulator | Exponent, mantissa, sign. |
+| `$0069–$006E` | 105–110 | FAC2/ARG | Secondary FP accumulator | Arithmetic argument. |
+| `$0070` | 112 | FACOV | FP rounding byte | Used by `ROUND`. |
+| `$0073–$008A` | 115–138 | **CHRGET/CHRGOT** | BASIC scanner in zero page | `CHRGOT` entry at `$0079`. |
+| `$007A–$007B` | 122–123 | **TXTPTR** | BASIC text pointer | Parser/evaluator input. |
+| `$008B–$008F` | 139–143 | RNDX | RND seed | Five-byte FP seed. |
+| `$0300–$030B` | 768–779 | BASIC vectors | Error, warm start, tokenize, LIST, execute, evaluate | Copied from `$E447`. |
+| `$030C–$030F` | 780–783 | SYS save | A, X, Y, status for BASIC `SYS` | Restored after SYS returns. |
+| `$0310–$0311` | 784–785 | USR vector | Target for `USR()` | Default illegal quantity. |
+
+## ROM Landmarks
+
+| Address | Decimal | Name | Function | Class | Notes |
+|:--|:--|:--|:--|:--|:--|
+| `$A000` | 40960 | Cold vector | Points to `$E394` | data | Do not execute as code. |
+| `$A002` | 40962 | Warm vector | Points to `$E37B` | data | BASIC warm start. |
+| `$A004` | 40964 | CBMBASIC | ROM signature | data | Identification text. |
+| `$A00C` | 40972 | Command table | 35 statement addresses minus 1 | data | Token `$80–$A2`. |
+| `$A052` | 41042 | Function table | 23 function addresses minus 1 | data | Token `$B4–$CA`. |
+| `$A080` | 41088 | Operator table | Precedence + address minus 1 | data | Arithmetic, compare, logical. |
+| `$A09E` | 41118 | Keyword table | Statement keywords | data | High bit marks final char. |
+| `$A129` | 41257 | Reserved-word table | `TAB(`, `TO`, `SPC(`, etc. | data | Tokenizer metadata. |
+| `$A140` | 41280 | Operator keyword table | `+ - * / ^ AND OR > = <` | data | Tokenizer metadata. |
+| `$A14D` | 41293 | Function keyword table | `SGN` through `MID$` | data | Tokenizer metadata. |
+| `$A19E` | 41374 | Error text | BASIC error message strings | data | Indexed by `$A328`. |
+| `$A328` | 41768 | Error pointers | Pointers to error text | data | X = error index. |
+| `$A364` | 41828 | Interpreter text | `OK`, `ERROR IN`, `READY`, `BREAK` | data | Screen messages. |
+| `$BFED` | 49133 | EXP | EXP function body | A/B | Continues at `$E000`. |
+| `$E000–$E4D2` | 57344–58578 | BASIC continuation | EXP/RND/trig, I/O wrappers, init, BASIC vectors | mixed | Located in ROM area often grouped with KERNAL. |
+
+## Core Reusable Entries
+
+| Address | Decimal | Name | Function | Args/Input | Output | Class | Notes |
+|:--|:--|:--|:--|:--|:--|:--|:--|
+| `$A533` | 42291 | **LNKPRG** | Relink tokenized BASIC program | Program at `TXTTAB` | Forward links rebuilt | B | Use after raw program writes. |
+| `$A57C` | 42364 | CRUNCH | Tokenize input line | BASIC input-buffer state | Tokenized line | B/C | Easier: use keyboard injection. |
+| `$A613` | 42515 | FNDLIN | Find BASIC line | `LINNUM` target | C set if found | B | Program table must be valid. |
+| `$A65E` | 42590 | **CLR** | Clear variables/runtime/string heap | BASIC pointers valid | Runtime reset | B/C | Use after program/memory-bound changes. |
+| `$A68E` | 42638 | STXTPT | Set text pointer to program start | `TXTTAB` valid | `TXTPTR=TXTTAB-1` | B/C | Prepares interpreter scan. |
+| `$A717` | 42775 | LIST helper | Detokenize through output channel | Program text/current channel | Output text | C | Output-channel dependent. |
+| `$AB1E` | 43806 | **STROUT** | Output zero/quote-terminated string | A/Y pointer | Characters output | B | Current output channel used. |
+| `$AB47` | 43847 | CHR output wrapper | Output PETSCII char | A=byte | Character output | B/C | Prefer KERNAL `CHROUT`. |
+| `$AD8A` | 44426 | **FRMNUM** | Evaluate numeric expression | `TXTPTR` at first char | FAC1 numeric | B | String result -> type error. |
+| `$AD8D` | 44429 | **CHKNUM** | Require numeric result | `VALTYP` | Return or error | A | Type mismatch jumps to error. |
+| `$AD8F` | 44431 | CHKSTR | Require string result | `VALTYP` | Return or error | A | Type mismatch jumps to error. |
+| `$AD90` | 44432 | CHKVAL | Type check by carry | C clear=numeric, set=string | Return or error | A | Helper under `CHKNUM/CHKSTR`. |
+| `$AD9E` | 44446 | **FRMEVL** | Evaluate any expression | `TXTPTR` at first char | FAC1 or string result; `VALTYP` | B | Most useful parser entry. |
+| `$AEF7` | 44791 | CHKCLS | Require `)` | Scanner state | Advances or error | B | Syntax helper. |
+| `$AEFA` | 44794 | CHKOPN | Require `(` | Scanner state | Advances or error | B | Syntax helper. |
+| `$AEFD` | 44797 | CHKCOM | Require `,` | Scanner state | Advances or error | B | Syntax helper. |
+| `$AEFF` | 44799 | SYNCHR | Require char in A | A=required char | Advances or error | B | Syntax helper. |
+| `$B08B` | 45195 | **PTRGET** | Find/create variable | `TXTPTR` at var name | `VARPNT`, Y/A value address | B | May allocate or evaluate subscripts. |
+| `$B1AA` | 45482 | FAC→int | Convert FAC1 to signed 16-bit | FAC1 | A=lo,Y=hi | A/B | Range-sensitive. |
+| `$B391` | 45969 | **GIVAYF** | Signed int to FAC1 | A=hi,Y=lo | FAC1 | A | Values >32767 become negative. |
+| `$B3A2` | 45986 | SNGFLT | Byte to FAC1 | Y=byte | FAC1 | A | Sets numeric result. |
+| `$B487` | 46215 | STRLIT | Create string descriptor from literal | A/Y pointer | Temp string descriptor | B | String heap/temps apply. |
+| `$B4F4` | 46324 | GETSPA | Allocate string space | A=bytes | X/Y pointer | B/C | May garbage collect or error. |
+| `$B526` | 46374 | GARBA2 | Garbage collect string heap | BASIC string state | Compacted strings | C | Avoid unless runtime owned. |
+| `$B6DB` | 46811 | FRETMS | Release temp string | A/Y descriptor | Temp stack updated | B/C | Descriptor discipline matters. |
+| `$B79E` | 47006 | **GETBYT** | Parse byte expression | `TXTPTR` expression | X=`0..255` | B | Illegal quantity on range error. |
+| `$B7EB` | 47083 | **GETNUM** | Parse `addr,byte` | `TXTPTR` expression | `$14/$15`, X=byte | B | Useful for POKE-style syntax. |
+| `$B7F1` | 47089 | COMBYT | Parse comma then byte | Current char comma | X=byte | B | Calls comma check. |
+| `$B7F7` | 47095 | **GETADR** | FAC1 to unsigned address | FAC1 | `$14/$15`, A/Y | A/B | `0..65535`. |
+| `$BBA2` | 48034 | **MOVFM** | Load packed float to FAC1 | A/Y pointer | FAC1 | A/B | Read numeric variable/constant. |
+| `$BBD4` | 48084 | **MOVMF** | Store FAC1 as packed float | X/Y destination, FAC1 | 5 bytes written | A/B | Floating scalar vars. |
+| `$BC1B` | 48155 | ROUND | Round FAC1 | FAC1/FACOV | FAC1 | A | Numeric helper. |
+| `$BC2B` | 48171 | SIGN | Sign of FAC1 | FAC1 | A=`0`,`1`,`$FF` | A | Zero/positive/negative. |
+| `$BDDD` | 48605 | **FOUT** | FAC1 to ASCII | FAC1 | A/Y temp string pointer | A/B | Copy text immediately. |
+
+## Math Helpers
+
+| Address | Decimal | Name | Input | Output | Class | Notes |
+|:--|:--|:--|:--|:--|:--|:--|
+| `$BC39` | 48185 | SGN | FAC1 | FAC1 = -1/0/1 | A | Function token `$B4`. |
+| `$BC58` | 48216 | ABS | FAC1 | FAC1 | A | Clears sign. |
+| `$BCCC` | 48332 | INT | FAC1 | FAC1 | A | BASIC floor semantics. |
+| `$B9EA` | 47594 | LOG | FAC1 > 0 | FAC1 | A/B | Domain errors jump to `ERROR`. |
+| `$BF71` | 49009 | SQR | FAC1 >= 0 | FAC1 | A/B | Uses LOG/EXP path. |
+| `$BFB4` | 49076 | NEGOP | FAC1 | -FAC1 | A | Unary negation. |
+| `$BFED` | 49133 | EXP | FAC1 | FAC1 | A/B | Continues at `$E000`; overflow possible. |
+| `$E097` | 57495 | RND | FAC1 argument | FAC1 | A/B | Positive advances, negative seeds, zero mixes time. |
+| `$E264` | 57956 | COS | FAC1 radians | FAC1 | A/B | Adds PI/2, uses SIN. |
+| `$E26B` | 57963 | SIN | FAC1 radians | FAC1 | A/B | Dispatch entry. |
+| `$E2B4` | 58036 | TAN | FAC1 radians | FAC1 | A/B | SIN/COS division. |
+| `$E30E` | 58126 | ATN | FAC1 | FAC1 radians | A/B | Polynomial approximation. |
+
+## Statement Dispatch Entries
+
+Statement entries assume live interpreter context unless noted. Prefer text/tokenized program execution over direct calls.
+
+| Token | Command | Entry | Class | Direct-use note |
+|:--|:--|:--|:--|:--|
+| `$80` | END | `$A831` | D | Program termination. |
+| `$81` | FOR | `$A742` | C | Requires FOR stack frame. |
+| `$82` | NEXT | `$AD1E` | C | Requires matching FOR frame. |
+| `$83` | DATA | `$A8F8` | C | Statement skipper. |
+| `$84` | INPUT# | `$ABA5` | C | Prefer KERNAL channel I/O. |
+| `$85` | INPUT | `$ABBF` | C | Editor/string context. |
+| `$86` | DIM | `$B081` | C | Allocates arrays. |
+| `$87` | READ | `$AC06` | C | Depends on `DATPTR`. |
+| `$88` | LET | `$A9A5` | C | Prefer `FRMEVL` + `PTRGET` + store helper. |
+| `$89` | GOTO | `$A8A0` | D | Interpreter flow. |
+| `$8A` | RUN | `$A871` | D | Non-local flow. |
+| `$8B` | IF | `$A928` | C | Interpreter-only. |
+| `$8C` | RESTORE | `$A81D` | C | Resets DATA state. |
+| `$8D` | GOSUB | `$A883` | C | Requires BASIC return frame. |
+| `$8E` | RETURN | `$A8D2` | C | Requires GOSUB frame. |
+| `$8F` | REM | `$A93B` | C | Statement skipper. |
+| `$90` | STOP | `$A82F` | D | STOP/BREAK path. |
+| `$91` | ON | `$A94B` | C | Interpreter-only. |
+| `$92` | WAIT | `$B82D` | C | Can hang; avoid for MCP. |
+| `$93` | LOAD | `$E168` | C | Prefer KERNAL `LOAD`. |
+| `$94` | SAVE | `$E156` | C | Prefer KERNAL `SAVE`. |
+| `$95` | VERIFY | `$E165` | C | Prefer KERNAL load/verify. |
+| `$96` | DEF | `$B3B3` | C | DEF FN machinery. |
+| `$97` | POKE | `$B824` | C | Prefer memory write or `GETNUM`. |
+| `$98` | PRINT# | `$AA80` | C | Prefer KERNAL channel output. |
+| `$99` | PRINT | `$AAA0` | C | Output context required. |
+| `$9A` | CONT | `$A857` | D | Requires continuation state. |
+| `$9B` | LIST | `$A69C` | C | Output-channel dependent. |
+| `$9C` | CLR | `$A65E` | B/C | Useful after memory/program edits. |
+| `$9D` | CMD | `$AA86` | C | Prefer KERNAL channel control. |
+| `$9E` | SYS | `$E12A` | C | Parses BASIC `SYS`; direct ML should `JSR/JMP`. |
+| `$9F` | OPEN | `$E1BE` | C | Prefer KERNAL `OPEN`. |
+| `$A0` | CLOSE | `$E1C7` | C | Prefer KERNAL `CLOSE`. |
+| `$A1` | GET | `$AB7B` | C | Assignment/string path. |
+| `$A2` | NEW | `$A642` | D | Destructive. |
+
+## Function Dispatch Entries
+
+Function entries are normally called by the evaluator. Direct use is safest for simple FAC1 numeric helpers.
+
+| Token | Function | Entry | Class | Direct-use note |
+|:--|:--|:--|:--|:--|
+| `$B4` | SGN | `$BC39` | A | FAC1 in/out. |
+| `$B5` | INT | `$BCCC` | A | FAC1 in/out. |
+| `$B6` | ABS | `$BC58` | A | FAC1 in/out. |
+| `$B7` | USR | `$0310` | C | RAM vector. |
+| `$B8` | FRE | `$B37D` | C | Can trigger GC. |
+| `$B9` | POS | `$B39E` | C | Reads cursor/channel state. |
+| `$BA` | SQR | `$BF71` | A/B | FAC1 non-negative. |
+| `$BB` | RND | `$E097` | A/B | FAC1 argument. |
+| `$BC` | LOG | `$B9EA` | A/B | FAC1 positive. |
+| `$BD` | EXP | `$BFED` | A/B | Overflow possible. |
+| `$BE` | COS | `$E264` | A/B | FAC1 radians. |
+| `$BF` | SIN | `$E26B` | A/B | FAC1 radians. |
+| `$C0` | TAN | `$E2B4` | A/B | FAC1 radians. |
+| `$C1` | ATN | `$E30E` | A/B | FAC1 in/out. |
+| `$C2` | PEEK | `$B80D` | C | Parser convention; ML should `LDA`. |
+| `$C3` | LEN | `$B77C` | C | String argument convention. |
+| `$C4` | STR$ | `$B465` | C | String descriptor result. |
+| `$C5` | VAL | `$B7AD` | C | String parser state. |
+| `$C6` | ASC | `$B78B` | C | Errors on empty string. |
+| `$C7` | CHR$ | `$B6EC` | C | String descriptor result. |
+| `$C8` | LEFT$ | `$B700` | C | String function convention. |
+| `$C9` | RIGHT$ | `$B72C` | C | String function convention. |
+| `$CA` | MID$ | `$B737` | C | String function convention. |
+
+## Operator Dispatch Entries
+
+| Operator | Entry | Precedence | Direct-use note |
+|:--|:--|:--|:--|
+| `+` | `$B86A` | `$79` | Prefer `FRMEVL`. |
+| `-` | `$B853` | `$79` | Prefer `FRMEVL`. |
+| `*` | `$BA2B` | `$7B` | Prefer `FRMEVL`. |
+| `/` | `$BB12` | `$7B` | Prefer `FRMEVL`. |
+| `^` | `$BF7B` | `$7D` | Prefer `FRMEVL`. |
+| `AND` | `$AFE9` | low | Evaluator convention. |
+| `OR` | `$AFE6` | low | Evaluator convention. |
+| comparison | `$B016` | compare | Evaluator convention. |
+| unary `-` | `$BFB4` | unary | FAC1 negation is reasonable. |
+| `NOT` | `$AF0D` | unary | Evaluator convention. |
+
+## C64-Specific BASIC Continuation (`$E000–$E4D2`)
+
+| Address | Decimal | Name | Function | Class | Notes |
+|:--|:--|:--|:--|:--|:--|
+| `$E000` | 57344 | EXP continuation | Completes EXP from `$BFED` | A/B | Cross-ROM BASIC code. |
+| `$E043` | 57411 | POLY1 | FP polynomial helper | B | FAC1/coefficient state. |
+| `$E059` | 57433 | POLY2 | FP polynomial helper | B | Used by math functions. |
+| `$E08D` | 57485 | RMULC | RND multiply constant | data | Five-byte FP. |
+| `$E092` | 57490 | RADDC | RND add constant | data | Five-byte FP. |
+| `$E097` | 57495 | RND | Random number function | A/B | FAC1 argument. |
+| `$E0F9` | 57593 | BASIC/KERNAL I/O bridge | Checked CHKIN/CHKOUT/CHRIN/CHROUT/GETIN | C/D | May enter BASIC error path. |
+| `$E12A` | 57642 | SYS | BASIC `SYS` parser/executor | C | Uses `$030C–$030F`. |
+| `$E156` | 57686 | SAVE wrapper | BASIC `SAVE` statement | C | Prefer KERNAL API. |
+| `$E165` | 57701 | VERIFY wrapper | BASIC `VERIFY` statement | C | Falls into LOAD path. |
+| `$E168` | 57704 | LOAD wrapper | BASIC `LOAD` statement | C | May relink BASIC program. |
+| `$E1BE` | 57790 | OPEN wrapper | BASIC `OPEN` statement | C | Prefer KERNAL API. |
+| `$E1C7` | 57799 | CLOSE wrapper | BASIC `CLOSE` statement | C | Prefer KERNAL API. |
+| `$E1D4` | 57812 | L/V/S parameter setup | Parse filename/LFN/dev/SA | C | For LOAD/SAVE/VERIFY. |
+| `$E200` | 57856 | Get int to X | Parse comma + integer byte | B/C | Parser helper. |
+| `$E206` | 57862 | Fetch/endline helper | Parser control-flow helper | D | Can unwind caller. |
+| `$E20E` | 57870 | Check comma | Require comma | B/C | Parser helper. |
+| `$E219` | 57881 | O/C parameter setup | Parse OPEN/CLOSE params | C | Sets KERNAL file state. |
+| `$E264` | 57956 | COS | Cosine | A/B | FAC1 radians. |
+| `$E26B` | 57963 | SIN | Sine | A/B | FAC1 radians. |
+| `$E2B4` | 58036 | TAN | Tangent | A/B | FAC1 radians. |
+| `$E30E` | 58126 | ATN | Arctangent | A/B | FAC1 in/out. |
+| `$E37B` | 58235 | Warm BASIC | READY/warm-start path | D | Jump target, not subroutine. |
+| `$E38B` | 58251 | Error message path | Print BASIC error and READY | D | X=error index. |
+| `$E394` | 58260 | Cold BASIC | Power-on BASIC init | D | Reset/init path. |
+| `$E3A2` | 58274 | CHRGET image | Source copied to `$0073` | data | Scanner code image. |
+| `$E3BF` | 58303 | INIT | BASIC zero-page init | C/D | Copies `CHRGET`. |
+| `$E422` | 58402 | Startup messages | Banner and bytes-free output | D | Boot path. |
+| `$E447` | 58439 | BASIC vector table | Defaults for `$0300–$030B` | data | Error, warm, crunch, list, execute, evaluate. |
+| `$E453` | 58451 | Copy BASIC vectors | Restore BASIC RAM vectors | B/C | Mostly init/recovery. |
+| `$E460` | 58464 | Text constants | Startup/message text | data | Constants. |
+
+## Compact Workflows
+
+| Need | Preferred mechanism | Minimal sequence |
+|:--|:--|:--|
+| Evaluate expression | `FRMNUM`/`FRMEVL` | Set `TXTPTR` to first char, `JSR $AD8A` or `JSR $AD9E`, handle BASIC errors. |
+| Numeric result as text | `FOUT` | FAC1 ready, `JSR $BDDD`, copy A/Y string immediately. |
+| Parse byte/address syntax | `GETBYT`/`GETADR`/`GETNUM` | Use BASIC-compatible expression text and controlled `TXTPTR`. |
+| Read/write numeric scalar | `PTRGET` + `MOVFM`/`MOVMF` | Set `TXTPTR` to var name; use returned `VARPNT`. |
+| Install tokenized program | Raw write + `LNKPRG` + `CLR` | Write at `TXTTAB`, final next pointer `$0000`, `JSR $A533`, `JSR $A65E`. |
+| Execute BASIC statement | Dynamic keyboard or normal interpreter | Avoid direct statement entries unless runtime/error context is controlled. |
+| Reserve high RAM | Lower `MEMSIZ`, then `CLR` | Update `$37/$38`, `JSR $A65E`; keep ML/sprites above new top. |
+
+## Avoid as General MCP APIs
+
+| Entry | Reason |
+|:--|:--|
+| `$A437` | BASIC error path; non-returning for normal callers. |
+| `$A7AE` | Main interpreter loop; full runtime context required. |
+| `$A7ED` | Command dispatcher; token/stack conventions required. |
+| `$E206` | May skip a return address at end-of-statement. |
+| `$E37B`, `$E394` | Warm/cold BASIC entry paths, not subroutines. |
+| Direct string allocation/GC | Safe only when descriptor stack and movable string heap are controlled. |

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.
 
@@ -33,7 +33,7 @@ Do not assume the current backend is correct without checking
 
 ## Memory Map (default RAM layout)
 
-For Full details see `../memory/memory-map.md` with focus on low-memory (pages 0-3) in `../memory/low-memory-map.md` and  KERNAL memory in `../memory/kernal-memory-map.md`.
+For full details see `../memory/memory-map.md`. Use `../memory/low-memory-map.md` for zero page/pages 0-3, `../basic/rom-routines.md` for BASIC ROM routines, `../kernal/rom-routines.md` for KERNAL ROM routines, and `../io/io-spec.md` or `../io/cia-spec.md` for hardware registers.
 
 - $0000–$00FF: Zero page
 - $0100–$01FF: Stack

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