c64bridge 1.0.6 → 1.1.0

package/.github/skills/assembly-program/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: assembly-program
+description: Execute 6502/6510 assembly workflows through c64bridge.
+---
+
+## Intent
+
+Use this skill for custom assembly routines, register work, IRQ handlers, and hardware-timed code.
+
+## Inputs
+
+- Hardware focus: VIC-II, SID, CIA, or mixed.
+- Memory layout constraints, zero-page usage, and interrupt ownership.
+- Validation target: screen state, memory state, or register state.
+
+## Execution
+
+1. Clarify which hardware blocks and memory ranges the routine may touch.
+2. Consult `c64://assembly/6510-spec`, `c64://memory/map`, and any hardware-specific resource that applies.
+3. Use `c64_rag` with `op: "asm"` when targeted timing tables or code examples are needed.
+4. Generate assembly source with explicit labels and memory usage.
+5. Execute with `c64_program` using `op: "upload_run_asm"`.
+
+## Validation
+
+1. Use `c64_memory` with `op: "read"` for installed code, vectors, or register checks.
+2. Use `c64_memory` with `op: "read_screen"` when the routine produces visible output.
+3. Report assembler diagnostics directly if compilation fails.
+
+## Safety
+
+- Confirm before invasive recovery actions such as reset or reboot.
+- Pause and resume the machine around manual memory patching when the workflow requires it.
+
+## Escalation
+
+- Switch to `.github/skills/basic-program/SKILL.md` when the task is better served by a high-level loader or a simple BASIC program.

package/.github/skills/basic-program/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: basic-program
+description: Execute bespoke Commodore BASIC v2 programs through c64bridge.
+---
+
+## Intent
+
+Use this skill when the user needs a custom BASIC program rather than a one-call demo.
+
+## Inputs
+
+- Desired behavior, inputs, and expected output.
+- Target backend or backend preference.
+- Whether current machine state must be preserved.
+
+## Execution
+
+1. If the request is only a hello-world, greeting, or smoke test, delegate to `.github/skills/hello-world/SKILL.md` instead of generating bespoke BASIC.
+2. Clarify missing requirements before generating code when the request is not already specific enough to execute.
+3. Consult `c64://basic/spec` and `c64://guide/bootstrap` only when syntax or workflow constraints matter.
+4. Generate uppercase, line-numbered BASIC. `upload_run_basic` repairs a missing closing quote or parenthesis on a failing line and runs the program again, reporting the rewritten lines; pass `autoFix: false` for programs with side effects.
+5. For VICE-backed local runs, assume the user should see a real visible emulator window unless CI or the lack of a framebuffer/display session forces headless operation.
+6. When running visible VICE BASIC manually, do not immediately follow the run with `read_screen` or `wait_for_text` unless the user explicitly asks for machine verification after the visible output has rendered.
+7. Use `c64_rag` with `op: "basic"` only when targeted BASIC examples are needed.
+
+## Validation
+
+1. For normal non-visual runs, call `c64_memory` with `op: "read_screen"` after execution.
+2. For visible VICE runs, prefer user-visible confirmation first and only do monitor-based reads after the screen has clearly rendered or when the user asks for explicit verification.
+3. Use `c64_memory` with `op: "read"` around the BASIC program area only when tokenization or memory placement needs verification.
+4. Summarize expected versus observed output.
+
+## Safety
+
+- Confirm before reset, reboot, or other disruptive recovery actions.
+- Preserve existing machine state when the user requests it.
+
+## Escalation
+
+- Switch to `.github/skills/assembly-program/SKILL.md` when performance, raster timing, or direct register control becomes the primary need.

package/.github/skills/cross-platform-demo/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: cross-platform-demo
+description: Run the shortest visible demo path across VICE and C64U.
+---
+
+## Intent
+
+Use this skill for quick greetings, smoke tests, and visible confirmation that one or more backends are responding.
+
+## Inputs
+
+- Target backends: `vice`, `c64u`, or both.
+- Optional message template when the default greeting is not sufficient.
+
+## Execution
+
+0. Grouped MCP tools always require `op`. Do not call `c64_program` without it.
+1. Execute `c64_program` with `op: "cross_platform_greeting"`.
+2. Pass `platforms` only when the user wants a subset of the configured backends.
+3. Pass `messageTemplate` only when the user explicitly wants custom text.
+4. On local machines with a graphical session, assume VICE should render in a real visible emulator window by default. Only expect Xvfb or other headless behavior in CI or when no framebuffer/display session exists.
+
+## Validation
+
+1. Trust the workflow's structured verification first.
+2. Summarize the reported text match results and screenshot paths.
+3. Fall back to `.github/skills/basic-program/SKILL.md` only when the user needs custom program flow beyond a simple greeting, not merely because they want to see VICE render live.
+
+## Safety
+
+- Warn if a running session may be overwritten by the demo.
+- Do not add manual reset steps unless the workflow fails and the user confirms recovery actions.

package/.github/skills/drive-manager/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: drive-manager
+description: Manage disk images and drive state through c64bridge.
+---
+
+## Intent
+
+Use this skill for disk image mounts, blank media creation, drive resets, power changes, and mode changes.
+
+## Inputs
+
+- Desired action: inspect, mount, create, unmount, reset, power cycle, or mode change.
+- Target drive slot.
+- Any image path, format, or verification requirement.
+
+## Execution
+
+1. Call `c64_disk` with `op: "list_drives"` before any mutation.
+2. For image mounts or unmounts, use `c64_disk` with `op: "mount"` or `op: "unmount"`.
+3. For new media, use `c64_disk` with `op: "create_image"` and then verify the result.
+4. For drive hardware state, use `c64_drive` with `op: "reset"`, `op: "power_on"`, `op: "power_off"`, or `op: "set_mode"`.
+5. To locate files by name on the device, use `c64_disk` with `op: "find_paths"` (`nameContains`, optional `root`, `extensions`, `maxResults`); a `truncated: true` result means more matches exist and the search should be narrowed.
+6. Use `c64_disk` with `op: "file_info"` or `op: "find_and_run"` when inspection or launch is part of the task.
+
+## Validation
+
+1. Re-run `c64_disk` with `op: "list_drives"` after each mutation.
+2. Confirm the final drive slot, mounted image, and mode in the summary.
+
+## Safety
+
+- Warn before power changes, resets, or other actions that may interrupt running software.
+- Confirm destructive or stateful actions before executing them.

package/.github/skills/graphics-demo/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: graphics-demo
+description: Execute PETSCII, sprite, bitmap, and frame-capture graphics workflows.
+---
+
+## Intent
+
+Use this skill when the user wants visual output on the C64, whether generated directly through graphics tools or through supporting BASIC or assembly loaders.
+
+## Inputs
+
+- Desired visual mode: PETSCII, text banner, sprite, bitmap, or frame capture.
+- Artistic direction, palette constraints, and target backend.
+- Whether the user wants a preview, a rendered asset, or a running program.
+
+## Execution
+
+1. For direct graphics generation, use `c64_graphics` with the relevant operation such as `render_petscii_art`, `render_petscii_text`, `render_sprite`, `render_bitmap`, or `capture_frame`.
+2. When the request needs custom loader logic, delegate code generation to `.github/skills/basic-program/SKILL.md` or `.github/skills/assembly-program/SKILL.md`.
+3. Reference `c64://graphics/vic/spec` and any character-set or PETSCII resources needed for the chosen mode.
+
+## Validation
+
+1. Use `c64_memory` with `op: "read_screen"` for text-mode validation.
+2. Use `c64_graphics` with `op: "capture_frame"` for full-frame verification. Pass `format: "png"` (at most 4 frames) to receive viewable images; raw pixels are off by default and need `includePixels: true` with a small `count`.
+3. Summarize the resulting mode, palette choices, and any captured assets.
+
+## Safety
+
+- Confirm before resets or teardown steps that would disrupt the current display state.

package/.github/skills/hello-world/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: hello-world
+description: Run the fastest greeting or smoke-test path across VICE and C64U.
+---
+
+## Intent
+
+Use this skill when the user wants the shortest hello-world, greeting, or smoke-test workflow.
+
+## Inputs
+
+- Target backends: `vice`, `c64u`, or both.
+- Optional greeting text or message template. Treat explicitly requested on-screen text such as `HELLO WORLD` as literal output to preserve.
+
+## Execution
+
+0. Grouped MCP tools always require `op`. Do not call `c64_program` without it.
+1. If `c64_program` is exposed in the current tool set, execute it immediately with `op: "cross_platform_greeting"`.
+2. If the current tool set does not expose `c64_program`, immediately delegate the same request to the `C64` agent instead of inspecting repository files, README sections, or MCP manifests.
+3. Pass `platforms` only when the user pins a backend or wants a subset of the configured backends.
+4. For a single visible VICE greeting, prefer the no-probe fast path: do not request screenshots or monitor-based verification unless the user explicitly asks for them.
+5. Pass `messageTemplate` whenever the user specifies the exact text that should appear on screen, including simple phrases such as `HELLO WORLD`. Do not substitute the workflow's default greeting when the prompt implies literal output.
+6. On local machines with a graphical session, assume VICE should render in a real visible emulator window. Only expect Xvfb or other headless behavior in CI or when no framebuffer/display session exists.
+7. Do not re-read README sections, MCP manifests, or BASIC references before executing unless the request is ambiguous or the workflow fails.
+8. Fall back to `.github/skills/basic-program/SKILL.md` only when the user needs custom BASIC logic beyond a static greeting.
+
+## Validation
+
+1. Trust the workflow's structured verification first.
+2. For local visible VICE runs, treat the emulator window as the primary confirmation and summarize any reported text matches or screenshot artifacts.
+3. Fall back to manual `read_screen` checks only when the user asks for explicit verification or the workflow fails.
+
+## Safety
+
+- Warn if a running session may be overwritten by the demo.
+- Do not add manual reset steps unless the workflow fails and the user confirms recovery actions.

package/.github/skills/memory-debug/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: memory-debug
+description: Inspect, patch, and validate C64 memory safely.
+---
+
+## Intent
+
+Use this skill for RAM inspection, screen reads, polling for output, and carefully scoped memory writes.
+
+## Inputs
+
+- Address range or text pattern to inspect.
+- Whether the operation is read-only or mutating.
+- Any expectation about program state before or after the change.
+
+## Execution
+
+1. For direct memory inspection, use `c64_memory` with `op: "read"`.
+   Pass `format: "dump"` for a 16-bytes-per-line listing with addresses and a PETSCII column; the default `"hex"` returns one hex string.
+2. For screen output, use `c64_memory` with `op: "read_screen"`. To see the BASIC program in memory as text, use `op: "list_basic"`.
+3. For polling, use `c64_memory` with `op: "wait_for_text"`.
+4. For writes, use `c64_memory` with `op: "write"` only after confirming the target range and side effects.
+
+## Validation
+
+1. Re-read the same memory range after every write.
+2. Summarize the before and after state when patching memory.
+
+## Safety
+
+- Warn before writes in I/O or ROM-adjacent regions.
+- Use pause and resume workflows when live execution makes writes risky.

package/.github/skills/pr-converge/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: pr-converge
+description: Converge an open pull request to merge-ready state.
+---
+
+## Intent
+
+Use this skill when the task is to address review feedback, clear CI, and bring a pull request to merge readiness.
+
+## Inputs
+
+- Target pull request or the currently checked out pull request.
+- Review comments, CI failures, and repository validation requirements.
+
+## Execution
+
+1. Retrieve active review comments and open threads.
+2. Evaluate each comment against the current code and decide whether it requires a fix, explanation, or no action.
+3. Implement focused fixes for valid issues and add regression coverage when the comment reveals a bug.
+4. Reply to each comment with a concise technical explanation.
+5. Re-run the minimal validation needed by the touched areas.
+6. Check CI status and iterate until failures are resolved.
+
+## Validation
+
+1. Confirm that review threads are responded to and ready for resolution.
+2. Confirm that local validation is green.
+3. Confirm that CI is green before declaring convergence.
+
+## Safety
+
+- Do not resolve comments without explanation.
+- Keep each fix minimal and scoped to the review issue it addresses.

package/.github/skills/printer-job/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: printer-job
+description: Execute Commodore and Epson printing workflows through c64bridge.
+---
+
+## Intent
+
+Use this skill for printer text output, bitmap output, and custom character definition.
+
+## Inputs
+
+- Printer family: Commodore or Epson.
+- Desired output type: text, bitmap row, or custom character definition.
+- Any device or secondary-address requirements.
+
+## Execution
+
+1. Use `c64_printer` with `op: "print_text"` for text workflows.
+2. Use `c64_printer` with `op: "print_bitmap"` for bitmap row workflows.
+3. Use `c64_printer` with `op: "define_chars"` for custom character definitions.
+4. Surface any generated BASIC or payload details the user must keep or reuse.
+
+## Validation
+
+1. Confirm which printer family and operation ran.
+2. Summarize any generated program text or printer control assumptions.
+
+## Safety
+
+- Confirm printer family before issuing printer-specific control sequences.

package/.github/skills/sid-music/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sid-music
+description: Execute built-in and custom SID playback workflows through c64bridge.
+---
+
+## Intent
+
+Use this skill for preset music demos, SIDWAVE composition, direct voice control, and audio verification.
+
+## Inputs
+
+- Whether the user wants the built-in `fuer_elise` preset or a custom composition.
+- Target backends and verification expectations.
+- Desired format for custom work: direct voice events, SIDWAVE, or BASIC playback.
+
+## Execution
+
+1. For a quick recognizable demo, execute `c64_sound` with `op: "play_preset"` and canonical preset `fuer_elise`.
+2. If a legacy preset identifier reaches this workflow, normalize it to `fuer_elise` before playback.
+3. For custom music, use `c64_sound` with `op: "generate"`, `op: "compile_play"`, or `op: "pipeline"` as appropriate.
+4. Use `.github/skills/basic-program/SKILL.md` only when the user explicitly wants BASIC-driven playback.
+
+## Validation
+
+1. On `c64u`, prefer `c64_sound` analysis results when verification is enabled.
+2. On `vice`, summarize successful playback launch and state clearly when live audio analysis is unavailable.
+3. Report the canonical preset or composition path that actually ran.
+
+## Safety
+
+- Confirm before reset or silence actions that would interrupt an in-progress performance.
+
+## Escalation
+
+- Switch from preset playback to custom composition only when the user requests a different arrangement, instrumentation, or score.

package/.github/skills/software-launch/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: software-launch
+description: Load and run existing C64 software through c64bridge.
+---
+
+## Intent
+
+Use this skill for existing PRG, CRT, or disk-image based software rather than newly authored programs.
+
+## Inputs
+
+- Media type: PRG, CRT, or disk image.
+- File path or image path.
+- Target backend and any drive-slot requirement.
+
+## Execution
+
+1. Confirm connectivity before launch when the environment looks uncertain.
+2. For loose files, use `c64_program` with `op: "run_prg"` or `op: "run_crt"`. `load_prg` loads a PRG without running it on C64U, U2 and VICE (on VICE the path is a host-local file); `run_crt` is not available on VICE.
+3. For disk images, use `.github/skills/drive-manager/SKILL.md` to mount the image first, then launch the correct program.
+4. Use `c64_disk` with `op: "find_and_run"` when the user needs discovery inside an image.
+
+## Validation
+
+1. Use `c64_memory` with `op: "read_screen"` after launch when visible output is expected.
+2. Summarize the loaded media, backend, and observed first-run state.
+
+## Safety
+
+- Confirm target drive slot before mutating disk state.
+- Warn before power or reset actions that would interrupt the launch flow.

package/.github/skills/stream-control/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: stream-control
+description: Start and stop live C64 audio or video streams.
+---
+
+## Intent
+
+Use this skill when the user wants a live audio or video stream forwarded to another host.
+
+## Inputs
+
+- Stream type: audio or video.
+- Destination host and port.
+- Whether the session should be stopped or started.
+
+## Execution
+
+1. Use `c64_stream` with `op: "start"` to begin a stream.
+2. Use `c64_stream` with `op: "stop"` to terminate a stream.
+3. Confirm the stream target back to the user after each action.
+
+## Validation
+
+1. Summarize the stream type and target that the workflow attempted.
+2. Report any failure clearly so the user can adjust network or backend settings.
+
+## Safety
+
+- Remind the user to stop streams explicitly when capture is finished.

package/.github/skills/system-control/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: system-control
+description: Control machine lifecycle, background tasks, and configuration state.
+---
+
+## Intent
+
+Use this skill for pause/resume, reset, reboot, power, menu actions, background tasks, and configuration workflows.
+
+## Inputs
+
+- Desired machine action or configuration change.
+- Any task name, configuration category, or configuration item involved.
+- Whether state persistence or flash save is required.
+
+## Execution
+
+1. Use `c64_system` with `op: "pause"`, `op: "resume"`, `op: "reset"`, `op: "reboot"`, `op: "poweroff"`, `op: "power_cycle"`, or `op: "menu"` as needed. `power_cycle` verifies C64U/U64 Tool Menu screens between injected keys; it uses REST reboot on U2-family cartridges and a fresh VICE start on VICE.
+   `reset`, `reboot` and `power_cycle` accept `waitForReady: true` (with `readyTimeoutMs`, default 15000) to wait for the BASIC READY. prompt; a timeout is reported as `ready=false`, not as an error. `pause` and `resume` are not available on VICE.
+2. Use `c64_system` task operations for background task lifecycle management.
+3. Use `c64_config` REST operations for all C64U/U64/U2 configuration reads, writes, snapshots, diffs, and status checks. `load_flash`, `save_flash` and `reset_defaults` take an optional `category` to limit the operation to one configuration category. Do not navigate configuration menus through injected keyboard input.
+4. Use `c64_input` `key` only for single PETSCII/KERNAL-queue keys and `keyboard` only for physical C64 key chords on Ultimate REST input. Firmware-menu navigation is an exception only when REST has no equivalent, such as the machine code monitor, visual SID editor, or Tool Menu.
+
+## Validation
+
+1. Confirm the resulting machine or configuration state in the summary.
+2. When configuration changes are involved, report the category and item that changed.
+
+## Safety
+
+- Require explicit confirmation before reset, reboot, poweroff, flash save, or destructive config resets.
+- Never leave the system paused without telling the user.

package/AGENTS.md

@@ -33,6 +33,20 @@ Use `C64_MODE=u2` to select that profile. U2-family cartridges support the share
 
 When Ultimate firmware network protection is enabled, `networkPassword` is sent as the `X-Password` header on every REST request.
 
+### Host File Access
+
+Tool arguments that become host file paths (memory dumps, config snapshots, sprite/charset exports, run artifacts, `symbolsFile`, VICE PRG and disk image paths) must lie inside the working directory (not when it is `~` or `/`), `~/.c64bridge`, or the system temp directory. Other locations are rejected with an error that lists the allowed roots; use a path inside one of them rather than retrying elsewhere. The operator can add roots with `C64BRIDGE_ALLOWED_DIRS` (entries separated by the path delimiter; `*` disables the check).
+
+### Environment Variables
+
+| Variable | Effect |
+| --- | --- |
+| `C64BRIDGE_ALLOWED_DIRS` | Extra directories for host file paths in tool arguments, separated by the path delimiter; `*` disables the check. |
+| `C64BRIDGE_ACCESS` | `full` (default), `no-destructive` or `read-only`. Limits which operations may be called; read on every call. |
+| `C64BRIDGE_HTTP_TOKEN` | Bearer token required (`Authorization: Bearer <token>`) by the optional HTTP transport (`--http`), which also accepts only loopback Host and Origin headers. |
+| `C64BRIDGE_DIAGNOSTICS_KEEP` | Number of diagnostics files kept at startup (default 200; files older than 30 days are always removed). |
+| `C64BRIDGE_VERBOSE_SCHEMA` | Set to `1` to include the full per-operation schemas in `tools/list` (omitted by default to keep it small). |
+
 ### Runtime Backend Switching
 
 When any combination of `c64u`, `u2`, and `vice` is configured, the server can keep the configured backends live at the same time.
@@ -90,15 +104,20 @@ If a workflow description starts listing tool calls outside `.github/skills`, tr
 
 ## Capabilities
 
-- Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`)
+- Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `load_prg`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`). `upload_run_basic` repairs a missing closing quote or parenthesis and reruns once; pass `autoFix: false` for programs with side effects.
 - 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`, `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)
-- Graphics: `c64_graphics` (PETSCII, sprites)
+- Screen & memory: `c64_memory` (`read`, `write`, `read_screen`, `wait_for_text`, `list_basic`, `disassemble`, `copy_memory`, `fill_memory`, `search_memory`, `compare_memory`, `save_memory`). `read` accepts `format: "hex"` (default) or `"dump"` (addresses plus a PETSCII column); `list_basic` lists the BASIC program in memory as text.
+- System control: `c64_system` (`pause`, `resume`, `reset`, `reboot`, `poweroff`, `power_cycle`, `menu`, tasks). `reset`, `reboot` and `power_cycle` accept `waitForReady` and `readyTimeoutMs` to wait for the BASIC READY. prompt. `pause` and `resume` are not available on VICE.
+- Input: `c64_input` (`write_text`, `key`, `keyboard`, `joystick`, `release_all`, `state`)
+- Configuration: `c64_config` (get/set, `batch_update`, `snapshot`, `restore`, `diff`, `shuffle`, `load_flash`, `save_flash`, `reset_defaults`). The flash operations take an optional `category`.
+- Drives & files: `c64_disk` (including `find_paths`, which returns `results` and `truncated`; limit with `maxResults`), `c64_drive`
+- SID / music: `c64_sound` (`play_preset`, playback, generate, analyze, `capture_samples`)
+- Graphics: `c64_graphics` (PETSCII, sprites, `capture_frame`). `capture_frame` omits raw pixels unless `includePixels: true`; `format: "png"` returns viewable images (at most 4 frames; raw output is capped at 2 MiB, as for `capture_samples`).
+- Debugging (VICE): `c64_debug` (checkpoints, registers, stepping, `wait_for_state`), `c64_vice` (resources)
+- Streaming and extraction: `c64_stream` (C64U), `c64_extract` (sprites, charset, memory dump, firmware health)
+- Batching: `c64_batch` runs several tool calls in one request
 - Knowledge & RAG: `c64_rag` (BASIC and ASM lookups)
+- Backend selection: `c64_select_backend`
 
 Tools and parameters are listed dynamically via ListTools.
 
@@ -154,6 +173,8 @@ For execution details, follow the matching skill rather than duplicating tool st
 ## Safety Notes
 
 - Some tools affect device state (power, reboot, drive ops). Use deliberately.
+- Every operation has an effect (`read`, `write`, `destructive`). `C64BRIDGE_ACCESS=full|no-destructive|read-only` (default `full`) limits what may be called; a blocked call returns a validation error naming the operation, effect and mode. Do not try to work around a block; ask the user to change the variable. `c64://platform/status` shows the active mode.
+- `poweroff` does not restore power by software. The machine returns only when power is restored at the outlet, and starts by itself only if automatic startup on power restoration is enabled.
 - Logs emit to stderr; stdout is reserved for the MCP protocol.
 
 ## Personas