c64bridge 0.8.0 → 0.9.0

package/dist/tools/registry/disk.js

@@ -252,7 +252,7 @@ export const diskModuleGroup = defineToolModule({
     domain: "storage",
     summary: "Grouped disk image management, mounting, and discovery tools.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["drive-management"],
     defaultTags: ["storage", "drive"],
     workflowHints: [

package/dist/tools/registry/drive.js

@@ -34,7 +34,7 @@ export const driveModuleGroup = defineToolModule({
     domain: "drive",
     summary: "Grouped drive power, reset, ROM, and mode helpers.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     defaultTags: ["drive", "hardware"],
     workflowHints: [
         "State the resulting power/mode/ROM so the user can reconcile IEC behaviour.",

package/dist/tools/registry/extract.js

@@ -33,7 +33,7 @@ const extractOperationHandlers = createOperationHandlers(extractOperations);
 export const extractModule = defineToolModule({
     domain: "extract",
     summary: "Grouped extraction helpers for sprites, charsets, memory dumps, and diagnostics.",
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     defaultTags: ["extract", "diagnostics"],
     workflowHints: [
         "Pause the machine when advised so dumps and sprite scans remain stable.",

package/dist/tools/registry/graphics.js

@@ -110,7 +110,7 @@ const graphicsOperationHandlers = createOperationHandlers(graphicsOperations);
 export const graphicsModuleGroup = defineToolModule({
     domain: "graphics",
     summary: "Grouped frame capture and graphics rendering helpers.",
-    resources: ["c64://specs/vic", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://graphics/vic/spec", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["graphics-demo", "basic-program", "assembly-program"],
     defaultTags: ["graphics", "vic"],
     workflowHints: [

package/dist/tools/registry/memory.js

@@ -31,7 +31,7 @@ export const memoryModuleGroup = defineToolModule({
     domain: "memory",
     summary: "Grouped memory, screen, and polling operations.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],
     workflowHints: [

package/dist/tools/registry/platform.js

@@ -92,7 +92,7 @@ export const platformModuleGroup = defineToolModule({
     domain: "platform",
     summary: "Runtime backend selection and platform-status coordination.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://platform/status", "c64://context/bootstrap"],
+    resources: ["c64://platform/status", "c64://guide/bootstrap"],
     prompts: [],
     defaultTags: ["platform", "backend", "grouped"],
     workflowHints: [

package/dist/tools/registry/printer.js

@@ -117,7 +117,7 @@ function invokePrintTool(toolName, rawArgs, ctx) {
 export const printerModuleGroup = defineToolModule({
     domain: "printer",
     summary: "Grouped printer text, bitmap, and character definition helpers.",
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     defaultTags: ["printer", "device"],
     workflowHints: [
         "Mention device/secondary addresses so the user knows which printer workflow ran.",

package/dist/tools/registry/program.js

@@ -50,7 +50,7 @@ const programOperationHandlers = createOperationHandlers(programOperations);
 export const programModule = defineToolModule({
     domain: "programs",
     summary: "Grouped program upload, run, and orchestration workflows.",
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["programs", "execution"],
     workflowHints: [

package/dist/tools/registry/rag.js

@@ -18,7 +18,7 @@ const ragOperationHandlers = createOperationHandlers(ragOperations);
 export const ragModuleGroup = defineToolModule({
     domain: "rag",
     summary: "Grouped retrieval helpers for BASIC and assembly references.",
-    resources: ["c64://specs/basic", "c64://specs/assembly", "c64://context/bootstrap"],
+    resources: ["c64://basic/spec", "c64://assembly/6510-spec", "c64://guide/bootstrap"],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["rag", "search"],
     workflowHints: [

package/dist/tools/registry/sound.js

@@ -140,7 +140,7 @@ export const soundModuleGroup = defineToolModule({
     domain: "audio",
     summary: "Grouped SID control, playback, composition, and analysis operations.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://specs/sid", "c64://specs/sidwave", "c64://docs/sid/file-structure"],
+    resources: ["c64://sound/sid/spec", "c64://sound/sidwave/spec", "c64://sound/sid/file-format"],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
     workflowHints: [

package/dist/tools/registry/stream.js

@@ -18,7 +18,7 @@ const streamOperationHandlers = createOperationHandlers(streamOperations);
 export const streamModule = defineToolModule({
     domain: "stream",
     summary: "Grouped streaming helpers for starting and stopping Ultimate capture sessions.",
-    resources: ["c64://docs/index", "c64://specs/sid"],
+    resources: ["c64://guide/index", "c64://sound/sid/spec"],
     prompts: ["sid-music"],
     defaultTags: ["stream", "monitor"],
     workflowHints: [

package/dist/tools/registry/system.js

@@ -66,7 +66,7 @@ export const systemModuleGroup = defineToolModule({
     domain: "system",
     summary: "Grouped machine control and background task orchestration.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["system", "control"],
     workflowHints: [

package/dist/tools/storage.js

@@ -144,7 +144,7 @@ export const storageModule = defineToolModule({
     domain: "storage",
     summary: "Drive management, disk image creation, and file inspection utilities.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["drive", "storage"],
     workflowHints: [
@@ -154,10 +154,10 @@ export const storageModule = defineToolModule({
     tools: [
         {
             name: "drives_list",
-            description: "List Ultimate drive slots and their currently mounted images. Read c64://context/bootstrap for drive safety.",
+            description: "List Ultimate drive slots and their currently mounted images. Read c64://guide/bootstrap for drive safety.",
             summary: "Fetches firmware drive status including mounted images, power state, and modes.",
             inputSchema: drivesListArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "status"],
             prerequisites: [],
             examples: [
@@ -193,7 +193,7 @@ export const storageModule = defineToolModule({
             description: "Mount a disk image onto a specific Ultimate drive slot.",
             summary: "Validates parameters and instructs the firmware to mount an image with optional type/mode overrides.",
             inputSchema: driveMountArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "mount"],
             prerequisites: ["drives_list"],
             examples: [
@@ -250,7 +250,7 @@ export const storageModule = defineToolModule({
             description: "Remove the currently mounted disk image from an Ultimate drive slot.",
             summary: "Ejects the image and leaves the drive empty without powering it off.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "unmount"],
             prerequisites: ["drives_list"],
             examples: [
@@ -292,7 +292,7 @@ export const storageModule = defineToolModule({
             description: "Reset the selected Ultimate drive slot.",
             summary: "Issues a IEC reset for the chosen drive without cycling the entire machine.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "reset"],
             prerequisites: ["drives_list"],
             examples: [
@@ -334,7 +334,7 @@ export const storageModule = defineToolModule({
             description: "Power on a specific Ultimate drive slot.",
             summary: "Ensures the selected drive is reported as powered and ready on the IEC bus.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "power"],
             prerequisites: ["drives_list"],
             examples: [
@@ -377,7 +377,7 @@ export const storageModule = defineToolModule({
             description: "Power off a specific Ultimate drive slot.",
             summary: "Disables the drive without altering mounted media so it can be re-enabled later.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "power"],
             prerequisites: ["drives_list"],
             examples: [
@@ -420,7 +420,7 @@ export const storageModule = defineToolModule({
             description: "Temporarily load a custom ROM into an Ultimate drive slot.",
             summary: "Points the drive at an alternative ROM file without flashing permanent storage.",
             inputSchema: driveLoadRomArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "rom"],
             prerequisites: ["drives_list"],
             examples: [
@@ -463,7 +463,7 @@ export const storageModule = defineToolModule({
             description: "Set the emulation mode for an Ultimate drive slot (1541/1571/1581).",
             summary: "Switches the drive hardware profile to match the mounted media and desired behaviour.",
             inputSchema: driveModeArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "mode"],
             prerequisites: ["drives_list"],
             examples: [
@@ -506,7 +506,7 @@ export const storageModule = defineToolModule({
             description: "Inspect metadata for a file on the Ultimate filesystem.",
             summary: "Queries the REST API for file size, type, and other details useful when managing disk images.",
             inputSchema: fileInfoArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["storage", "info"],
             prerequisites: [],
             examples: [
@@ -543,7 +543,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D64 disk image on the Ultimate filesystem.",
             summary: "Allocates a 35 or 40 track D64 image with an optional disk name.",
             inputSchema: createD64ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -594,7 +594,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D71 disk image on the Ultimate filesystem.",
             summary: "Allocates a 1571-compatible disk image with optional labelling.",
             inputSchema: createD71ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -642,7 +642,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D81 disk image on the Ultimate filesystem.",
             summary: "Allocates a 1581-compatible disk image with optional labelling.",
             inputSchema: createD81ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -690,7 +690,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank DNP disk image on the Ultimate filesystem.",
             summary: "Allocates a CMD-native DNP image with custom track count and optional label.",
             inputSchema: createDnpArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: [
                 "drives_list"

package/dist/tools/streaming.js

@@ -36,8 +36,8 @@ export const streamingModule = defineToolModule({
     domain: "streaming",
     summary: "Long-running or streaming workflows such as audio capture or SID playback monitoring.",
     resources: [
-        "c64://specs/sid",
-        "c64://docs/index",
+        "c64://sound/sid/spec",
+        "c64://guide/index",
     ],
     prompts: ["sid-music"],
     defaultLifecycle: "stream",
@@ -50,7 +50,7 @@ export const streamingModule = defineToolModule({
     tools: [
         {
             name: "stream_start",
-            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://docs/index for usage notes.",
+            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://guide/index for usage notes.",
             summary: "Validates stream arguments and forwards the request to firmware, returning status metadata.",
             inputSchema: streamStartArgsSchema.jsonSchema,
             tags: ["stream", "start"],

package/dist/tools/types.js

@@ -30,13 +30,50 @@ export function discriminatedUnionSchema(options) {
     if (!variants || variants.length === 0) {
         throw new Error("Discriminated union schemas require at least one variant.");
     }
+    // Flatten the discriminated union into a single object schema.
+    // Claude's API does not support oneOf/allOf/anyOf at the top level,
+    // so we merge all variant properties and use an enum for the discriminator.
+    const opValues = [];
+    const mergedProperties = {};
+    const opDescriptions = [];
+    for (const variant of variants) {
+        const variantProps = variant.properties ?? {};
+        const discProp = variantProps[discriminator];
+        const opValue = discProp?.const;
+        if (opValue) {
+            opValues.push(opValue);
+            const variantDesc = variant.description ?? discProp?.description ?? "";
+            if (variantDesc) {
+                opDescriptions.push(`${opValue}: ${variantDesc}`);
+            }
+        }
+        for (const [key, propSchema] of Object.entries(variantProps)) {
+            if (key === discriminator)
+                continue;
+            if (!mergedProperties[key]) {
+                mergedProperties[key] = propSchema;
+            }
+        }
+    }
+    const opPropertySchema = opValues.length > 0
+        ? { type: "string", enum: opValues, description: `Selects the operation.` }
+        : { type: "string", description: `Selects the operation.` };
+    const fullDescription = description
+        ? (opDescriptions.length > 0
+            ? `${description}\n\nOperations:\n${opDescriptions.map((d) => `- ${d}`).join("\n")}`
+            : description)
+        : (opDescriptions.length > 0
+            ? `Operations:\n${opDescriptions.map((d) => `- ${d}`).join("\n")}`
+            : undefined);
     const schema = {
         type: "object",
-        ...(description ? { description } : {}),
-        oneOf: [...variants],
-        discriminator: {
-            propertyName: discriminator,
+        ...(fullDescription ? { description: fullDescription } : {}),
+        properties: {
+            [discriminator]: opPropertySchema,
+            ...mergedProperties,
         },
+        required: [discriminator],
+        additionalProperties: false,
     };
     return schema;
 }

package/dist/tools/vice.js

@@ -15,11 +15,8 @@ const SAFE_RESOURCE_PREFIXES = [
 ];
 const resourceValueSchema = {
     jsonSchema: {
+        type: ["string", "integer"],
         description: "VICE resource value (string or integer).",
-        oneOf: [
-            { type: "string" },
-            { type: "integer" },
-        ],
     },
     parse(value, path) {
         const resolvedPath = path ?? "$.value";
@@ -110,7 +107,7 @@ const viceOperationDispatcher = createOperationDispatcher("c64_vice", viceOperat
 export const viceModuleGroup = defineToolModule({
     domain: "vice",
     summary: "VICE emulator helpers for safe runtime resource access.",
-    resources: ["c64://specs/memory-map"],
+    resources: ["c64://memory/map"],
     prompts: ["assembly-program", "memory-debug"],
     defaultTags: ["vice", "emulator"],
     workflowHints: [

package/dist/vice/process.js

@@ -3,10 +3,37 @@ import fs from "node:fs";
 import net from "node:net";
 import { createOutputTailCapture, getDiagnosticsSessionInfo, writeDiagnosticEvent } from "../diagnostics.js";
 const DEFAULT_DISPLAY = ":99";
+function hasDisplayArtifacts(display) {
+    const match = /^:([0-9]+)$/.exec(display.trim());
+    if (!match) {
+        return false;
+    }
+    const displayNumber = match[1];
+    return fs.existsSync(`/tmp/.X11-unix/X${displayNumber}`) || fs.existsSync(`/tmp/.X${displayNumber}-lock`);
+}
+export function resolveXvfbDisplayForLaunch(display) {
+    const explicitDisplay = process.env.VICE_XVFB_DISPLAY?.trim();
+    if (explicitDisplay) {
+        return explicitDisplay;
+    }
+    if (display !== DEFAULT_DISPLAY || !hasDisplayArtifacts(display)) {
+        return display;
+    }
+    const baseDisplay = Number.parseInt(display.slice(1), 10);
+    for (let candidate = baseDisplay + 1; candidate < baseDisplay + 100; candidate += 1) {
+        const candidateDisplay = `:${candidate}`;
+        if (!hasDisplayArtifacts(candidateDisplay)) {
+            return candidateDisplay;
+        }
+    }
+    return display;
+}
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function hasGraphicalSession() {
+    if (process.platform === "darwin" || process.platform === "win32")
+        return true;
     return configuredDisplay() !== undefined || configuredWaylandDisplay() !== undefined;
 }
 function configuredDisplay() {
@@ -64,6 +91,53 @@ export async function waitForPort(host, port, timeoutMs = 4000) {
     }
     throw new Error(`Timeout waiting for VICE monitor at ${host}:${port}`);
 }
+async function sendResumeMonitorCommand(host, port, timeoutMs = 1500) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            await new Promise((resolve, reject) => {
+                const socket = net.connect({ host, port });
+                const cleanup = () => {
+                    socket.removeAllListeners();
+                    socket.destroy();
+                };
+                const packet = Buffer.alloc(11);
+                packet[0] = 0x02;
+                packet[1] = 0x02;
+                packet.writeUInt32LE(0, 2);
+                packet.writeUInt32LE(1, 6);
+                packet[10] = 0xaa;
+                socket.setTimeout(500, () => {
+                    cleanup();
+                    reject(new Error(`Timed out sending VICE monitor resume command to ${host}:${port}`));
+                });
+                socket.once("error", (error) => {
+                    cleanup();
+                    reject(error);
+                });
+                socket.once("connect", () => {
+                    socket.write(packet, (error) => {
+                        cleanup();
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                });
+            });
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            await delay(50);
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Failed to resume VICE monitor at ${host}:${port}`);
+}
 async function waitForXvfb(display, timeoutMs = 5000) {
     const match = /^:([0-9]+)/.exec(display.trim());
     if (!match) {
@@ -113,7 +187,8 @@ export async function terminateProcess(child, signal = "SIGTERM", timeoutMs = 10
 }
 export async function startViceProcess(options) {
     const debugEnabled = process.env.VICE_DEVICE_TEST_DEBUG === "1";
-    const { useXvfb, display } = shouldUseXvfb(options.visible);
+    const { useXvfb, display: requestedDisplay } = shouldUseXvfb(options.visible);
+    const display = useXvfb ? resolveXvfbDisplayForLaunch(requestedDisplay) : requestedDisplay;
     const viceEnv = { ...process.env };
     let xvfb = null;
     const xvfbOutput = createOutputTailCapture("xvfb");
@@ -157,6 +232,7 @@ export async function startViceProcess(options) {
         });
         viceEnv.DISPLAY = display;
         await waitForXvfb(display);
+        await delay(300);
     }
     const args = [
         "-binarymonitor",
@@ -216,7 +292,8 @@ export async function startViceProcess(options) {
             child.once("exit", onExit);
             child.once("error", onError);
             waitForPort(options.host, options.port)
-                .then(() => {
+                .then(async () => {
+                await sendResumeMonitorCommand(options.host, options.port);
                 if (debugEnabled) {
                     console.error("[vice-process] monitor port is ready", { host: options.host, port: options.port });
                 }

package/dist/vice/readiness.js

@@ -30,6 +30,41 @@ export async function waitForScreenPattern(bm, pattern, timeoutMs, tickMs = 50,
     await exitMonitorIfNeeded(bm);
     return idx;
 }
+export async function waitForStableScreenPattern(bm, pattern, timeoutMs, tickMs = 50, stableReads = 2, onRead, between) {
+    const requiredStableReads = Math.max(1, stableReads);
+    const start = nowNs();
+    let idx = -1;
+    let stableIdx = -1;
+    let consecutiveMatches = 0;
+    while (msSince(start) < timeoutMs) {
+        const t = nowNs();
+        const screen = await bm.memGet(0x0400, 0x0400 + 999);
+        onRead?.("bm_read_screen", t);
+        idx = screen.indexOf(pattern);
+        if (idx >= 0) {
+            if (idx === stableIdx) {
+                consecutiveMatches += 1;
+            }
+            else {
+                stableIdx = idx;
+                consecutiveMatches = 1;
+            }
+            if (consecutiveMatches >= requiredStableReads) {
+                break;
+            }
+        }
+        else {
+            stableIdx = -1;
+            consecutiveMatches = 0;
+        }
+        await exitMonitorIfNeeded(bm);
+        if (between)
+            await between();
+        await new Promise((r) => setTimeout(r, Math.max(1, tickMs)));
+    }
+    await exitMonitorIfNeeded(bm);
+    return consecutiveMatches >= requiredStableReads ? idx : -1;
+}
 /** Wait until any non-blank (non-0x00/0x20) character appears on the text screen. */
 export async function waitForAnyScreenText(bm, timeoutMs, tickMs = 50, onRead, between) {
     const start = nowNs();

package/dist/vice/smokeOptions.js

@@ -0,0 +1,44 @@
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+function parseVicePort(value) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        return { configuredPort: 6502, hasExplicitPort: false };
+    }
+    const parsed = Number(normalized);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return { configuredPort: 6502, hasExplicitPort: false };
+    }
+    return { configuredPort: parsed, hasExplicitPort: true };
+}
+export function parseEnvBoolean(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+export function resolveViceSmokeOptions(env = process.env, argv = process.argv.slice(2)) {
+    const visibleDemo = argv.includes("--visible-demo") || parseEnvBoolean(env.VICE_VISIBLE_DEMO) === true;
+    const useMock = String(env.VICE_TEST_TARGET ?? "").trim().toLowerCase() === "mock";
+    const { configuredPort, hasExplicitPort } = parseVicePort(env.VICE_PORT);
+    const visible = visibleDemo || parseEnvBoolean(env.VICE_VISIBLE) === true;
+    const keepOpen = visibleDemo || parseEnvBoolean(env.VICE_KEEP_OPEN) === true;
+    const warpSetting = parseEnvBoolean(env.VICE_WARP);
+    return {
+        useMock,
+        configuredPort,
+        hasExplicitPort,
+        visible,
+        keepOpen,
+        warp: useMock ? true : visibleDemo ? false : warpSetting ?? true,
+        display: env.DISPLAY || ":99",
+        visibleDemo,
+    };
+}

package/dist/viceRunner.js

@@ -65,6 +65,8 @@ function which(binary) {
     return null;
 }
 function shouldUseXvfb() {
+    if (process.platform === "darwin" || process.platform === "win32")
+        return false;
     if (process.env.FORCE_XVFB === "1")
         return true;
     const ciValue = (process.env.CI || "").toLowerCase();

package/doc/developer.md

@@ -119,8 +119,16 @@ Environment knobs: `RAG_EMBEDDINGS_DIR`, `RAG_BUILD_ON_START`, `RAG_REINDEX_INTE
 
 - `./build check` — build + test matrix in one pass
 - `./build changelog` — update CHANGELOG draft
-- `./build release --version <version>` — bump version, regenerate manifest, prepend changelog notes
-- Published package ships [`dist/`](../dist/), [`doc/`](../doc/), [`data/`](../data/), [`scripts/`](../scripts/), [`generated/`](../generated/), and [`mcp.json`](../mcp.json)
+- `./build release --version <version>` — bump version, refresh [`mcp.json`](../mcp.json) and [`server.json`](../server.json), prepend changelog notes
+- Published package ships [`dist/`](../dist/), [`doc/`](../doc/), [`data/`](../data/), [`scripts/`](../scripts/), [`generated/`](../generated/), [`mcp.json`](../mcp.json), and [`server.json`](../server.json)
+
+Tagging a release through the GitHub release UI triggers [`.github/workflows/release.yaml`](../.github/workflows/release.yaml), which publishes the npm package and then publishes the same version to the MCP Registry.
+
+- Required GitHub secret: `NPM_TOKEN`
+- No dedicated MCP Registry secret is required for the GitHub-driven flow; the workflow uses `mcp-publisher login github-oidc`
+- The release workflow must grant `id-token: write` so GitHub Actions can mint the short-lived OIDC token used by `mcp-publisher`
+- Keep [`package.json`](../package.json) `mcpName` aligned with [`server.json`](../server.json) `name`
+- The root [`server.json`](../server.json) is the MCP Registry manifest; [`mcp/server.json`](../mcp/server.json) remains generated MCP interface output
 
 ## 9. Troubleshooting Cheatsheet
 

package/doc/plans/prompts/README.md

@@ -27,13 +27,13 @@ suite can assert expectations in upcoming steps.
 
 | 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. |
+| `basic-program` | `c64://basic/spec`, `c64://guide/bootstrap`, `c64://guide/index` | Reinforce BASIC token rules, PETSCII gotchas, workflow expectations. |
+| `assembly-program` | `c64://assembly/6510-spec`, `c64://guide/bootstrap`, `c64://graphics/vic/spec`, `c64://sound/sid/spec` | Provide opcode tables, IRQ setup, VIC/SID register references. |
+| `sid-music` | `c64://sound/sid/spec`, `c64://sound/sidwave/spec`, `c64://sound/sid/file-format` | Supply register map, SIDWAVE format, SID file metadata. |
+| `graphics-demo` | `c64://graphics/vic/spec`, `c64://guide/bootstrap` | Cover VIC mode bits, raster constraints, general workflow guidance. |
+| `printer-job` | `c64://printer/spec`, `c64://printer/commodore/text`, `c64://printer/prompt-guide` | Document PETSCII vs ESC/P workflows, sample templates, and safety checks. |
+| `memory-debug` | `c64://guide/bootstrap`, `c64://assembly/6510-spec`, `c64://guide/index` | Highlight addressing safeguards, workflow rules, and knowledge map summaries. |
+| `drive-manager` | `c64://guide/bootstrap` | Ensure awareness of system-wide safety rules before altering drives. |
 
 Notes: