c64bridge 0.5.0

package/doc/developer.md

@@ -0,0 +1,312 @@
+# Developer Guide
+
+Concise reference for contributors working on the MCP server that bridges LLM workflows with Commodore 64 Ultimate hardware.
+
+## Project Layout
+
+- `src/` — core TypeScript sources for the MCP server.
+  - `mcp-server.ts` wires tools, resources, and prompts into the stdio server entry point imported by `index.ts`.
+  - Support modules such as `c64Client.ts`, `device.ts`, `viceRunner.ts`, `sidplayRunner.ts`, `loggingHttpClient.ts`, and `logger.ts` isolate hardware access and observability.
+  - Domain folders include:
+    - `audio/` for MCP-driven audio capture and analysis.
+    - `rag/` for indexing, retrieval, and external source discovery.
+    - `tools/` for individual MCP tool implementations plus decorators.
+    - `prompts/` for authored prompt definitions surfaced to clients.
+    - `types/` and `context.ts` for shared type definitions and session context helpers.
+    - `petscii*.ts`, `basicConverter.ts`, `assemblyConverter.ts`, and `chargen.ts` for Commodore-specific encoders and assets.
+    - `knowledge.ts` for resource wiring and `config.ts` for environment resolution.
+- `scripts/` — Node/TypeScript utilities for starting the server, rebuilding docs, running tests, regenerating embeddings, packaging releases, and providing the CLI shim used by `c64bridge`.
+- `doc/` — documentation set (developer guide, REST references, troubleshooting, task notes).
+- `data/` — knowledge corpus, embeddings, and example programs consumed by the RAG pipeline.
+- `test/` — Node test suites plus mock server helpers; includes real-hardware toggles.
+- `generated/` — OpenAPI-derived REST client (`npm run api:generate`).
+- `scripts/cli.js` and `dist/` — compiled CLI façade and build artifacts produced by `npm run build` / npm packaging.
+- `artifacts/` — gitignored output for PRG conversions, test embeddings, and other scratch products.
+- `external/` — optional fetched corpora included in the RAG index.
+
+Key documentation:
+
+- `data/basic/basic-spec.md` — BASIC tokenisation rules used by the converter.
+- `doc/rest/c64-rest-api.md` — Summary of the Ultimate REST API.
+- `doc/rest/c64-openapi.yaml` — Machine-readable API schema for mocking and generators.
+- `doc/tasks/use-mcp-sdk.md` — Step-by-step migration log with requirements.
+
+## 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.
+
+## Setup
+
+```bash
+npm install
+```
+
+Configuration resolution (first match wins):
+
+1. Load the file referenced by `C64BRIDGE_CONFIG` (when set); if unset, use `~/.c64bridge.json`.
+2. If missing, fall back to `.c64bridge.json` at the repo root.
+3. Otherwise, default to `host=c64u`, `port=80`.
+
+`loadConfig()` normalises IPv6 literals, coerces legacy keys (`c64_host`, `c64_ip`), and caches the resolved structure for subsequent calls.
+
+## Useful npm Scripts
+
+**Core server flows**
+
+- `npm start` launches the stdio MCP server with hot TypeScript support (`scripts/start.mjs`).
+- `npm run mcp` runs the TypeScript entry point directly via `ts-node`; `npm run mcp:build` compiles to `dist/` first, then executes the bundled server for parity testing.
+- `npm run build` compiles TypeScript, runs post-build normalization, and regenerates `README.md` tool/resource tables via `scripts/update-readme.ts`.
+- `npm run lint` maps to `npm run check` for quick consistency with CI.
+
+**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: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**
+
+- `npm run rag:rebuild` (alias `npm run build:rag`) rebuilds embeddings; `npm run rag:fetch` pulls external corpora declared in `src/rag/sources.csv`.
+- `npm run rag:discover` performs experimental GitHub discovery using `src/rag/discover.ts` (requires credentials in `.env`).
+
+**Tooling and release**
+
+- `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.
+
+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.
+
+## MCP Architecture
+
+The server is organised around three core surfaces exposed through the MCP SDK: **tools**, **resources**, and **prompts**. `src/mcp-server.ts` wires these registries together, loads configuration, and enforces platform compatibility.
+
+```text
+src/mcp-server.ts
+├── toolRegistry (src/tools/registry.ts)
+│    └── Domain modules (audio, graphics, memory, printer, rag, etc.)
+├── knowledge resources (src/rag/knowledgeIndex.ts)
+│    └── data/ and doc/ references surfaced via c64:// URIs
+├── prompt registry (src/prompts/registry.ts)
+│    └── Authored prompt definitions under .github/prompts and doc/prompts
+└── platform awareness (src/platform.ts)
+     └── Evaluates backend compatibility (C64U vs VICE) for each tool
+```
+
+`scripts/start.mjs` detects whether TypeScript sources are available and launches `src/mcp-server.ts` (via `src/index.ts`), ensuring both local development and packaged CLI usage share the same entry point.
+
+```mermaid
+flowchart TD
+    subgraph "MCP Server (stdio)"
+      Stdio["src/mcp-server.ts"]
+      ToolRegistry["Tool metadata (src/tools/*)"]
+      PromptRegistry["Prompt registry (src/prompts/*)"]
+      Resources["Knowledge resources (src/rag/knowledgeIndex.ts)"]
+    end
+
+    subgraph "Generated SDK"
+      Api["generated/c64/index.ts"]
+    end
+
+    Stdio --> ToolRegistry
+    Stdio --> PromptRegistry
+    Stdio --> Resources
+    ToolRegistry --> Client["C64Client (src/c64Client.ts)"]
+    ToolRegistry --> BasicConverter["basicConverter.ts"]
+    ToolRegistry --> Rag["RAG helpers (src/rag/*)"]
+    Client --> Api
+    Api -->|HTTP| UltimateAPI["Ultimate 64 REST API"]
+```
+
+```mermaid
+flowchart LR
+  OpenAPI["doc/rest/c64-openapi.yaml"]
+  Generator["npm run api:generate"]
+  Generated["generated/c64/index.ts"]
+  Facade["src/c64Client.ts"]
+
+  OpenAPI --> Generator --> Generated --> Facade
+```
+
+## MCP Server Tips
+
+- Preferred transport is stdio (`src/mcp-server.ts`); `src/index.ts` simply imports this module so CLI and npm consumers share the same entry point.
+- The legacy Fastify HTTP server now lives in `src/http-server.ts.backup`. Keep it untouched unless you need to resurrect HTTP compatibility for debugging.
+- MCP tools enforce platform compatibility via `src/platform.ts`; run `npm test` to cover both metadata and runtime enforcement.
+- Keep REST interactions isolated in `src/c64Client.ts` for easy mocking.
+
+## 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.
+- `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).
+
+## Fast Development Workflow
+
+1. `npm run build` to validate types.
+2. `npm test` against the mock server.
+3. `npm test -- --real` when hardware is available.
+4. Update `doc/` and keep `doc/rest/c64-openapi.yaml` in sync with code.
+
+## Release Workflow
+
+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.
+4. After the PR merges, create and push the tag (`git tag X.Y.Z && git push origin X.Y.Z`) or use the GitHub release UI; CI will now see matching versions.
+5. Perform the publish/release steps that rely on the tag (npm publish, GitHub release, etc.).
+
+### Commit Messages and CHANGELOG Generation
+
+This repository uses a light [Conventional Commits](https://www.conventionalcommits.org) style to generate [`CHANGELOG.md`](https://github.com/chrisgleissner/c64bridge/blob/main/CHANGELOG.md) entries (aligned with [Keep a Changelog](https://keepachangelog.com/)) during `release:prepare`:
+
+- Format: `type(scope)?: subject`.
+- Examples:
+  - `feat: add SID triangle-wave example`
+  - `fix(petscii): correct chargen mapping for inverted glyphs`
+  - `docs: clarify health checks (/health vs /tools/version)`
+  - `refactor: extract audio analyzer helpers`
+  - `perf: speed up RAG embedding load`
+  - `chore(ci): pin setup-node to v4`
+- Breaking changes: add a `!` after the type, e.g., `feat!: remove deprecated /tools/info fallback`.
+
+During a release prep, the script groups commits since the previous tag into sections:
+
+- Features (`feat`)
+- Bug Fixes (`fix`)
+- Performance (`perf`)
+- Refactoring (`refactor`)
+- Documentation (`docs`)
+- Tests (`test`)
+- Chores (`build`, `ci`, `chore`)
+- Other (non-conforming subjects)
+
+Tips:
+
+- Prefer concise subjects; the changelog lists the subject plus the short SHA.
+- Skip “Merge …” subjects; they are filtered automatically.
+- Run `npm run changelog:generate` to regenerate locally; it prepends a new section for the current `package.json` version using commits since the last tag.
+
+
+## Local RAG
+
+### Overview
+
+- The retrieval-augmented generation subsystem ingests C64-related BASIC, assembly, and Markdown files under `data/` plus a curated subset of docs.
+- Embeddings are written as deterministic JSON payloads (`embeddings_*.json`) inside `data/` unless you override the target with `RAG_EMBEDDINGS_DIR`.
+- The server consumes these indices at startup to enrich MCP tool prompts; if indices are missing it simply serves empty results until you build them.
+
+### Indexed Content
+
+- Drop additional snippets, notes, or source code anywhere under `data/` and the indexer will pick them up recursively.
+- Include documentation that lives outside `data/` by exporting `RAG_DOC_FILES=path/to/doc1.md,path/to/doc2.md` before rebuilding; the defaults already cover `data/assembly/assembly-spec.md`.
+
+### Configuration Flags
+
+- `RAG_EMBEDDINGS_DIR`: relocate the generated JSON files (the test suite points this at `artifacts/test-embeddings`).
+- `RAG_REINDEX_INTERVAL_MS`: set to `0` (default) to disable background polling; raise it to opt into periodic rebuilds.
+- `RAG_BUILD_ON_START`: unset by default so the server reuses existing indices; set to `1` for a one-time rebuild during startup.
+
+The indexer only touches files when content changes to avoid noisy diffs.
+
+### Maintenance Commands
+
+- `npm run rag:rebuild` — rebuild embeddings immediately.
+- `npm run rag:fetch` — refresh external source material defined in `src/rag/sources.csv` before rebuilding.
+
+### Using the Retriever
+
+- Tools: call `rag_retrieve_basic` or `rag_retrieve_asm` over the MCP stdio session with `{ "q": "query", "k": 3 }` to pull BASIC or assembly references.
+- Optional HTTP probe: only if you manually launch the legacy Fastify server (see "Optional HTTP Compatibility" in `doc/troubleshooting-mcp.md`), you can `GET /rag/retrieve?q=<text>&k=3&lang=basic|asm` for quick inspection.
+
+```bash
+# Example legacy probe once the optional HTTP server is running
+curl -s "http://localhost:8000/rag/retrieve?q=draw%20a%20sine%20wave&k=3&lang=basic" | jq
+```
+
+### Index Hygiene
+
+- Keep `RAG_REINDEX_INTERVAL_MS=0` in CI and local development unless you are actively modifying the corpus.
+- Run `npm run rag:rebuild` after significant documentation imports so teammates receive the updated indices in version control.
+- When experimentation requires rapid iteration, point `RAG_EMBEDDINGS_DIR` at a temporary folder and skip committing the generated files.
+
+### External Sources
+
+Extending the RAG from external sources is a three-step process: discover sources, fetch content from them, and add the content to the index.
+
+#### Discover
+
+> [!NOTE]
+> This feature is experimental.
+
+To discover new C64 sources on GitHub, first create a `.env` file with GitHub credentials with these contents:
+
+```env
+GITHUB_TOKEN=<personalAccessToken>
+```
+
+The `<personalAccessToken>` can be issued at [GitHub Personal Access Tokens](https://github.com/settings/personal-access-tokens) with these values:
+
+- Expiration: 90 days
+- Resource owner: Your GitHub user account
+- Repository access: All repositories
+- Access type: Public repositories
+- Permissions: Metadata (Read-only), Contents (Read-only)
+
+Then run:
+
+```bash
+npm install --save-dev dotenv-cli
+npx dotenv -e .env -- npm run rag:discover
+```
+
+This will extend the file `src/rag/sources.csv`.
+
+#### Fetch
+
+To download sources available at locations defined in `src/rag/sources.csv`:
+
+1. (Optional) Extend `src/rag/sources.csv` (columns: `type,description,link,depth`) with new sources.
+1. Fetch sources (opt-in, no network on builds/tests):
+
+   ```bash
+   npm run rag:fetch
+   ```
+
+#### Rebuild
+
+1. Rebuild the RAG index to incorporate new or changed sources:
+
+   ```bash
+   # either rely on the running server's auto-reindexer (default ~15s), or
+   npm run rag:rebuild
+   ```
+
+#### Notes
+
+- Downloads are stored under `external/` (gitignored) and included in the index alongside `data/*`.
+- If you delete files from `external/` and rebuild, their content will be removed from the RAG. To “freeze” current embeddings, avoid rebuilding (e.g., set `RAG_REINDEX_INTERVAL_MS=0`) until you want to refresh.
+
+For advanced options (depth semantics, throttling/limits, adaptive rate limiting, retries, logs, and environment overrides), see the dedicated section in `doc/developer.md`.
+
+## Utility Scripts 🛠️
+
+- `npm run c64:tool` — interactive helper that can:
+  - convert a BASIC file to a PRG and store it under `artifacts/` (or a path you choose),
+  - convert and immediately run the generated PRG on the configured c64 device,
+  - upload an existing PRG and run it on the c64 device.
+- `npm run api:generate` — regenerate the typed REST client under `generated/c64/` from [`doc/rest/c64-openapi.yaml`](doc/rest/c64-openapi.yaml).
+- 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
+  ```
+
+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/prompts/README.md

@@ -0,0 +1,96 @@
+# 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://specs/basic`, `c64://context/bootstrap`, `c64://docs/index` | Reinforce BASIC token rules, PETSCII gotchas, workflow expectations. |
+| `assembly-program` | `c64://specs/assembly`, `c64://context/bootstrap`, `c64://specs/vic`, `c64://specs/sid` | Provide opcode tables, IRQ setup, VIC/SID register references. |
+| `sid-music` | `c64://specs/sid`, `c64://specs/sidwave`, `c64://docs/sid/file-structure` | Supply register map, SIDWAVE format, SID file metadata. |
+| `graphics-demo` | `c64://specs/vic`, `c64://context/bootstrap` | Cover VIC mode bits, raster constraints, general workflow guidance. |
+| `printer-job` | `c64://specs/printer`, `c64://docs/printer/guide`, `c64://docs/printer/prompts` | Document PETSCII vs ESC/P workflows, sample templates, and safety checks. |
+| `memory-debug` | `c64://context/bootstrap`, `c64://specs/assembly`, `c64://docs/index` | Highlight addressing safeguards, workflow rules, and knowledge map summaries. |
+| `drive-manager` | `c64://context/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` | `upload_and_run_basic`, `read_screen`, `read_memory` | `write_memory`, `reset_c64` | Remind to reset only if user confirms; highlight PETSCII newline handling. |
+| `assembly-program` | `upload_and_run_asm`, `write_memory`, `read_memory` | `read_screen`, `reset_c64`, `pause`, `resume` | Require IRQ acknowledgement steps for raster code; caution on zero-page writes. |
+| `sid-music` | `music_generate`, `analyze_audio`, `sid_note_on` *(for manual passages)* | `music_compile_and_play`, `sidplay_file`, `sid_volume` | Warn about volume resets (`$D418`) and making backups before overwriting SID memory. |
+| `graphics-demo` | `upload_and_run_basic` or `upload_and_run_asm`, `render_petscii_screen`, `generate_sprite_prg` | `create_petscii_image`, `read_memory`, `pause` | Emphasise safe colour RAM usage; mention border side-effects for raster tricks. |
+| `printer-job` | `print_text`, `print_bitmap_commodore`, `print_bitmap_epson` | `define_printer_chars`, `read_memory` | Remind users to send `CHR$(12)` before closing; confirm `target` (`commodore` vs `epson`) before printing. |
+| `memory-debug` | `read_memory`, `write_memory`, `pause`, `resume` | `reset_c64`, `read_screen` | Advise capturing snapshots before writes; include address validation heuristics. |
+| `drive-manager` | `drives_list`, `drive_mount`, `drive_remove` | `drive_reset`, `drive_on`, `drive_off`, `create_d64`, `create_d71`, `create_d81`, `create_dnp`, `file_info`, `drive_load_rom` | 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 `read_screen` capture, optional `read_memory` 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 or `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, reading range before write, 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/prompts/user-prompt-ideas.md

@@ -0,0 +1,147 @@
+# 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."