c64bridge 1.0.6 → 1.1.0

package/doc/plans/improve-knowledge/rollout.md

@@ -1,110 +0,0 @@
-# Knowledge Improvement Rollout Plan
-
-Purpose: Execute the prioritized improvements captured in `doc/improve-knowledge/plan.md` so the MCP server delivers better grounding, creative defaults, and structured outputs. This rollout is written for an LLM operator; all tasks must be completed strictly in order with checkboxes ticked sequentially.
-
-## Required Reading (complete before any checkbox work)
-
-- `doc/improve-knowledge/plan.md` — Findings, recommendations, ranked shortlist.
-- `doc/developer.md` — Contribution workflow, testing guidance.
-- `README.md` (API section) — Current tool/resource surface to validate documentation updates.
-- Target source files referenced per recommendation (see sections below).
-
-## Operator Rules (follow for the entire rollout)
-
-- Always process tasks exactly in the order listed. Do not tick a checkbox until all previous boxes in this document are ticked.
-- After completing any checklist item, immediately run `npm run check`. Only proceed if it succeeds.
-- If `npm run check` fails:
-  - Attempt a focused fix once.
-  - If still failing, revert the latest change, note the failure in a status log, and stop execution.
-- Keep changes minimal and scoped to the current checklist item. Avoid refactors unless explicitly required.
-- When implementing new behavior, update or add tests that cover the happy path and at least one failure/edge case.
-- Update documentation in the same change when tool surfaces, schemas, or defaults shift.
-- Respect hardware-affecting safeguards already in the codebase (pause/resume, timeouts, mutual exclusion).
-
-## Global Implementation Template (apply for each improvement)
-
-For every checklist item below, execute the following sub-steps in order (these sub-steps do not require additional checkboxes but must be followed):
-
-1. Review the cited code paths and confirm dependencies are in place.
-2. Draft minimal changes to satisfy the recommendation.
-3. Extend or add tests covering the new behavior.
-4. Update documentation, schemas, and TypeScript types as required.
-5. Run `npm run check` and ensure it passes before ticking the item.
-
-## Phase 0 — Rollout Initialization
-
-- [x] Confirm all documents in “Required Reading” are reviewed and summarize key acceptance criteria from `doc/improve-knowledge/plan.md` in your working notes.
-
-## Phase 1 — Retrieval & Knowledge Grounding (highest-priority shortlist items)
-
-- [x] R1: Implement structured RAG results with URI, origin, and score metadata (`src/tools/rag.ts`, `src/rag/retriever.ts`, `src/rag/indexer.ts`). Ensure responses expose resource URIs compatible with `ReadResource`.
-- [x] K1: Expose memory and IO documentation as MCP resources (`src/rag/knowledgeIndex.ts`, `src/mcp-server.ts`, `data/memory/*`, `data/io/*`). Add schema entries if needed.
-- [x] K2: Publish SID best-practices as an accessible MCP resource (`data/sound/sid-programming-best-practices.md`, resource registry).
-
-## Phase 2 — Creative Defaults & Validation
-
-- [x] G1: Update `music_generate` defaults to triangle waveform with recommended ADSR profile; document the new “musical expression” preset (`src/tools/audio.ts`, `src/c64Client.ts`, best-practices doc). Preserve options to request legacy pulse behavior.
-- [x] T1: Add automated tests verifying the new SID defaults (PAL/NTSC pitch accuracy and ADSR adherence) (`test/audioAnalysis.test.mjs` or adjacent suites).
-
-## Phase 3 — MCP Surface Improvements
-
-- [x] M2: Standardize structured JSON outputs for all program runners, including entry addresses, artifacts, and URIs while retaining human-readable summaries (`src/tools/programRunners.ts`, `src/tools/types.ts`).
-- [x] M1: Remove the artificial dependency between `upload_run_basic` and `read_screen`, ensuring documentation reflects independent usage (`src/tools/memory.ts`, related docs or schemas).
-
-## Phase 4 — Reproducibility & Packaging
-
-> Implementation guardrails for S1  
-> • Base image must be `node:24-bookworm-slim` (or newer 24.x digest) to keep parity with local tooling.  
-> • Create a dedicated non-root user (e.g., `bridge`) with home `/app` and run the container as that user.  
-> • Copy `package.json`, `package-lock.json`, and `npm ci` during build before adding the rest of the repo to leverage caching.  
-> • Switch `WORKDIR` to `/app`, copy the code, and set `CMD ["npm","start"]`.  
-> • Ensure the container runs `npm start` without extra flags, reading configuration from env vars.  
-> • Update `README.md` (Containers section) and `doc/improve-knowledge/notes.md` with build/run examples (`docker build` / `docker run`).  
-> • Validate locally via `docker build` + `docker run --rm c64bridge:dev` before checking the box.
-
-- [x] S1: Produce the reproducible container workflow described above, updating `Dockerfile`, README, and notes so future operators can rebuild and run the MCP server in that container.
-- [x] S2: Replace license name and URL with SPDX identifier in structured RAG refs (ensure `origin`, `uri`, `spdxId` fields are present; map when possible) (`src/rag/indexer.ts`, `src/rag/retriever.ts`, `src/tools/rag.ts`).
-- [x] D1: Add a concise “What changed” MCP summary to README/resource index after build; link the platform status resource (`README.md`, `src/mcp-server.ts`).
-- [x] D2: Cross-link prompts to key resources (SID best-practices, VIC-II, PETSCII/charset quickrefs) for richer in-editor guidance (`src/prompts/registry.ts`).
-
-## Phase 5 — Knowledge Exposure & Retrieval Enhancements
-
-- [x] K3: Add “BASIC pitfalls” quickref and publish as MCP resource; link from BASIC runners (`data/basic/basic-pitfalls.md`, `src/rag/knowledgeIndex.ts`, `src/tools/programRunners.ts`).
-- [x] K4: Publish PETSCII/charset quickrefs (char codes, glyph map) as MCP resources; dynamically generate Markdown table from `data/graphics/character-set.csv` (build-time or runtime) to avoid duplicate sources (`src/rag/knowledgeIndex.ts`).
-- [x] K5: Publish VIC-II register quickref as MCP resource and ensure graphics tools reference it (`data/graphics/vic-spec.md`, `src/tools/graphics.ts`).
-- [x] R2: Include bundle/resource URIs in RAG results when matches originate from docs (`src/rag/retriever.ts`, `src/tools/rag.ts`).
-- [x] R3: Add retrieval diversity and simple duplicate suppression in top-K (`src/rag/retriever.ts`).
-- [x] M5: Add PAL/NTSC-sensitive tags to relevant tools (SID, graphics) to nudge system-awareness (`src/tools/audio.ts`, `src/tools/graphics.ts`).
-- [x] M4: Audit remaining tools for validation messages and examples; bring to parity (`src/tools/*`).
-- [x] T2: Add e2e test for `rag_retrieve_*` verifying structured refs open via `ReadResource` (`test/rag.test.mjs`).
-
-## Phase 6 — Creative Surface: Graphics & SID Workflows
-
-- [x] G2: Auto-detect or remind PAL/NTSC context for `sid_note_on`; reflect in metadata (`src/c64Client.ts`, `src/tools/audio.ts`).
-- [x] G3: Include PRG metadata (entry addresses, bytes) in program runners’ structured outputs (`src/tools/programRunners.ts`).
-- [x] G4: Ensure PETSCII structured outputs and docs highlight selected glyphs/codes and miniature preview (`src/tools/graphics.ts`, docs).
-- [x] G5: Document PETSCII style presets (contrast, dithering, palette) and link from prompts (`src/prompts/registry.ts`, docs under `data/graphics/`).
-- [ ] G6: Add hires bitmap PRG generator tool and document a minimal usage flow (`src/tools/graphics.ts`, `test/graphicsModule.test.mjs`).
-- [x] K6: Add “Sprite & Charset workflows best-practices” document and expose as resource (`data/graphics/sprite-charset-best-practices.md`, `src/rag/knowledgeIndex.ts`).
-- [x] T4: Add PETSCII generation e2e test verifying preview fields and PRG execution (`test/graphicsModule.test.mjs`).
-- [x] T5: Add sprite preview PRG test (bytes copied, coords/colour applied, screen captured) (`test/graphicsModule.test.mjs`).
-
-## Done Definition (before ticking any item)
-
-Only tick a checkbox when all of the following are true for that item:
-
-- TypeScript compilation succeeds with no new errors.
-- All new or updated tests pass locally.
-- `npm run check` has been executed successfully immediately after the change.
-- Relevant documentation and schemas reflect the change.
-- No subsequent checklist item has been started.
-
-## Notes on Sequencing
-
-- If a task reveals a missing prerequisite not covered earlier, pause, document the gap, and stop instead of reordering tasks.
-- Within each phase, tasks are intentionally ordered by dependency and impact; do not parallelize or skip.
-
-## Post-Rollout Wrap-Up (perform after all checkboxes are ticked)
-
-- Document a short retrospective (location of your choice) summarizing lessons learned, remaining risks, and follow-up candidates that were out of scope.
-- Share the retrospective with maintainers alongside the final change set.

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

@@ -1,110 +0,0 @@
-# Meta Tools Documentation
-
-This folder contains documentation for c64bridge meta tools — high-level orchestration tools that compose multiple MCP operations into single, stateful workflows.
-
-## Documents
-
-- **[catalog.md](catalog.md)** — Comprehensive catalog of all meta tools with detailed specifications, effort/benefit analysis, and dependency matrix
-- **[rollout.md](rollout.md)** — Implementation checklist with phases, dependencies, and done criteria for executing the meta tools rollout
-- **[analysis.md](analysis.md)** — Impact analysis and prioritization rationale; explains why tools are ordered as they are based on agent effectiveness
-- **[notes.md](notes.md)** — Implementation notes, observations, lessons learned, and technical decisions
-
-## Quick Overview
-
-### What are Meta Tools?
-
-Meta tools reduce round-trips between client and server by bundling multiple REST/MCP calls into single, stateful operations with agent-side state management (snapshots, buffers, registries, etc.).
-
-### Current Status
-
-**Implemented (Phase 0-2a quick wins)**:
-
-- Foundation tools (Phase 0): firmware health checks, screen polling, memory verification, background tasks
-- Orchestration (Phase 1): program shuffle, batch assertions, artifact bundling, compile-run-verify cycles
-- Quick wins (Phase 2a): find-and-run program by name, silence-and-verify SID output, filesystem stats by extension
-
-**Not Implemented (~60 tools)**: See catalog.md for full list
-
-### Implementation Priority (New Reprioritization)
-
-See [analysis.md](analysis.md) for detailed rationale.
-
-**Phase 2a — Quick Wins** (~3.4 hours, high impact):
-
-1. `find_and_run_program_by_name` — Find and run programs in disk collections
-2. `silence_and_verify` — SID testing foundation
-3. `filesystem_stats_by_extension` — Understand file collections
-4. `music_compile_play_analyze` — Complete music workflow
-
-**Phase 2b — Graphics & Extraction** (~3.3 hours):
-
-- Extract sprites and character sets from RAM
-- Reliable drive mounting
-
-**Phase 2c — Advanced Features**: Classification, timelines, parameter sweeps, memory diffing
-
-**Phase 3 — Container Management**: Classify PRG types, deduplication
-
-**Phase 4 — Additional Orchestration**: Developer loops, RAG-coupled tools
-
-**Phase 5 — Debug Streaming** (Post-GA, requires ~72 hours of infrastructure):
-
-- Assembly verification, IRQ validation, bus tracing
-- Deferred until UDP ingest pipeline is ready
-
-## Key Insights from Analysis
-
-1. **Filesystem navigation is critical** — Agents struggle to find programs in disk collections; `find_and_run_program_by_name` is the #1 priority
-2. **SID testing needs proper silence verification** — Quick win that unblocks music composition
-3. **Debug streaming is valuable but complex** — Requires UDP infrastructure; better to ship simpler high-value features first
-4. **Graphics extraction has broad appeal** — Sprite/charset extraction enables creative reuse
-
-## For Implementers
-
-Start with [rollout.md](rollout.md) which provides:
-
-- Required reading list
-- Operator rules (process strictly in order, run tests after each change)
-- Global implementation template
-- Phase-by-phase checklists with dependencies
-
-Each meta tool entry includes:
-
-- Priority ranking
-- Effort estimate (minutes)
-- Benefit level (high/medium/low)
-- Dependencies
-- Implementation notes
-- REST endpoints used
-
-## For Users
-
-See [catalog.md](catalog.md) for:
-
-- Tool purpose and use cases
-- Agent-managed state
-- Underlying REST/MCP operations
-- Expected behavior
-
-## Architecture
-
-Meta tools live in `src/tools/meta/` with submodules:
-
-- `diagnostics.ts` — Health checks, firmware info
-- `screen.ts` — Screen polling, text matching
-- `memory.ts` — Memory dumps, verification, diffs
-- `background.ts` — Background task scheduling
-- `filesystem.ts` — File discovery, stats
-- `config.ts` — Configuration snapshots
-- `program.ts` — Program orchestration
-- `artifacts.ts` — Artifact bundling
-- `compilation.ts` — Build-test cycles
-
-All meta tools are marked as experimental and exposed through the standard MCP tool registry.
-
-## Related Documentation
-
-- `doc/agent-state-spec.md` — Background task registry specification
-- `doc/developer.md` — Architecture overview and contribution guidelines
-- `doc/improve-knowledge/` — Similar documentation structure pattern
-- `src/tools/meta/` — Implementation source code

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

@@ -1,272 +0,0 @@
-# Meta Tools Impact Analysis
-
-Purpose: Analyze unimplemented meta tools to identify high-impact, low-effort candidates that will most improve agent capabilities for BASIC/ASM coding, graphics generation, SID music composition, and C64 filesystem navigation.
-
-## Current Implementation Status
-
-### Implemented (Phases 0-2a quick wins)
-
-- ✅ `firmware_info_and_healthcheck` — Verify firmware readiness
-- ✅ `wait_for_screen_text` — Poll screen for text/regex matches
-- ✅ `verify_and_write_memory` — Safe memory write with verification
-- ✅ `start_background_task`, `stop_background_task`, `list_background_tasks`, `stop_all_background_tasks` — Background task orchestration
-- ✅ `find_paths_by_name` — Container-aware file discovery
-- ✅ `memory_dump_to_file` — Export memory ranges to files
-- ✅ `config_snapshot_and_restore` — Configuration backup/restore
-- ✅ `program_shuffle` — Run multiple programs sequentially
-- ✅ `batch_run_with_assertions` — Run programs with validation
-- ✅ `bundle_run_artifacts` — Collect run artifacts
-- ✅ `compile_run_verify_cycle` — Complete build-test cycle
-- ✅ `find_and_run_program_by_name` — Discover and run programs by substring
-- ✅ `silence_and_verify` — SID silence guard/verification workflow
-- ✅ `filesystem_stats_by_extension` — Filesystem and container stats aggregation
-
-### Not Implemented: ~60 tools across multiple domains
-
-## Impact Analysis for Agent Capabilities
-
-### 1. C64 Filesystem Navigation & Program Discovery (CRITICAL)
-
-**Problem**: Agents struggle to find and run programs in large C64 file collections (D64/D71/D81/T64 images)
-
-**High-Impact Tools**:
-
-- **`find_and_run_program_by_name`** ⭐⭐⭐⭐⭐ (Effort: 45min, Benefit: HIGH)
-  - Impact: Enables agents to search entire filesystem and run programs by name
-  - Use cases: "Run Archon from my games collection", "Load the demo called Boulder"
-  - Dependencies: `find_paths_by_name` (✅ implemented)
-  - **PRIORITY: #1** — Essential for effective C64 interaction
-
-- **`filesystem_stats_by_extension`** ⭐⭐⭐ (Effort: 35min, Benefit: MEDIUM)
-  - Impact: Helps agents understand file collections and provide insights
-  - Use cases: "How many games do I have?", "List all PRG files"
-  - Dependencies: None
-  - **PRIORITY: #3** — Good context for navigation
-
-- **`classify_prg_basic_or_mc`** ⭐⭐⭐ (Effort: 45min, Benefit: MEDIUM)
-  - Impact: Distinguishes BASIC from machine code programs
-  - Use cases: Better error messages, appropriate testing strategies
-  - Dependencies: `container_aware_walk_and_classify`
-  - **PRIORITY: #8** — Useful but not urgent
-
-### 2. Graphics Generation & Extraction (HIGH)
-
-**Problem**: Agents need better tools to create, manipulate, and extract C64 graphics
-
-**High-Impact Tools**:
-
-- **`extract_sprites_from_ram`** ⭐⭐⭐⭐ (Effort: 80min, Benefit: MEDIUM)
-  - Impact: Extract sprites from running programs for analysis/reuse
-  - Use cases: "Show me the sprites from this game", sprite library building
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - **PRIORITY: #5** — Moderate effort, good payoff for graphics work
-
-- **`rip_charset_from_ram`** ⭐⭐⭐⭐ (Effort: 75min, Benefit: MEDIUM)
-  - Impact: Extract custom character sets for reuse/study
-  - Use cases: Font library creation, PETSCII art analysis
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - **PRIORITY: #6** — Similar to sprites, good for graphics
-
-- **`screen_capture_timeline`** ⭐⭐⭐ (Effort: 50min, Benefit: MEDIUM)
-  - Impact: Record program execution over time
-  - Use cases: Demo capture, animation analysis, debugging
-  - Dependencies: `wait_for_screen_text` (✅ implemented)
-  - **PRIORITY: #9** — Nice to have but lower urgency
-
-### 3. SID Music & Audio (HIGH)
-
-**Problem**: Agents need better workflows for creating and testing SID music
-
-**High-Impact Tools**:
-
-- **`silence_and_verify`** ⭐⭐⭐⭐⭐ (Effort: 35min, Benefit: HIGH)
-  - Impact: Essential for reliable SID testing and music composition
-  - Use cases: Verify silence before playing, clean state for tests
-  - Dependencies: None
-  - **PRIORITY: #2** — Quick win, high value for music work
-
-- **`music_compile_play_analyze`** ⭐⭐⭐⭐ (Effort: 90min, Benefit: HIGH)
-  - Impact: Complete music development workflow in one tool
-  - Use cases: "Create a C major scale and verify it plays correctly"
-  - Dependencies: `silence_and_verify`
-  - **PRIORITY: #4** — After silence_and_verify, excellent workflow tool
-
-- **`sid_param_sweep`** ⭐⭐⭐ (Effort: 90min, Benefit: MEDIUM)
-  - Impact: Experiment with SID parameters systematically
-  - Use cases: Find best ADSR settings, explore waveforms
-  - Dependencies: `silence_and_verify`
-  - **PRIORITY: #10** — Advanced feature, implement later
-
-### 4. Debug Streaming & Assembly Verification (COMPLEX)
-
-**Problem**: Verifying assembly execution requires debug stream integration
-
-**High-Impact Tools** (all require infrastructure):
-
-- **`debug_stream_watch`** ⭐⭐⭐⭐⭐ (Effort: 55min, Benefit: MEDIUM)
-  - Impact: Foundation for all debug streaming features
-  - Use cases: Monitor CPU/VIC/1541 activity
-  - Dependencies: UDP ingest pipeline (NOT YET IMPLEMENTED)
-  - **PRIORITY: Post-GA** — Requires infrastructure work first
-
-- **`debug_loop_run_and_capture`** ⭐⭐⭐⭐⭐ (Effort: 80min, Benefit: HIGH)
-  - Impact: Verify assembly programs by comparing expected vs actual execution
-  - Use cases: "Did my IRQ handler fire correctly?", "Verify timing"
-  - Dependencies: `debug_stream_watch` + infrastructure
-  - **PRIORITY: Post-GA** — Very valuable but infrastructure-gated
-
-- **`verify_raster_irq_line`** ⭐⭐⭐⭐ (Effort: 70min, Benefit: HIGH)
-  - Impact: Critical for graphics programming verification
-  - Use cases: Validate IRQ setup in demos and games
-  - Dependencies: `debug_loop_run_and_capture`
-  - **PRIORITY: Post-GA** — Excellent feature but requires debug foundation
-
-**Note**: All debug streaming tools are marked Post-GA because they require:
-
-- UDP packet ingest pipeline with backpressure handling
-- Sampling/windowing for high-rate streams
-- Performance validation via load tests
-- Observability infrastructure
-
-### 5. Drive & Filesystem Management (MEDIUM)
-
-**High-Impact Tools**:
-
-- **`drive_mount_and_verify`** ⭐⭐⭐ (Effort: 45min, Benefit: MEDIUM)
-  - Impact: Reliable drive mounting with retry logic
-  - Use cases: Mount disk images for program loading
-  - Dependencies: `firmware_info_and_healthcheck` (✅ implemented)
-  - **PRIORITY: #7** — Good utility, implement after higher priorities
-
-- **`create_and_mount_blank_d64`** ⭐⭐ (Effort: 35min, Benefit: MEDIUM)
-  - Impact: Create working disks for file operations
-  - Use cases: Save programs, create disk collections
-  - Dependencies: `drive_mount_and_verify`
-  - **PRIORITY: #11** — Lower priority, niche use case
-
-### 6. Memory & Disassembly (MEDIUM)
-
-**High-Impact Tools**:
-
-- **`memory_snapshot_and_diff`** ⭐⭐⭐⭐ (Effort: 50min, Benefit: HIGH)
-  - Impact: Debug memory changes during program execution
-  - Use cases: "What changed after running this?", reverse engineering
-  - Dependencies: `memory_dump_to_file` (✅ implemented)
-  - **PRIORITY: #12** — Useful for advanced debugging
-
-- **`disassemble_ram_region`** ⭐⭐⭐ (Effort: 60min, Benefit: MEDIUM)
-  - Impact: Understand machine code in memory
-  - Use cases: Reverse engineering, learning assembly
-  - Dependencies: None (agent-side disassembler)
-  - **PRIORITY: #13** — Nice to have, not urgent
-
-## Reprioritized Rollout Order
-
-Based on impact analysis focusing on:
-
-1. **Immediate agent effectiveness** (find and run programs, compose music)
-2. **Low-hanging fruit** (small effort, high impact)
-3. **Foundation for future work** (enables other tools)
-4. **Deferring complex infrastructure** (debug streaming to Post-GA)
-
-### New High-Priority Sequence
-
-#### Quick Wins (Phase 2a — High Impact, Low Effort)
-
-1. **`find_and_run_program_by_name`** (45min) — Enables program discovery
-2. **`silence_and_verify`** (35min) — Essential for SID work
-3. **`filesystem_stats_by_extension`** (35min) — Context for file operations
-4. **`music_compile_play_analyze`** (90min) — Complete music workflow
-
-#### Graphics & Extraction (Phase 2b — Medium Effort, High Value)
-
-1. **`extract_sprites_from_ram`** (80min) — Graphics extraction
-2. **`rip_charset_from_ram`** (75min) — Character set extraction
-3. **`drive_mount_and_verify`** (45min) — Reliable disk handling
-
-#### Advanced Features (Phase 2c — Lower Priority)
-
-1. **`classify_prg_basic_or_mc`** (45min) — Program classification
-2. **`screen_capture_timeline`** (50min) — Timeline recording
-3. **`sid_param_sweep`** (90min) — SID experimentation
-4. **`create_and_mount_blank_d64`** (35min) — Disk creation
-5. **`memory_snapshot_and_diff`** (50min) — Memory comparison
-6. **`disassemble_ram_region`** (60min) — Disassembly
-
-#### Container & Classification (Phase 3 — When Filesystem Work Needed)
-
-- **`container_aware_walk_and_classify`** (60min)
-- **`dedup_scan`** (60min)
-- **`dedup_plan_and_apply`** (75min)
-
-#### Debug Streaming (Phase 5 — Post Infrastructure)
-
-- All debug stream tools deferred until UDP infrastructure is ready
-- These are high-value but require significant foundation work
-
-## Key Insights
-
-### Why This Order?
-
-1. **`find_and_run_program_by_name` is #1** because it's the most requested feature — agents need to find programs in disk collections. Without this, users must manually locate files.
-
-2. **`silence_and_verify` is #2** because it's a quick win (35min) that unblocks all SID testing and music composition work. Currently, SID tests can be flaky without proper silence verification.
-
-3. **Graphics tools (#5-6)** are grouped together because they share similar patterns (RAM scanning, pattern detection, export). Implementing them consecutively leverages shared code.
-
-4. **Debug streaming deferred** because it needs infrastructure (UDP pipeline, backpressure, performance testing) that would take weeks to implement properly. Better to ship other high-value features first.
-
-### Impact on Agent Capabilities
-
-After implementing the Phase 2a quick wins, agents will be able to:
-
-- ✅ Find and run any program in a C64 file collection by name
-- ✅ Reliably test SID music with proper silence verification
-- ✅ Understand file collection contents and statistics
-- ✅ Create and verify complete music compositions in one workflow
-
-After Phase 2b graphics tools:
-
-- ✅ Extract sprites and character sets from running programs
-- ✅ Build reusable graphics libraries
-- ✅ Analyze and learn from existing C64 graphics
-
-### ROI Summary
-
-**Top 4 Quick Wins (Phase 2a)**: ~205 minutes (3.4 hours)
-
-- Unlocks: Program discovery, music composition, file navigation
-- Impact: Transforms agent from "follow instructions" to "find and create"
-
-**Graphics Suite (Phase 2b)**: ~200 minutes (3.3 hours)
-
-- Unlocks: Sprite/charset extraction, graphics analysis
-- Impact: Enables graphics-focused workflows
-
-**Total High-Priority Work**: ~6.7 hours for 11 tools
-
-- Massive improvement in agent capabilities
-- All low-risk (no infrastructure dependencies)
-- Clear, testable outcomes
-
-### Deferred Work: Debug Streaming
-
-Debug streaming tools (Phase 5) are incredibly valuable but require:
-
-- UDP packet ingest infrastructure (~40 hours)
-- Performance validation (~8 hours)
-- Observability & monitoring (~8 hours)
-- Integration testing (~16 hours)
-
-**Total infrastructure: ~72 hours** before first debug tool can ship (see `rollout.md` Phase 5 for detailed breakdown)
-
-**Decision**: Ship high-value, low-complexity features first (Phases 2a-3), then revisit debug streaming as a separate project with dedicated infrastructure sprint.
-
-## Recommendations
-
-1. **Immediate**: Implement Phase 2a (quick wins) in next sprint
-2. **Near-term**: Follow with Phase 2b (graphics) when graphics work is prioritized
-3. **Medium-term**: Phase 2c and Phase 3 tools as needed based on user feedback
-4. **Long-term**: Plan debug streaming infrastructure project, then implement Phase 5
-
-This prioritization maximizes near-term agent effectiveness while deferring complex infrastructure work that would block faster progress.