c64bridge 0.5.1 → 0.6.0

package/doc/developer.md

@@ -33,14 +33,42 @@ Key documentation:
 
 ## Prerequisites
 
-- Node.js 18+ (20+ recommended); ESM TypeScript via `ts-node`.
-- npm for dependency management.
-- Optional: Ultimate 64 hardware (or compatible REST device) for real tests.
+- Node.js 18+ (20+ recommended) or Bun 1.1+
+- npm (for user installation) or Bun (for development)
+- Optional: Ultimate 64 hardware (or compatible REST device) for real tests
+
+## Development Tooling
+
+This project uses **Bun** for building and testing during development due to its significantly higher performance compared to npm/node. However, the published npm package remains **fully compatible with both Bun and npm/node**, ensuring that end users can install and run it using standard Node.js tooling.
+
+For **release preparation**, npm/node is used to ensure everything works correctly on the target platform, as Node.js remains our primary deployment target.
+
+### Bun vs npm Command Reference
+
+Common development commands are available for both toolchains:
+
+| Task | Bun Command | npm Command |
+|------|-------------|-------------|
+| Install dependencies | `bun install` | `npm install` |
+| Build project | `bun run build` | `npm run build` |
+| Run tests | `bun test` or `npm test` | `npm test` |
+| Run with coverage | `bun test --coverage` or `npm run coverage` | `npm run coverage` |
+| Start MCP server | `npm start` | `npm start` |
+| Run single script | `bun scripts/script-name.ts` | `node scripts/invoke-bun.mjs scripts/script-name.ts` |
+
+**Notes:**
+- Bun can execute TypeScript files directly without transpilation
+- npm scripts internally use Bun where configured via `scripts/invoke-bun.mjs` wrapper
+- Both toolchains produce identical `dist/` output for packaging
 
 ## Setup
 
 ```bash
+# For end users (npm)
 npm install
+
+# For contributors (Bun - faster)
+bun install
 ```
 
 Configuration resolution (first match wins):
@@ -51,7 +79,39 @@ Configuration resolution (first match wins):
 
 `loadConfig()` normalises IPv6 literals, coerces legacy keys (`c64_host`, `c64_ip`), and caches the resolved structure for subsequent calls.
 
-## Useful npm Scripts
+## Container (Docker)
+
+For reproducible deployments, you can build and run C64 Bridge in a container:
+
+1. Build the container image
+
+```bash
+docker build -t c64bridge:dev .
+```
+
+2. Run the container
+
+```bash
+docker run --rm \
+  -e C64_HOST=192.168.1.64 \
+  -e C64_PORT=80 \
+  c64bridge:dev
+```
+
+The container uses `ubuntu:24.04` as the base image with Node.js 20 (installed via `n` version manager) and Bun, runs as a non-root user (`c64bridge`), and starts the MCP server with `npm start`. Configure the C64 connection through environment variables (`C64_HOST`, `C64_PORT`, `C64_BACKEND`) as needed.
+
+For development or testing, you can mount a volume to access logs or temporary files:
+
+```bash
+docker run --rm \
+  -e C64_HOST=192.168.1.64 \
+  -v /tmp/c64bridge:/tmp \
+  c64bridge:dev
+```
+
+## npm Scripts Reference
+
+All commands below work with both `npm run <script>` and `bun run <script>`. For consistency with user documentation, npm syntax is shown.
 
 **Core server flows**
 
@@ -63,7 +123,7 @@ Configuration resolution (first match wins):
 **Quality gates**
 
 - `npm test` drives `scripts/run-tests.mjs` against the mock C64 server; pass `-- --real [--base-url=http://host]` to exercise actual hardware.
-- `npm run check` executes `npm run build` followed by the mock test suite; `npm run coverage` wraps the same runner with c8.
+- `npm run check` executes `npm run build` followed by the mock test suite; `npm run coverage` now invokes the Bun runner with `--coverage`, producing `coverage/lcov.info` for Codecov.
 - `npm run check:package` validates packaging metadata, while `npm run check:run-local` / `npm run check:run-npm` execute `scripts/run-mcp-check.sh` against local and packaged installs.
 
 **RAG workflows**
@@ -76,7 +136,7 @@ Configuration resolution (first match wins):
 - `npm run c64:tool` opens the interactive helper for PRG conversion and upload; `npm run api:generate` refreshes the generated REST client.
 - `npm run changelog:generate` distills Conventional Commit history, and `npm run release:prepare -- <semver>` orchestrates version bumps plus manifest regeneration.
 
-Invoke `node --import ./scripts/register-ts-node.mjs scripts/update-readme.ts` directly when you need to refresh documentation tables without a full rebuild.
+Invoke `bun scripts/update-readme.ts` directly when you need to refresh documentation tables without a full rebuild.
 
 The test driver in `scripts/run-tests.mjs` accepts additional flags: `--mock` (default) to use `test/mockC64Server.mjs`, `--real` to target hardware (`C64_TEST_TARGET=real`), and `--base-url` to override the REST endpoint during real runs.
 
@@ -141,7 +201,7 @@ flowchart LR
 ## Testing Notes
 
 - Node’s built-in test runner (`node --test`) is wrapped by `scripts/run-tests.mjs`.
-- Use `npm run coverage` (c8) to capture coverage without double-running tests.
+- Use `npm run coverage` (Bun runner) to capture coverage without double-running tests. The command emits `coverage/lcov.info`, which CI uploads to Codecov.
 - `test/basicConverter.test.mjs`: byte-level PRG output validation.
 - `test/c64Client.test.mjs`: REST client and mock-server integration; `--real` toggles hardware.
 - `test/suites/mcpServer*.mjs`: End-to-end MCP surface coverage (tools, resources, prompts).
@@ -155,6 +215,8 @@ flowchart LR
 
 ## Release Workflow
 
+Releases are prepared using **npm/node** to ensure the published package works correctly on the target platform (Node.js 18+), even though development uses Bun for speed.
+
 1. Create a short-lived branch (for example `release/X.Y.Z`) from the target commit.
 2. Run `npm run release:prepare -- <semver>` to bump versions (`major`, `minor`, `patch`, or explicit like `0.2.0`). This updates `package.json`, `package-lock.json`, `mcp.json`, and prepends a new section to `CHANGELOG.md` from commit messages since the last tag.
 3. Review and commit the changes, then open a pull request.
@@ -303,9 +365,9 @@ For advanced options (depth semantics, throttling/limits, adaptive rate limiting
 - Advanced users can call the underlying CLI directly:
 
   ```bash
-  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs convert-basic --input path/to/program.bas
-  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs run-basic --input path/to/program.bas
-  node --import ./scripts/register-ts-node.mjs scripts/c64-cli.mjs run-prg --input artifacts/program.prg
+  bun scripts/c64-cli.mjs convert-basic --input path/to/program.bas
+  bun scripts/c64-cli.mjs run-basic --input path/to/program.bas
+  bun scripts/c64-cli.mjs run-prg --input artifacts/program.prg
   ```
 
 Generated binaries are written to the `artifacts/` directory by default (ignored by git) so you can transfer them to real hardware or flash media. Make sure your `~/.c64bridge.json` (or `C64BRIDGE_CONFIG`) points at your c64 device before using the run options.

package/doc/improve-knowledge/notes.md

@@ -12,3 +12,32 @@
 - **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/audio/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/improve-knowledge/plan.md

@@ -33,6 +33,9 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 | 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/audio/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/video/character-set.csv` (retain CSV for programmatic access). Prefer dynamic generation to avoid duplicate sources of truth. | `data/video/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/video/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/video/` referencing `src/tools/graphics.ts` capabilities | M | 4 | Guides consistent, high-quality sprite/charset pipelines for LLMs. |
 
 #### RAG & Retrieval
 
@@ -41,6 +44,7 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 | 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)
 
@@ -50,6 +54,8 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 | 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
 
@@ -58,6 +64,8 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 | 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_and_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
 
@@ -65,13 +73,14 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 |----|----------------|-----------------------------|---------|-----------|------------------|
 | 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/video/`, `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 runnable, reproducible container (Node 20 LTS, non-root user, `npm ci`, `npm start`), not just apt base. | Current Dockerfile doesn’t copy/build/run: `Dockerfile:1-12` | M | 3 | Larger image and CI time; greatly simplifies reproducibility. |
-| S2 | Preserve and surface external source license info in RAG outputs (already recorded in index), include SPDX in structured refs. | License metadata recorded: `src/rag/indexer.ts:592-699` | S | 3 | Clarifies usage constraints; minimal change. |
+| 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)
@@ -87,7 +96,23 @@ The server exposes a rich, well-typed MCP surface with clear schemas, strong log
 | 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 | M | 3 | Eases local/CI reproducibility and onboarding. |
+| 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
 

package/doc/improve-knowledge/rollout.md

@@ -43,17 +43,51 @@ For every checklist item below, execute the following sub-steps in order (these
 
 ## Phase 2 — Creative Defaults & Validation
 
-- [ ] 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.
-- [ ] T1: Add automated tests verifying the new SID defaults (PAL/NTSC pitch accuracy and ADSR adherence) (`test/audioAnalysis.test.mjs` or adjacent suites).
+- [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
 
-- [ ] 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`).
-- [ ] M1: Remove the artificial dependency between `upload_and_run_basic` and `read_screen`, ensuring documentation reflects independent usage (`src/tools/memory.ts`, related docs or schemas).
+- [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_and_run_basic` and `read_screen`, ensuring documentation reflects independent usage (`src/tools/memory.ts`, related docs or schemas).
 
 ## Phase 4 — Reproducibility & Packaging
 
-- [ ] S1: Produce a runnable, reproducible container path (Node 20 LTS, non-root user, `npm ci`, `npm start`) updating `Dockerfile` and associated docs.
+> Implementation guardrails for S1  
+> • Base image must be `node:20-bookworm-slim` (or newer 20.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/video/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/video/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/video/`).
+- [ ] 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/video/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)
 

package/doc/meta-tools/README.md

@@ -0,0 +1,101 @@
+# 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 (11 tools)**:
+- 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
+
+**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