c64bridge 0.8.1 → 0.9.1

package/dist/c64Client.js

@@ -8,8 +8,8 @@ See <https://www.gnu.org/licenses/> for details.
 import { Buffer } from "node:buffer";
 import { createSocket } from "node:dgram";
 import axios from "axios";
-import { basicToPrg } from "./basicConverter.js";
-import { assemblyToPrg } from "./assemblyConverter.js";
+import { basicToPrg } from "./tools/basicTokenizer.js";
+import { assemblyToPrg } from "./tools/assember.js";
 import { screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
 import { createAllFacades, createFacade } from "./device.js";
@@ -1492,6 +1492,80 @@ export class C64Client {
         }
         return body instanceof ArrayBuffer ? new Uint8Array(body) : this.extractBytes(body);
     }
+    /**
+     * Low-level memory write that delegates to the active backend's facade.
+     * Public so tools that need to drive cross-platform machine state (e.g.
+     * keyboard-buffer injection) can avoid backend-specific paths.
+     */
+    async writeMemoryRaw(address, bytes) {
+        const facade = await this.facadePromise;
+        const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        await facade.writeMemory(address, buf);
+    }
+    /**
+     * Inject a sequence of PETSCII byte values into the KERNAL keyboard buffer
+     * using shared memory writes. Works on both C64U and VICE because both
+     * backends expose `writeMemory`/`readMemory` against the C64 zero-page and
+     * the keyboard queue at $0277.
+     *
+     * The KERNAL buffer ($0277-$0280) holds 10 bytes; $00C6 (NDX) tracks the
+     * number of pending characters. We chunk the input, then poll NDX until
+     * the kernel has consumed each chunk before queueing the next one.
+     *
+     * @param bytes      Raw PETSCII bytes (already token-expanded by caller)
+     * @param options    Optional knobs for chunk size, drain timing, and total
+     *                   timeout. The defaults mirror KERNAL behavior.
+     */
+    async injectKeyboardQueue(bytes, options) {
+        const data = Buffer.isBuffer(bytes)
+            ? bytes
+            : Buffer.from(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes));
+        if (data.length === 0) {
+            return;
+        }
+        const chunkSize = Math.max(1, Math.min(10, options?.chunkSize ?? 10));
+        const pollMs = Math.max(1, options?.drainPollMs ?? 8);
+        const totalTimeoutMs = Math.max(50, options?.drainTimeoutMs ?? 2000);
+        const facade = await this.facadePromise;
+        const KEYD = 0x0277; // KERNAL keyboard buffer base
+        const NDX = 0x00C6; // pending byte count
+        for (let offset = 0; offset < data.length; offset += chunkSize) {
+            const slice = data.subarray(offset, Math.min(data.length, offset + chunkSize));
+            // Write the bytes into the queue first so KERNAL never reads a stale
+            // length+old-byte combination.
+            await facade.writeMemory(KEYD, Buffer.from(slice));
+            await facade.writeMemory(NDX, Buffer.from([slice.length]));
+            // Drain: wait for KERNAL to consume the queue. If the machine is paused
+            // or otherwise not running, give up after the timeout and continue —
+            // higher layers can decide whether that is a failure for their context.
+            const drainStart = Date.now();
+            while (Date.now() - drainStart < totalTimeoutMs) {
+                const ndx = await facade.readMemory(NDX, 1);
+                if ((ndx[0] ?? 0) === 0) {
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollMs));
+            }
+        }
+    }
+    async viceExitMonitor() {
+        await this.withViceMonitor((client) => client.exitMonitor());
+    }
+    async viceKeyboardFeed(text) {
+        await this.withViceMonitor((client) => client.keyboardFeed(text));
+    }
+    async viceMemSet(address, bytes) {
+        const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        await this.withViceMonitor((client) => client.memSet(address, buf));
+    }
+    async viceMemGet(address, length) {
+        const end = (address + length - 1) & 0xffff;
+        return this.withViceMonitor((client) => client.memGet(address, end));
+    }
+    async viceNuclearReset() {
+        const backend = await this.requireViceBackend();
+        await backend.nuclearReset();
+    }
     async viceCheckpointList() {
         return this.withViceMonitor((client) => client.checkpointList());
     }

package/dist/device.js

@@ -18,6 +18,18 @@ const DEFAULT_VICE_PORT = 6502;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function resumeViceMonitor(client, timeoutMs = 250) {
+    try {
+        const exitMonitor = client.exitMonitor().catch(() => { });
+        await Promise.race([
+            exitMonitor,
+            delay(timeoutMs),
+        ]);
+    }
+    catch {
+        // Ignore resume failures while tearing down a monitor session.
+    }
+}
 function coalesceMemoryWriteBlocks(blocks) {
     const merged = [];
     for (const block of blocks) {
@@ -215,12 +227,18 @@ export class ViceBackend {
         const configBinary = config.exe !== undefined
             ? configuredString(config.exe) ?? (typeof config.exe === "string" ? config.exe : String(config.exe))
             : undefined;
-        this.exe = resolveViceBinary({ envBinary, configBinary });
+        const resolvedLaunch = resolveViceLaunch({
+            envBinary,
+            configBinary,
+            envDirectory: configuredString(process.env.VICE_DIRECTORY),
+            configDirectory: configuredString(config.directory),
+        });
+        this.exe = resolvedLaunch.binary;
         const envHost = normaliseViceHost(process.env.VICE_HOST);
         const envPort = normaliseVicePort(process.env.VICE_PORT);
         this.host = firstDefined(envHost, normaliseViceHost(config.host)) ?? DEFAULT_VICE_HOST;
         this.port = firstDefined(envPort, normaliseVicePort(config.port)) ?? DEFAULT_VICE_PORT;
-        this.directory = firstDefined(resolveViceDirectory(configuredString(process.env.VICE_DIRECTORY)), resolveViceDirectory(configuredString(config.directory)), findViceResourceDirectory(this.exe));
+        this.directory = resolvedLaunch.directory;
         this.mockMode = (process.env.VICE_TEST_TARGET || "").toLowerCase() === "mock";
         const hostLower = this.host.toLowerCase();
         const isLocal = hostLower === "127.0.0.1" || hostLower === "localhost";
@@ -238,6 +256,10 @@ export class ViceBackend {
                 console.error("[vice-backend] probing existing VICE", this.host, this.port);
             await client.connect(this.port, this.host);
             await client.info();
+            try {
+                await client.exitMonitor();
+            }
+            catch { }
             if (this.debugEnabled)
                 console.error("[vice-backend] existing VICE is reachable");
             return true;
@@ -257,6 +279,10 @@ export class ViceBackend {
             try {
                 await client.connect(this.port, this.host);
                 await client.info();
+                try {
+                    await client.exitMonitor();
+                }
+                catch { }
                 return;
             }
             catch (error) {
@@ -275,6 +301,7 @@ export class ViceBackend {
         const client = new ViceClient();
         try {
             await client.connect(this.port, this.host);
+            await client.reset();
             const readiness = await waitForBasicReady(client, { timeoutMs, ensurePrompt: true });
             if (!readiness.pointersOk || !readiness.promptOk) {
                 throw new Error(`VICE machine at ${this.host}:${this.port} did not reach the BASIC prompt within ${timeoutMs}ms`);
@@ -312,15 +339,15 @@ export class ViceBackend {
                 extraArgs: this.extraArgs,
             });
         }
-        const handle = await startViceProcess({
+        const handle = await startViceProcess(buildManagedViceProcessOptions({
             binary: this.exe,
             directory: this.directory,
             host: this.host,
             port: this.port,
             warp: this.warp,
             visible: this.visible,
-            extraArgs: this.extraArgs.length > 0 ? this.extraArgs : undefined,
-        });
+            extraArgs: this.extraArgs,
+        }));
         this.lastProcessStart = Date.now();
         if (this.debugEnabled) {
             console.error("[vice-backend] VICE process started", { pid: handle.process.pid });
@@ -351,6 +378,7 @@ export class ViceBackend {
             return;
         }
         ViceBackend.cleanupRegistered = true;
+        /* c8 ignore next 5 -- global process exit hooks are not practical to exercise in the unit test process */
         process.once("exit", () => {
             for (const [, handle] of ViceBackend.supervisors) {
                 handle.stop().catch(() => { });
@@ -358,7 +386,7 @@ export class ViceBackend {
             ViceBackend.supervisors.clear();
         });
     }
-    async withClient(fn) {
+    async withClient(fn, options) {
         const previous = this.monitorQueue;
         let releaseQueue = () => { };
         this.monitorQueue = new Promise((resolve) => {
@@ -385,6 +413,9 @@ export class ViceBackend {
                 return await fn(client);
             }
             finally {
+                if (options?.resumeOnClose !== false) {
+                    await resumeViceMonitor(client);
+                }
                 if (this.debugEnabled)
                     console.error("[vice-backend] closing VICE monitor connection");
                 client.close();
@@ -532,7 +563,7 @@ export class ViceBackend {
                 catch {
                     // Ignore transport errors during quit; the emulator will terminate regardless.
                 }
-            });
+            }, { resumeOnClose: false });
             if (managedHandle) {
                 try {
                     await managedHandle.stop();
@@ -549,6 +580,31 @@ export class ViceBackend {
             return { success: false, details };
         }
     }
+    async nuclearReset() {
+        const poweroffResult = await this.poweroff();
+        if (!poweroffResult.success) {
+            return poweroffResult;
+        }
+        if (!this.manageProcess) {
+            return {
+                success: false,
+                details: {
+                    code: "UNSUPPORTED",
+                    message: "VICE nuclear reset requires a managed process; unmanaged instances can only be powered off.",
+                },
+            };
+        }
+        try {
+            await this.ensureProcess();
+            return { success: true };
+        }
+        catch (error) {
+            const details = error instanceof Error
+                ? { message: error.message }
+                : error;
+            return { success: false, details };
+        }
+    }
     async menuButton() { throw unsupported("menuButton"); }
     async debugregRead() { throw unsupported("debugregRead"); }
     async debugregWrite(_v) { throw unsupported("debugregWrite"); }
@@ -775,9 +831,59 @@ function resolveViceBinary(options, findBinary = which) {
     }
     return findBinary("x64sc") ?? findBinary("x64") ?? "x64sc";
 }
+function resolveViceLaunch(options, dependencies = {}) {
+    const findBinary = dependencies.findBinary ?? which;
+    const isResourceDirectory = dependencies.isResourceDirectory ?? isViceResourceDirectory;
+    const explicitBinary = firstDefined(options.envBinary, options.configBinary);
+    const explicitDirectory = firstDefined(resolveViceDirectoryWithValidator(options.envDirectory, isResourceDirectory), resolveViceDirectoryWithValidator(options.configDirectory, isResourceDirectory));
+    let binary = resolveViceBinary({ envBinary: options.envBinary, configBinary: options.configBinary }, findBinary);
+    if (explicitDirectory) {
+        return { binary, directory: explicitDirectory };
+    }
+    const adjacentDirectory = findViceResourceDirectory(binary, {
+        allowGlobalFallback: false,
+        isResourceDirectory,
+    });
+    if (adjacentDirectory) {
+        return { binary, directory: adjacentDirectory };
+    }
+    if (explicitBinary) {
+        return {
+            binary,
+            directory: findViceResourceDirectory(binary, {
+                allowGlobalFallback: true,
+                isResourceDirectory,
+            }),
+        };
+    }
+    return {
+        binary,
+        directory: findViceResourceDirectory(binary, {
+            allowGlobalFallback: true,
+            isResourceDirectory,
+        }),
+    };
+}
+function buildManagedViceProcessOptions(input) {
+    return {
+        binary: input.binary,
+        directory: input.directory,
+        host: input.host,
+        port: input.port,
+        warp: input.warp,
+        visible: input.visible,
+        extraArgs: input.extraArgs.length > 0 ? input.extraArgs : undefined,
+    };
+}
 export function __resolveViceBinaryForTests(options, findBinary) {
     return resolveViceBinary(options, findBinary ?? which);
 }
+export function __resolveViceLaunchForTests(options, dependencies) {
+    return resolveViceLaunch(options, dependencies);
+}
+export function __buildViceProcessOptionsForTests(input) {
+    return buildManagedViceProcessOptions(input);
+}
 export async function createFacade(logger, options) {
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {
@@ -935,7 +1041,15 @@ function resolveViceDirectory(value) {
     }
     return isViceResourceDirectory(input) ? input : undefined;
 }
-function findViceResourceDirectory(binaryPath) {
+function resolveViceDirectoryWithValidator(value, isResourceDirectory) {
+    const input = configuredString(value);
+    if (!input) {
+        return undefined;
+    }
+    return isResourceDirectory(input) ? input : undefined;
+}
+function findViceResourceDirectory(binaryPath, options = {}) {
+    const isResourceDirectory = options.isResourceDirectory ?? isViceResourceDirectory;
     const candidates = new Set();
     const resolvedBinary = configuredString(binaryPath);
     if (resolvedBinary) {
@@ -943,12 +1057,14 @@ function findViceResourceDirectory(binaryPath) {
         candidates.add(path.resolve(binaryDir, "..", "share", "vice"));
         candidates.add(path.resolve(binaryDir, "..", "..", "share", "vice"));
     }
-    candidates.add("/usr/local/share/vice");
-    candidates.add("/usr/share/vice");
-    candidates.add("/opt/homebrew/share/vice");
-    candidates.add("/opt/local/share/vice");
+    if (options.allowGlobalFallback !== false) {
+        candidates.add("/usr/local/share/vice");
+        candidates.add("/usr/share/vice");
+        candidates.add("/opt/homebrew/share/vice");
+        candidates.add("/opt/local/share/vice");
+    }
     for (const candidate of candidates) {
-        if (isViceResourceDirectory(candidate)) {
+        if (isResourceDirectory(candidate)) {
             return candidate;
         }
     }

package/dist/mcp-server.js

@@ -8,6 +8,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import { loadConfig } from "./config.js";
 import { C64Client } from "./c64Client.js";
 import { listKnowledgeResources, readKnowledgeResource, } from "./rag/knowledgeIndex.js";
+import { PLATFORM_RESOURCE_URI } from "./rag/resourceUris.js";
 import { createLazyRagRetriever, initRag } from "./rag/init.js";
 import { getMcpServerImplementationInfo } from "./mcp/metadata.js";
 import { toolRegistry } from "./tools/registry/index.js";
@@ -417,7 +418,6 @@ async function main() {
         diagnosticsFile: diagnostics.filePath,
     });
 }
-const PLATFORM_RESOURCE_URI = "c64://platform/status";
 function createPlatformResourceDescriptor() {
     return {
         uri: PLATFORM_RESOURCE_URI,

package/dist/prompts/registry.js

@@ -1,4 +1,5 @@
 import { listKnowledgeResources } from "../rag/knowledgeIndex.js";
+import { RESOURCE_URIS } from "../rag/resourceUris.js";
 import { toolRegistry } from "../tools/registry/index.js";
 const ASSEMBLY_HARDWARE_NOTES = {
     sid: [
@@ -34,6 +35,7 @@ const ROUTING_CORE_SEGMENT = {
     content: [
         "Prompts in this repository define intent and routing only.",
         "Execution logic, validation steps, and safety rules live exclusively in `.github/skills/*/SKILL.md`.",
+        `When the request targets the \`vice\` backend, read \`${RESOURCE_URIS.vice.binaryMonitorSpec}\` before executing the skill so Binary Monitor single-client behaviour, trap/resume semantics, and monitor-side side effects stay in scope.`,
         "Use the referenced skill, extract missing inputs from the user request, execute the skill, and summarize the outcome.",
     ].join("\n"),
 };
@@ -115,7 +117,7 @@ export function createPromptRegistry() {
                 name: "hello-world",
                 title: "Hello World Workflow",
                 description: "Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://context/fast-paths", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.fastPaths, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_program"],
                 tags: ["hello", "demo", "greeting", "smoke-test"],
@@ -134,8 +136,8 @@ export function createPromptRegistry() {
                 name: "basic-program",
                 title: "BASIC Program Workflow",
                 description: "Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill.",
-                requiredResources: ["c64://specs/basic", "c64://context/bootstrap", "c64://docs/index"],
-                optionalResources: ["c64://context/fast-paths"],
+                requiredResources: [RESOURCE_URIS.basic.spec, RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.index],
+                optionalResources: [RESOURCE_URIS.guide.fastPaths],
                 tools: ["c64_program", "c64_memory"],
                 tags: ["basic", "program"],
             },
@@ -150,7 +152,7 @@ export function createPromptRegistry() {
                 name: "cross-platform-demo",
                 title: "Cross-Platform Demo Workflow",
                 description: "Route quick visible demo requests to the cross-platform demo skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://context/fast-paths", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.fastPaths, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_program"],
                 tags: ["demo", "platform", "greeting"],
@@ -166,8 +168,8 @@ export function createPromptRegistry() {
                 name: "preset-music-demo",
                 title: "Preset Music Demo Workflow",
                 description: "Route quick recognizable tune requests to the SID music skill.",
-                requiredResources: ["c64://specs/sid", "c64://specs/sidwave", "c64://context/fast-paths"],
-                optionalResources: ["c64://docs/sid/best-practices"],
+                requiredResources: [RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.sound.sidwave.spec, RESOURCE_URIS.guide.fastPaths],
+                optionalResources: [RESOURCE_URIS.sound.sid.bestPractices],
                 tools: ["c64_sound"],
                 tags: ["sid", "music", "demo"],
             },
@@ -181,8 +183,8 @@ export function createPromptRegistry() {
                 name: "assembly-program",
                 title: "Assembly Program Workflow",
                 description: "Route 6502/6510 routine requests to the canonical assembly skill.",
-                requiredResources: ["c64://specs/assembly", "c64://specs/vic", "c64://specs/sid", "c64://context/bootstrap"],
-                optionalResources: ["c64://docs/sid/best-practices"],
+                requiredResources: [RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.guide.bootstrap],
+                optionalResources: [RESOURCE_URIS.sound.sid.bestPractices],
                 tools: ["c64_program", "c64_memory"],
                 tags: ["assembly", "program"],
             },
@@ -201,7 +203,7 @@ export function createPromptRegistry() {
             selectOptionalResources: (args) => {
                 const hardware = args.hardware;
                 return hardware === "sid" || hardware === "multi"
-                    ? ["c64://docs/sid/best-practices"]
+                    ? [RESOURCE_URIS.sound.sid.bestPractices]
                     : [];
             },
             renderRoutingNotes: (args) => {
@@ -220,12 +222,12 @@ export function createPromptRegistry() {
                 title: "SID Composition Workflow",
                 description: "Route SID playback and composition work to the canonical SID skill.",
                 requiredResources: [
-                    "c64://specs/sid",
-                    "c64://specs/sidwave",
-                    "c64://docs/sid/file-structure",
-                    "c64://docs/sid/best-practices",
+                    RESOURCE_URIS.sound.sid.spec,
+                    RESOURCE_URIS.sound.sidwave.spec,
+                    RESOURCE_URIS.sound.sid.fileFormat,
+                    RESOURCE_URIS.sound.sid.bestPractices,
                 ],
-                optionalResources: ["c64://context/fast-paths"],
+                optionalResources: [RESOURCE_URIS.guide.fastPaths],
                 tools: ["c64_sound"],
                 tags: ["sid", "music"],
             },
@@ -239,8 +241,8 @@ export function createPromptRegistry() {
                 name: "graphics-demo",
                 title: "Graphics Demo Workflow",
                 description: "Route graphics requests to the canonical graphics skill.",
-                requiredResources: ["c64://specs/vic", "c64://context/bootstrap"],
-                optionalResources: ["c64://specs/assembly", "c64://specs/charset", "c64://docs/petscii-style"],
+                requiredResources: [RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.guide.bootstrap],
+                optionalResources: [RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.graphics.characterSet, RESOURCE_URIS.graphics.petscii.styleGuide],
                 tools: ["c64_program", "c64_memory", "c64_graphics"],
                 tags: ["graphics", "vic"],
             },
@@ -271,12 +273,12 @@ export function createPromptRegistry() {
                 name: "printer-job",
                 title: "Printer Job Workflow",
                 description: "Route printer work to the canonical printer skill.",
-                requiredResources: ["c64://specs/printer", "c64://docs/printer/guide", "c64://docs/printer/prompts"],
+                requiredResources: [RESOURCE_URIS.printer.spec, RESOURCE_URIS.printer.promptGuide],
                 optionalResources: [
-                    "c64://docs/printer/commodore-text",
-                    "c64://docs/printer/commodore-bitmap",
-                    "c64://docs/printer/epson-text",
-                    "c64://docs/printer/epson-bitmap",
+                    RESOURCE_URIS.printer.commodore.text,
+                    RESOURCE_URIS.printer.commodore.bitmap,
+                    RESOURCE_URIS.printer.epson.text,
+                    RESOURCE_URIS.printer.epson.bitmap,
                 ],
                 tools: ["c64_printer"],
                 tags: ["printer"],
@@ -296,10 +298,10 @@ export function createPromptRegistry() {
             selectOptionalResources: (args) => {
                 const printerType = args.printerType;
                 if (printerType === "commodore") {
-                    return ["c64://docs/printer/commodore-text", "c64://docs/printer/commodore-bitmap"];
+                    return [RESOURCE_URIS.printer.commodore.text, RESOURCE_URIS.printer.commodore.bitmap];
                 }
                 if (printerType === "epson") {
-                    return ["c64://docs/printer/epson-text", "c64://docs/printer/epson-bitmap"];
+                    return [RESOURCE_URIS.printer.epson.text, RESOURCE_URIS.printer.epson.bitmap];
                 }
                 return [];
             },
@@ -315,7 +317,7 @@ export function createPromptRegistry() {
                 name: "memory-debug",
                 title: "Memory Debug Workflow",
                 description: "Route reversible memory inspection or patching work to the canonical memory skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_memory", "c64_system"],
                 tags: ["memory", "debug"],
@@ -330,7 +332,7 @@ export function createPromptRegistry() {
                 name: "drive-manager",
                 title: "Drive Manager Workflow",
                 description: "Route disk-image and drive-state requests to the canonical drive skill.",
-                requiredResources: ["c64://context/bootstrap"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap],
                 optionalResources: [],
                 tools: ["c64_disk", "c64_drive"],
                 tags: ["drive", "storage"],

package/dist/rag/indexer.js

@@ -474,20 +474,30 @@ export async function buildAllIndexes({ model, embeddingsDir: overrideDir, basic
     repoMetadataCache.clear();
     const embeddingsDir = resolveEmbeddingsDir(overrideDir);
     const paths = embeddingIndexPaths(embeddingsDir);
-    // Collect all markdown files under doc/ recursively, plus any explicitly provided RAG_DOC_FILES
+    // Production indexing defaults to the repo docs tree. Tests and other callers can
+    // override that set explicitly, including passing an empty array to opt out.
     const docCandidates = [];
-    try {
-        const mdFiles = await collectFiles(DOC_ROOT, [".md"]);
-        for (const f of mdFiles) {
+    if (docFiles !== undefined) {
+        for (const f of docFiles) {
             if (!shouldExcludeDocFile(f)) {
                 docCandidates.push(f);
             }
         }
     }
-    catch { }
-    for (const f of ENV_DOC_FILES) {
-        if (!shouldExcludeDocFile(f)) {
-            docCandidates.push(f);
+    else {
+        try {
+            const mdFiles = await collectFiles(DOC_ROOT, [".md"]);
+            for (const f of mdFiles) {
+                if (!shouldExcludeDocFile(f)) {
+                    docCandidates.push(f);
+                }
+            }
+        }
+        catch { }
+        for (const f of ENV_DOC_FILES) {
+            if (!shouldExcludeDocFile(f)) {
+                docCandidates.push(f);
+            }
         }
     }
     // De-duplicate