c64bridge 0.7.4 → 0.8.1

package/dist/vice/viceClient.js

@@ -1,5 +1,5 @@
 /*
- * Minimal VICE Binary Monitor client with length-aware framing.
+ * VICE Binary Monitor client with debugger, resource, and display helpers.
  */
 import net from "node:net";
 export class ViceClient {
@@ -7,25 +7,56 @@ export class ViceClient {
         this.buffer = Buffer.alloc(0);
         this.nextReqId = 1;
         this.pending = new Map();
+        this.closing = false;
     }
     async connect(port, host = "127.0.0.1") {
         this.socket = net.connect({ host, port });
+        this.closing = false;
         this.socket.setNoDelay(true);
         await new Promise((resolve, reject) => {
-            this.socket.once("connect", () => resolve());
-            this.socket.once("error", reject);
+            const onConnect = () => {
+                this.socket.off("error", onError);
+                resolve();
+            };
+            const onError = (error) => {
+                this.socket.off("connect", onConnect);
+                reject(error);
+            };
+            this.socket.once("connect", onConnect);
+            this.socket.once("error", onError);
         });
         this.socket.on("data", (chunk) => this.onData(chunk));
         this.socket.on("error", (err) => {
-            for (const [, p] of this.pending)
-                p.reject(err);
-            this.pending.clear();
+            this.rejectAllPending(err);
         });
+        this.socket.on("close", (hadError) => {
+            if (this.pending.size === 0 || this.closing) {
+                return;
+            }
+            const reason = hadError ? new Error("VICE monitor connection closed due to error") : new Error("VICE monitor connection closed");
+            this.rejectAllPending(reason);
+        });
+    }
+    close() {
+        const reason = new Error("VICE monitor connection closed");
+        try {
+            this.closing = true;
+            this.rejectAllPending(reason);
+            this.buffer = Buffer.alloc(0);
+            this.socket?.removeAllListeners();
+            this.socket?.destroy();
+        }
+        catch { }
     }
-    close() { try {
-        this.socket?.destroy();
+    rejectAllPending(reason) {
+        for (const [, pending] of this.pending) {
+            try {
+                pending.reject(reason);
+            }
+            catch { }
+        }
+        this.pending.clear();
     }
-    catch { } }
     onData(chunk) {
         const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         this.buffer = Buffer.concat([this.buffer, data]);
@@ -42,21 +73,33 @@ export class ViceClient {
                 return;
             const frame = this.buffer.subarray(0, total);
             this.buffer = this.buffer.subarray(total);
-            const respType = frame[6];
+            const responseType = frame[6];
             const err = frame[7];
             const reqId = frame.readUInt32LE(8);
-            if (reqId === 0xffffffff)
-                continue; // unsolicited event — ignore
+            if (reqId === 0xffffffff) {
+                continue; // unsolicited event
+            }
             const pending = this.pending.get(reqId);
-            if (!pending)
+            if (!pending) {
                 continue;
+            }
             if (err !== 0x00) {
                 pending.reject(new Error(`BM error 0x${err.toString(16)}`));
                 this.pending.delete(reqId);
                 continue;
             }
-            if (pending.cmd !== respType) {
-                pending.reject(new Error(`BM mismatched response: expected 0x${pending.cmd.toString(16)} got 0x${respType.toString(16)}`));
+            if (pending.cmd !== responseType) {
+                if (pending.onFrame) {
+                    try {
+                        pending.onFrame(responseType, frame);
+                    }
+                    catch (error) {
+                        pending.reject(error);
+                        this.pending.delete(reqId);
+                    }
+                    continue;
+                }
+                pending.reject(new Error(`BM mismatched response: expected 0x${pending.cmd.toString(16)} got 0x${responseType.toString(16)}`));
                 this.pending.delete(reqId);
                 continue;
             }
@@ -64,19 +107,30 @@ export class ViceClient {
             this.pending.delete(reqId);
         }
     }
-    send(cmd, body) {
+    send(cmd, body, options) {
+        if (!this.socket || this.socket.destroyed) {
+            return Promise.reject(new Error("VICE monitor socket is not connected"));
+        }
         const reqId = this.nextReqId++;
-        const b = body ?? Buffer.alloc(0);
-        const header = Buffer.alloc(2 + 4 + 4 + 1);
+        const payload = body ?? Buffer.alloc(0);
+        const header = Buffer.alloc(11);
         header[0] = 0x02; // STX
         header[1] = 0x02; // API v2
-        header.writeUInt32LE(b.length, 2);
+        header.writeUInt32LE(payload.length, 2);
         header.writeUInt32LE(reqId, 6);
         header[10] = cmd;
-        const packet = Buffer.concat([header, b]);
-        const p = new Promise((resolve, reject) => this.pending.set(reqId, { cmd, resolve, reject }));
+        const packet = Buffer.concat([header, payload]);
+        const expectedCmd = options?.responseType ?? cmd;
+        const promise = new Promise((resolve, reject) => {
+            this.pending.set(reqId, {
+                cmd: expectedCmd,
+                resolve,
+                reject,
+                onFrame: options?.onFrame,
+            });
+        });
         this.socket.write(packet);
-        return p;
+        return promise;
     }
     async info() { await this.send(0x85); }
     async resetSoft() { await this.send(0xCC, Buffer.from([0x00])); }
@@ -120,4 +174,310 @@ export class ViceClient {
         const body = Buffer.concat([Buffer.from([bytes.length & 0xff]), bytes]);
         await this.send(0x72, body);
     }
+    async checkpointGet(id) {
+        const body = Buffer.alloc(4);
+        body.writeUInt32LE(id >>> 0, 0);
+        const frame = await this.send(0x11, body, { responseType: 0x11 });
+        return this.parseCheckpoint(frame);
+    }
+    async checkpointCreate(options) {
+        const start = options.start & 0xffff;
+        const end = (options.end ?? options.start) & 0xffff;
+        const stop = options.stopOnHit !== false;
+        const enabled = options.enabled !== false;
+        const ops = options.operations ?? { execute: true };
+        const mask = (ops.load ? 0x01 : 0) | (ops.store ? 0x02 : 0) | (ops.execute === false ? 0 : 0x04);
+        const temporary = options.temporary === true;
+        const memspace = options.memspace ?? 0;
+        const hasMemspace = options.memspace !== undefined;
+        const body = Buffer.alloc(hasMemspace ? 9 : 8);
+        body.writeUInt16LE(start, 0);
+        body.writeUInt16LE(end, 2);
+        body[4] = stop ? 1 : 0;
+        body[5] = enabled ? 1 : 0;
+        body[6] = mask;
+        body[7] = temporary ? 1 : 0;
+        if (hasMemspace) {
+            body[8] = memspace & 0xff;
+        }
+        const frame = await this.send(0x12, body, { responseType: 0x11 });
+        return this.parseCheckpoint(frame);
+    }
+    async checkpointDelete(id) {
+        const body = Buffer.alloc(4);
+        body.writeUInt32LE(id >>> 0, 0);
+        await this.send(0x13, body);
+    }
+    async checkpointToggle(id, enabled) {
+        const body = Buffer.alloc(5);
+        body.writeUInt32LE(id >>> 0, 0);
+        body[4] = enabled ? 1 : 0;
+        await this.send(0x15, body);
+    }
+    async checkpointSetCondition(id, expression) {
+        const expr = Buffer.from(expression ?? "", "utf8");
+        if (expr.length > 255) {
+            throw new Error("Condition expressions are limited to 255 bytes");
+        }
+        const body = Buffer.alloc(5 + expr.length);
+        body.writeUInt32LE(id >>> 0, 0);
+        body[4] = expr.length & 0xff;
+        expr.copy(body, 5);
+        await this.send(0x22, body);
+    }
+    async checkpointList() {
+        const checkpoints = [];
+        await this.send(0x14, undefined, {
+            responseType: 0x14,
+            onFrame: (type, frame) => {
+                if (type === 0x11) {
+                    checkpoints.push(this.parseCheckpoint(frame));
+                }
+            },
+        });
+        return checkpoints;
+    }
+    async registersAvailable(memspace = 0) {
+        const frame = await this.send(0x83, Buffer.from([memspace & 0xff]), { responseType: 0x83 });
+        return this.parseRegisterInfo(frame);
+    }
+    async registersGet(memspace = 0) {
+        const frame = await this.send(0x31, Buffer.from([memspace & 0xff]), { responseType: 0x31 });
+        return this.parseRegisterValues(frame);
+    }
+    async registersSet(writes, options) {
+        if (!writes || writes.length === 0) {
+            throw new Error("At least one register write must be provided");
+        }
+        const memspace = options?.memspace ?? 0;
+        const metadata = options?.metadata ?? (await this.registersAvailable(memspace));
+        const entries = [];
+        for (const write of writes) {
+            const target = this.resolveRegisterTarget(write, metadata);
+            const value = write.value & 0xffff;
+            const entry = Buffer.alloc(4);
+            entry[0] = 3;
+            entry[1] = target.id & 0xff;
+            entry.writeUInt16LE(value, 2);
+            entries.push(entry);
+        }
+        const header = Buffer.alloc(3);
+        header[0] = memspace & 0xff;
+        header.writeUInt16LE(entries.length & 0xffff, 1);
+        const frame = await this.send(0x32, Buffer.concat([header, ...entries]), { responseType: 0x31 });
+        return this.parseRegisterValues(frame);
+    }
+    async stepInstructions(count = 1, options) {
+        const body = Buffer.alloc(3);
+        body[0] = options?.stepOver ? 1 : 0;
+        body.writeUInt16LE(Math.max(1, Math.min(count, 0xffff)), 1);
+        await this.send(0x71, body);
+    }
+    async stepReturn() {
+        await this.send(0x73);
+    }
+    async displayGet(options) {
+        const alt = options?.alternateCanvas ? 1 : 0;
+        const format = options?.format ?? 0;
+        const frame = await this.send(0x84, Buffer.from([alt & 0xff, format & 0xff]), { responseType: 0x84 });
+        return this.parseDisplay(frame);
+    }
+    async resourceGet(name) {
+        const trimmed = name.trim();
+        if (!trimmed) {
+            throw new Error("Resource name must not be empty");
+        }
+        const nameBytes = Buffer.from(trimmed, "utf8");
+        if (nameBytes.length === 0 || nameBytes.length > 255) {
+            throw new Error("Resource names must be 1-255 bytes");
+        }
+        const body = Buffer.concat([Buffer.from([nameBytes.length & 0xff]), nameBytes]);
+        const frame = await this.send(0x51, body, { responseType: 0x51 });
+        return this.parseResource(frame);
+    }
+    async resourceSet(name, value) {
+        const trimmed = name.trim();
+        if (!trimmed) {
+            throw new Error("Resource name must not be empty");
+        }
+        const nameBytes = Buffer.from(trimmed, "utf8");
+        if (nameBytes.length === 0 || nameBytes.length > 255) {
+            throw new Error("Resource names must be 1-255 bytes");
+        }
+        let body;
+        if (typeof value === "number") {
+            const header = Buffer.from([1, nameBytes.length & 0xff]);
+            const intPayload = Buffer.alloc(4);
+            intPayload.writeInt32LE(value | 0, 0);
+            body = Buffer.concat([header, nameBytes, Buffer.from([4]), intPayload]);
+        }
+        else {
+            const valueBytes = Buffer.from(value, "utf8");
+            if (valueBytes.length > 255) {
+                throw new Error("String resource values are limited to 255 bytes");
+            }
+            const header = Buffer.from([0, nameBytes.length & 0xff]);
+            body = Buffer.concat([header, nameBytes, Buffer.from([valueBytes.length & 0xff]), valueBytes]);
+        }
+        await this.send(0x52, body);
+    }
+    parseCheckpoint(frame) {
+        const body = frame.subarray(12);
+        if (body.length < 23) {
+            throw new Error("Checkpoint response too short");
+        }
+        const id = body.readUInt32LE(0);
+        const hit = body[4] === 1;
+        const start = body.readUInt16LE(5);
+        const end = body.readUInt16LE(7);
+        const stopOnHit = body[9] === 1;
+        const enabled = body[10] === 1;
+        const mask = body[11] ?? 0;
+        const temporary = body[12] === 1;
+        const hitCount = body.readUInt32LE(13);
+        const ignoreCount = body.readUInt32LE(17);
+        const hasCondition = body[21] === 1;
+        const memspace = (body[22] ?? 0) & 0xff;
+        return {
+            id,
+            hit,
+            start,
+            end,
+            stopOnHit,
+            enabled,
+            temporary,
+            operations: {
+                load: (mask & 0x01) !== 0,
+                store: (mask & 0x02) !== 0,
+                execute: (mask & 0x04) !== 0,
+            },
+            hitCount,
+            ignoreCount,
+            hasCondition,
+            memspace: memspace,
+        };
+    }
+    parseRegisterValues(frame) {
+        const body = frame.subarray(12);
+        if (body.length < 2)
+            return [];
+        const count = body.readUInt16LE(0);
+        const values = [];
+        let offset = 2;
+        for (let i = 0; i < count && offset < body.length; i += 1) {
+            const entrySize = body[offset] ?? 0;
+            const entryLength = entrySize + 1;
+            if (entryLength < 3 || offset + entryLength > body.length) {
+                break;
+            }
+            const id = body[offset + 1] ?? 0;
+            const valueBytes = Math.max(0, entryLength - 2);
+            let value = 0;
+            if (valueBytes >= 2) {
+                value = body.readUInt16LE(offset + 2);
+            }
+            else if (valueBytes === 1) {
+                value = body[offset + 2] ?? 0;
+            }
+            values.push({ id, size: Math.max(1, valueBytes), value });
+            offset += entryLength;
+        }
+        return values;
+    }
+    parseRegisterInfo(frame) {
+        const body = frame.subarray(12);
+        if (body.length < 2)
+            return [];
+        const count = body.readUInt16LE(0);
+        const info = [];
+        let offset = 2;
+        for (let i = 0; i < count && offset < body.length; i += 1) {
+            const entrySize = body[offset] ?? 0;
+            const entryLength = entrySize + 1;
+            if (entryLength < 4 || offset + entryLength > body.length) {
+                break;
+            }
+            const id = body[offset + 1] ?? 0;
+            const bits = body[offset + 2] ?? 0;
+            const nameLen = body[offset + 3] ?? 0;
+            const nameStart = offset + 4;
+            const nameEnd = Math.min(nameStart + nameLen, offset + entryLength);
+            const name = body.toString("utf8", nameStart, nameEnd);
+            const size = Math.max(1, Math.ceil(Math.min(bits || 8, 16) / 8));
+            info.push({ id, name, bits, size });
+            offset += entryLength;
+        }
+        return info;
+    }
+    parseDisplay(frame) {
+        const body = frame.subarray(12);
+        if (body.length < 17) {
+            throw new Error("Display response too short");
+        }
+        const infoLength = body.readUInt32LE(0);
+        if (body.length < 4 + infoLength) {
+            throw new Error("Display response length mismatch");
+        }
+        const debugWidth = body.readUInt16LE(4);
+        const debugHeight = body.readUInt16LE(6);
+        const offsetX = body.readUInt16LE(8);
+        const offsetY = body.readUInt16LE(10);
+        const innerWidth = body.readUInt16LE(12);
+        const innerHeight = body.readUInt16LE(14);
+        const bitsPerPixel = body[16] ?? 8;
+        const pixelLength = body.readUInt32LE(17);
+        const pixelStart = 4 + infoLength;
+        if (pixelStart + pixelLength > body.length) {
+            throw new Error("Display pixel buffer truncated");
+        }
+        const pixels = Buffer.from(body.subarray(pixelStart, pixelStart + pixelLength));
+        return {
+            debugWidth,
+            debugHeight,
+            offsetX,
+            offsetY,
+            innerWidth,
+            innerHeight,
+            bitsPerPixel,
+            pixels,
+        };
+    }
+    parseResource(frame) {
+        const body = frame.subarray(12);
+        if (body.length < 2) {
+            throw new Error("Resource response too short");
+        }
+        const type = body[0] ?? 0;
+        const length = body[1] ?? 0;
+        if (type === 0) {
+            const value = body.subarray(2, 2 + length).toString("utf8");
+            return { type: "string", value };
+        }
+        if (type === 1) {
+            if (length < 1 || length > 4) {
+                throw new Error("Unsupported integer resource width");
+            }
+            const temp = Buffer.alloc(4);
+            body.subarray(2, 2 + length).copy(temp, 0);
+            return { type: "int", value: temp.readInt32LE(0) };
+        }
+        throw new Error(`Unsupported resource type 0x${type.toString(16)}`);
+    }
+    resolveRegisterTarget(write, metadata) {
+        if (write.id !== undefined) {
+            const entry = metadata.find((meta) => meta.id === write.id);
+            if (!entry) {
+                throw new Error(`Unknown register id ${write.id}`);
+            }
+            return entry;
+        }
+        if (write.name) {
+            const entry = metadata.find((meta) => meta.name.toLowerCase() === write.name.toLowerCase());
+            if (!entry) {
+                throw new Error(`Unknown register name ${write.name}`);
+            }
+            return entry;
+        }
+        throw new Error("Register write requires id or name");
+    }
 }

package/doc/developer.md

@@ -11,28 +11,52 @@ Focused reference for maintainers and contributors. User-facing setup lives in [
 Install once:
 
 ```bash
+./build install      # install via the project build helper
+# or directly:
 npm install          # reliable everywhere
-# or
 bun install          # faster workflow (respects package-lock)
 ```
 
 ## 2. Core Workflows
 
+Most day-to-day tasks are run through the [`./build`](../build) helper at the project root. It wraps every `npm run` script behind a consistent, self-documented interface.
+
+```bash
+./build --help       # full command reference
+```
+
 | Task | Command |
 | --- | --- |
 | Launch MCP server (TS-aware) | `npm start` |
 | Run TypeScript entry directly | `npm run mcp` (Bun) · `npm run mcp:node` (dist only) |
-| Build + refresh generated docs | `npm run build` |
-| Tests (mock backend) | `npm test` |
-| Tests against hardware | `npm test -- --real [--base-url=http://host]` |
-| Coverage report | `npm run coverage` (emits `coverage/lcov.info`, minimum 90%) |
-| End-to-end smoke (local/npm) | `npm run check:run-local` · `npm run check:run-npm` |
-| Node-only sanity | `npm run check:node-compat` |
-| VICE smoke (readiness + HELLO) | `npm run vice:smoke` |
+| Build + refresh generated docs | `./build build` |
+| Tests (mock backend) | `./build test` |
+| Tests against hardware | `./build test --real [--base-url http://host]` |
+| Full test matrix | `./build test:matrix` |
+| Coverage report | `./build coverage` (merged matrix LCOV in `coverage/lcov.info`) |
+| End-to-end smoke (local/npm) | `./build check:run-local` · `./build check:run-npm` |
+| Node-only sanity | `./build check:node-compat` |
+| VICE smoke (readiness + HELLO) | `./build vice:smoke` |
 
 `scripts/invoke-bun.mjs` automatically delegates npm scripts to Bun when available; stay on the npm variants if Bun is not installed.
 
-Subsequent `npm run build` invocations reuse the incremental cache stored in `dist/.tsbuildinfo`; delete that file (or `dist/`) for a fully clean rebuild when needed.
+### Test Matrix
+
+| Platform | Target | Command | Environment |
+| --- | --- | --- | --- |
+| c64u | mock | `./build test --platform c64u --target mock` | `C64_MODE=c64u C64_TEST_TARGET=mock` |
+| c64u | device | `./build test --platform c64u --target device --base-url http://c64u` | `C64_MODE=c64u C64_TEST_TARGET=real C64_TEST_BASE_URL=http://c64u` |
+| vice | mock | `./build test --platform vice --target mock` | `C64_MODE=vice VICE_TEST_TARGET=mock` |
+| vice | device | `./build test --platform vice --target device` | `C64_MODE=vice VICE_TEST_TARGET=vice` |
+| mixed | aggregate (no real c64u) | `./build test:matrix` | see individual rows |
+
+The runner still accepts legacy flags (`--mock`, `--real`) for c64u workflows, but the explicit matrix keeps cross-platform runs symmetrical.
+
+`./build coverage` executes the same three matrix legs, then merges the resulting LCOV reports while filtering to the same source scope configured in `.c8rc.json`. Use `./build coverage:single --platform <p> --target <t>` for a one-leg Bun report when debugging a local coverage regression.
+
+> **Note**: Only suites that explicitly opt-in touch real hardware. Today that is `test/device.test.mjs` (real VICE via `target=device`) and the "C64Client against real C64" block in `test/c64Client.test.mjs` when `C64_TEST_TARGET=real`; all other tests continue to run against mocks even under a hardware matrix leg.
+
+Subsequent `./build build` invocations reuse the incremental cache stored in `dist/.tsbuildinfo`; delete that file (or `dist/`) for a fully clean rebuild when needed.
 
 ## 3. Repository Layout (Essentials)
 
@@ -52,67 +76,89 @@ Subsequent `npm run build` invocations reuse the incremental cache stored in `di
 
 - **Tools**: Implement under `src/tools/<domain>/`, export from [`src/tools/registry/index.ts`](../src/tools/registry/index.ts). Share helpers via [`src/tools/registry/utils.ts`](../src/tools/registry/utils.ts). Add coverage in [`test/`](../test/).
 - **Prompts**: Author in [`src/prompts/`](../src/prompts/), register via [`src/prompts/registry.ts`](../src/prompts/registry.ts), mirror description updates in [AGENTS.md](../AGENTS.md) and `.github/prompts/`.
-- **REST surface**: Keep [`doc/c64u/c64-openapi.yaml`](c64u/c64-openapi.yaml) current. Regenerate the typed client with `npm run api:generate` when endpoints change.
-- **Docs**: `npm run build` calls [`scripts/update-readme.ts`](../scripts/update-readme.ts); never hand-edit the `<!-- AUTO-GENERATED:MCP-DOCS-* -->` block in the README.
+- **REST surface**: Keep [`doc/c64u/c64-openapi.yaml`](c64u/c64-openapi.yaml) current. Regenerate the typed client with `./build api:generate` when endpoints change.
+- **Docs**: `./build build` calls [`scripts/update-readme.ts`](../scripts/update-readme.ts); never hand-edit the `<!-- AUTO-GENERATED:MCP-DOCS-* -->` block in the README.
 
 ## 5. Configuration & Backends
 
-Resolution order: `C64BRIDGE_CONFIG` → `./.c64bridge.json` → `~/.c64bridge.json` → defaults (`host=c64u`, `port=80`). Supports hardware (`c64u`) and experimental VICE (`vice.exe`). For secured Ultimate firmware, set `c64u.networkPassword` in the config file to send `X-Password` on every REST request.
+Resolution order: `C64BRIDGE_CONFIG` → `./.c64bridge.json` → `~/.c64bridge.json` → defaults (`host=c64u`, `port=80`). Supports hardware (`c64u`) and phase-one VICE. For secured Ultimate firmware, set `c64u.networkPassword` in the config file to send `X-Password` on every REST request.
+
+The authoritative VICE contract lives in [doc/vice/support-matrix.md](vice/support-matrix.md). Treat that file plus the generated README compatibility tables as release-blocking artifacts: if runtime, tests, and docs disagree, the contract is broken.
 
 Key env flags:
 
 - `C64_MODE=c64u|vice` — force backend
 - `LOG_LEVEL=debug` — verbose logging (stderr)
+- `C64BRIDGE_DIAGNOSTICS_DIR=/path` — persistent NDJSON crash and request diagnostics (default: `~/.c64bridge/diagnostics`)
+- `C64BRIDGE_DISABLE_DIAGNOSTICS=1` — disable persistent diagnostics if they interfere with a constrained environment
 - `C64_TEST_TARGET` / `C64_TEST_BASE_URL` — influence test harness
+- `VICE_TEST_TARGET=mock|vice` — test selection for VICE (default: auto-detect real VICE; set `mock` to run against the BM stub during tests)
 
-### VICE smoke test (Binary Monitor)
+Managed VICE launch is currently Linux/X11-oriented. The launcher and smoke workflow assume Unix facilities such as `Xvfb`, `/tmp/.X11-unix`, and `/dev/null`; on other hosts, connect to an already running Binary Monitor endpoint or use the mock backend instead of assuming supervised startup will work.
+
+For MCP stability work, always check the latest file under `~/.c64bridge/diagnostics/` before assuming a VS Code or Copilot crash came from repository logic. The file captures MCP request flow plus VICE/Xvfb stderr tails, which is usually enough to separate a repo fault from an editor or extension-host crash.
+
+Public VICE support excludes mock-only behaviors. If a capability only works in the BM stub or an internal backend experiment, keep it out of grouped tool support tables until it is explicitly promoted in [doc/vice/support-matrix.md](vice/support-matrix.md).
 
 ## 6. RAG Maintenance
 
 - Indices live under [`data/embeddings_*.json`](../data/)
-- Rebuild: `npm run rag:rebuild`
-- Fetch external sources: `npm run rag:fetch` (writes to [`external/`](../external/))
-- Discover sources (experimental): `npm run rag:discover` with `GITHUB_TOKEN`
+- Rebuild: `./build rag:rebuild`
+- Fetch external sources: `./build rag:fetch` (writes to [`external/`](../external/))
+- Discover sources (experimental): `./build rag:discover` with `GITHUB_TOKEN`
 
 Environment knobs: `RAG_EMBEDDINGS_DIR`, `RAG_BUILD_ON_START`, `RAG_REINDEX_INTERVAL_MS`, `RAG_DOC_FILES`.
 
 ## 7. Optional Services
 
-- **HTTP bridge**: Disabled by default; enable with `npm start -- --http [port]` for manual curl experiments. Details in [`doc/troubleshooting-mcp.md`](troubleshooting-mcp.md).
+- **HTTP bridge**: Disabled by default; enable with `npm start -- --http [port]` for manual curl experiments (the MCP server start is not managed by `./build`). Details in [`doc/troubleshooting-mcp.md`](troubleshooting-mcp.md).
 - **Docker image**: [`Dockerfile`](../Dockerfile) builds Ubuntu 24.04 + Node 24 + Bun for reproducible environments.
 - **Audio pipeline**: SID analysis uses [`naudiodon`](https://www.npmjs.com/package/naudiodon); see [`src/audio/`](../src/audio/) and tests like [`test/audioAnalysis.test.mjs`](../test/audioAnalysis.test.mjs).
 
 ## 8. Release & Packaging
 
-- `npm run check` — build + test in one pass (mock backend)
-- `npm run changelog:generate` — update CHANGELOG draft
-- `npm run release:prepare -- <version>` — pre-publish sanity checks
-- Published package ships [`dist/`](../dist/), [`doc/`](../doc/), [`data/`](../data/), [`scripts/`](../scripts/), [`generated/`](../generated/), and [`mcp.json`](../mcp.json)
+- `./build check` — build + test matrix in one pass
+- `./build changelog` — update CHANGELOG draft
+- `./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
 
-- Missing entrypoint? Ensure dev deps are installed or run `npm run build` so [`dist/index.js`](../dist/index.js) exists.
+- Missing entrypoint? Ensure dev deps are installed or run `./build build` so [`dist/index.js`](../dist/index.js) exists.
 - Tool not exposed? Confirm registry wiring (`src/tools/registry/index.ts`) and rebuild.
 - Real-device tests flaky? Verify `C64_TEST_BASE_URL` reachability; replay curl probes while the HTTP bridge is active.
-- Empty RAG answers? Rebuild embeddings (`npm run rag:rebuild`) and confirm `RAG_EMBEDDINGS_DIR` points at committed data.
+- Empty RAG answers? Rebuild embeddings (`./build rag:rebuild`) and confirm `RAG_EMBEDDINGS_DIR` points at committed data.
 - Logs quiet? Remember all server logs emit to stderr to keep stdout dedicated to MCP.
 
 Stay in lockstep with the [README](../README.md) and [`AGENTS.md`](../AGENTS.md) when introducing features so external docs remain accurate.
+
 ### VICE smoke test (Binary Monitor)
 
 Quick sanity that VICE is reachable and BASIC readiness + simple run works end‑to‑end.
 
 ```bash
-npm run vice:smoke
+./build vice:smoke
 ```
 
 Env knobs:
 
-- `VICE_BINARY=/path/to/x64sc` — pick emulator binary
+- `VICE_BINARY=/path/to/x64sc` — pick emulator binary on Unix-like hosts
 - `VICE_VISIBLE=1` — show the VICE window (recommended during dev)
 - `VICE_WARP=0` — disable warp so you can observe visible output
 - `VICE_KEEP_OPEN=1` — keep window open after success
   (The smoke test registers exit/signal handlers and tears down spawned processes; with `VICE_KEEP_OPEN=1` only your visible VICE is left running.)
+- `VICE_TEST_TARGET=mock` — run the smoke test against the BM stub instead of launching VICE (useful on CI or platforms without VICE installed)
+- `FORCE_XVFB=1` — run headless via Xvfb even if a display is detected (default on CI)
+- `DISABLE_XVFB=1` — skip Xvfb and use the current `$DISPLAY` even in headless environments
+- `VICE_XVFB_DISPLAY=:nn` — override the Xvfb display number (defaults to `:99`)
 
 Implementation tip: programmatic shutdown