c64bridge 0.9.2 → 1.0.0

package/AGENTS.md

@@ -17,19 +17,28 @@ On startup the server probes connectivity (REST + zero-page read) and announces
 
 The server resolves config in this order: `C64BRIDGE_CONFIG` → `./.c64bridge.json` → `~/.c64bridge.json` → defaults (`host=c64u`, `port=80`).
 
-Example:
+Example C64U/U64 configuration:
 
 ```json
 { "c64u": { "host": "c64u", "port": 80, "networkPassword": "secret" } }
 ```
 
+U2, U2+, and U2+L use the `u2` profile, which is a firmware-defined subset of the C64U/U64 API:
+
+```json
+{ "u2": { "host": "u2", "port": 80, "networkPassword": "secret" } }
+```
+
+Use `C64_MODE=u2` to select that profile. U2-family cartridges support the shared REST operations, including configuration and `machine:menu_screen`, but not `machine:input`, debug-register access, power-off, or streaming.
+
 When Ultimate firmware network protection is enabled, `networkPassword` is sent as the `X-Password` header on every REST request.
 
 ### Runtime Backend Switching
 
-When both `c64u` and `vice` are configured, the server can keep both backends live at the same time.
+When any combination of `c64u`, `u2`, and `vice` is configured, the server can keep the configured backends live at the same time.
 Use `c64_select_backend` to switch the active backend without restarting the MCP server.
 The `c64://platform/status` resource always reports the currently active backend and the configured backend set.
+Before using physical `machine:input`, `machine:menu_screen`, or C64U/U64 `power_cycle`, read it for native endpoint availability. If `machine:input` is unavailable or unknown, use `key` or `write_text` for ordinary C64 input; do not attempt physical matrix injection. `machine:menu_screen` is only confirmed while an Ultimate menu is visible.
 State the desired backend directly in the prompt when you want to pin execution, for example: `use vice`, `vice: load this PRG`, `use c64u`, or `run this on hardware`.
 When using the VS Code `C64` agent, keep the backend request in the same prompt so tool routing can call `c64_select_backend` before backend-specific operations.
 
@@ -84,7 +93,7 @@ If a workflow description starts listing tool calls outside `.github/skills`, tr
 - Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`)
 - Fast demo workflow: `c64_program` (`cross_platform_greeting`) for one-call greetings on VICE and/or C64U with screenshot capture and verification
 - Screen & memory: `c64_memory` (`read`, `write`, `read_screen`, `wait_for_text`)
-- System control: `c64_system` (`pause`, `resume`, `reset`, `reboot`, `poweroff`, `menu`, tasks)
+- System control: `c64_system` (`pause`, `resume`, `reset`, `reboot`, `poweroff`, `power_cycle`, `menu`, tasks)
 - Configuration: `c64_config` (get/set, `batch_update`, `snapshot`, `restore`, `diff`, `shuffle`)
 - Drives & files: `c64_disk`, `c64_drive`
 - SID / music: `c64_sound` (`play_preset`, playback, generate, analyze)
@@ -93,6 +102,13 @@ If a workflow description starts listing tool calls outside `.github/skills`, tr
 
 Tools and parameters are listed dynamically via ListTools.
 
+### Configuration and menu navigation
+
+Change C64U/U64/U2 configuration through `c64_config` REST operations; do not navigate configuration menus with injected keyboard input.
+`c64_input` `key` is PETSCII/KERNAL-queue input, while `keyboard` sends physical key combinations through Ultimate REST input.
+Keyboard menu navigation is reserved for device features with no REST equivalent, for example the machine code monitor, visual SID editor, or Tool Menu.
+`power_cycle` is the deliberate Tool Menu exception on C64U/U64: it reads `machine:menu_screen` after every navigation step and stops rather than blindly selecting an unverified item. It uses REST reboot on U2-family cartridges and a fresh VICE start on VICE.
+
 ## Skill Routing
 
 | Intent | Skill |
@@ -115,12 +131,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.