c64bridge 1.0.7 → 1.1.0

package/doc/plans/meta-tools/rollout.md

@@ -1,368 +0,0 @@
-# Meta Tools Rollout Plan for c64bridge
-
-Purpose: Provide a concrete, dependency-aware rollout approach for the meta tools defined in `doc/meta-tools/catalog.md`. This plan gives ordered, checkable task lists and high-level implementation notes. It is written so another LLM can execute the rollout autonomously.
-
-## Required reading
-
-The following documents need to be read and understood before starting the rollout:
-
-- `doc/meta-tools/catalog.md` — Meta tools definitions, effort/benefit/dependencies matrix
-- `doc/meta-tools/analysis.md` — Impact analysis and prioritization rationale
-- `doc/agent-state-spec.md` — Background task registry and persistence model
-- `doc/developer.md` — Architecture overview and contribution guidelines
-
-## Operator rules for the LLM performing the rollout
-
-- Always work tasks strictly in order as listed. Do not skip ahead unless a task is cancelled.
-- After each checklist item, run the full build and test suite and proceed only if it passes:
-  - Preferred: `npm run check` (build + tests) or `npm test` if already built.
-- If tests fail:
-  - Fix the cause if obvious and retry once.
-  - If still failing, revert the last change and leave a short note in the status log, then stop.
-- Keep edits minimal and focused. Prefer small, incremental changes.
-- Update documentation in the same change when tool behavior or surface changes.
-- For any new code, add/extend tests that cover basic happy path and one failure path.
-- Respect device-affecting safeguards already in the codebase (pause/resume, stream mutual exclusion, time limits).
-
-### Global implementation template (apply per meta tool)
-
-- [ ] Read the tool’s entry in `doc/meta-tools/catalog.md` and its Effort/Benefit/Dependencies.
-- [ ] Verify prerequisites (dependencies implemented). If missing, pause and complete dependencies first.
-- [ ] Implement the meta tool wrapper in the MCP server (compose existing low-level tools; avoid firmware-only assumptions).
-- [ ] Add or extend unit/integration tests for the meta tool’s happy path and a basic failure case.
-- [ ] Update docs: ensure the tool’s documentation is aligned; add usage hints if applicable.
-- [ ] Run full build + tests: `npm run check` must pass.
-
-Notes:
-
-- Do not expand the REST surface; meta tools must compose existing MCP tools.
-- Ensure mutual exclusion where streams and debug capture conflict.
-- Enforce timeouts and guardrails for background/scheduled operations.
-
----
-
-### Phase 0 — Foundations (low-effort, high-benefit, unlocks others)
-
-- [x] `firmware_info_and_healthcheck` — Implementation notes:
-  - Compose version, info, and a tiny `readmem` probe. Return structured readiness.
-  - Use short, bounded timeouts; capture latency metrics.
-- [x] `wait_for_screen_text` — Implementation notes:
-  - Poll screen RAM via existing helper; support regex and plain text. Provide timeout and interval.
-  - Return match bounds and elapsed time.
-- [x] `verify_and_write_memory` — Implementation notes:
-  - Pause → read → verify → write → read-back → resume. Abort on mismatch.
-  - Parameterize verification masks and expected buffer; return a diff when failing.
-- [x] `start_background_task` / `stop_background_task` / `list_background_tasks` / `stop_all_background_tasks` — Implementation notes:
-  - Implement a persistent registry (in-memory with serialized state to disk if available).
-  - Support fixed-interval scheduling and a maximum iterations cap.
-- [x] `find_paths_by_name` — Implementation notes:
-  - Container-aware discovery using wildcard info endpoints; return host and logical paths.
-  - Cache recent results with a short TTL to avoid repeated scans.
-- [x] `memory_dump_to_file` — Implementation notes:
-  - Chunked reads with retries; optional pause/resume. Support hex and binary formats.
-  - Emit a checksum and write a manifest alongside the dump.
-- [x] `config_snapshot_and_restore` — Implementation notes:
-  - Read all categories, persist versioned JSON; support batch restore and diff preview.
-
-Requirement: After each checkbox completion, run `npm run check` and proceed only on success.
-
----
-
-### Phase 1 — Orchestration and assertions
-
-- [x] `program_shuffle` — Implementation notes:
-  - Discover PRG/CRT under root; run each for a duration; capture screen; soft reset.
-  - Persist a light run log per program.
-- [x] `batch_run_with_assertions` — Implementation notes:
-  - Accept assertions: screen contains text, memory equals byte, SID silent.
-  - Produce junit-like results; stop on failure or continue-on-error per flag.
-- [x] `bundle_run_artifacts` — Implementation notes:
-  - Gather screen, memory snapshot, debugreg; structure outputs per run id.
-- [x] `compile_run_verify_cycle` — Implementation notes:
-  - Support BASIC/ASM/SID build routes; then run and verify via screen/audio.
-  - Archive artifacts in a run folder.
-
----
-
-### Phase 2 — Remaining Topics Snapshot (2025-10-30)
-
-- **Completed with tests**
-  - `find_and_run_program_by_name` — Covered by `test/meta/filesystem.test.mjs`
-  - `silence_and_verify` — Covered by `test/meta/audio.test.mjs`
-  - `filesystem_stats_by_extension` — Covered by `test/meta/filesystem.test.mjs`
-  - `music_compile_play_analyze` — Covered by `test/meta/audio.test.mjs`
-  - `extract_sprites_from_ram` — Covered by `test/meta/screen.test.mjs`
-- **Pending (add tests during implementation)**
-  - `rip_charset_from_ram` — Add charset export cases (extend `test/meta/screen.test.mjs`).
-  - `drive_mount_and_verify` — Add drive lifecycle coverage (extend `test/meta/program.test.mjs` or create `test/meta/drive.test.mjs` when introduced).
-  - `classify_prg_basic_or_mc` — Add classification logic tests (extend `test/meta/filesystem.test.mjs`).
-  - `screen_capture_timeline` — Add timeline sampling coverage (extend `test/meta/screen.test.mjs`).
-  - `sid_param_sweep` — Add SID parameter sweep coverage (extend `test/meta/audio.test.mjs`).
-  - `create_and_mount_blank_d64` — Add disk creation coverage (extend `test/meta/filesystem.test.mjs`).
-  - `memory_snapshot_and_diff` — Add snapshot/diff coverage (extend `test/meta/memory.test.mjs`).
-  - `disassemble_ram_region` — Add disassembly coverage (extend `test/meta/memory.test.mjs`).
-
-### Phase 2a — Quick Wins (high-impact, low-effort tools for immediate agent effectiveness)
-
-Rationale: These tools provide maximum value with minimal implementation effort. They enable core agent capabilities: finding programs, composing music, and understanding file collections. See `doc/meta-tools/analysis.md` for detailed impact analysis.
-
-- [x] `find_and_run_program_by_name` — Implementation notes:
-  - **Priority #1** — Most requested feature; enables agents to search and run programs from disk collections.
-  - Search under a root (including inside `.d64/.d71/.d81/.t64`) for the first program whose filename contains a substring; run it.
-  - Supports PRG and CRT, case sensitivity toggle, and optional sort (path order vs. alphabetical).
-  - Agent state: recent searches (root, pattern, extensions), last run path.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info (wildcards) to discover; if target is inside a container, mount via PUT /v1/drives/{drive}:mount and run via a tiny BASIC loader (upload_run_basic) or menu automation; direct PUT /v1/runners:run_prg|:run_crt when file is on the host filesystem.
-  - Dependencies: `find_paths_by_name` (✅ implemented)
-  - Effort: 45 minutes
-- [x] `silence_and_verify` — Implementation notes:
-  - **Priority #2** — Essential foundation for all SID testing; quick win that unblocks music workflows.
-  - Silence all voices, then verify via short audio capture that output drops below a threshold.
-  - Agent state: threshold, capture window.
-  - REST: PUT|POST /v1/machine:writemem (SID reset), optional streams
-  - Dependencies: None
-  - Effort: 35 minutes
-- [x] `filesystem_stats_by_extension` — Implementation notes:
-  - **Priority #3** — Provides context for file operations; helps agents understand collections.
-  - Walk all files beneath a root—including files inside disk/tape images—and compute counts and size statistics (total, min, max, mean) per extension.
-  - Agent state: cached directoryg index, prior stats snapshots for trend comparisons.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info (wildcards); fallback: mount images and scrape directory via BASIC.
-  - Dependencies: None
-  - Effort: 35 minutes
-- [x] `music_compile_play_analyze` — Implementation notes:
-  - **Priority #4** — Complete music development workflow in one tool; high value for composition.
-  - Compile SIDWAVE→PRG or SID, play, then record-and-analyze; export analysis JSON and summary.
-  - Agent state: compilation cache, expected score, analysis logs.
-  - REST: POST /v1/runners:run_prg or POST /v1/runners:sidplay
-  - Dependencies: `silence_and_verify`
-  - Effort: 90 minutes
-
-Phase 2a total effort: ~205 minutes (3.4 hours) — High-impact foundation for agent capabilities.
-
----
-
-### Phase 2b — Graphics & Extraction (medium effort, high value for creative work)
-
-- [x] `extract_sprites_from_ram` — Implementation notes:
-  - **Priority #5** — Extract sprites from running programs for analysis and reuse.
-  - Search with stride for 63-byte sprite patterns; export `.spr`/hex/base64.
-  - Agent state: candidate heuristics, sprite index mapping, output folder.
-  - REST: GET /v1/machine:readmem, optional PUT /v1/machine:pause|resume
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - Effort: 80 minutes
-  - Coverage: `test/meta/screen.test.mjs`
-- [x] `rip_charset_from_ram` — Implementation notes:
-  - **Priority #6** — Extract custom character sets for reuse and font library building.
-  - Locate 2KB charsets by structure; export binary and a PNG preview.
-  - Agent state: range scan plan, preview images, output paths.
-  - REST: GET /v1/machine:readmem, optional PUT /v1/machine:pause|resume
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - Effort: 75 minutes
-  - Coverage: `test/meta/screen.test.mjs`
-- [x] `drive_mount_and_verify` — Implementation notes:
-  - **Priority #7** — Reliable drive mounting with retry logic.
-  - Power on if needed; mount; reset; verify via drives list. Retry with backoff.
-  - Agent state: retries, final mode, verification snapshot.
-  - REST: PUT /v1/drives/{drive}:on, PUT /v1/drives/{drive}:mount, PUT /v1/drives/{drive}:reset, GET /v1/drives
-  - Dependencies: `firmware_info_and_healthcheck` (✅ implemented)
-  - Effort: 45 minutes
-  - Coverage: `test/meta/filesystem.test.mjs`
-
-Phase 2b total effort: ~200 minutes (3.3 hours) — Graphics extraction and reliable disk handling.
-
----
-
-### Phase 2c — Advanced Features (lower priority, implement as needed)
-
-- [ ] `classify_prg_basic_or_mc` — Implementation notes:
-  - **Priority #8** — Distinguish BASIC from machine code for better error messages.
-  - For a given PRG path (host or inside a container), determine if it is tokenized BASIC or machine code/data using load address and token checks.
-  - Agent state: last probe result, token scanner configuration (PAL/NTSC irrelevant here).
-  - REST: PUT /v1/runners:load_prg (does not run), GET /v1/machine:readmem (few hundred bytes from load address), optional PUT /v1/machine:reset.
-  - Dependencies: None
-  - Effort: 45 minutes
-- [ ] `screen_capture_timeline` — Implementation notes:
-  - **Priority #9** — Record program execution over time.
-  - Timed captures; export timestamped log and optional GIF.
-  - Agent state: timer, frame store, export settings.
-  - REST: GET /v1/machine:readmem (via screen helper), or use MCP read_screen; optional PUT /v1/machine:pause|resume
-  - Dependencies: `wait_for_screen_text` (✅ implemented)
-  - Effort: 50 minutes
-- [ ] `sid_param_sweep` — Implementation notes:
-  - **Priority #10** — Advanced SID experimentation tool.
-  - Sweep ADSR/waveform/pulse width across ranges; schedule notes, capture audio, and score results.
-  - Agent state: sweep matrix, top-N results, audio artifacts.
-  - REST: PUT|POST /v1/machine:writemem (via SID registers), POST /v1/runners:sidplay (for sid attachments), optional streams
-  - Dependencies: `silence_and_verify`
-  - Effort: 90 minutes
-- [ ] `create_and_mount_blank_d64` — Implementation notes:
-  - **Priority #11** — Create working disks for file operations.
-  - Create blank D64; mount; optional BASIC header writer.
-  - Agent state: created image metadata.
-  - REST: PUT /v1/files/{path}:create_d64, PUT /v1/drives/{drive}:mount
-  - Dependencies: `drive_mount_and_verify`
-  - Effort: 35 minutes
-- [ ] `memory_snapshot_and_diff` — Implementation notes:
-  - **Priority #12** — Debug memory changes during program execution.
-  - Take two or more snapshots of one or multiple address ranges and produce a diff report (hex and structured JSON with offsets and values).
-  - Agent state: named snapshots, diff histories.
-  - REST: GET /v1/machine:readmem, PUT /v1/machine:pause, PUT /v1/machine:resume
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - Effort: 50 minutes
-- [ ] `disassemble_ram_region` — Implementation notes:
-  - **Priority #13** — Understand machine code in memory.
-  - Pause, read region, disassemble 6502 bytes (agent-side disassembler), write labeled listing to disk with optional symbol hints; resume.
-  - Agent state: symbol map, disassembly options, output files.
-  - REST: PUT /v1/machine:pause, GET /v1/machine:readmem, PUT /v1/machine:resume
-  - Dependencies: None
-  - Effort: 60 minutes
-
----
-
-### Phase 3 — Container Classification & Filesystem Management (when advanced filesystem work needed)
-
-- [ ] `container_aware_walk_and_classify` — Implementation notes:
-  - Recurse host and container entries; classify BASIC vs PRG-MC via load + read.
-  - Agent state: classification cache keyed by content hash and CBM directory entry, per-container manifests.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info; for BASIC vs PRG‑MC, either (a) read PRG header bytes if `/files:read` is available, or (b) use PUT /v1/runners:load_prg followed by GET /v1/machine:readmem at the file's load address to inspect tokens; cleanup via PUT /v1/machine:reset.
-  - Dependencies: `find_paths_by_name` (✅ implemented)
-  - Effort: 60 minutes
-- [ ] `dedup_scan` — Implementation notes:
-  - Group by size and extension; optional normalized names; optional hash when available.
-  - Agent state: size→paths index, optional fingerprint cache, serialized scan manifests.
-  - REST: GET /v1/files/{root}/**/*:info (wildcards). Note: content hashing requires a future `/files:read` capability; when absent, tool limits to size/name heuristics.
-  - Dependencies: `filesystem_stats_by_extension`
-  - Effort: 60 minutes
-- [ ] `dedup_plan_and_apply` — Implementation notes:
-  - Produce reversible quarantine plan; default dry-run; require explicit confirm to apply.
-  - Agent state: quarantine root, manifest of moved paths, rollback map, retention policy.
-  - REST: No direct delete/move endpoints today; this tool defaults to dry‑run and plan output. Apply is disabled unless host‑side filesystem integration or future endpoints are configured.
-  - Safety guards: dry‑run by default; explicit `apply=true` and `confirm_phrase` required; path allowlist; maximum deletions threshold; quarantine with rollback window; never touches outside allowed roots.
-  - Dependencies: `dedup_scan`
-  - Effort: 75 minutes
-
-Optional filesystem tools:
-
-- [ ] `sprite_preview_prg_batch` — Generate+run preview PRGs for many sprite blobs; capture screens. (Effort: 60 minutes)
-- [ ] `drive_mode_profile_switch` — Set drive mode with ROM load support. (Effort: 40 minutes)
-- [ ] `eject_and_poweroff_drive` — Remove image and power off drive. (Effort: 25 minutes)
-
----
-
-### Phase 4 — Additional Orchestration & Workflows (as needed)
-
-Not yet prioritized. See `doc/meta-tools/catalog.md` for full list of additional meta tools including:
-
-- Storage orchestration (batch_on_assets_apply_tools, etc.)
-- Screen/UI automation (menu_navigation_script, wait_for_screen_text extensions)
-- Developer loops (red_green_refactor_loop, multi_range_guardrails, safe_reset_sequence, drive_recovery_sequence)
-- Streaming workflows (stream_video_for_duration, stream_audio_and_record)
-- RAG-coupled tools (ask_and_apply_memory_fix, sprite_program_from_prompt)
-- Artifact pipelines (export_directory_listing_via_basic)
-
-These tools remain in the catalog for future implementation based on user demand and feedback.
-
----
-
-### Phase 5 — Debug Stream Workflows (post‑GA)
-
-**Infrastructure Prerequisites** (must be satisfied before starting this phase):
-
-- UDP ingest pipeline with backpressure and packet-loss handling (~40 hours — estimate includes design, implementation, testing)
-- Sampling/windowing design for high-rate streams and summary accuracy (~8 hours — research and prototyping)
-- Performance targets validated via load and soak tests (~8 hours — test infrastructure and benchmarking)
-- Observability and failure-mode coverage (metrics, logs, alerts, drop counters) (~16 hours — instrumentation and monitoring setup)
-- **Total infrastructure work: ~72 hours** (estimates based on similar streaming pipeline projects)
-
-**Rationale for Deferral**: Debug streaming tools are extremely valuable for assembly program verification (comparing expected vs actual execution) but require significant infrastructure work. Better to ship high-value, low-complexity features first (Phases 2a-3), then revisit debug streaming as a dedicated infrastructure project.
-
-**High-Value Debug Tools** (implement after infrastructure ready):
-
-- [ ] `debug_stream_watch` — Implementation notes:
-  - **Foundation tool** — Start/stop debug streams; summarize packet rates; enforce mutual exclusion with video stream.
-  - Agent state: packet counters, idle detection.
-  - REST: PUT /v1/streams/debug:start, PUT /v1/streams/debug:stop
-  - Dependencies: UDP infrastructure
-  - Effort: 55 minutes
-- [ ] `debug_loop_run_and_capture` — Implementation notes:
-  - **Critical for assembly verification** — Pause → start debug → resume → action → pause → stop → summarize packets.
-  - Support modes: 6510, VIC, 1541; choose minimal scope by default.
-  - Agent state: host:port, selected mode, rolling buffer, filters (address ranges, R/W, device), last summary.
-  - REST: PUT /v1/machine:pause, PUT /v1/streams/debug:start, PUT /v1/machine:resume, [action tool], PUT /v1/machine:pause, PUT /v1/streams/debug:stop
-  - Safety: refuse when video stream is active; enforce max duration; auto-stop on packet loss; configurable throttling.
-  - Dependencies: `debug_stream_watch`
-  - Effort: 80 minutes
-- [ ] `verify_raster_irq_line` — Implementation notes:
-  - **Essential for graphics programming** — Verify raster IRQ is programmed to a specific line by correlating writes to $D012/$D011 and ensuing IRQ acks; report mismatches.
-  - Agent state: expected lines, tolerance for off-by-one conditions.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop
-  - Dependencies: `debug_loop_run_and_capture`
-  - Effort: 70 minutes
-- [ ] `debug_trace_until_cpu_write` — Implementation notes:
-  - **Precise debugging** — Run until a CPU write to an address (or set) is observed; then immediately pause and return a short trace window around the event.
-  - Agent state: address watch set, pre/post window sizes, event metadata.
-  - REST: PUT /v1/machine:pause, PUT /v1/streams/debug:start, PUT /v1/machine:resume, PUT /v1/machine:pause, PUT /v1/streams/debug:stop
-  - Dependencies: `debug_loop_run_and_capture`
-  - Effort: 70 minutes
-- [ ] `action_latency_measure` — Implementation notes:
-  - **Performance measurement** — Measure cycles between issuing an action (e.g., menu_button, `c64_memory` `write`) and the first observed matching bus event; return cycle/µs estimate.
-  - Agent state: action timestamp, first-match timestamp, CPU clock assumption (PAL/NTSC option).
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop, PUT /v1/machine:menu_button|:writemem|runners
-  - Dependencies: `debug_loop_run_and_capture`
-  - Effort: 75 minutes
-
-Optional debug tools (implement after above pass):
-
-- [ ] `verify_irq_jitter` — Measure IRQ handler periodicity. (Effort: 70 minutes)
-- [ ] `sid_register_write_profile` — Capture and summarize SID writes. (Effort: 70 minutes)
-- [ ] `iec_bus_handshake_probe` — Use 1541 debug mode to capture IEC bus activity. (Effort: 85 minutes)
-- [ ] `time_bounded_trace_around_event` — Maintain circular buffer and freeze on predicate match. (Effort: 70 minutes)
-
-Notes:
-
-- Debug stream consumes significant bandwidth and cannot run concurrently with video; tools enforce mutual exclusion and strict time limits.
-- Modes supported: 6510, VIC, 6510&VIC, 1541, 6510&1541. Tools select minimal necessary mode for the predicate to reduce load.
-
----
-
-### Phase 4 — Additional Orchestration & Workflows (moved from original Phase 6, lower priority)
-
-Not yet prioritized; these tools remain in the catalog for future implementation based on user demand:
-
-- [ ] `red_green_refactor_loop` — Iterate: run → capture screen → `c64_memory` `write` fixes → rerun until pass.
-- [ ] `multi_range_guardrails` — Continuously verify invariants; auto-restore from snapshot on violations.
-- [ ] `safe_reset_sequence` — Snapshot select ranges; reset; compare persistence; resume.
-- [ ] `drive_recovery_sequence` — Detect error; reset; power cycle; remount last image; verify.
-
-RAG-coupled meta tools:
-
-- [ ] `ask_and_apply_memory_fix` — Retrieve assembly guidance (RAG), compute targeted writes, then `verify_and_write_memory`.
-- [ ] `sprite_program_from_prompt` — Generate PETSCII/sprite asset from text; preview PRG; capture screen.
-
-Optional experiments:
-
-- [ ] `memory_heatmap_over_time`
-- [ ] `irq_latency_probe`
-- [ ] `sid_voice_stuck_guard`
-- [ ] `auto_benchmark_suite`
-- [ ] `firmware_compat_matrix`
-- [ ] `ultimate_config_migrate`
-
----
-
-### Per-task Done Definition (LLM must verify before ticking)
-
-- Implementation compiles with no TypeScript errors (where applicable).
-- New/updated tests exist and are passing locally.
-- `npm run check` passes end-to-end.
-- Documentation updated if tool behavior changed.
-
-### How to tick off checkboxes (LLM instructions)
-
-- After completing a checklist item and confirming the Done Definition, update the corresponding `- [ ]` line to `- [x]` in `doc/meta-tools/rollout.md`.
-- Only tick one line at a time, from top to bottom, respecting phases and dependencies.
-- After ticking, immediately run `npm run check` again to ensure that the documentation update did not break formatting-sensitive scripts.
-
-### Notes on sequencing
-
-- Respect the dependency graph from `doc/meta-tools/catalog.md` (Effort/Benefit/Dependencies Matrix).
-- Within a phase, process items in order. If an item depends on another not yet done, jump to the dependency’s phase, complete it, then resume.

package/doc/plans/prompts/README.md

@@ -1,96 +0,0 @@
-# Prompt Taxonomy and Context Plan
-
-This document captures the design work for **Phase 5 / Step 4.1** of the MCP migration: defining the prompt
-families, required context, and reusable prompt segments. These notes do **not** contain the final prompt
-strings; they specify the structure so that `promptRegistry` can assemble concrete prompts and the test
-suite can assert expectations in upcoming steps.
-
----
-
-## 1. Prompt Families & Goals
-
-| Family ID | Mission | Primary Users | Core Outputs |
-| --- | --- | --- | --- |
-| `basic-program` | Generate, run, and verify Commodore BASIC programs. | BASIC Agent / general workflows | Tokenised BASIC source, post-run verification steps, tool invocation hints. |
-| `assembly-program` | Author 6502/6510 assembly for VIC/SID/CIA tasks with safety checks. | ASM Agent / low-level workflows | Assembly source blocks, load/execute instructions, IRQ or memory safety reminders. |
-| `sid-music` | Compose SID music with expressive timing and iterative audio checks. | SID Composer | Melody plans, SID register recipes, guidance to analyse playback. |
-| `graphics-demo` | Produce graphics routines (sprites, PETSCII art, bitmap/raster effects). | VIC Painter | Mode setup instructions, colour guidance, verification routines. |
-| `printer-job` | Send formatted output to Commodore or Epson printers safely. | Printer Operator | Device selection, character-set notes, print/eject workflow. |
-| `memory-debug` | Inspect or patch memory without destabilising the system. | Memory Debugger | Safe read/write plans, freeze/resume advice, logging expectations. |
-| `drive-manager` | Mount/create disk images and manage drives carefully. | Drive Manager | Pre-flight checks, mount/remove sequences, follow-up validation. |
-
-> These families mirror the MCP tool domains so that prompt guidance matches available capabilities.
-
----
-
-## 2. Required Resource Context per Family
-
-| Family | Baseline Resources (URIs) | Rationale |
-| --- | --- | --- |
-| `basic-program` | `c64://basic/spec`, `c64://guide/bootstrap`, `c64://guide/index` | Reinforce BASIC token rules, PETSCII gotchas, workflow expectations. |
-| `assembly-program` | `c64://assembly/6510-spec`, `c64://guide/bootstrap`, `c64://graphics/vic/spec`, `c64://sound/sid/spec` | Provide opcode tables, IRQ setup, VIC/SID register references. |
-| `sid-music` | `c64://sound/sid/spec`, `c64://sound/sidwave/spec`, `c64://sound/sid/file-format` | Supply register map, SIDWAVE format, SID file metadata. |
-| `graphics-demo` | `c64://graphics/vic/spec`, `c64://guide/bootstrap` | Cover VIC mode bits, raster constraints, general workflow guidance. |
-| `printer-job` | `c64://printer/spec`, `c64://printer/commodore/text`, `c64://printer/prompt-guide` | Document PETSCII vs ESC/P workflows, sample templates, and safety checks. |
-| `memory-debug` | `c64://guide/bootstrap`, `c64://assembly/6510-spec`, `c64://guide/index` | Highlight addressing safeguards, workflow rules, and knowledge map summaries. |
-| `drive-manager` | `c64://guide/bootstrap` | Ensure awareness of system-wide safety rules before altering drives. |
-
-Notes:
-
-- Resource URIs reflect existing knowledge catalog entries; verify actual IDs during prompt implementation.
-- `drive-manager` currently relies on orientation material only; plan to author a dedicated storage/drive guide resource.
-- Additional resources (memory map, VIC character set, SID best practices) remain desirable—tracked in follow-ups below.
-
----
-
-## 3. Default Tool Suggestions per Family
-
-| Family | Must-Suggest Tools | Optional Tools | Warnings |
-| --- | --- | --- | --- |
-| `basic-program` | `c64_program`, `c64_memory` | `c64_system` (ops `reset`, `start_task`) | Remind to reset only if user confirms; highlight PETSCII newline handling. |
-| `assembly-program` | `c64_program`, `c64_memory` | `c64_system` (ops `reset`, `pause`, `resume`) | Require IRQ acknowledgement steps for raster code; caution on zero-page writes. |
-| `sid-music` | `c64_sound` (ops `generate`, `note_on`, `analyze`) | `c64_sound` (ops `compile_play`, `play_sid_file`, `set_volume`) | Warn about volume resets (`$D418`) and making backups before overwriting SID memory. |
-| `graphics-demo` | `c64_program`, `c64_memory`, `c64_graphics` | `c64_system` (op `pause`), `c64_memory` (op `read`) | Emphasise safe colour RAM usage; mention border side-effects for raster tricks. |
-| `printer-job` | `c64_printer` (ops `print_text`, `print_bitmap`) | `c64_printer` (op `define_chars`), `c64_memory` | Remind users to send `CHR$(12)` before closing; confirm `printer` argument (`commodore` vs `epson`) before printing. |
-| `memory-debug` | `c64_memory`, `c64_system` (ops `pause`, `resume`) | `c64_system` (op `reset`) | Advise capturing snapshots before writes; include address validation heuristics. |
-| `drive-manager` | `c64_disk` (ops `list_drives`, `mount`, `unmount`) | `c64_disk` (ops `file_info`, `create_image`, `find_and_run`), `c64_drive` (ops `reset`, `power_on`, `power_off`, `load_rom`, `set_mode`), `c64_system` (op `resume`) | Highlight risk of interrupting running programs; recommend verifying mounts after actions. |
-
----
-
-## 4. Reusable Prompt Segments (`promptSegments`)
-
-| Segment ID | Purpose | Content Summary |
-| --- | --- | --- |
-| `intro/core` | Universal introduction | Remind user the MCP runs against Ultimate 64 REST, mention tool invocation expectation. |
-| `safety/reset` | Caution about disruptive actions | Ask for confirmation before resets/writes that halt the machine. |
-| `workflow/basic-verify` | Post-run checklist for BASIC | Suggest `c64_memory` (op `read_screen`) capture, optional `c64_memory` (op `read`) for program area, note PETSCII output quirks. |
-| `workflow/asm-irq` | IRQ safety guidance | Outline `SEI`, vector setup, `$D01A` mask, `$D019` acknowledge, `CLI`. |
-| `workflow/sid-iterate` | Audio feedback loop | Steps: compose → play → run `analyze_audio` → adjust ADSR/frequency. |
-| `workflow/graphics-verify` | Visual validation | Encourage screenshot via `c64_memory` (op `read_screen`), mention border/background toggles. |
-| `workflow/printer` | Print job completion | Ensure `CHR$(12)` for page eject, close channel, suggest checking printer status. |
-| `workflow/memory-snapshot` | Safe memory editing | Recommend pausing, using `c64_memory` reads before writes, and resuming afterwards. |
-| `workflow/drive` | Drive changes | Pre-check currently mounted images, confirm after action, note potential interference with running programs. |
-
-Segments should be composable so prompts can include `intro/core` + family-specific workflow + optional `safety/reset` depending on requested action.
-
----
-
-## 5. Arguments & Variations (Preliminary)
-
-- `assembly-program` may accept a `hardware` argument (`sid`, `vic`, `cia`, `multi`) to pull in targeted resource snippets.
-- `graphics-demo` may accept `mode` (`text`, `multicolour`, `bitmap`, `sprite`) to tailor register setup.
-- `printer-job` may accept `printerType` (`commodore`, `epson`) to adjust command examples and character-set notes.
-- Future prompts should validate arguments and provide descriptive errors if unsupported values are provided.
-
-Argument handling will be implemented in `promptRegistry.resolve` during Step 4.3; this section informs schema design.
-
----
-
-## 6. Open Questions & Follow-Ups
-
-- Extend the knowledge index with dedicated memory-map, drive-management, and character-set resources so prompts can cite them directly.
-- Add SID best-practices material (triangle wave workflow) to the knowledge catalog or link from prompts explicitly.
-- Adjust `storageModule.prompts` to include `drive-manager` once the prompt is authored, keeping tool metadata consistent.
-- Ensure prompt tests assert for resource/tool mentions and safety callouts per family.
-
-Document owner: Prompts migration effort (Phase 5).

package/doc/plans/prompts/user-prompt-ideas.md

@@ -1,147 +0,0 @@
-# Example LLM Prompts for C64 Bridge Server
-
-These example prompts illustrate what a user can ask the MCP server to perform on a real or emulated Commodore 64.
-The MCP bridges the user’s intent with direct program generation, execution, or device control.
-
->[!NOTE] This is meant as a brainstorm collection of prompts. Some of the prompts mentioned below are not yet supported by the current MCP tools.
-
----
-
-## 🧠 General Interaction
-
-- "Show me the current C64 system state."
-- "Reset the C64 and verify that BASIC is ready."
-- "List all mounted disk images."
-- "Mount the disk `games.d64` and list its directory."
-- "Save the current memory to `snapshot.bin`."
-- "Restore RAM from `snapshot.bin` and continue execution."
-- "Transfer and run the program `demo.prg`."
-- "Print the current screen output as text."
-- "Show me the registers of CIA 1 and CIA 2."
-- "Pause execution and dump memory from `$0800` to `$0FFF`."
-
----
-
-## 💾 Memory and System Control
-
-- "Read 32 bytes starting at `$C000`."
-- "Write the value `$A9` to address `$C000`."
-- "Fill memory from `$0400` to `$07E7` with `$20` (space)."
-- "Dump the zero page as a hex table."
-- "Freeze the CPU, modify `$D020` to `$06`, and resume."
-- "Trigger a soft reset."
-- "Hard reset the C64 and reload `boot.prg`."
-
----
-
-## 💡 BASIC Programming
-
-- "Create a BASIC program that prints 'HELLO WORLD' in the center of the screen."
-- "Generate a BASIC listing for a bouncing ball animation."
-- "Convert this text into a valid BASIC tokenized PRG:"
-  
-  ```basic
-  10 PRINT "READY."
-  20 GOTO 10
-  ```
-
-- "List all BASIC variables after program execution."
-- "Run the currently loaded BASIC program and capture its output."
-- "Save the BASIC program as `HELLO.PRG` to disk."
-- "Show the BASIC memory map and string descriptors."
-
----
-
-## ⚙️ Assembly Programming
-
-- "Assemble a short 6502 routine that changes the border colour every frame."
-- "Inject this code into RAM at `$C000` and execute:"
-  
-  ```assembly
-  LDA #$06
-  STA $D020
-  RTS
-  ```
-
-- "Assemble and run a raster interrupt that flashes the screen every 50 Hz."
-- "Disassemble memory from `$C000` to `$C050`."
-- "Step through 10 instructions and show registers after each step."
-- "Assemble a SID music player routine at `$1000`."
-- "Assemble and export a `.prg` file from this source."
-
----
-
-## 🎵 SID Music Composition
-
-- "Compose a short SID tune in the style of early Rob Hubbard."
-- "Generate a 3-voice arpeggio sequence in C major, lasting 8 seconds."
-- "Export this tune as `demo.sid`."
-- "Play the current SID file through the C64 SID chip."
-- "Visualize the waveform and envelope data for each voice."
-- "Show which SID registers are used for filter modulation."
-
----
-
-## 🎨 PETSCII Art and Graphics
-
-- "Create a PETSCII logo reading 'C64 Bridge' with rainbow gradient."
-- "Generate a PETSCII image of a spaceship using block characters."
-- "Convert this PNG into PETSCII art compatible with C64 screen memory."
-- "Preview the PETSCII output as text."
-- "Export the artwork to `logo.seq` and `logo.prg`."
-- "Display the PETSCII artwork on the screen."
-
----
-
-## 🖨️ Printing and Document Generation
-
-- "Print the current BASIC listing to a virtual printer."
-- "Render a document header: 'Commodore 64 Report – 1984 Edition'."
-- "Generate a formatted report of all memory changes in the last session."
-- "Print the PETSCII artwork as a text file."
-- "Export screen contents to PDF via MCP printer adapter."
-
----
-
-## 🧩 Disk and File Management
-
-- "Create a new disk image called `workbench.d64`."
-- "Mount `music.d64` as drive 8."
-- "List files on drive 8."
-- "Delete the file `OLDGAME.PRG` from drive 8."
-- "Copy `HELLO.PRG` to drive 9 as `HELLO2.PRG`."
-- "Transfer file `game.prg` from local PC to drive 8."
-- "Unmount all drives."
-
----
-
-## 🧪 Testing and Diagnostics
-
-- "Run a video sync test pattern."
-- "Play a POP audio + frame sync signal for calibration."
-- "Measure frame delay between video and audio."
-- "Report VIC-II raster timing and SID voice status."
-- "Check if the system is running at PAL or NTSC frequency."
-- "Benchmark CPU speed using a short 1000-iteration loop."
-
----
-
-## 🤖 Integrated AI Tasks
-
-- "Generate a new BASIC game idea and create its program automatically."
-- "Write assembly code that plays a melody while showing scrolling text."
-- "Convert a SID file into BASIC DATA statements."
-- "Explain what the program at `$0801` does."
-- "Translate this assembly snippet into commented pseudocode."
-- "Optimize this BASIC program for speed and memory."
-- "Summarize the PETSCII image currently displayed."
-
----
-
-## 📚 Meta Commands
-
-- "Describe all capabilities of this MCP server."
-- "List all available agents (BASIC, Assembly, SID, PETSCII, Disk)."
-- "Explain how to connect an external tool (like VICE or Ultimate 64)."
-- "Show examples of valid API calls for writing to memory."
-- "Show recent system logs."

package/doc/plans/tool-consolidation/notes.md

@@ -1,28 +0,0 @@
-# Tool Consolidation Working Notes
-
-## Required Reading Confirmation
-
-- `doc/tool-consolidation/plan.md` — Consolidation objectives, grouped tool mapping, and implementation checklist.
-- `doc/developer.md` — Contribution workflow, testing gates (`npm run check`), and documentation requirements.
-- `README.md` (auto-generated MCP surface section) — Current tool/resource listings to validate documentation updates.
-- `scripts/generate-docs.ts` and `src/tools/registry/index.ts` — Existing documentation pipeline and registration mechanics to be refactored.
-
-## Key Acceptance Criteria from the Consolidation Plan
-
-- Expose exactly **12 grouped tools** prefixed with `c64.*`, each defined as a discriminated union on an `op` field.
-- Preserve every legacy operation by mapping it into one of the grouped tools without behavior regressions.
-- Introduce `verify?: boolean` where prior tools performed separate verification (memory writes, SID silence, disk mount, upload+run flows).
-- Collapse background task management into `c64_system` while keeping streaming as a dedicated `c64_stream` tool.
-- Provide shared dispatch helpers that route `args.op` to the appropriate handler with concise descriptions (≤2 sentences per op).
-- Update TypeScript types, schemas, and validators so LLM clients receive complete JSON Schema visibility for every operation.
-- Regenerate documentation such that grouped tools appear in a unified section with nested operations and a summary line reflecting 12 tools / ~81 ops / 25 resources / 7 prompts.
-- Maintain automated tests that assert grouped tool registration, schema discrimination, and representative happy-path executions for each tool family.
-- Refresh the changelog with an entry describing the consolidation and the move to discriminated schemas.
-
-## Additional Implementation Considerations
-
-- Stage migrations to keep the MCP server runnable at all times; introduce compatibility shims if some clients still expect legacy tool names until rollout completion.
-- Ensure `scripts/generate-docs.ts` and any README automation remain idempotent after schema changes.
-- Re-run `npm run check` after each incremental change set; prioritize small, reviewable commits to simplify rollback.
-- Validate LLM discoverability by exercising Copilot Chat or `list_tools` once grouped schemas are in place.
-- Document any noteworthy deviations (e.g., future `generate_bitmap` operation) so downstream prompts can reference upcoming capabilities without confusing current behavior.