claws-code 0.8.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "claws-code",
+  "version": "0.8.0",
+  "description": "Claws — Terminal Control Bridge for VS Code. One command to install.",
+  "bin": {
+    "claws-code": "./bin/cli.js",
+    "claws": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "mcp_server.js",
+    "cli.js",
+    "scripts/",
+    ".claude/",
+    "templates/",
+    "rules/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "extension/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neunaha/claws"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "terminal",
+    "orchestration",
+    "ai",
+    "vscode",
+    "mcp"
+  ],
+  "author": "Anish Neunaha",
+  "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "chmod +x bin/cli.js",
+    "test:mcp": "node tests/mcp/worker.test.js",
+    "test:installer": "node --test test/installer-platform.test.js",
+    "test:installer-full": "node --test test/installer.test.js",
+    "test:json-safe": "node --test test/json-safe.test.mjs"
+  }
+}

package/rules/claws-default-behavior.md

@@ -0,0 +1,72 @@
+> **Scope note**: This file is loaded by the ECC plugin's `SessionStart` hook as a system-reminder.
+> It is NOT auto-loaded by stock Claude Code. The canonical imperative rules that every Claude
+> session sees are in the `CLAWS:BEGIN` block injected into `CLAUDE.md` by `scripts/inject-claude-md.js`.
+> This file is a supplement for ECC users — do not rely on it as the sole enforcement layer.
+
+---
+
+# Claws — Terminal Behavior Override
+
+> Auto-installed by Claws. This rule OVERRIDES default terminal behavior.
+
+## MANDATORY: when the user invokes any /claws command, you MUST use Claws terminals
+
+When the user types `/claws-do`, `/claws-go`, or any `/claws-*` command, you are REQUIRED to create visible terminals via the Claws socket. Do NOT fall back to the Bash tool. Do NOT say "this isn't a Claws task." EVERYTHING asked through a /claws command IS a Claws task.
+
+**If MCP tools (claws_list, claws_create, etc.) are available**: use them directly.
+
+**If MCP tools are NOT loaded** (new session, MCP not registered): use raw socket calls via `node -e` with `require('net').createConnection('.claws/claws.sock')`. The socket commands are documented in every /claws-* slash command file.
+
+**If the socket doesn't exist**: tell the user to reload VS Code (Cmd+Shift+P → Developer: Reload Window).
+
+## For all other work (no /claws prefix), use this behavior:
+
+**DO**: run visible work in Claws terminals — builds, tests, deploys, servers, AI workers, refactoring, audits. The user watches it happen live in their VS Code terminal panel.
+
+**DO**: use `claws_worker` when the user asks to "fix", "refactor", "audit", or any complex task. This spawns a Claude Code session with full permissions that the user can watch.
+
+**DO**: spawn parallel terminals for independent tasks. "lint + test + build" = 3 terminals, all running simultaneously.
+
+**DO**: always create wrapped terminals (`wrapped=true`). Always close them when done.
+
+**USE BASH DIRECTLY FOR**: quick lookups — `ls`, `cat`, `git status`, `grep`, file reads. No terminal needed.
+
+## Pattern matching — what the user says → what you do
+
+"run tests" / "run the build" / "lint the code"
+→ `claws_create` wrapped → `claws_send` the command → `claws_read_log` → report → `claws_close`
+
+"run lint, test, and build" / "do these in parallel"
+→ 3x `claws_create` → send all 3 commands → monitor all 3 → close all → aggregate report
+
+"fix the bug" / "refactor this" / "audit the code" / "write tests for X"
+→ `claws_worker` with the mission → monitor via `claws_read_log` → report → close
+
+"start the server" / "watch for crashes"
+→ `claws_create` wrapped → send start command → monitor → restart if crash detected
+
+"spawn a worker" / "launch claude in a terminal"
+→ `claws_worker` — auto-launches Claude Code with `--dangerously-skip-permissions`
+
+"what's running" / "show me the terminals"
+→ `claws_list` → format as dashboard
+
+"clean up" / "close the workers"
+→ `claws_list` → close all worker terminals → confirm
+
+## Terminal naming
+
+Always descriptive: `worker-tests`, `worker-lint`, `build-server`, `ai-refactor`, `deploy-staging`.
+Never generic: `terminal`, `shell`, `worker-1`.
+
+## Cleanup is non-negotiable
+
+Every `claws_create` must have a matching `claws_close`. At the end of any orchestration, run `claws_list` and close anything you own that's still open. Stale terminals are a bug.
+
+## Never headless
+
+When spawning Claude Code in a worker terminal:
+- ALWAYS: `claude --dangerously-skip-permissions` (interactive, visible TUI)
+- NEVER: `claude -p "..."` (headless, invisible)
+
+The user must see every AI worker in their terminal panel.

package/scripts/_helpers/atomic-file.mjs

@@ -0,0 +1,137 @@
+// Rename-pattern atomic file and directory operations.
+// Used by install.sh (M-09 hooks-copy atomicity, M-01 dotfile backup)
+// and json-safe.mjs (mergeIntoFile).
+// Self-contained — no imports from other _helpers/ modules in L0.
+
+import fs from 'fs';
+import path from 'path';
+
+let _nonce = 0;
+function tmpSuffix() {
+  return `${process.pid}-${++_nonce}`;
+}
+
+/**
+ * Write content to filePath atomically via a tmp → rename pattern.
+ * Writes to ${filePath}.claws-tmp.${pid}, fsyncs, then renames over the target.
+ * On POSIX the rename is atomic; on Windows it is best-effort (no atomic rename API).
+ *
+ * @param {string} filePath
+ * @param {string | Buffer} content
+ * @param {{ mode?: number }} [opts]  mode defaults to 0o644
+ */
+export async function writeAtomic(filePath, content, opts = {}) {
+  const mode = opts.mode ?? 0o644;
+  const tmp = `${filePath}.claws-tmp.${tmpSuffix()}`;
+
+  let fd;
+  try {
+    await fs.promises.mkdir(path.dirname(path.resolve(filePath)), { recursive: true });
+    fd = await fs.promises.open(tmp, 'w', mode);
+    await fd.writeFile(content);
+    await fd.sync();
+    await fd.close();
+    fd = null;
+    await fs.promises.rename(tmp, filePath);
+  } catch (err) {
+    if (fd) {
+      try { await fd.close(); } catch { /* ignore */ }
+      fd = null;
+    }
+    try { await fs.promises.unlink(tmp); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+/**
+ * Copy srcDir to destDir atomically via:
+ *   1. Copy srcDir → destDir.claws-tmp.${pid}
+ *   2. Move existing destDir → destDir.claws-old.${ts}
+ *   3. Rename tmp → destDir
+ *   4. Remove the moved-aside old dir
+ *
+ * On failure before step 3, destDir is left untouched (tmp is cleaned up).
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ */
+export async function copyDirAtomic(srcDir, destDir) {
+  const tmp = `${destDir}.claws-tmp.${tmpSuffix()}`;
+  const ts = Date.now();
+
+  // Step 1: copy into tmp
+  try {
+    await fs.promises.rm(tmp, { recursive: true, force: true });
+    await copyDirRecursive(srcDir, tmp);
+  } catch (err) {
+    // Clean up partial tmp — destDir untouched
+    try { await fs.promises.rm(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw err;
+  }
+
+  // Step 2+3: swap atomically — move old aside, rename tmp into place
+  const old = `${destDir}.claws-old.${ts}`;
+  let destExisted = false;
+  try {
+    await fs.promises.access(destDir);
+    destExisted = true;
+  } catch { /* doesn't exist */ }
+
+  try {
+    if (destExisted) {
+      await fs.promises.rename(destDir, old);
+    }
+    await fs.promises.rename(tmp, destDir);
+  } catch (err) {
+    // Roll back: restore old dir if we moved it, remove tmp
+    if (destExisted) {
+      try {
+        await fs.promises.access(destDir);
+      } catch {
+        // destDir is gone — put old back
+        try { await fs.promises.rename(old, destDir); } catch { /* ignore */ }
+      }
+    }
+    try { await fs.promises.rm(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw err;
+  }
+
+  // Step 4: remove the moved-aside old dir (best-effort)
+  if (destExisted) {
+    try { await fs.promises.rm(old, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Create a timestamped backup of filePath.
+ * Backup path: ${filePath}.claws-bak.${ISO-timestamp}[.suffix]
+ * Returns the backup path.
+ *
+ * @param {string} filePath
+ * @param {string} [suffix]  optional extra suffix appended after the timestamp
+ * @returns {Promise<string>}
+ * @throws {Error} If filePath does not exist (ENOENT) or is not readable.
+ *   Layer 2 callers (M-01 dotfile backup) must guard against missing files with
+ *   a prior fs.access() check or try/catch — backupFile does not silently skip.
+ */
+export async function backupFile(filePath, suffix) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${filePath}.claws-bak.${ts}${suffix ? '.' + suffix : ''}`;
+  await fs.promises.copyFile(filePath, backupPath);
+  return backupPath;
+}
+
+// ─── internal ────────────────────────────────────────────────────────────────
+
+async function copyDirRecursive(src, dest) {
+  await fs.promises.mkdir(dest, { recursive: true });
+  const entries = await fs.promises.readdir(src, { withFileTypes: true });
+  await Promise.all(entries.map(entry => {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      return copyDirRecursive(srcPath, destPath);
+    }
+    return fs.promises.copyFile(srcPath, destPath);
+  }));
+}

package/scripts/_helpers/fix-repair.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// M-45/M-46: safe repair helper for fix.sh — replaces inline node -e repair
+// scripts that used JSON.parse (silent-reset on malformed, M-02) + writeFileSync
+// (non-atomic, M-30) + embedded paths (injection risk, M-20).
+//
+// Uses json-safe.mjs: abort-on-malformed, atomic write, JSONC-tolerant.
+// Paths passed via env vars — no string interpolation into JS source.
+//
+// Usage (called by fix.sh):
+//   CLAWS_REPAIR_TARGET=<path> node fix-repair.js mcp
+//   CLAWS_REPAIR_TARGET=<path> node fix-repair.js extensions
+
+'use strict';
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const HELPERS_URL = pathToFileURL(path.resolve(__dirname, 'json-safe.mjs')).href;
+
+(async () => {
+  const { mergeIntoFile } = await import(HELPERS_URL);
+  const op = process.argv[2];
+  const target = process.env.CLAWS_REPAIR_TARGET;
+
+  if (!op || !target) {
+    console.error('[fix-repair] Usage: CLAWS_REPAIR_TARGET=<path> node fix-repair.js <mcp|extensions>');
+    process.exit(1);
+  }
+
+  let result;
+
+  if (op === 'mcp') {
+    result = await mergeIntoFile(target, (cfg) => {
+      if (!cfg.mcpServers) cfg.mcpServers = {};
+      cfg.mcpServers.claws = {
+        command: 'node',
+        args: ['./.claws-bin/mcp_server.js'],
+        env: { CLAWS_SOCKET: '.claws/claws.sock' },
+      };
+    });
+  } else if (op === 'extensions') {
+    result = await mergeIntoFile(target, (cfg) => {
+      if (!Array.isArray(cfg.recommendations)) cfg.recommendations = [];
+      if (!cfg.recommendations.includes('neunaha.claws')) {
+        cfg.recommendations.push('neunaha.claws');
+      }
+    });
+  } else {
+    console.error('[fix-repair] Unknown operation:', op);
+    process.exit(1);
+  }
+
+  if (!result.ok) {
+    console.error(`[fix-repair] ${op} repair failed: ${result.error.message}`);
+    if (result.error.backupSavedAt) {
+      console.error('  Malformed original backed up to:', result.error.backupSavedAt);
+      console.error('  File left unchanged — manual intervention required.');
+    }
+    process.exit(1);
+  }
+  console.log(`[fix-repair] ${op === 'mcp' ? '.mcp.json' : 'extensions.json'} repaired (atomic write)`);
+})().catch(e => {
+  console.error('[fix-repair] unexpected error:', e.message);
+  process.exit(1);
+});

package/scripts/_helpers/json-safe.mjs

@@ -0,0 +1,218 @@
+// JSONC-tolerant JSON parsing + abort-on-error file merge.
+// Used by install.sh (M-02 .mcp.json) and inject-settings-hooks.js (M-03 settings.json).
+// Both helpers in _helpers/ are self-contained — no cross-imports in L0.
+
+import fs from 'fs';
+import path from 'path';
+
+export class JsonSafeError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'JsonSafeError';
+    this.code = code;
+  }
+}
+
+// Strip JSONC extensions: // line comments, /* block comments */, and trailing commas.
+// Handles strings correctly — comment sequences inside quoted values are preserved.
+function stripJsonc(input) {
+  let result = '';
+  let i = 0;
+  const len = input.length;
+
+  while (i < len) {
+    const ch = input[i];
+
+    if (ch === '"') {
+      // Consume a JSON string verbatim (including escape sequences).
+      result += ch;
+      i++;
+      while (i < len) {
+        const sc = input[i];
+        result += sc;
+        if (sc === '\\') {
+          i++;
+          if (i < len) { result += input[i]; i++; }
+          continue;
+        }
+        if (sc === '"') { i++; break; }
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '/' && i + 1 < len && input[i + 1] === '*') {
+      // Block comment — skip everything until closing */, preserving newlines
+      // so that line/col error positions remain accurate.
+      i += 2;
+      while (i + 1 < len && !(input[i] === '*' && input[i + 1] === '/')) {
+        if (input[i] === '\n') result += '\n';
+        i++;
+      }
+      i += 2; // consume closing */
+      continue;
+    }
+
+    if (ch === '/' && i + 1 < len && input[i + 1] === '/') {
+      // Line comment — skip to end of line, preserve the newline itself.
+      i += 2;
+      while (i < len && input[i] !== '\n') i++;
+      continue;
+    }
+
+    result += ch;
+    i++;
+  }
+
+  // Remove trailing commas before ] or } (handles whitespace/newlines between).
+  return result.replace(/,(\s*[}\]])/g, '$1');
+}
+
+// Compute 1-based line/col from a character position within a string.
+function posToLineCol(str, pos) {
+  const before = str.slice(0, pos);
+  const lines = before.split('\n');
+  return { line: lines.length, col: lines[lines.length - 1].length + 1 };
+}
+
+/**
+ * Parse JSON (optionally JSONC) without throwing.
+ * @param {string} input
+ * @param {{ allowJsonc?: boolean }} [opts]  allowJsonc defaults to true
+ * @returns {{ ok: true, data: unknown } | { ok: false, error: { code: string, message: string, line?: number, col?: number, original: string } }}
+ */
+export function parseJsonSafe(input, opts = {}) {
+  if (input == null || typeof input !== 'string') {
+    return {
+      ok: false,
+      error: {
+        code: 'PARSE_ERROR',
+        message: `Expected string, got ${input === null ? 'null' : typeof input}`,
+        original: String(input),
+      },
+    };
+  }
+  // Strip UTF-8 BOM (U+FEFF) that Windows editors sometimes write at file start.
+  const normalized = input.charCodeAt(0) === 0xFEFF ? input.slice(1) : input;
+  const allowJsonc = opts.allowJsonc !== false;
+  const source = allowJsonc ? stripJsonc(normalized) : normalized;
+
+  try {
+    return { ok: true, data: JSON.parse(source) };
+  } catch (e) {
+    let line, col;
+    // Node's SyntaxError messages include "position N" for the error offset.
+    const m = e.message.match(/position (\d+)/);
+    if (m) {
+      const loc = posToLineCol(source, parseInt(m[1], 10));
+      line = loc.line;
+      col = loc.col;
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'PARSE_ERROR',
+        message: e.message,
+        ...(line != null && { line, col }),
+        original: input,
+      },
+    };
+  }
+}
+
+// Per-call nonce for unique tmp filenames across concurrent mergeIntoFile calls (F1).
+let _mergeNonce = 0;
+
+// Minimal inline atomic write (rename pattern) — avoids importing atomic-file.mjs
+// so each L0 helper stays self-contained. Layer 2/3 wiring may replace this.
+// Uses pid+nonce for tmp uniqueness (F1) and fsyncs before rename for durability (F2).
+async function writeAtomicInline(filePath, content) {
+  const tmp = `${filePath}.claws-tmp.${process.pid}-${++_mergeNonce}`;
+  let fd;
+  try {
+    fd = await fs.promises.open(tmp, 'w', 0o644);
+    await fd.writeFile(content);
+    await fd.sync();
+    await fd.close();
+    fd = null;
+    await fs.promises.rename(tmp, filePath);
+  } catch (err) {
+    if (fd) {
+      try { await fd.close(); } catch { /* ignore */ }
+      fd = null;
+    }
+    try { await fs.promises.unlink(tmp); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+/**
+ * Read filePath, parse JSONC, apply mutator, write back atomically.
+ * On parse error: saves a timestamped backup and returns ok:false WITHOUT
+ * touching the original file (critical: never silently reset to {}).
+ *
+ * @param {string} filePath
+ * @param {(cfg: object) => object | void} mutator  return new obj or mutate in place
+ * @param {{ allowJsonc?: boolean }} [opts]
+ * @returns {Promise<{ ok: true, written: boolean } | { ok: false, error: object }>}
+ */
+export async function mergeIntoFile(filePath, mutator, opts = {}) {
+  const allowJsonc = opts.allowJsonc !== false;
+
+  // Read — absent file is treated as empty object, not an error.
+  let raw = '{}';
+  try {
+    raw = await fs.promises.readFile(filePath, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: { code: 'READ_ERROR', message: e.message } };
+    }
+  }
+
+  const parsed = parseJsonSafe(raw, { allowJsonc });
+
+  if (!parsed.ok) {
+    // Backup the malformed original BEFORE returning — never overwrite it.
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${filePath}.claws-bak.${ts}`;
+    try {
+      await fs.promises.writeFile(backupPath, raw, 'utf8');
+    } catch (backupErr) {
+      return {
+        ok: false,
+        error: {
+          code: 'PARSE_FAILED',
+          message: parsed.error.message,
+          backupSavedAt: null,
+          backupError: backupErr.message,
+          parseError: parsed.error,
+        },
+      };
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'PARSE_FAILED',
+        message: parsed.error.message,
+        backupSavedAt: backupPath,
+        parseError: parsed.error,
+      },
+    };
+  }
+
+  let cfg = parsed.data;
+  const mutatorResult = mutator(cfg);
+  if (mutatorResult !== undefined && mutatorResult !== null) {
+    cfg = mutatorResult;
+  }
+
+  const content = JSON.stringify(cfg, null, 2) + '\n';
+
+  try {
+    await fs.promises.mkdir(path.dirname(path.resolve(filePath)), { recursive: true });
+    await writeAtomicInline(filePath, content);
+    return { ok: true, written: true };
+  } catch (e) {
+    return { ok: false, error: { code: 'WRITE_ERROR', message: e.message } };
+  }
+}

package/scripts/bump-version.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# scripts/bump-version.sh — single source of truth for version bumps.
+#
+# Updates every place where the version is hard-coded:
+#   - package.json (root)
+#   - extension/package.json
+#   - extension/package-lock.json (root + nested "" package)
+#
+# Usage:
+#   bash scripts/bump-version.sh 0.7.10
+#
+# After running, sync the extension CHANGELOG and refresh .claws-bin if needed:
+#   cp CHANGELOG.md extension/CHANGELOG.md
+#   cp mcp_server.js .claws-bin/mcp_server.js
+#
+# This script is the only blessed way to change the version. Manual edits to
+# any one file invite drift — and version drift on this codebase has caused
+# real shipping bugs (v0.7.7.1 semver invalidation, v0.7.5 stale lockfile, ...).
+#
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "usage: bash scripts/bump-version.sh <new-version>" >&2
+  echo "  e.g. bash scripts/bump-version.sh 0.7.10" >&2
+  exit 64
+fi
+
+NEW="$1"
+# SemVer 2.0 strict: MAJOR.MINOR.PATCH only. No fourth segment (the v0.7.7.1 trap).
+if ! echo "$NEW" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  echo "ERROR: '$NEW' is not a valid SemVer 2.0 version (MAJOR.MINOR.PATCH only)." >&2
+  echo "  VS Code rejects four-segment versions (this broke v0.7.7.1)." >&2
+  exit 65
+fi
+
+# Find the project root — script lives in scripts/ which lives at repo root.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+cd "$ROOT"
+
+# Capture old version from root package.json so the report is meaningful.
+OLD="$(node -p "require('./package.json').version")"
+
+if [ "$OLD" = "$NEW" ]; then
+  echo "version is already $NEW — nothing to do."
+  exit 0
+fi
+
+echo "bumping $OLD → $NEW across all source files…"
+
+# Update each file via Node so the JSON stays well-formed (no sed regex edge cases).
+node --no-deprecation -e "
+const fs=require('fs');
+const targets=[
+  'package.json',
+  'extension/package.json',
+  'extension/package-lock.json',
+];
+for (const f of targets) {
+  const j=JSON.parse(fs.readFileSync(f,'utf8'));
+  if (j.version) j.version='$NEW';
+  // package-lock has a nested top-level package entry that ALSO carries a
+  // version field — keep it in sync so 'npm install' doesn't re-write a stale
+  // value back in.
+  if (j.packages && j.packages['']) j.packages[''].version='$NEW';
+  fs.writeFileSync(f, JSON.stringify(j,null,2)+'\n');
+  console.log('  ✓', f);
+}
+"
+
+echo ""
+echo "verify (all 3 should be $NEW):"
+echo "  root           $(node -p "require('./package.json').version")"
+echo "  extension      $(node -p "require('./extension/package.json').version")"
+echo "  extension lock $(node -p "require('./extension/package-lock.json').version")"
+echo ""
+echo "next steps:"
+echo "  1. Update CHANGELOG.md with [$NEW] section"
+echo "  2. Sync extension CHANGELOG: cp CHANGELOG.md extension/CHANGELOG.md"
+echo "  3. Refresh runtime:          cp mcp_server.js .claws-bin/mcp_server.js"
+echo "  4. Run tests:                cd extension && npm test"
+echo "  5. Commit + tag:             git tag -a v$NEW -m 'v$NEW'"

package/scripts/codegen/gen-docs.mjs

@@ -0,0 +1,61 @@
+// gen-docs.mjs — Regenerate the schema reference table in docs/event-protocol.md.
+// Called by index.mjs. Default export is the generator function.
+// Replaces content between <!-- BEGIN GENERATED SCHEMAS --> and
+// <!-- END GENERATED SCHEMAS --> markers. If markers are absent, warns and
+// exits without modifying the file.
+
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const BEGIN_MARKER = '<!-- BEGIN GENERATED SCHEMAS -->';
+const END_MARKER   = '<!-- END GENERATED SCHEMAS -->';
+
+const TOPIC_TABLE = `\
+_This section is auto-generated by \`npm run schemas\` in \`extension/\`. Run to update._
+
+| Topic Pattern | Schema Name | Key Required Fields |
+|---|---|---|
+| \`worker.*.boot\` | \`worker-boot-v1\` | model, role, mission_summary, cwd, terminal_id |
+| \`worker.*.phase\` | \`worker-phase-v1\` | phase, prev, transition_reason, phases_completed |
+| \`worker.*.event\` | \`worker-event-v1\` | kind, severity, message |
+| \`worker.*.heartbeat\` | \`worker-heartbeat-v1\` | current_phase, time_in_phase_ms, tokens_used, cost_usd |
+| \`worker.*.complete\` | \`worker-complete-v1\` | result, summary, artifacts, phases_completed |
+| \`cmd.*.approve\` | \`cmd-approve-v1\` | correlation_id |
+| \`cmd.*.reject\` | \`cmd-reject-v1\` | correlation_id, reason |
+| \`cmd.*.abort\` | \`cmd-abort-v1\` | reason |
+| \`cmd.*.pause\` | \`cmd-pause-v1\` | _(none)_ |
+| \`cmd.*.resume\` | \`cmd-resume-v1\` | _(none)_ |
+| \`cmd.*.set_phase\` | \`cmd-set-phase-v1\` | phase, reason |
+| \`cmd.*.spawn\` | \`cmd-spawn-v1\` | name, mission |
+| \`cmd.*.inject_text\` | \`cmd-inject-text-v1\` | text |
+| \`system.peer.joined\` | \`system-peer-joined-v1\` | peerId, role, peerName, ts |
+| \`system.peer.left\` | \`system-peer-left-v1\` | peerId, role, reason |
+| \`system.peer.stale\` | \`system-peer-stale-v1\` | peerId, last_seen, missed_heartbeats |
+| \`system.gate.fired\` | \`system-gate-fired-v1\` | tool, reason, peerId |
+| \`system.budget.warning\` | \`system-budget-warning-v1\` | current_usd, threshold_usd |
+| \`system.malformed.received\` | \`system-malformed-received-v1\` | from, topic, error |`;
+
+export default async function genDocs(repoRoot) {
+  const docPath = join(repoRoot, 'docs', 'event-protocol.md');
+  let content;
+  try {
+    content = readFileSync(docPath, 'utf8');
+  } catch {
+    process.stderr.write(`[codegen/gen-docs] WARNING: docs/event-protocol.md not found — skipping\n`);
+    return;
+  }
+
+  const beginIdx = content.indexOf(BEGIN_MARKER);
+  const endIdx   = content.indexOf(END_MARKER);
+
+  if (beginIdx === -1 || endIdx === -1) {
+    process.stderr.write('[codegen/gen-docs] WARNING: markers not found in docs/event-protocol.md — skipping\n');
+    return;
+  }
+
+  const before  = content.slice(0, beginIdx + BEGIN_MARKER.length);
+  const after   = content.slice(endIdx);
+  const updated = `${before}\n${TOPIC_TABLE}\n${after}`;
+  writeFileSync(docPath, updated, 'utf8');
+  console.log('[codegen/gen-docs] updated docs/event-protocol.md schema reference table');
+}