c64bridge 0.8.1 → 0.9.1

package/dist/rag/knowledgeIndex.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { CANONICAL_KNOWLEDGE_RESOURCE_URIS, PLATFORM_RESOURCE_URI, RESOURCE_URIS } from "./resourceUris.js";
 function generateCharsetQuickref() {
     const csvPath = join(process.cwd(), "data/graphics/character-set.csv");
     const csvContent = readFileSync(csvPath, "utf-8");
@@ -34,14 +35,14 @@ function generateCharsetQuickref() {
 }
 const KNOWLEDGE_BUNDLES = [
     {
-        id: "orientation",
-        title: "Workflow & Orientation",
+        id: "guide",
+        title: "Guides & Orientation",
         summary: "Mandatory workflow and safety guidance before issuing any C64 commands.",
         prompts: ["basic-program", "assembly-program", "memory-debug", "cross-platform-demo", "preset-music-demo"],
         tools: ["upload_run_basic", "upload_run_asm", "cross_platform_greeting", "music_play_preset", "read_screen", "read"],
         resources: [
             {
-                uri: "c64://context/bootstrap",
+                uri: RESOURCE_URIS.guide.bootstrap,
                 name: "Workflow Rules & Best Practices",
                 description: "CRITICAL: Mandatory workflow rules for all C64 programming",
                 relativePath: "data/context/bootstrap.md",
@@ -52,7 +53,7 @@ const KNOWLEDGE_BUNDLES = [
                 tags: ["workflow", "safety"],
             },
             {
-                uri: "c64://context/fast-paths",
+                uri: RESOURCE_URIS.guide.fastPaths,
                 name: "Fast Path Workflows",
                 description: "Shortest reliable workflows for common C64U and VICE tasks, including dual-backend demos.",
                 relativePath: "data/context/fast-paths.md",
@@ -60,11 +61,56 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Condensed routing guide for one-call demos, backend switching, and when to prefer orchestration over manual tool composition.",
                 prompts: ["basic-program", "graphics-demo", "cross-platform-demo", "sid-music", "preset-music-demo"],
                 tools: ["c64_program", "c64_sound", "c64_select_backend", "c64_memory", "c64_graphics"],
-                relatedResources: ["c64://context/bootstrap", "c64://platform/status"],
+                relatedResources: [RESOURCE_URIS.guide.bootstrap, PLATFORM_RESOURCE_URI],
                 tags: ["workflow", "fast-path", "routing"],
             },
         ],
     },
+    {
+        id: "vice",
+        title: "VICE Emulator",
+        summary: "Critical Binary Monitor protocol guidance for any workflow that targets the VICE backend.",
+        prompts: [
+            "hello-world",
+            "basic-program",
+            "cross-platform-demo",
+            "preset-music-demo",
+            "assembly-program",
+            "sid-music",
+            "graphics-demo",
+            "memory-debug",
+            "drive-manager",
+        ],
+        tools: ["c64_program", "c64_memory", "c64_debug", "c64_vice", "c64_system"],
+        resources: [
+            {
+                uri: RESOURCE_URIS.vice.binaryMonitorSpec,
+                name: "VICE Binary Monitor Specification",
+                description: "Critical VICE Binary Monitor reference for emulator-backed workflows and debugger operations.",
+                relativePath: "data/vice/vice-binary-monitor-spec.md",
+                priority: "critical",
+                summary: "Transport framing, single-client constraints, command semantics, and monitor side effects that shape all VICE-backed operations.",
+                prompts: [
+                    "hello-world",
+                    "basic-program",
+                    "cross-platform-demo",
+                    "preset-music-demo",
+                    "assembly-program",
+                    "sid-music",
+                    "graphics-demo",
+                    "memory-debug",
+                    "drive-manager",
+                ],
+                tools: ["c64_program", "c64_memory", "c64_debug", "c64_vice", "c64_system"],
+                relatedResources: [
+                    RESOURCE_URIS.guide.bootstrap,
+                    RESOURCE_URIS.guide.fastPaths,
+                    PLATFORM_RESOURCE_URI,
+                ],
+                tags: ["vice", "binary-monitor", "emulator", "debugger"],
+            },
+        ],
+    },
     {
         id: "languages",
         title: "Programming Languages",
@@ -73,7 +119,7 @@ const KNOWLEDGE_BUNDLES = [
         tools: ["upload_run_basic", "upload_run_asm", "read_screen", "read"],
         resources: [
             {
-                uri: "c64://specs/basic",
+                uri: RESOURCE_URIS.basic.spec,
                 name: "Commodore BASIC v2 Specification",
                 description: "Complete BASIC v2 reference. READ THIS BEFORE generating any BASIC code!",
                 relativePath: "data/basic/basic-spec.md",
@@ -81,11 +127,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Token definitions, syntax rules, and device I/O guidance for BASIC v2.",
                 prompts: ["basic-program"],
                 tools: ["upload_run_basic", "read_screen"],
-                relatedResources: ["c64://context/bootstrap", "c64://docs/basic/pitfalls"],
+                relatedResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.basic.pitfalls],
                 tags: ["basic", "language"],
             },
             {
-                uri: "c64://docs/basic/pitfalls",
+                uri: RESOURCE_URIS.basic.pitfalls,
                 name: "BASIC Pitfalls & Gotchas",
                 description: "Common mistakes and gotchas when writing Commodore BASIC v2 programs",
                 relativePath: "data/basic/basic-pitfalls.md",
@@ -93,11 +139,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps.",
                 prompts: ["basic-program"],
                 tools: ["upload_run_basic"],
-                relatedResources: ["c64://specs/basic"],
+                relatedResources: [RESOURCE_URIS.basic.spec],
                 tags: ["basic", "pitfalls", "quickref"],
             },
             {
-                uri: "c64://specs/assembly",
+                uri: RESOURCE_URIS.assembly.spec6510,
                 name: "6502/6510 Assembly Reference",
                 description: "Full instruction set and addressing modes. READ THIS BEFORE generating assembly!",
                 relativePath: "data/assembly/assembly-spec.md",
@@ -105,7 +151,7 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU.",
                 prompts: ["assembly-program"],
                 tools: ["upload_run_asm", "read"],
-                relatedResources: ["c64://context/bootstrap"],
+                relatedResources: [RESOURCE_URIS.guide.bootstrap],
                 tags: ["assembly", "language"],
             },
         ],
@@ -118,7 +164,7 @@ const KNOWLEDGE_BUNDLES = [
         tools: ["c64_sound"],
         resources: [
             {
-                uri: "c64://specs/sid",
+                uri: RESOURCE_URIS.sound.sid.spec,
                 name: "SID Chip Programming Guide",
                 description: "Sound Interface Device registers and music programming",
                 relativePath: "data/sound/sid-spec.md",
@@ -126,11 +172,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Register map, waveform behaviour, and ADSR envelopes for expressive SID playback.",
                 prompts: ["sid-music"],
                 tools: ["c64_sound"],
-                relatedResources: ["c64://specs/sidwave", "c64://docs/sid/file-structure"],
+                relatedResources: [RESOURCE_URIS.sound.sidwave.spec, RESOURCE_URIS.sound.sid.fileFormat],
                 tags: ["sid", "audio"],
             },
             {
-                uri: "c64://specs/sidwave",
+                uri: RESOURCE_URIS.sound.sidwave.spec,
                 name: "SIDWAVE Music Format Specification",
                 description: "YAML/JSON music composition format for SID chip",
                 relativePath: "data/sound/sidwave.md",
@@ -138,11 +184,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Defines the SIDWAVE interchange format used by the SID composer workflow.",
                 prompts: ["sid-music"],
                 tools: ["c64_sound"],
-                relatedResources: ["c64://specs/sid", "c64://docs/sid/file-structure"],
+                relatedResources: [RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.sound.sid.fileFormat],
                 tags: ["sid", "format"],
             },
             {
-                uri: "c64://docs/sid/file-structure",
+                uri: RESOURCE_URIS.sound.sid.fileFormat,
                 name: "SID File Structure Reference",
                 description: "Breakdown of the SID file format layout and metadata",
                 relativePath: "data/sound/sid-file-structure.md",
@@ -150,11 +196,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music.",
                 prompts: ["sid-music"],
                 tools: ["c64_sound"],
-                relatedResources: ["c64://specs/sid", "c64://specs/sidwave"],
+                relatedResources: [RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.sound.sidwave.spec],
                 tags: ["sid", "format"],
             },
             {
-                uri: "c64://docs/sid/best-practices",
+                uri: RESOURCE_URIS.sound.sid.bestPractices,
                 name: "SID Programming Best Practices",
                 description: "Expressive SID composition defaults, ADSR guidance, and musical phrasing tips.",
                 relativePath: "data/sound/sid-programming-best-practices.md",
@@ -162,7 +208,7 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music.",
                 prompts: ["sid-music"],
                 tools: ["c64_sound"],
-                relatedResources: ["c64://specs/sid", "c64://specs/sidwave"],
+                relatedResources: [RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.sound.sidwave.spec],
                 tags: ["sid", "best-practices", "audio"],
             },
         ],
@@ -175,7 +221,7 @@ const KNOWLEDGE_BUNDLES = [
         tools: ["c64_graphics", "c64_memory"],
         resources: [
             {
-                uri: "c64://specs/vic",
+                uri: RESOURCE_URIS.graphics.vic.spec,
                 name: "VIC-II Graphics Specification",
                 description: "Video chip, sprites, raster programming, and timing",
                 relativePath: "data/graphics/vic-spec.md",
@@ -183,11 +229,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II.",
                 prompts: ["graphics-demo"],
                 tools: ["c64_graphics", "c64_memory"],
-                relatedResources: ["c64://specs/assembly", "c64://specs/charset", "c64://docs/petscii-style"],
+                relatedResources: [RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.graphics.characterSet, RESOURCE_URIS.graphics.petscii.styleGuide],
                 tags: ["vic", "graphics"],
             },
             {
-                uri: "c64://specs/charset",
+                uri: RESOURCE_URIS.graphics.characterSet,
                 name: "PETSCII Character Set Reference",
                 description: "Complete PETSCII character codes, screen codes, and glyph mappings",
                 relativePath: "data/graphics/character-set.csv",
@@ -195,11 +241,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input.",
                 prompts: ["graphics-demo"],
                 tools: ["c64_graphics"],
-                relatedResources: ["c64://specs/vic", "c64://docs/petscii-style"],
+                relatedResources: [RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.graphics.petscii.styleGuide],
                 tags: ["petscii", "charset", "graphics"],
             },
             {
-                uri: "c64://docs/petscii-style",
+                uri: RESOURCE_URIS.graphics.petscii.styleGuide,
                 name: "PETSCII Style Guide and Presets",
                 description: "Colour combinations, contrast guidelines, and recommended presets for PETSCII art",
                 relativePath: "data/graphics/petscii-style-guide.md",
@@ -207,11 +253,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays.",
                 prompts: ["graphics-demo"],
                 tools: ["c64_graphics"],
-                relatedResources: ["c64://specs/vic", "c64://specs/charset", "c64://docs/sprite-charset-workflows"],
+                relatedResources: [RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.graphics.characterSet, RESOURCE_URIS.graphics.spriteCharset.bestPractices],
                 tags: ["petscii", "style", "colours", "graphics"],
             },
             {
-                uri: "c64://docs/sprite-charset-workflows",
+                uri: RESOURCE_URIS.graphics.spriteCharset.bestPractices,
                 name: "Sprite & Charset Workflows Best Practices",
                 description: "Comprehensive guide to creating, managing, and deploying sprites and custom character sets",
                 relativePath: "data/graphics/sprite-charset-best-practices.md",
@@ -219,7 +265,7 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics.",
                 prompts: ["graphics-demo"],
                 tools: ["c64_graphics", "c64_memory", "c64_program"],
-                relatedResources: ["c64://specs/vic", "c64://specs/charset", "c64://docs/petscii-style", "c64://specs/memory-map"],
+                relatedResources: [RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.graphics.characterSet, RESOURCE_URIS.graphics.petscii.styleGuide, RESOURCE_URIS.memory.map],
                 tags: ["sprites", "charset", "graphics", "workflows"],
             },
         ],
@@ -232,7 +278,7 @@ const KNOWLEDGE_BUNDLES = [
         tools: ["read", "write", "verify_and_write_memory", "debugreg_read", "debugreg_write"],
         resources: [
             {
-                uri: "c64://specs/memory-map",
+                uri: RESOURCE_URIS.memory.map,
                 name: "C64 Memory Map",
                 description: "Complete RAM, ROM, and I/O address map for the Commodore 64.",
                 relativePath: "data/memory/memory-map.md",
@@ -240,11 +286,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: ["c64://specs/assembly"],
+                relatedResources: [RESOURCE_URIS.assembly.spec6510],
                 tags: ["memory", "hardware"],
             },
             {
-                uri: "c64://specs/memory-low",
+                uri: RESOURCE_URIS.memory.zeroPageAndWorkspace,
                 name: "Low Memory Usage Guide",
                 description: "Zero-page and system vector reference for low-memory addresses.",
                 relativePath: "data/memory/low-memory-map.md",
@@ -252,11 +298,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: ["c64://specs/memory-map", "c64://specs/assembly"],
+                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
                 tags: ["memory", "zero-page"],
             },
             {
-                uri: "c64://specs/memory-kernal",
+                uri: RESOURCE_URIS.kernal.romRoutines,
                 name: "KERNAL Memory Map",
                 description: "Detailed breakdown of KERNAL ROM routines and entry points.",
                 relativePath: "data/memory/kernal-memory-map.md",
@@ -264,11 +310,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Lists KERNAL ROM vectors and service routines for OS-level functionality.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "verify_and_write_memory"],
-                relatedResources: ["c64://specs/memory-map", "c64://specs/assembly"],
+                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
                 tags: ["memory", "kernal"],
             },
             {
-                uri: "c64://specs/io",
+                uri: RESOURCE_URIS.io.spec,
                 name: "C64 I/O Register Map",
                 description: "Comprehensive table of memory-mapped hardware registers.",
                 relativePath: "data/io/io-spec.md",
@@ -276,11 +322,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read", "debugreg_write"],
-                relatedResources: ["c64://specs/memory-map", "c64://specs/assembly"],
+                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
                 tags: ["io", "hardware"],
             },
             {
-                uri: "c64://specs/cia",
+                uri: RESOURCE_URIS.io.cia.spec,
                 name: "CIA Register Reference",
                 description: "Timer, keyboard, and peripheral register reference for CIA chips.",
                 relativePath: "data/io/cia-spec.md",
@@ -288,7 +334,7 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read"],
-                relatedResources: ["c64://specs/io", "c64://specs/memory-map"],
+                relatedResources: [RESOURCE_URIS.io.spec, RESOURCE_URIS.memory.map],
                 tags: ["io", "hardware"],
             },
         ],
@@ -308,7 +354,7 @@ const KNOWLEDGE_BUNDLES = [
         ],
         resources: [
             {
-                uri: "c64://specs/printer",
+                uri: RESOURCE_URIS.printer.spec,
                 name: "Printer Programming Guide",
                 description: "Commodore MPS and Epson FX printer control",
                 relativePath: "data/printer/printer-spec.md",
@@ -317,30 +363,13 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_guide", "printer_commodore_text", "printer_epson_text"],
                 relatedResources: [
-                    "c64://docs/printer/guide",
-                    "c64://docs/printer/commodore-text",
-                    "c64://docs/printer/epson-text",
+                    RESOURCE_URIS.printer.commodore.text,
+                    RESOURCE_URIS.printer.epson.text,
                 ],
                 tags: ["printer", "spec"],
             },
             {
-                uri: "c64://docs/printer/guide",
-                name: "Printer Workflow Guide",
-                description: "Unified quick reference for Commodore and Epson printers",
-                relativePath: "data/printer/printer-spec.md",
-                priority: "reference",
-                summary: "Quick-look workflow covering setup, troubleshooting, and sample jobs for both printer families.",
-                prompts: ["printer-job"],
-                tools: ["printer_guide"],
-                relatedResources: [
-                    "c64://specs/printer",
-                    "c64://docs/printer/commodore-text",
-                    "c64://docs/printer/epson-text",
-                ],
-                tags: ["printer", "workflow"],
-            },
-            {
-                uri: "c64://docs/printer/commodore-text",
+                uri: RESOURCE_URIS.printer.commodore.text,
                 name: "Commodore Printer Text Guide",
                 description: "Device 4 character printing reference for Commodore MPS printers",
                 relativePath: "data/printer/printer-commodore.md",
@@ -349,13 +378,13 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_commodore_text"],
                 relatedResources: [
-                    "c64://specs/printer",
-                    "c64://docs/printer/commodore-bitmap",
+                    RESOURCE_URIS.printer.spec,
+                    RESOURCE_URIS.printer.commodore.bitmap,
                 ],
                 tags: ["printer", "commodore"],
             },
             {
-                uri: "c64://docs/printer/commodore-bitmap",
+                uri: RESOURCE_URIS.printer.commodore.bitmap,
                 name: "Commodore Printer Bitmap Guide",
                 description: "Bitmap and custom character printing workflow for Commodore printers",
                 relativePath: "data/printer/printer-commodore-bitmap.md",
@@ -364,13 +393,13 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_commodore_bitmap"],
                 relatedResources: [
-                    "c64://docs/printer/commodore-text",
-                    "c64://specs/printer",
+                    RESOURCE_URIS.printer.commodore.text,
+                    RESOURCE_URIS.printer.spec,
                 ],
                 tags: ["printer", "commodore", "graphics"],
             },
             {
-                uri: "c64://docs/printer/epson-text",
+                uri: RESOURCE_URIS.printer.epson.text,
                 name: "Epson Printer Text Guide",
                 description: "Text control sequences for Epson FX-compatible printers",
                 relativePath: "data/printer/printer-epson.md",
@@ -379,13 +408,13 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_epson_text"],
                 relatedResources: [
-                    "c64://docs/printer/epson-bitmap",
-                    "c64://specs/printer",
+                    RESOURCE_URIS.printer.epson.bitmap,
+                    RESOURCE_URIS.printer.spec,
                 ],
                 tags: ["printer", "epson"],
             },
             {
-                uri: "c64://docs/printer/epson-bitmap",
+                uri: RESOURCE_URIS.printer.epson.bitmap,
                 name: "Epson Printer Bitmap Guide",
                 description: "Bitmap printing and graphics control for Epson FX printers",
                 relativePath: "data/printer/printer-epson-bitmap.md",
@@ -394,13 +423,13 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_epson_bitmap"],
                 relatedResources: [
-                    "c64://docs/printer/epson-text",
-                    "c64://specs/printer",
+                    RESOURCE_URIS.printer.epson.text,
+                    RESOURCE_URIS.printer.spec,
                 ],
                 tags: ["printer", "epson", "graphics"],
             },
             {
-                uri: "c64://docs/printer/prompts",
+                uri: RESOURCE_URIS.printer.promptGuide,
                 name: "Printer Prompt Templates",
                 description: "Template prompts and workflow guidance for printer jobs",
                 relativePath: "data/printer/printer-prompts.md",
@@ -409,16 +438,20 @@ const KNOWLEDGE_BUNDLES = [
                 prompts: ["printer-job"],
                 tools: ["printer_prompts"],
                 relatedResources: [
-                    "c64://docs/printer/guide",
-                    "c64://docs/printer/commodore-text",
-                    "c64://docs/printer/epson-text",
+                    RESOURCE_URIS.printer.spec,
+                    RESOURCE_URIS.printer.commodore.text,
+                    RESOURCE_URIS.printer.epson.text,
                 ],
                 tags: ["printer", "prompts"],
             },
         ],
     },
 ];
+const CANONICAL_KNOWLEDGE_RESOURCE_URI_SET = new Set(CANONICAL_KNOWLEDGE_RESOURCE_URIS);
 const BASE_RESOURCES = KNOWLEDGE_BUNDLES.flatMap((bundle, bundleIndex) => bundle.resources.map((resource, resourceIndex) => {
+    if (!CANONICAL_KNOWLEDGE_RESOURCE_URI_SET.has(resource.uri)) {
+        throw new Error(`Knowledge resource URI ${resource.uri} is not part of the canonical resource set`);
+    }
     const baseResource = {
         uri: resource.uri,
         name: resource.name,
@@ -443,18 +476,18 @@ const BASE_RESOURCES = KNOWLEDGE_BUNDLES.flatMap((bundle, bundleIndex) => bundle
         },
     };
     // Add buildContent for resources that need dynamic generation
-    if (resource.uri === "c64://specs/charset") {
+    if (resource.uri === RESOURCE_URIS.graphics.characterSet) {
         return { ...baseResource, buildContent: generateCharsetQuickref };
     }
     return baseResource;
 }));
 const INDEX_RESOURCE = {
-    uri: "c64://docs/index",
+    uri: RESOURCE_URIS.guide.index,
     name: "C64 Knowledge Map",
     description: "Start here for a guided tour of all Commodore 64 knowledge resources",
     mimeType: "text/markdown",
     metadata: {
-        domain: "overview",
+        domain: "guide",
         priority: "critical",
         summary: "Explains how to approach each knowledge bundle and when to consult it.",
         prompts: ["basic-program", "assembly-program", "sid-music", "graphics-demo", "printer-job", "memory-debug", "cross-platform-demo", "preset-music-demo"],
@@ -468,7 +501,7 @@ const INDEX_RESOURCE = {
         ],
         tags: ["overview"],
         bundle: {
-            id: "overview",
+            id: "guide",
             title: "Knowledge Overview",
             summary: "Read this first to understand how the MCP server organizes Commodore 64 expertise.",
             order: -1,
@@ -523,7 +556,7 @@ export function readKnowledgeResource(uri, projectRoot) {
     if (resource.buildContent) {
         const baseResources = ALL_RESOURCES.filter((item) => item.uri !== resource.uri);
         return {
-            uri: resource.uri,
+            uri,
             mimeType: resource.mimeType,
             text: resource.buildContent(baseResources),
         };
@@ -534,7 +567,7 @@ export function readKnowledgeResource(uri, projectRoot) {
     const fullPath = join(projectRoot, resource.relativePath);
     const text = readFileSync(fullPath, "utf-8");
     return {
-        uri: resource.uri,
+        uri,
         mimeType: resource.mimeType,
         text,
     };

package/dist/rag/resourceUris.js

@@ -0,0 +1,93 @@
+export const RESOURCE_URIS = {
+    guide: {
+        index: "c64://guide/index",
+        bootstrap: "c64://guide/bootstrap",
+        fastPaths: "c64://guide/fast-paths",
+    },
+    vice: {
+        binaryMonitorSpec: "c64://vice/binary-monitor-spec",
+    },
+    basic: {
+        spec: "c64://basic/spec",
+        pitfalls: "c64://basic/pitfalls",
+    },
+    assembly: {
+        spec6510: "c64://assembly/6510-spec",
+    },
+    sound: {
+        sid: {
+            spec: "c64://sound/sid/spec",
+            fileFormat: "c64://sound/sid/file-format",
+            bestPractices: "c64://sound/sid/best-practices",
+        },
+        sidwave: {
+            spec: "c64://sound/sidwave/spec",
+        },
+    },
+    graphics: {
+        vic: {
+            spec: "c64://graphics/vic/spec",
+        },
+        characterSet: "c64://graphics/character-set",
+        petscii: {
+            styleGuide: "c64://graphics/petscii/style-guide",
+        },
+        spriteCharset: {
+            bestPractices: "c64://graphics/sprite-charset/best-practices",
+        },
+    },
+    memory: {
+        map: "c64://memory/map",
+        zeroPageAndWorkspace: "c64://memory/zero-page-and-workspace",
+    },
+    kernal: {
+        romRoutines: "c64://kernal/rom-routines",
+    },
+    io: {
+        spec: "c64://io/spec",
+        cia: {
+            spec: "c64://io/cia/spec",
+        },
+    },
+    printer: {
+        spec: "c64://printer/spec",
+        commodore: {
+            text: "c64://printer/commodore/text",
+            bitmap: "c64://printer/commodore/bitmap",
+        },
+        epson: {
+            text: "c64://printer/epson/text",
+            bitmap: "c64://printer/epson/bitmap",
+        },
+        promptGuide: "c64://printer/prompt-guide",
+    },
+};
+export const PLATFORM_RESOURCE_URI = "c64://platform/status";
+export const CANONICAL_KNOWLEDGE_RESOURCE_URIS = Object.freeze([
+    RESOURCE_URIS.guide.bootstrap,
+    RESOURCE_URIS.guide.fastPaths,
+    RESOURCE_URIS.vice.binaryMonitorSpec,
+    RESOURCE_URIS.basic.spec,
+    RESOURCE_URIS.basic.pitfalls,
+    RESOURCE_URIS.assembly.spec6510,
+    RESOURCE_URIS.sound.sid.spec,
+    RESOURCE_URIS.sound.sidwave.spec,
+    RESOURCE_URIS.sound.sid.fileFormat,
+    RESOURCE_URIS.sound.sid.bestPractices,
+    RESOURCE_URIS.graphics.vic.spec,
+    RESOURCE_URIS.graphics.characterSet,
+    RESOURCE_URIS.graphics.petscii.styleGuide,
+    RESOURCE_URIS.graphics.spriteCharset.bestPractices,
+    RESOURCE_URIS.memory.map,
+    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+    RESOURCE_URIS.kernal.romRoutines,
+    RESOURCE_URIS.io.spec,
+    RESOURCE_URIS.io.cia.spec,
+    RESOURCE_URIS.printer.spec,
+    RESOURCE_URIS.printer.commodore.text,
+    RESOURCE_URIS.printer.commodore.bitmap,
+    RESOURCE_URIS.printer.epson.text,
+    RESOURCE_URIS.printer.epson.bitmap,
+    RESOURCE_URIS.printer.promptGuide,
+    RESOURCE_URIS.guide.index,
+]);

package/dist/sidwaveCompiler.js

@@ -6,7 +6,7 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
-import { assemblyToPrg } from "./assemblyConverter.js";
+import { assemblyToPrg } from "./tools/assember.js";
 import { midiToHz, noteNameToMidi } from "./sidwave.js";
 /**
  * Small SIDWAVE to PRG compiler: generates a 50/60Hz player that writes SID registers from a precomputed frame table.

package/dist/{assemblyConverter.js → tools/assember.js}

@@ -77,6 +77,9 @@ const DIRECTIVE_ALIASES = {
 };
 const RELATIVE_ONLY = new Set(["BCC", "BCS", "BEQ", "BMI", "BNE", "BPL", "BVC", "BVS"]);
 export function assemblyToPrg(source, options) {
+    return assemblyToPrgDetailed(source, options).prg;
+}
+export function assemblyToPrgDetailed(source, options) {
     const normalized = normalizeSource(source);
     const loadAddress = options?.loadAddress ?? DEFAULT_LOAD_ADDRESS;
     const rootFile = options?.fileName ?? "(input)";
@@ -86,7 +89,7 @@ export function assemblyToPrg(source, options) {
     const assembler = new Assembler(statements, loadAddress);
     assembler.runPass(0);
     assembler.runPass(1);
-    return assembler.buildPrg();
+    return { prg: assembler.buildPrg(), symbols: assembler.getSymbols() };
 }
 function normalizeSource(input) {
     return input.replace(/\r\n?/g, "\n");
@@ -608,6 +611,9 @@ class SymbolTable {
         }
         return this.globals.get(label);
     }
+    allGlobals() {
+        return this.globals;
+    }
     ensureLocalScope(scope) {
         if (!this.locals.has(scope)) {
             this.locals.set(scope, new Map());
@@ -658,6 +664,9 @@ class Assembler {
         header.writeUInt16LE(start, 0);
         return Buffer.concat([header, Buffer.from(body)]);
     }
+    getSymbols() {
+        return this.symbolTable.allGlobals();
+    }
     processLine(line, pass) {
         for (const label of line.labels) {
             if (pass === 0) {