c64bridge 1.0.6 → 1.1.0

package/doc/agent-state-spec.md

@@ -1,243 +0,0 @@
-# c64bridge — Agent State Specification
-
-This specification defines how the **c64bridge** agent stores and manages its persistent **task** and **session** state.
-
-A **task** is the fundamental unit of work executed by the agent. There are two task types:
-
-- **Foreground tasks** — short-lived, single-execution operations (e.g., extract sprites from RAM).  
-- **Background tasks** — long-running, periodic operations (e.g., sample memory every second).
-
----
-
-## 1. Directory Layout
-
-All state is stored under the user’s home directory (`~/.c64bridge/`).
-
-```text
-~/.c64bridge/
- ├─ tasks.json                  # global registry of all tasks (foreground + background)
- └─ tasks/
-     ├─ background/             # background (recurring) tasks
-   │   └─ <taskId>/           # e.g. 0001_read
-     │       ├─ task.json
-     │       ├─ result.json
-     │       └─ log.txt
-     └─ <taskId>/               # foreground (one-shot) tasks
-         ├─ task.json
-         ├─ result.json
-         ├─ artifacts/          # optional outputs (e.g., sprites, dumps)
-         └─ log.txt
-```
-
-### Task ID Convention
-
-Each task folder name equals its **`task.id`**, constructed as:
-
-```text
-<4-digit counter>_<task.name>
-```
-
-Example:
-
-```text
-0001_extract_sprites
-0002_extract_sprites
-0003_extract_ram
-```
-
-Counters increment per new task creation (shared across both task types).  
-All background tasks are placed under `tasks/background/`, all foreground tasks under `tasks/`.
-
----
-
-## 2. Task Types
-
-### Foreground Tasks
-
-- Short-lived, synchronous operations that run once and complete quickly.  
-- Used for “extract” or “analyze” style commands where the user requests data immediately.
-
-Examples:
-
-- **Extract all sprites from RAM**  
-  → Reads sprite data from `$2000`–`$3FFF`, decodes shapes, saves PNGs and binary blobs to  
-  `~/.c64bridge/tasks/0001_extract_sprites/artifacts/sprites/`.
-- **Extract RAM region to file**  
-  → Dumps a range of memory into a `.bin` or `.hex` file for later inspection.
-
-A foreground task executes once and then transitions from `running → completed` or `running → error`.  
-No repetition or scheduling logic applies.
-
----
-
-### Background Tasks
-
-- Long-running, recurring operations that execute periodically.  
-- Used for sampling, monitoring, or repeated execution of a fixed operation.
-
-Examples:
-
-- Read C64 memory every second for 1 minute.  
-- Poll the C64 screen until specific text appears.  
-- Periodically capture state for regression detection.
-
-Background tasks have an interval and optional maximum iteration count.
-
----
-
-## 3. tasks.json — Global Task Registry
-
-This file tracks all tasks, regardless of type.  
-It is updated atomically after each task start, update, or completion.
-
-```json
-{
-  "tasks": [
-    {
-      "id": "0001_extract_sprites",
-      "name": "extract_sprites",
-      "type": "foreground",
-      "operation": "extract_sprites_from_ram",
-      "args": { "persistArtifacts": true },
-      "status": "completed",
-      "startedAt": "2025-10-27T11-42-03Z",
-      "updatedAt": "2025-10-27T11-42-05Z",
-      "stoppedAt": "2025-10-27T11-42-05Z",
-      "lastError": null,
-      "folder": "tasks/0001_extract_sprites"
-    },
-    {
-      "id": "0002_read",
-      "name": "read",
-      "type": "background",
-      "operation": "read",
-      "args": { "address": "$0400", "length": 256 },
-      "intervalMs": 1000,
-      "maxIterations": 60,
-      "iterations": 60,
-      "status": "completed",
-      "startedAt": "2025-10-27T11-45-00Z",
-      "updatedAt": "2025-10-27T11-46-00Z",
-      "stoppedAt": "2025-10-27T11-46-00Z",
-      "lastError": null,
-      "folder": "tasks/background/0002_read"
-    }
-  ]
-}
-```
-
-### Field meanings
-
-| Field | Type | Description |
-|--------|------|-------------|
-| `id` | string | Unique folder name (`0001_extract_sprites`). |
-| `name` | string | Logical name (user-assigned). |
-| `type` | string | `"foreground"` or `"background"`. |
-| `operation` | string | Operation performed (`read`, `write`, `extract_sprites_from_ram`, etc.). |
-| `args` | object | Operation-specific arguments. |
-| `intervalMs` | number \| undefined | Interval between runs (background only). |
-| `maxIterations` | number \| undefined | Total iterations before stop (background only). |
-| `iterations` | number \| undefined | Iterations completed (background only). |
-| `status` | string | `"running"` \| `"completed"` \| `"stopped"` \| `"error"`. |
-| `startedAt` | string | Timestamp (`YYYY-MM-DDTHH-mm-ssZ`) of first run start. |
-| `updatedAt` | string | Timestamp of last state change. |
-| `stoppedAt` | string \| null | Timestamp when finished or stopped. |
-| `lastError` | string \| null | Error message if failed. |
-| `folder` | string | Path of the task folder relative to `~/.c64bridge/`. |
-
----
-
-## 4. task.json — Individual Task State
-
-Each task’s folder contains a standalone `task.json`, mirroring its registry entry plus any additional metadata.
-
-```json
-{
-  "id": "0001_extract_sprites",
-  "name": "extract_sprites",
-  "type": "foreground",
-  "operation": "extract_sprites_from_ram",
-  "args": { "persistArtifacts": true },
-  "status": "completed",
-  "startedAt": "2025-10-27T11-42-03Z",
-  "updatedAt": "2025-10-27T11-42-05Z",
-  "stoppedAt": "2025-10-27T11-42-05Z",
-  "resultPath": "tasks/0001_extract_sprites/result.json"
-}
-```
-
----
-
-## 5. result.json — Structured Task Output
-
-Optional file describing high-level output of a task.
-
-Example for **foreground** sprite extraction:
-
-```json
-{
-  "id": "0001_extract_sprites",
-  "type": "task",
-  "name": "extract_sprites_from_ram",
-  "created": "2025-10-27T11-42-03Z",
-  "completed": "2025-10-27T11-42-05Z",
-  "status": "completed",
-  "summary": {
-    "spriteCount": 8,
-    "spriteAddresses": ["0x2000", "0x2080"]
-  },
-  "artifacts": {
-    "spritesDir": "artifacts/sprites/"
-  }
-}
-```
-
----
-
-## 6. session.json — Session Summary (optional)
-
-Sessions are logical groupings of tasks run in the same time window.  
-This file is optional and only created if session tracking is enabled.
-
-```json
-{
-  "sessionId": "2025-10-27T11-42-00Z",
-  "created": "2025-10-27T11-42-00Z",
-  "ended": null,
-  "status": "active",
-  "tasks": [
-    { "id": "0001_extract_sprites", "type": "foreground" },
-    { "id": "0002_read", "type": "background" }
-  ]
-}
-```
-
----
-
-## 7. Update & Persistence Model
-
-- **In-memory source of truth:** `TASKS: Map<string, Task>`
-- **On-disk persistence:** `~/.c64bridge/tasks.json`
-- On startup:
-  - `ensureTasksLoaded()` loads `tasks.json`.
-  - If missing, an empty file is created.
-- On every task state change:
-  - Update `tasks.json` (atomic rewrite).
-  - Write or update the per-task `task.json` and optional `result.json`.
-- **Timestamps:** All stored as UTC strings in `YYYY-MM-DDTHH-mm-ssZ` format.
-
----
-
-## 8. Summary
-
-| Concept | Description | Example |
-|----------|--------------|----------|
-| **Foreground Task** | One-shot, short operation returning immediate data (e.g., extract sprites, read memory once). | `0001_extract_sprites` |
-| **Background Task** | Recurring scheduled operation (e.g., read memory every second). | `0002_read` |
-| **Task Folder** | Directory under `tasks/` (foreground) or `tasks/background/` containing JSON state and logs. | `~/.c64bridge/tasks/0001_extract_sprites/` |
-| **Registry File** | Global view of all tasks. | `~/.c64bridge/tasks.json` |
-| **Session Summary** | Optional grouping of related tasks run during a session. | `~/.c64bridge/sessions/<id>/session.json` |
-
----
-
-**This specification is authoritative for all task persistence and state tracking in c64bridge.**

package/doc/plans/bun/baseline-metrics.md

@@ -1,16 +0,0 @@
-# Bun Migration Baseline (Node.js)
-
-Captured before introducing Bun tooling. All commands executed on the `bun-migration` branch using Node.js 18 (system default).
-
-| Command | Notes | Duration |
-|---------|-------|----------|
-| `npm run build` | TypeScript compile + postbuild + README update | **10.44 s** |
-| `npm test` | Full TAP suite via `scripts/run-tests.mjs` | **47.61 s** |
-
-Additional context:
-
-- Dependencies installed with `npm install` (fresh, no cache) before measuring.
-- No Bun tooling in use; these timings represent our current Node-only baseline.
-- Results recorded on 2025-10-29 to anchor future comparisons.
-
-Next step: use these numbers to evaluate improvements once Bun drives install/build/test tasks.

package/doc/plans/bun/migration-checklist.md

@@ -1,55 +0,0 @@
-# Bun Migration Checklist
-
-> Track the incremental migration from Node.js/npm tooling to Bun.  
-> Update each item as it is completed and keep a short note/date beside the checkbox.
-> Before doing any work, ensure you understand the [Bun Migration Strategy](./migration.md).
-> Keep notes of any deviations or important observations in the checklist itself.
-
-## 1. Foundations
-
-- [x] **1.1** Capture baseline metrics (install/build/test timings, coverage reports) for comparison. *(doc/bun/baseline-metrics.md, 2025-10-29)*
-- [x] **1.2** Introduce Bun toolchain alongside existing Node workflow (lockfile, `packageManager`, basic `bun install` smoke test).
-
-## 2. Package & Tooling
-
-- [x] **2.1** Update `package.json` scripts to use Bun equivalents while keeping Node fallbacks where required. *(added Bun packageManager + `check:node-compat`)*
-- [x] **2.2** Ensure `bun run build` reproduces the existing `dist/` layout (compare key artifacts). *(verified 2025-10-29)*
-- [x] **2.3** Add an automated check that validates the published package still runs under `npm install` + `node`. *(npm script + compatibility harness)*
-
-## 3. Test Suite
-
-- [x] **3.1** Migrate test runner to `bun test`, converting assertion helpers and harness utilities. *(bun harness + timeout guardrails, 2025-10-29)*
-- [x] **3.2** Ensure `bun test` runs the full suite with the same semantics (mock servers, fixtures, CLI tools). *(`bun scripts/run-tests.ts --mock`, 2025-10-29)*
-- [x] **3.3** Provide an explicit npm/node compatibility test (e.g., `npm test` wrapper or integration smoke test). *(`npm run test:node`, 2025-10-29)*
-
-## 4. Coverage & Reporting
-
-- [x] **4.1** Replace `c8` with Bun’s coverage tooling and export lcov output. *(bun coverage emits `coverage/lcov.info`, 2025-10-29)*
-- [x] **4.2** Verify Codecov integration with the new coverage artifacts. *(workflow uploads Bun lcov, 2025-10-29)*
-
-## 5. Scripts & Utilities
-
-- [x] **5.1** Port repository scripts (`scripts/*.mjs`) from Node-specific loaders/`ts-node` to Bun-native execution. *(start, rag, CLI now Bun-aware; Node fallbacks use dist, 2025-10-29)*
-- [x] **5.2** Replace `register-ts-node` usage with Bun-compatible module loading. *(ts-node loader inlined; helper removed, 2025-10-29)*
-- [x] **5.3** Update shell helpers (e.g., `run-mcp-check.sh`, `c64-tool.sh`) to call Bun commands by default. *(preferred Bun paths with Node fallback, 2025-10-29)*
-
-## 6. Automation & CI
-
-- [x] **6.1** Update GitHub Actions to install Bun (`oven-sh/setup-bun`) and run build/test/coverage using Bun. *(added setup-bun, switched to `bun run build`, ensured LCOV output for Codecov, 2025-10-30)*
-- [x] **6.2** Ensure Docker-based checks (if any) consume the new Bun workflow without regressions. *(builder image now includes Bun; CI jobs use container and run Bun successfully, 2025-10-30)*
-
-## 7. Docker & Runtime
-
-- [x] **7.1** Rebuild the Dockerfile using an official Bun base image; retain runtime parity and entrypoints. *(deviation: kept `ubuntu:24.04` base but installed Bun system-wide; image provides both Node and Bun for CI parity, 2025-10-30)*
-- [x] **7.2** Confirm resulting image passes existing smoke tests and compatibility checks. *(Docker workflow builds `mcp-builder` and downstream package smoke tests pass, 2025-10-30)*
-
-## 8. Documentation
-
-- [x] **8.1** Refresh README, developer docs, and setup guides to reference Bun (with a note about Node compatibility). *(README Build & Test updated to include Bun; dev docs already referenced Bun, 2025-10-30)*
-- [x] **8.2** Document the npm/node compatibility verification process for external consumers. *(`npm run check:node-compat` documented in dev docs; retained, 2025-10-30)*
-
-## 9. Final Verification
-
-- [x] **9.1** Run full validation suite: `bun install`, `bun run build`, `bun test --coverage`, npm compatibility smoke test. *(wired in CI; local scripts use Bun runner; coverage emits LCOV, 2025-10-30)*
-- [x] **9.2** Compare final artifacts and confirm no API/package layout changes. *(build parity verified earlier; CI keeps packaging check, 2025-10-30)*
-- [x] **9.3** Remove obsolete Node-only tooling and close out migration notes. *(no remaining Node-only paths required for CI; kept Node paths for consumer compatibility, 2025-10-30)*

package/doc/plans/bun/migration.md

@@ -1,83 +0,0 @@
-# Bun Migration Strategy
-
-Our goal is to adopt Bun everywhere it improves speed (local dev, CI, container builds) **without sacrificing Node compatibility** for downstream consumers.
-
----
-
-## Approach Overview
-
-1. **Track incremental work via the checklist** (`doc/bun/migration-checklist.md`).
-2. **Introduce Bun tooling in parallel** with Node/npm. Validate parity before turning off Node paths.
-3. **Port the build/test pipeline** to Bun (`bun install`, `bun run build`, `bun test --coverage`) and keep comparing against Node outputs (especially `dist/` packaging).
-4. **Update automation and docs** once Bun passes all checks.
-5. **Retain Node smoke tests** to ensure published artifacts remain consumable by Node users.
-
-### Current Status (2025-10-29)
-
-- Baseline Node metrics captured (`npm run build` ~10.44 s, `npm test` ~47.61 s) in `doc/bun/baseline-metrics.md`.
-- Bun toolchain bootstrapped alongside Node (`bun.lock`, `packageManager`, smoke `bun install`).
-- Added `npm run check:node-compat` (packs the module, installs via npm, and imports key ESM modules with Node) to guard compatibility as we iterate.
-- `bun run build` verified to produce the same `dist/` output as the Node workflow.
-
----
-
-## Guardrails
-
-### 1. Build & Runtime Rules
-
-- Sources remain TypeScript, emitting standard ESM/CJS modules compatible with Node.
-- Published code may not depend on Bun-only APIs (no `Bun.file`, `Bun.serve`, etc.).
-- The compiled `dist/` must execute under both **Bun ≥1.1** and **Node ≥24**.
-- `package.json` stays valid for npm clients (no Bun-only metadata).
-
-### 2. CI Strategy (Asymmetric Validation)
-
-- **Primary path (PRs, default CI):**
-
-  ```bash
-  bun install
-  bun run build
-  bun test --coverage
-  ```
-
-- **Release/nightly Node validation (reuse `dist/`):**
-
-  ```bash
-  npm ci --omit=dev
-  node dist/index.js --version
-  npm test -- --smoke
-  ```
-
-### 3. Docker Strategy
-
-Build with Bun, run with Node:
-
-```dockerfile
-FROM oven/bun:latest AS build
-WORKDIR /app
-COPY . .
-RUN bun install && bun run build
-
-FROM node:24-slim
-WORKDIR /app
-COPY --from=build /app/dist ./dist
-COPY package.json .
-CMD ["node", "dist/index.js"]
-```
-
-### 4. Validation Matrix
-
-- **Bun:** install/build/test/coverage on every PR.
-- **Node:** smoke tests on main branch, releases, or nightly jobs.
-- **Rule:** only build once; reuse Bun artifacts for Node checks.
-
-### 5. Documentation Messaging
->
-> Built and tested with **Bun** ⚡  
-> Fully compatible with **Node.js 24+** 🟩
-
----
-
-## Next Steps
-
-Use this document together with the checklist to plan each migration phase. Update both as milestones are completed and ensure the guardrails stay enforced.

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

@@ -1,43 +0,0 @@
-# Knowledge Improvement Rollout Working Notes
-
-## Required Reading Confirmation
-
-- `doc/improve-knowledge/plan.md` — Reviewed priorities and scoped improvements.
-- `doc/developer.md` — Reviewed contribution workflow, testing gates (`npm run check`), and documentation update expectations.
-- `README.md` (API and MCP surface sections) — Reconfirmed autogenerated tool/resource tables and need to update documentation alongside code changes.
-
-## Key Acceptance Criteria from the Improvement Plan
-
-- **Structured RAG outputs (R1)**: Responses must include structured fields (`uri`, `origin`, `snippet`, `score`) so `ReadResource` consumers can follow references without parsing prose.
-- **Memory/IO resource exposure (K1)**: Memory maps and IO reference docs under `data/memory` and `data/io` must be published as MCP resources with appropriate metadata for retrieval and grounding.
-- **SID best-practices resource (K2)**: `data/sound/sid-programming-best-practices.md` must be surfaced as a first-class MCP resource to guide audio tools and prompts.
-- **Validation gates**: Each improvement requires incremental changes with companion tests or documentation updates, followed by a successful `npm run check` prior to marking tasks complete.
-
-## Additional Acceptance Criteria (New Tasks)
-
-- **License info in RAG (S2)**: Structured RAG outputs expose `spdxId` only (replaces license name/URL), along with `uri`, `origin`, `snippet`, and `score`.
-- **What changed summary (D1)**: README or resource index contains a concise, auto-updated summary of tool/resource changes with a link to platform status.
-- **Prompt cross-links (D2)**: Prompts referencing SID/graphics/PETSCII include `relatedResources` pointing to best-practices and quickrefs.
-- **BASIC pitfalls resource (K3)**: A brief, actionable quickref exists and is listed in the knowledge index; BASIC runners reference it.
-- **PETSCII/charset quickrefs (K4)**: PETSCII char codes and glyph mapping are published as resources; retrieval returns URIs to them.
-- **VIC-II quickref (K5)**: Register quickref is exposed as a resource and linked from graphics tools.
-- **Sprite & Charset workflows doc (K6)**: New doc published and exposed; graphics tools and prompts link to it.
-- **RAG URIs (R2)**: RAG results consistently include `c64://` resource URIs where applicable; `ReadResource` can open them.
-- **Retrieval diversity (R3)**: Top-K results have basic de-duplication and domain diversity; tests cover presence of varied domains.
-- **PETSCII presets docs (G5)**: Documented style presets exist; prompts mention how to select them.
-- **Hires bitmap PRG generator (G6)**: A tool exists to render a static bitmap; a minimal example and test verify it runs and captures a screen.
-- **Graphics tests (T4/T5)**: PETSCII generation and sprite preview PRG flows have e2e tests asserting key structured fields and behavior.
-- **Container workflow (S1)**: ✅ Dockerfile updated to use `ubuntu:24.04` with Node.js 20 (via `n` version manager) and Bun, create a non-root `c64bridge` user at `/app`, run `npm ci` during build, copy the repo, and set `CMD ["npm","start"]`; doc/developer.md documents `docker build` / `docker run` usage and verification steps.
-
-## Container Build/Run Examples
-
-```bash
-# Build the container
-docker build -t c64bridge:dev .
-
-# Run with environment configuration
-docker run --rm \
-  -e C64_HOST=192.168.1.64 \
-  -e C64_PORT=80 \
-  c64bridge:dev
-```

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

@@ -1,121 +0,0 @@
-# Knowledge Improvement Plan
-
-This plan aims to identify and prioritize improvements to the C64 Bridge MCP server.
-
-The main goal is to enhance the server's effectiveness when used with LLMs for code generation, music creation, graphics, and general C64 programming tasks.
-
-The focus is on improving the MCP surface, knowledge base, RAG capabilities, generator defaults, and overall developer experience.
-
-### 1) Executive Summary
-
-The server exposes a rich, well-typed MCP surface with clear schemas, strong logging, a deterministic local RAG, and extensive tests. The biggest gaps affecting LLM effectiveness are:
-
-- (1) RAG results are returned as raw text rather than structured, referenceable snippets;
-- (2) key domain docs (memory/IO maps, SID best-practices) are not exposed as MCP resources;
-- (3) creative defaults (e.g., SID waveform/ADSR) aren’t aligned with the repo’s own musical best-practices. Addressing these will materially improve determinism, provenance, and the quality of BASIC/ASM/graphics/SID outputs.
-
-### 2) Recommendations (Grouped by Topic)
-
-#### MCP Surface & Tooling
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| M1 | Remove `upload_run_basic` as a prerequisite for `read_screen` to avoid misleading LLM plans (screen read works independently). | `src/tools/memory.ts:81-99`, `88-89` | S | 3 | Slightly changes listed workflow hints; no runtime impact. |
-| M2 | Standardize structured JSON outputs for runner tools (include entry addresses, artifacts, URIs) similar to graphics/audio tools using `structuredContent`. | `src/tools/types.ts:64-72, 90-106`; program runners return only `textResult` in `src/tools/programRunners.ts:129-140,176-180,231-236,276-281,320-324` | M | 4 | Minor API output change; keep text message for backward compatibility. |
-| M3 | Add a lightweight tool to set platform at runtime (uses existing `setPlatform`) and surface platform resource in resources index for LLM clarity. | `src/platform.ts:29-46,58-91`; resource exists: `src/mcp-server.ts:371-432` | S | 3 | Requires documenting when platform switch affects tool availability. |
-| M4 | Ensure all tools include concise validation messages and examples (many already do); audit remaining modules for parity. | e.g., `src/tools/audio.ts:190-224,517-583,747-756` | S | 3 | Small doc/schema edits; keeps LLM prompts aligned with schemas. |
-| M5 | Add explicit tool tags and related resources for PAL/NTSC-sensitive tools (SID, graphics) to nudge LLM to check system differences. | `src/tools/audio.ts:94-101`, `src/knowledge.ts:368-438` | S | 3 | Slight metadata churn; improves prompt-tool alignment. |
-
-#### Knowledge Base & Resources
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| K1 | Add memory/IO maps and low-memory docs as MCP resources (critical grounding for ASM/memory tools). | Missing under `src/rag/knowledgeIndex.ts:55-299`; candidate docs: `data/memory/*.md`, `data/io/*.md` | S | 5 | Larger resource list; very high grounding value for LLMs. |
-| K2 | Expose SID best-practices as a resource (used by creative flows). | Not in knowledge index; exists at `data/sound/sid-programming-best-practices.md` | S | 5 | Aligns generation defaults with proven musical outcomes. |
-| K3 | Add a short “BASIC pitfalls” quickref (quoting, line length, tokenization) and link from runners. | Tokenizer: `src/basicConverter.ts`; hints exist but not resource-linked | M | 4 | Minor doc work; reduces BASIC generation errors. |
-| K4 | Publish PETSCII/charset quickrefs as MCP resources; generate a Markdown table from the existing `data/graphics/character-set.csv` (retain CSV for programmatic access). Prefer dynamic generation to avoid duplicate sources of truth. | `data/graphics/character-set.csv`, `src/petscii.ts`, `src/petsciiArt.ts` | S | 5 | Improves PETSCII/charset fluency while avoiding duplication. |
-| K5 | Publish VIC-II register quickref and addressing guide as MCP resource. | `data/graphics/vic-spec.md` | S | 5 | Essential grounding for sprites, colours, raster, screen control. |
-| K6 | Add “Sprite & Charset workflows best-practices” doc and expose as resource. | New doc under `data/graphics/` referencing `src/tools/graphics.ts` capabilities | M | 4 | Guides consistent, high-quality sprite/charset pipelines for LLMs. |
-
-#### RAG & Retrieval
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| R1 | Return structured refs from RAG: `[uri|origin, snippet, score]` instead of only text. Parse `<!-- Source: ... -->` and include score. | Text returned: `src/tools/rag.ts:82-128`; retriever: `src/rag/retriever.ts:37-80`; provenance comment injected: `src/rag/indexer.ts:769-772` | M | 5 | Requires minor client-side changes reading structured refs. |
-| R2 | Include bundle/resource URIs (e.g., `c64://specs/*`) in RAG results when matches originate from docs; enable quick “open resource.” | `src/rag/knowledgeIndex.ts:328-359` (index resource), doc chunking: `720-767` | S | 4 | Slight mapping logic; greatly improves provenance and navigation. |
-| R3 | Add diversity heuristic (basic+asm mixed fallback already exists) and simple duplicate suppression in top-K. | `src/rag/retriever.ts:70-76,78-80` | S | 3 | Keeps refs varied; minimal complexity. |
-| R4 | Add domain weighting to retrieval (boost SID/graphics docs when relevant). | `src/rag/retriever.ts` scoring path; tool domain is known at call sites | M | 4 | More relevant grounding for PETSCII/sprites/SID prompts. |
-
-#### Generators & Creative Pipelines (BASIC/ASM/Graphics/SID)
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| G1 | Change `music_generate` defaults to triangle waveform and best-practice ADSR; optionally expose a “musical expression” preset. | Current defaults pulse+ADSR: `src/tools/audio.ts:747-756,783-801`; PAL/NTSC in client: `src/c64Client.ts:773-786`; best-practices doc: `data/sound/sid-programming-best-practices.md` | S | 5 | Slight change to expected timbre; add arg to opt back to pulse. |
-| G2 | When `sid_note_on` is used without `system`, auto-detect or remind to check `$02A6` (PAL/NTSC) and reflect in response metadata. | Client freq calc + defaults: `src/c64Client.ts:371-407,773-778`; PAL/NTSC doc: `src/knowledge.ts:373-421` | S | 4 | Small change; better tuning accuracy. |
-| G3 | Include generated PRG metadata (addresses, bytes written) in program runners’ structured output to aid follow-up memory ops. | Runners return text only: `src/tools/programRunners.ts:129-140,176-180,231-236,276-281,320-324` | M | 4 | Minor tool API enhancement; improves post-run determinism. |
-| G4 | For PETSCII, surface chosen glyph/codes and a miniature preview in structured output (already present; ensure docs highlight usage). | Already included: `src/tools/graphics.ts:489-515` | S | 3 | Doc-only; improves downstream use. |
-| G5 | Document PETSCII style presets (contrast, dithering, palette) and link from prompts. | `src/tools/graphics.ts` PETSCII args; `src/prompts/registry.ts` | S | 4 | Helps LLM pick good defaults for readable, artistic output. |
-| G6 | Add hires bitmap PRG generator tool (render static bitmap with colour RAM). | New tool in `src/tools/graphics.ts`; preview via screen capture | M | 4 | Enables high-quality hires demonstrations and asset previews. |
-
-#### Validation, Testing & CI
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| T1 | Add tests asserting `music_generate` new defaults (tri/ADSR) and pitch accuracy by PAL/NTSC. | Audio analysis tests exist: `test/audioAnalysis.test.mjs:56-141`; `hzToSidFrequency`: `src/c64Client.ts:773-778` | S | 4 | Keeps musical defaults from regressing. |
-| T2 | Add a small e2e test for `rag_retrieve_*` verifying structured refs and that URIs open via `ReadResource`. | `src/tools/rag.ts:82-128`, `src/mcp-server.ts:133-176` | M | 4 | Increases confidence in RAG interoperability. |
-| T3 | Quick test to ensure `read_screen` works without prior `upload_run_basic`. | `src/tools/memory.ts:81-99` | S | 3 | Guards against accidental pre-req regressions. |
-| T4 | Add e2e test for PETSCII generation: verify preview fields and PRG runs. | `src/tools/graphics.ts`, `test/graphicsModule.test.mjs` | S | 4 | Prevents regressions in graphics outputs crucial for PETSCII art. |
-| T5 | Add sprite preview PRG test: bytes copied, coords/colour applied, screen captured. | `src/tools/graphics.ts`, `test/graphicsModule.test.mjs` | S | 4 | Ensures sprite workflows stay reliable for asset iteration. |
-
-#### Developer Experience & Documentation
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| D1 | Add a “What changed” MCP summary to README or resource index after build (already partially auto-generated) and link platform status resource. | Auto-generated API in `README.md:346-589`; platform resource in `src/mcp-server.ts:371-432` | S | 3 | Keeps LLM and humans in sync with tool/resource changes. |
-| D2 | Cross-link prompts to resources (e.g., SID prompts to best-practices) for richer in-editor help. | Prompt registry references tools/resources: `src/prompts/registry.ts:369-547` | S | 3 | Small doc metadata lift; improves LLM contextual grounding. |
-| D3 | Add PETSCII/sprite/hires quickstarts and example-driven guides; link from prompts. | New docs under `data/graphics/`, `src/prompts/registry.ts` | M | 4 | Streamlines creative workflows aligned to the core mission. |
-
-#### Security/Licensing & Reproducibility
-
-| ID | Recommendation | Evidence (paths/lines/refs) | Effort* | Benefit** | Risks/Trade-offs |
-|----|----------------|-----------------------------|---------|-----------|------------------|
-| S1 | Provide a reproducible container workflow anchored on Node 20 LTS (bookworm-slim), create a non-root runtime user, run `npm ci` during build, and set `npm start` as the default command; document how to build/run it. | Current Dockerfile doesn’t copy/build/run: `Dockerfile:1-12` | M | 3 | Larger image and CI time; greatly simplifies reproducibility. |
-| S2 | Replace license name and URL with SPDX identifier in structured RAG refs (map when possible; omit if unknown). | License metadata recorded: `src/rag/indexer.ts:592-699` | S | 3 | Normalizes licensing with a single standard field. |
-
-\* Effort: S (small), M (medium), L (large)  
-\** Benefit: 1–5 (5 = highest impact)
-
-### 3) Ranked Shortlist (Cross-Topic)
-
-| Rank | ID | Title | Effort | Benefit | One-line Justification |
-|------|----|-------|--------|---------|------------------------|
-| 1 | R1 | Structured RAG refs with URIs and scores | M | 5 | Makes retrieval actionable and referenceable for LLMs. |
-| 2 | K1 | Add memory/IO docs as MCP resources | S | 5 | Critical grounding for reliable ASM/memory operations. |
-| 3 | G1 | Align music defaults to best-practices (tri/ADSR) | S | 5 | Immediate quality uplift for SID output. |
-| 4 | K2 | Expose SID best-practices as resource | S | 5 | Guides LLM toward proven musical results. |
-| 5 | M2 | Standardize structured JSON outputs for runners | M | 4 | Improves determinism and follow-up automation. |
-| 6 | T1 | Tests for PAL/NTSC and new music defaults | S | 4 | Locks in audible quality and tuning accuracy. |
-| 7 | M1 | Remove `read_screen` pre-req coupling | S | 3 | Avoids confusing plans; reduces unnecessary steps. |
-| 8 | S1 | Ship a runnable container with the exact steps above (Dockerfile, README section, and reference in rollout notes). | M | 3 | Eases local/CI reproducibility and onboarding. |
-
-### 3b) Additional Prioritized Improvements (Next Phases)
-
-| Rank | ID | Title | Effort | Benefit | One-line Justification |
-|------|----|-------|--------|---------|------------------------|
-| 9 | K4 | PETSCII/charset quickrefs (Markdown from CSV; keep CSV) | S | 5 | Avoids duplication; improves PETSCII/charset fluency. |
-| 10 | K5 | VIC-II register quickref resource | S | 5 | Core for graphics, sprites, raster, and colours. |
-| 11 | R2 | Resource URIs in RAG refs | S | 4 | Faster navigation from retrieval to action. |
-| 12 | R3 | Retrieval diversity + de-dup | S | 3 | Improves variety and reduces redundancy. |
-| 13 | G5 | PETSCII style presets docs | S | 4 | Better default art quality and readability. |
-| 14 | T4 | PETSCII e2e generation test | S | 4 | Prevents regressions in critical graphics flow. |
-| 15 | G2 | PAL/NTSC reminder in SID note-on | S | 4 | Reduces tuning errors automatically. |
-| 16 | K6 | Sprite/charset workflows guide | M | 4 | Teaches robust workflows for assets. |
-| 17 | G6 | Hires bitmap PRG generator | M | 4 | Enables hires demos and previews. |
-| 18 | D3 | Creative quickstarts and guides | M | 4 | Guides LLMs and users to success paths. |
-| 19 | S2 | SPDX id in RAG refs (replace name/URL) | S | 3 | Single normalized field; reduces duplication. |
-
-### 4) Top Three Priorities
-
-- Implement structured RAG results (URIs, origin, score) and wire `ReadResource` for direct follow-ups.  
-- Add memory/IO maps and SID best-practices to the exposed MCP resources to improve grounding.  
-- Switch `music_generate` defaults to triangle + recommended ADSR, and add tests for PAL/NTSC tuning.