@orquentra/codebuddy 0.0.0-stage → 2.4.0

package/dist/main-ZZ3EQLYA.js

@@ -0,0 +1,4575 @@
+import {
+  renderLeanBlock,
+  runLeanHookCommand
+} from "./chunk-DSN5CEHO.js";
+import {
+  runPreToolHookCommand
+} from "./chunk-WHZSVY2L.js";
+import {
+  failSoft,
+  readHookInput,
+  writeStdout
+} from "./chunk-PYLH4MH5.js";
+import {
+  MemoryFileStore,
+  PlanFileStore,
+  PlanLifecycle,
+  ReviewStore,
+  VERSION,
+  WorklogStore,
+  approveReviewItem,
+  assessRisk,
+  bootstrapDatabase,
+  buildBeforeEditContext,
+  buildBootstrapContext,
+  createDatabaseClient,
+  createRuntime,
+  generateSuggestions,
+  inspectNamespace,
+  listFactsPage,
+  migrateMemoryToFiles,
+  pingDatabase,
+  registerCodeBuddyTools,
+  renderContextBlock,
+  resolveRiskPaths,
+  runCaptureHook,
+  runContextHook,
+  runDoctor,
+  runMigrations,
+  runResetHook,
+  runStageHook,
+  startMcpServer,
+  watchRepository
+} from "./chunk-SYHB3AMM.js";
+import {
+  SessionCapsuleLedger,
+  computeFactHash,
+  estimateTokens,
+  generateEntityId
+} from "./chunk-5OWZVZSO.js";
+import {
+  DEFAULT_ZVEC_MODEL,
+  buildZvecIndex,
+  zvecStatus
+} from "./chunk-TI5TQD6D.js";
+import {
+  loadLlmSummaries,
+  summarizeRepository
+} from "./chunk-3ZELDCR3.js";
+import {
+  buildArchitectureMap,
+  generateGraphifyGraph,
+  indexRepository,
+  loadFreshIndex,
+  loadGraphifyMap,
+  neighbours,
+  queryMap,
+  setupGraphify
+} from "./chunk-IBMJYIEP.js";
+import {
+  extractSymbolTable,
+  supportsSymbols
+} from "./chunk-PQK3GKZH.js";
+import "./chunk-IHQM2ZDV.js";
+import {
+  chatJson,
+  coolingDown,
+  usageToday
+} from "./chunk-IE2OUO54.js";
+import {
+  redactPersisted
+} from "./chunk-GDJH7XJC.js";
+import {
+  resolveLlmConfig
+} from "./chunk-ITGRANYW.js";
+import {
+  PLAN_POLICIES,
+  configPath,
+  initConfigFile,
+  initProjectScaffold,
+  loadPlanPolicy,
+  loadRuntimeConfig,
+  readConfigFile,
+  redactSecrets,
+  resolveNamespaceFrom,
+  setLlmEnabled,
+  setPlanPolicy,
+  setZvecEnabled,
+  writeAtomic,
+  writeConfigFile
+} from "./chunk-K63EOA4B.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/cli/main.ts
+import { Command } from "commander";
+import pc20 from "picocolors";
+
+// src/integrations/github.ts
+import { constants } from "fs";
+import { access, mkdir, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+var CODEBUDDY_WORKFLOW_PATH = ".github/workflows/codebuddy.yml";
+function renderGitHubWorkflow(version = VERSION) {
+  return `name: CodeBuddy Change Safety
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  codebuddy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out pull request
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install CodeBuddy
+        run: npm install --global --no-audit --no-fund @orquentra/codebuddy@${version}
+
+      - name: Generate change report
+        run: codebuddy change --json > codebuddy-report.json
+
+      - name: Publish step summary
+        env:
+          REPORT_PATH: codebuddy-report.json
+          SUMMARY_PATH: $GITHUB_STEP_SUMMARY
+        run: |
+          node <<'NODE'
+          const fs = require("fs");
+          const report = JSON.parse(fs.readFileSync(process.env.REPORT_PATH, "utf8"));
+          const status = report.status.toUpperCase();
+          const findings = (report.suggestions || []).slice(0, 8).map((item) =>
+            "- **" + item.severity + "** " + item.title + " \u2014 " + item.detail,
+          );
+          const body = [
+            "<!-- codebuddy-report -->",
+            "## CodeBuddy change report",
+            "**Status:** " + status,
+            "**Highest risk:** " + report.risk.highestScore + "/100",
+            "**Changed paths:** " + report.paths.length,
+            "**Direct dependents:** " + report.architecture.totalDependents,
+            findings.length ? "\\n### Findings\\n" + findings.join("\\n") : "\\nNo findings.",
+          ].join("\\n");
+          fs.writeFileSync("codebuddy-report.md", body + "\\n");
+          fs.appendFileSync(process.env.SUMMARY_PATH, body + "\\n");
+          NODE
+
+      - name: Comment on pull request
+        uses: actions/github-script@v7
+        with:
+          github-token: \${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require("fs");
+            const body = fs.readFileSync("codebuddy-report.md", "utf8");
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number, per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body?.includes("<!-- codebuddy-report -->"));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }
+`;
+}
+async function installGitHubWorkflow(repositoryRoot = process.cwd(), options = {}) {
+  const root = resolve(repositoryRoot);
+  const path = join(root, CODEBUDDY_WORKFLOW_PATH);
+  if (!options.force) {
+    try {
+      await access(path, constants.F_OK);
+      return { path, created: false };
+    } catch {
+    }
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, renderGitHubWorkflow(), "utf8");
+  return { path, created: true };
+}
+
+// src/cli/commands/change.ts
+import pc from "picocolors";
+
+// src/change/engine.ts
+import { spawn } from "child_process";
+import { constants as constants2 } from "fs";
+import { access as access2, readFile } from "fs/promises";
+import { extname, join as join2 } from "path";
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+var DEFAULT_TEST_TIMEOUT_MS = 12e4;
+var MAX_TEST_OUTPUT_CHARS = 12e3;
+async function buildChangeReport(input) {
+  const repositoryRoot = input.repositoryRoot ?? process.cwd();
+  const hasExplicitSelection = (input.paths?.length ?? 0) > 0 || input.planId !== void 0;
+  const paths = input.useGit === false && !hasExplicitSelection ? [] : await resolveRiskPaths({
+    repositoryRoot,
+    ...input.paths !== void 0 ? { paths: input.paths } : {},
+    ...input.planId !== void 0 ? { planId: input.planId } : {},
+    ...input.useGit !== void 0 ? { useGit: input.useGit } : { useGit: true }
+  });
+  const planStore = new PlanFileStore(repositoryRoot);
+  const [risk, suggestions, plan, architecture] = await Promise.all([
+    paths.length === 0 ? Promise.resolve(emptyAssessment()) : assessRisk({
+      repositoryRoot,
+      namespace: input.namespace,
+      paths,
+      ...input.useGit !== void 0 ? { useGit: input.useGit } : {},
+      ...input.planId !== void 0 ? { planId: input.planId } : {}
+    }),
+    paths.length === 0 ? Promise.resolve(emptySuggestions()) : generateSuggestions({ repositoryRoot, namespace: input.namespace, paths }),
+    resolveRelevantPlan(planStore, input.namespace, input.planId),
+    input.graphifyPath ? loadGraphifyMapOrFallback(input.graphifyPath, repositoryRoot) : buildArchitectureMap(repositoryRoot).then((map2) => ({ map: map2, warning: null }))
+  ]);
+  const planSummary = summarizePlan(plan, paths);
+  const verification = buildVerification(paths, planSummary, suggestions);
+  const { map, warning: graphifyWarning } = architecture;
+  const dependentsByPath = countDependents(map.edges, paths);
+  const highestScore = risk.items.reduce((highest, item) => Math.max(highest, item.score), 0);
+  const status = getStatus(paths, highestScore, suggestions, verification);
+  return {
+    status,
+    paths,
+    plan: planSummary,
+    risk: { highestScore, items: risk.items },
+    architecture: {
+      dependentsByPath,
+      totalDependents: Object.values(dependentsByPath).reduce((sum, count) => sum + count, 0),
+      source: input.graphifyPath && !graphifyWarning ? "graphify" : "imports",
+      ...graphifyWarning ? { warning: graphifyWarning } : {}
+    },
+    suggestions: suggestions.suggestions,
+    verification
+  };
+}
+async function verifyChange(input) {
+  const report = await buildChangeReport(input);
+  const detected = input.command ? { command: input.command, source: "explicit" } : await detectTestCommand(input.repositoryRoot ?? process.cwd());
+  if (!detected) {
+    return {
+      report,
+      test: {
+        status: "not_run",
+        command: null,
+        source: null,
+        exitCode: null,
+        signal: null,
+        durationMs: 0,
+        output: "No test command found. Pass --command or add a test script to package.json."
+      }
+    };
+  }
+  return {
+    report,
+    test: await runTestCommand(
+      detected.command,
+      detected.source,
+      input.repositoryRoot ?? process.cwd(),
+      input.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS
+    )
+  };
+}
+async function detectTestCommand(repositoryRoot) {
+  const packagePath = join2(repositoryRoot, "package.json");
+  try {
+    const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+    if (typeof packageJson.scripts?.test === "string") {
+      return {
+        command: `${packageManagerName(packageJson.packageManager)} test`,
+        source: "package_script"
+      };
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  for (const candidate of [
+    ["pnpm-lock.yaml", "pnpm test"],
+    ["yarn.lock", "yarn test"],
+    ["bun.lockb", "bun test"],
+    ["bun.lock", "bun test"],
+    ["package-lock.json", "npm test"]
+  ]) {
+    try {
+      await access2(join2(repositoryRoot, candidate[0]), constants2.F_OK);
+      return { command: candidate[1], source: "package_manager" };
+    } catch {
+    }
+  }
+  return null;
+}
+function packageManagerName(value) {
+  if (typeof value !== "string") return "npm";
+  const name = value.split(/[\s@]/, 1)[0] ?? "npm";
+  return ["npm", "pnpm", "yarn", "bun"].includes(name) ? name : "npm";
+}
+function runTestCommand(command, source, repositoryRoot, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("--timeout must be a positive number of milliseconds.");
+  }
+  return new Promise((resolve14) => {
+    const startedAt = Date.now();
+    const child = spawn(command, {
+      cwd: repositoryRoot,
+      env: process.env,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    let timedOut = false;
+    const append = (chunk) => {
+      output += chunk.toString();
+      if (output.length > MAX_TEST_OUTPUT_CHARS) {
+        output = `[output truncated; showing last ${MAX_TEST_OUTPUT_CHARS} characters]
+${output.slice(-MAX_TEST_OUTPUT_CHARS)}`;
+      }
+    };
+    child.stdout.on("data", append);
+    child.stderr.on("data", append);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    child.on("close", (exitCode, signal) => {
+      clearTimeout(timer);
+      resolve14({
+        status: timedOut ? "timed_out" : exitCode === 0 ? "passed" : "failed",
+        command,
+        source,
+        exitCode,
+        signal,
+        durationMs: Date.now() - startedAt,
+        output: output.trim()
+      });
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve14({
+        status: "failed",
+        command,
+        source,
+        exitCode: null,
+        signal: null,
+        durationMs: Date.now() - startedAt,
+        output: `${output.trim()}
+${error.message}`.trim()
+      });
+    });
+  });
+}
+async function loadGraphifyMapOrFallback(graphifyPath, repositoryRoot) {
+  try {
+    return { map: await loadGraphifyMap(graphifyPath, repositoryRoot), warning: null };
+  } catch (error) {
+    return {
+      map: await buildArchitectureMap(repositoryRoot),
+      warning: `Graphify graph unusable, fell back to the import scan: ${error.message}`
+    };
+  }
+}
+function emptyAssessment() {
+  return {
+    items: [],
+    stats: { pathsConsidered: 0, itemsProduced: 0, signalsRun: 0, perSignal: [] }
+  };
+}
+function emptySuggestions() {
+  return {
+    suggestions: [],
+    stats: { pathsConsidered: 0, produced: 0, byCategory: {}, bySeverity: {} }
+  };
+}
+async function resolveRelevantPlan(store, namespace, planId) {
+  if (planId) {
+    try {
+      return await store.readPlan(planId);
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+  return new PlanLifecycle(store).current(namespace);
+}
+function summarizePlan(plan, paths) {
+  if (!plan) return null;
+  const plannedPaths = plan.filesToTouch.map((file) => file.path).sort();
+  const plannedSet = new Set(plannedPaths);
+  const unexpectedPaths = paths.filter((path) => !plannedSet.has(path));
+  const plannedTests = plan.testsToAdd.map((test) => test.path).sort();
+  const changed = new Set(paths);
+  const missingPlannedTests = plannedTests.filter((path) => !changed.has(path));
+  return {
+    id: plan.id,
+    title: plan.title,
+    status: plan.status,
+    plannedPaths,
+    unexpectedPaths,
+    plannedTests,
+    missingPlannedTests
+  };
+}
+function buildVerification(paths, plan, suggestions) {
+  const changedTestFiles = paths.filter(isTestFile);
+  const changedCodeFiles = paths.filter((path) => isCodeFile(path) && !isTestFile(path));
+  const uncovered = new Set(
+    suggestions.suggestions.filter((suggestion) => suggestion.category === "missing_test" && suggestion.path).map((suggestion) => suggestion.path)
+  );
+  const plannedTests = plan?.plannedTests ?? [];
+  const missingPlannedTests = plan?.missingPlannedTests ?? [];
+  return {
+    changedCodeFiles,
+    changedTestFiles,
+    uncoveredCodeFiles: changedCodeFiles.filter((path) => uncovered.has(path)),
+    plannedTests,
+    missingPlannedTests,
+    readyToVerify: changedTestFiles.length > 0 || changedCodeFiles.length === 0
+  };
+}
+function countDependents(edges, paths) {
+  const targets = new Set(paths);
+  const counts = {};
+  for (const path of paths) counts[path] = 0;
+  for (const edge of edges) {
+    if (targets.has(edge.to)) counts[edge.to] = (counts[edge.to] ?? 0) + 1;
+  }
+  return counts;
+}
+function getStatus(paths, highestRisk, suggestions, verification) {
+  if (paths.length === 0) return "no_changes";
+  if (highestRisk >= 75 || suggestions.suggestions.some((item) => item.severity === "high")) {
+    return "blocked";
+  }
+  if (highestRisk >= 50 || suggestions.suggestions.some((item) => item.severity === "medium") || verification.uncoveredCodeFiles.length > 0 || verification.missingPlannedTests.length > 0) {
+    return "review";
+  }
+  return "ready";
+}
+function isCodeFile(path) {
+  return CODE_EXTENSIONS.has(extname(path).toLowerCase());
+}
+function isTestFile(path) {
+  return /(^|\/)(__tests__\/|.*\.(test|spec)\.)/.test(path);
+}
+
+// src/cli/commands/change.ts
+function registerChangeCommand(program, runSafely2) {
+  const change = program.command("change").description("Assess and verify the current change.");
+  change.command("report", { isDefault: true }).description("Report whether the current change is ready, needs review, or is blocked.").option("--paths <paths>", "Comma-separated repo-relative paths to review.").option("--plan <id>", "Review the files listed in a plan.").option("--no-git", "Do not include the current Git change set.").option("--graphify <path>", "Use a Graphify graph.json for deeper architecture edges.").option("--json", "Print machine-readable JSON.").action(async (opts) => {
+    await runSafely2(async () => {
+      const report = await buildChangeReport(toInput(opts, await resolveNamespaceFrom()));
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+      printReport(report);
+    });
+  });
+  change.command("verify").description("Run the detected test command and report whether the change is verified.").option("--paths <paths>", "Comma-separated repo-relative paths to review.").option("--plan <id>", "Review the files listed in a plan.").option("--no-git", "Do not include the current Git change set.").option("--graphify <path>", "Use a Graphify graph.json for deeper architecture edges.").option("--command <command>", "Override the detected test command.").option("--timeout <ms>", "Stop the test command after this many milliseconds.", Number).option("--json", "Print machine-readable JSON.").action(async (opts) => {
+    await runSafely2(async () => {
+      const result = await verifyChange({
+        ...toInput(opts, await resolveNamespaceFrom()),
+        ...opts.command ? { command: opts.command } : {},
+        ...opts.timeout !== void 0 ? { timeoutMs: opts.timeout } : {}
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printVerification(result);
+      }
+      if (result.test.status !== "passed") process.exitCode = 1;
+    });
+  });
+}
+function toInput(opts, namespace) {
+  return {
+    namespace,
+    ...opts.paths ? { paths: parsePaths(opts.paths) } : {},
+    ...opts.plan ? { planId: opts.plan } : {},
+    ...opts.git !== void 0 ? { useGit: opts.git } : {},
+    ...opts.graphify ? { graphifyPath: opts.graphify } : {}
+  };
+}
+function parsePaths(value) {
+  return value.split(",").map((path) => path.trim()).filter(Boolean);
+}
+function printReport(report) {
+  console.log(`${statusBadge(report.status)} ${pc.bold("change report")}`);
+  if (report.paths.length === 0) {
+    console.log(pc.dim("  no changed paths detected"));
+    return;
+  }
+  console.log(`  ${report.paths.length} path(s): ${report.paths.join(", ")}`);
+  console.log(`  highest risk: ${report.risk.highestScore}`);
+  console.log(
+    `  architecture: ${report.architecture.totalDependents} direct dependent edge(s) across the change set (${report.architecture.source})`
+  );
+  if (report.architecture.warning) console.log(pc.yellow(`  ${report.architecture.warning}`));
+  if (report.plan) {
+    console.log(`  plan: ${report.plan.id} ${report.plan.title} (${report.plan.status})`);
+    if (report.plan.unexpectedPaths.length > 0)
+      console.log(`  plan drift: ${report.plan.unexpectedPaths.join(", ")}`);
+    if (report.plan.missingPlannedTests.length > 0)
+      console.log(`  planned tests still missing: ${report.plan.missingPlannedTests.join(", ")}`);
+  } else {
+    console.log(pc.dim("  plan: no active plan"));
+  }
+  console.log(
+    `  verification: ${report.verification.changedTestFiles.length} test file(s) changed; ${report.verification.uncoveredCodeFiles.length} code file(s) without a discovered test`
+  );
+  if (report.suggestions.length > 0) {
+    console.log("\n  findings:");
+    for (const suggestion of report.suggestions.slice(0, 8)) {
+      console.log(`  ${severityBadge(suggestion.severity)} ${suggestion.title}`);
+      console.log(pc.dim(`    ${suggestion.detail}`));
+    }
+  } else {
+    console.log(pc.dim("\n  findings: none"));
+  }
+}
+function printVerification(result) {
+  printReport(result.report);
+  console.log(`
+${testBadge(result.test.status)} verification`);
+  console.log(`  command: ${result.test.command ?? "none detected"}`);
+  if (result.test.durationMs > 0) console.log(`  duration: ${result.test.durationMs}ms`);
+  if (result.test.output) {
+    console.log("  output:");
+    for (const line of result.test.output.split("\n")) console.log(`    ${line}`);
+  }
+}
+function statusBadge(status) {
+  if (status === "blocked") return pc.red("[blocked]");
+  if (status === "review") return pc.yellow("[review ]");
+  if (status === "ready") return pc.green("[ready  ]");
+  return pc.dim("[no diff ]");
+}
+function severityBadge(severity) {
+  if (severity === "high") return pc.red("[high]");
+  if (severity === "medium") return pc.yellow("[med ]");
+  return pc.dim(`[${severity.padEnd(5)}]`);
+}
+function testBadge(status) {
+  if (status === "passed") return pc.green("[passed ]");
+  if (status === "timed_out") return pc.red("[timeout]");
+  if (status === "failed") return pc.red("[failed ]");
+  return pc.yellow("[not run]");
+}
+
+// src/cli/commands/claude-desktop.ts
+import { existsSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+function claudeDesktopConfigPath(home = process.env.HOME ?? "") {
+  if (process.platform === "darwin") {
+    return join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "win32") {
+    return join3(process.env.APPDATA ?? home, "Claude", "claude_desktop_config.json");
+  }
+  return join3(home, ".config", "Claude", "claude_desktop_config.json");
+}
+async function readClaudeConfig(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(await readFile2(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `Failed to parse Claude Desktop config at ${path}: ${error.message}`
+    );
+  }
+}
+async function writeClaudeConfig(path, config) {
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeAtomic(path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+}
+function resolveCliEntrypoint() {
+  const fromArgv = process.argv[1];
+  if (fromArgv && existsSync(fromArgv)) return fromArgv;
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve2(here, "index.js"),
+    // bundled: here = dist/cli/
+    resolve2(here, "..", "cli", "index.js"),
+    // source: here = src/cli/commands/
+    resolve2(here, "..", "index.js")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return fromArgv ?? candidates[0] ?? "";
+}
+function buildEntry(options) {
+  const env = {
+    CODEBUDDY_NAMESPACE: options.namespace
+  };
+  if (options.projectRoot) env.CODEBUDDY_PROJECT_ROOT = options.projectRoot;
+  if (options.hfToken) env.HF_TOKEN = options.hfToken;
+  if (options.groqApiKey) env.GROQ_API_KEY = options.groqApiKey;
+  if (options.databaseUrl) env.DATABASE_URL = options.databaseUrl;
+  return {
+    command: "node",
+    args: [resolveCliEntrypoint(), "serve"],
+    env
+  };
+}
+async function installClaudeEntry(options) {
+  const path = claudeDesktopConfigPath();
+  const config = await readClaudeConfig(path);
+  config.mcpServers ??= {};
+  const serverKey = options.serverName ?? `codebuddy-${options.namespace}`;
+  const existed = config.mcpServers[serverKey] !== void 0;
+  config.mcpServers[serverKey] = buildEntry(options);
+  await writeClaudeConfig(path, config);
+  return { path, serverKey, created: !existed };
+}
+async function removeClaudeEntry(serverKey) {
+  const path = claudeDesktopConfigPath();
+  const config = await readClaudeConfig(path);
+  if (!config.mcpServers || !(serverKey in config.mcpServers)) {
+    return { removed: false, path };
+  }
+  delete config.mcpServers[serverKey];
+  await writeClaudeConfig(path, config);
+  return { removed: true, path };
+}
+async function listClaudeEntries() {
+  const path = claudeDesktopConfigPath();
+  const config = await readClaudeConfig(path);
+  const entries = Object.entries(config.mcpServers ?? {}).filter(([key]) => key === "codebuddy" || key.startsWith("codebuddy-")).map(([key, entry]) => ({
+    key,
+    namespace: entry.env?.CODEBUDDY_NAMESPACE ?? null,
+    databaseUrl: entry.env?.DATABASE_URL ?? null
+  }));
+  return { path, entries };
+}
+
+// src/cli/commands/clients.ts
+import { relative } from "path";
+import pc2 from "picocolors";
+
+// src/clients/adapters.ts
+var AUTOMATION_MODES = ["agent", "hooks", "mcp-only", "lean"];
+var MODE_LABELS = {
+  agent: "agent-driven",
+  hooks: "hook-driven",
+  "mcp-only": "MCP-only",
+  lean: "Lean (token reduction)"
+};
+var LIFECYCLE_EVENTS = ["prompt", "edit", "turn-end", "compaction"];
+var CLIENT_IDS = ["claude", "codex", "opencode", "freebuff", "hermes"];
+var CLIENT_ADAPTERS = {
+  claude: {
+    name: "Claude Code",
+    host: { bin: "claude", verified: "2.1.287" },
+    rulesFile: "CLAUDE.md",
+    mcp: { file: ".mcp.json", format: "mcpServers" },
+    hookEvents: LIFECYCLE_EVENTS,
+    hooks: "claude-settings",
+    framing: "UserPromptSubmit stdout is added to the prompt as hook context (wrapper is host-defined); unchanged lines are not resent; MCP schemas may be deferred by tool search",
+    defersMcpSchemas: true
+  },
+  codex: {
+    name: "Codex",
+    host: { bin: "codex", verified: "0.163.0" },
+    rulesFile: "AGENTS.md",
+    mcp: { global: "codex", manual: "codebuddy codex install (global ~/.codex/config.toml)" },
+    hookEvents: [],
+    gap: "no CodeBuddy hook adapter for Codex yet",
+    framing: "agent mode only; AGENTS.md is part of the instructions every request"
+  },
+  opencode: {
+    name: "OpenCode",
+    host: { bin: "opencode", verified: "1.18.32" },
+    rulesFile: "AGENTS.md",
+    // opencode.jsonc is used instead when it is the only one present.
+    mcp: { file: "opencode.json", format: "opencode" },
+    // Plugin bridge: chat.message (prompt), tool.execute.after (edit),
+    // session.idle (turn-end), session.compacted.
+    hookEvents: LIFECYCLE_EVENTS,
+    hooks: "opencode-plugin",
+    framing: "block appended verbatim as a synthetic text part that stays in history; unchanged lines are not resent"
+  },
+  freebuff: {
+    name: "Freebuff",
+    // Not installed; checked against source CodebuffAI/freebuff@f9ae64dd.
+    host: { bin: "freebuff", verified: "source f9ae64dd" },
+    rulesFile: "AGENTS.md",
+    mcp: { file: ".agents/mcp.json", format: "mcpServers" },
+    hookEvents: [],
+    gap: "no lifecycle surface at CodebuffAI/freebuff@f9ae64dd: no user hook config, and the SDK run_file_change_hooks tool is a no-op (sdk/src/tools/run-file-change-hooks.ts)",
+    note: "reads AGENTS.md, and CLAUDE.md only in a directory without one (common/src/constants/knowledge.ts)",
+    framing: "agent mode only; AGENTS.md is sent as a fenced block under a fixed project-instructions header"
+  },
+  hermes: {
+    name: "Hermes Agent",
+    host: { bin: "hermes", verified: "0.17.0" },
+    rulesFile: "AGENTS.md",
+    mcp: {
+      global: "hermes",
+      manual: "add a codebuddy entry under mcp_servers in ~/.hermes/config.yaml"
+    },
+    // Project Python plugin: pre_llm_call (prompt), post_tool_call (edit),
+    // on_session_end (turn-end). Compaction has no plugin hook; the context is
+    // resent in full every turn and the session ledger reset with it.
+    hookEvents: LIFECYCLE_EVENTS,
+    hooks: "hermes-plugin",
+    ephemeralContext: true,
+    framing: "block appended to this turn's user message only and never persisted, so it is resent in full every turn",
+    note: "hooks load only with HERMES_ENABLE_PROJECT_PLUGINS=1 and codebuddy in plugins.enabled of ~/.hermes/config.yaml; .hermes.md takes precedence over AGENTS.md"
+  }
+};
+function parseClient(value) {
+  const client = value ?? "claude";
+  if (!CLIENT_IDS.includes(client)) {
+    throw new Error(`Unknown client "${client}". Use one of: ${CLIENT_IDS.join(", ")}.`);
+  }
+  return client;
+}
+function parseMode(value) {
+  if (!AUTOMATION_MODES.includes(value)) {
+    throw new Error(`Unknown mode "${value}". Use one of: ${AUTOMATION_MODES.join(", ")}.`);
+  }
+  return value;
+}
+function supportedModes(adapter) {
+  return adapter.hookEvents.length === LIFECYCLE_EVENTS.length ? [...AUTOMATION_MODES] : ["agent", "mcp-only"];
+}
+function sharedRulesReaders(client) {
+  const file = CLIENT_ADAPTERS[client].rulesFile;
+  return CLIENT_IDS.filter((id) => id !== client && CLIENT_ADAPTERS[id].rulesFile === file);
+}
+
+// src/clients/cost.ts
+import { mkdtemp, rm as rm3 } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join8, resolve as resolve7 } from "path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/templates/install.ts
+import { readFile as readFile7, rm as rm2 } from "fs/promises";
+import { join as join7, resolve as resolve6 } from "path";
+
+// src/hooks/hermes-plugin.ts
+import { readFile as readFile4 } from "fs/promises";
+import { dirname as dirname4, join as join4, resolve as resolve3 } from "path";
+
+// src/hooks/managed-plugin.ts
+import { mkdir as mkdir3, readFile as readFile3, rm, rmdir } from "fs/promises";
+import { dirname as dirname3 } from "path";
+async function read(path) {
+  try {
+    return await readFile3(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function managedPluginInstalled(plugin3) {
+  for (const file of plugin3.files) {
+    if (!(await read(file.path))?.startsWith(plugin3.marker)) return false;
+  }
+  return true;
+}
+async function setManagedPlugin(plugin3, enabled) {
+  const current = await Promise.all(plugin3.files.map((file) => read(file.path)));
+  const foreign = plugin3.files.find((_, i) => {
+    const text3 = current[i];
+    return text3 != null && !text3.startsWith(plugin3.marker);
+  });
+  if (foreign) {
+    if (!enabled) return false;
+    throw new Error(
+      `${foreign.path} exists and is not managed by CodeBuddy; move it aside and re-run.`
+    );
+  }
+  let changed = false;
+  for (const [i, file] of plugin3.files.entries()) {
+    if (enabled && current[i] !== file.content) {
+      await mkdir3(dirname3(file.path), { recursive: true });
+      await writeAtomic(file.path, file.content, { mode: 420 });
+      changed = true;
+    } else if (!enabled && current[i] != null) {
+      await rm(file.path, { force: true });
+      changed = true;
+    }
+  }
+  if (!enabled && changed) {
+    for (const dir of plugin3.dirs) await rmdir(dir).catch(() => {
+    });
+  }
+  return changed;
+}
+
+// src/hooks/hermes-plugin.ts
+var HERMES_PLUGIN_MARKER = "# codebuddy-managed: hermes-plugin";
+var HERMES_PLUGIN_MANIFEST = `${HERMES_PLUGIN_MARKER} v1
+name: codebuddy
+version: 1.0.0
+kind: standalone
+description: CodeBuddy recall and capture bridge (codebuddy clients install hermes --mode hooks).
+provides_hooks:
+  - pre_llm_call
+  - post_tool_call
+  - post_llm_call
+  - on_session_end
+`;
+var HERMES_LEAN_MANIFEST = `${HERMES_PLUGIN_MARKER} v1 lean
+name: codebuddy
+version: 1.0.0
+kind: standalone
+description: CodeBuddy lean bridge (codebuddy clients install hermes --mode lean).
+provides_hooks:
+  - pre_llm_call
+`;
+var HERMES_HOOK_FN = `def _hook(command, payload):
+    """Run one fail-soft CodeBuddy hook; its stdout, or "" on any failure."""
+    try:
+        done = subprocess.run(
+            ["codebuddy", "hooks", command],
+            input=json.dumps({"cwd": ROOT, **payload}),
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT_S[command],
+            cwd=ROOT,
+        )
+    except Exception:
+        return ""
+    return done.stdout if done.returncode == 0 else ""
+
+
+`;
+function renderHermesPlugin(variant) {
+  return variant === "lean" ? `${HERMES_PLUGIN_MARKER} v1 lean
+# Generated by "codebuddy clients install hermes --mode lean"; removed by
+# "codebuddy clients uninstall hermes". Local edits are overwritten.
+"""CodeBuddy lean bridge: forwards each prompt to "codebuddy hooks lean"."""
+
+import json
+import subprocess
+from pathlib import Path
+
+# <root>/.hermes/plugins/codebuddy/__init__.py
+ROOT = str(Path(__file__).absolute().parents[3])
+TIMEOUT_S = {"lean": 2}
+
+
+${HERMES_HOOK_FN}def _pre_llm_call(session_id="", user_message="", **_):
+    if not isinstance(user_message, str) or not user_message.strip():
+        return None
+    payload = {
+        "session_id": session_id,
+        "hook_event_name": "pre_llm_call",
+        "ephemeral_context": True,
+        "prompt": user_message,
+    }
+    block = _hook("lean", payload).strip()
+    return {"context": block} if block else None
+
+
+def register(ctx):
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+` : `${HERMES_PLUGIN_MARKER} v1
+# Generated by "codebuddy clients install hermes --mode hooks"; removed by
+# "codebuddy clients uninstall hermes". Local edits are overwritten.
+"""CodeBuddy lifecycle bridge: forwards Hermes hooks to "codebuddy hooks <command>"."""
+
+import json
+import subprocess
+import threading
+from pathlib import Path
+
+# <root>/.hermes/plugins/codebuddy/__init__.py
+ROOT = str(Path(__file__).absolute().parents[3])
+EDIT_TOOLS = {"write_file", "patch"}
+TIMEOUT_S = {"context": 20, "stage": 10, "capture": 60}
+_lock = threading.Lock()
+_turns = {}
+
+
+${HERMES_HOOK_FN}def _turn(turn_id, session_id):
+    # Compression can rotate the session id mid-turn; a turn keeps its first id.
+    with _lock:
+        return _turns.setdefault(
+            turn_id or session_id, {"session": session_id, "text": "", "commands": []}
+        )
+
+
+def _pre_llm_call(session_id="", turn_id="", user_message="", **_):
+    _turn(turn_id, session_id)
+    payload = {"session_id": session_id, "hook_event_name": "pre_llm_call", "ephemeral_context": True}
+    if isinstance(user_message, str) and user_message.strip():
+        payload["prompt"] = user_message
+    block = _hook("context", payload).strip()
+    return {"context": block} if block else None
+
+
+def _post_tool_call(tool_name="", args=None, result=None, session_id="", turn_id="", **_):
+    turn = _turn(turn_id, session_id)
+    args = args if isinstance(args, dict) else {}
+    if tool_name in EDIT_TOOLS:
+        # Paths only: write_file content never needs to cross the pipe.
+        tool_input = {k: args[k] for k in ("path", "mode", "patch") if k in args}
+        _hook("stage", {
+            "session_id": turn["session"],
+            "hook_event_name": "post_tool_call",
+            "tool_name": tool_name,
+            "tool_input": tool_input,
+        })
+    elif tool_name == "terminal" and isinstance(args.get("command"), str):
+        exit_code = None
+        if not args.get("background"):  # a background process has not finished
+            try:
+                exit_code = json.loads(result).get("exit_code")
+            except Exception:
+                pass
+        turn["commands"].append({
+            "command": args["command"],
+            "exit_code": exit_code if type(exit_code) is int else None,
+        })
+
+
+def _post_llm_call(session_id="", turn_id="", assistant_response="", **_):
+    if isinstance(assistant_response, str) and assistant_response.strip():
+        _turn(turn_id, session_id)["text"] = assistant_response
+
+
+def _on_session_end(session_id="", turn_id="", **_):
+    with _lock:
+        turn = _turns.pop(turn_id or session_id, None)
+    turn = turn or {"session": session_id, "text": "", "commands": []}
+    payload = {"session_id": turn["session"], "hook_event_name": "on_session_end"}
+    if turn["text"]:
+        payload["last_assistant_message"] = turn["text"]
+    if turn["commands"]:
+        payload["shell_commands"] = turn["commands"][-20:]
+    _hook("capture", payload)
+
+
+def register(ctx):
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+    ctx.register_hook("post_tool_call", _post_tool_call)
+    ctx.register_hook("post_llm_call", _post_llm_call)
+    ctx.register_hook("on_session_end", _on_session_end)
+`;
+}
+var HERMES_PLUGIN_SOURCE = renderHermesPlugin("full");
+function hermesPluginDir(repositoryRoot) {
+  return join4(resolve3(repositoryRoot), ".hermes", "plugins", "codebuddy");
+}
+function plugin(repositoryRoot, variant = "full") {
+  const dir = hermesPluginDir(repositoryRoot);
+  return {
+    marker: HERMES_PLUGIN_MARKER,
+    files: [
+      {
+        path: join4(dir, "plugin.yaml"),
+        content: variant === "lean" ? HERMES_LEAN_MANIFEST : HERMES_PLUGIN_MANIFEST
+      },
+      { path: join4(dir, "__init__.py"), content: renderHermesPlugin(variant) }
+    ],
+    dirs: [dir, dirname4(dir), dirname4(dirname4(dir))]
+  };
+}
+function hermesPluginInstalled(repositoryRoot) {
+  return managedPluginInstalled(plugin(repositoryRoot));
+}
+function setHermesPlugin(repositoryRoot, enabled, variant = "full") {
+  return setManagedPlugin(plugin(repositoryRoot, variant), enabled);
+}
+async function hermesPluginVariant(repositoryRoot) {
+  if (!await hermesPluginInstalled(repositoryRoot)) return null;
+  const source = await readFile4(join4(hermesPluginDir(repositoryRoot), "__init__.py"), "utf8");
+  return source.startsWith(`${HERMES_PLUGIN_MARKER} v1 lean`) ? "lean" : "full";
+}
+
+// src/hooks/opencode-plugin.ts
+import { readFile as readFile5 } from "fs/promises";
+import { dirname as dirname5, join as join5, resolve as resolve4 } from "path";
+var OPENCODE_PLUGIN_MARKER = "// codebuddy-managed: opencode-plugin";
+var OPENCODE_RUNTIME = `const ID_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+let lastMs = 0;
+let counter = 0;
+
+/** Run one fail-soft CodeBuddy hook; resolves to its stdout, "" on any failure. */
+function hook(command, payload) {
+  return new Promise((done) => {
+    let out = "";
+    let child;
+    try {
+      child = spawn("codebuddy", ["hooks", command], {
+        cwd: payload.cwd,
+        stdio: ["pipe", "pipe", "ignore"],
+      });
+    } catch {
+      done("");
+      return;
+    }
+    const timer = setTimeout(() => child.kill(), TIMEOUT_MS[command]);
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      out += chunk;
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      done("");
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      done(code === 0 ? out : "");
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+/** An ascending OpenCode part id (prt_ + 48-bit time/counter hex + 14 base62). */
+function partId() {
+  const now = Date.now();
+  if (now !== lastMs) {
+    lastMs = now;
+    counter = 0;
+  }
+  counter += 1;
+  const time = (BigInt(now) * 4096n + BigInt(counter)) & 0xffffffffffffn;
+  let random = "";
+  for (const byte of crypto.getRandomValues(new Uint8Array(14))) random += ID_CHARS[byte % 62];
+  return "prt_" + time.toString(16).padStart(12, "0") + random;
+}
+
+`;
+function renderOpencodePlugin(variant) {
+  return variant === "lean" ? `${OPENCODE_PLUGIN_MARKER} v1 lean
+// Generated by \`codebuddy clients install opencode --mode lean\`; removed by
+// \`codebuddy clients uninstall opencode\`. Local edits are overwritten.
+import { spawn } from "node:child_process";
+
+const TIMEOUT_MS = { lean: 2000, reset: 10000 };
+${OPENCODE_RUNTIME}/** @type {import("@opencode-ai/plugin").Plugin} */
+export const CodeBuddyPlugin = async ({ directory }) => {
+  const base = (sessionID, event) => ({ session_id: sessionID, cwd: directory, hook_event_name: event });
+
+  return {
+    "chat.message": async (input, output) => {
+      const prompt = output.parts
+        .flatMap((part) => (part.type === "text" && !part.synthetic ? [part.text] : []))
+        .join("\\n")
+        .trim();
+      if (!prompt) return;
+      const block = (await hook("lean", { ...base(input.sessionID, "chat.message"), prompt })).trim();
+      if (!block) return;
+      output.parts.push({
+        id: partId(),
+        sessionID: input.sessionID,
+        messageID: output.message.id,
+        type: "text",
+        text: block,
+        synthetic: true,
+      });
+    },
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") {
+        await hook("reset", { ...base(event.properties.sessionID, "session.compacted"), source: "compact" });
+      }
+    },
+  };
+};
+` : `${OPENCODE_PLUGIN_MARKER} v1
+// Generated by \`codebuddy clients install opencode --mode hooks\`; removed by
+// \`codebuddy clients uninstall opencode\`. Local edits are overwritten.
+import { spawn } from "node:child_process";
+
+const EDIT_TOOLS = new Set(["edit", "write", "patch", "apply_patch"]);
+const TIMEOUT_MS = { context: 20000, stage: 10000, capture: 60000, reset: 10000 };
+${OPENCODE_RUNTIME}/** @type {import("@opencode-ai/plugin").Plugin} */
+export const CodeBuddyPlugin = async ({ directory }) => {
+  /** @type {Map<string, { text: string, commands: Array<{ command: string, exit_code: number | null }> }>} */
+  const turns = new Map();
+  const turn = (sessionID) => {
+    if (!turns.has(sessionID)) turns.set(sessionID, { text: "", commands: [] });
+    return turns.get(sessionID);
+  };
+  const base = (sessionID, event) => ({ session_id: sessionID, cwd: directory, hook_event_name: event });
+
+  return {
+    "chat.message": async (input, output) => {
+      turns.delete(input.sessionID);
+      const prompt = output.parts
+        .flatMap((part) => (part.type === "text" && !part.synthetic ? [part.text] : []))
+        .join("\\n")
+        .trim();
+      const block = (
+        await hook("context", { ...base(input.sessionID, "chat.message"), ...(prompt ? { prompt } : {}) })
+      ).trim();
+      if (!block) return;
+      output.parts.push({
+        id: partId(),
+        sessionID: input.sessionID,
+        messageID: output.message.id,
+        type: "text",
+        text: block,
+        synthetic: true,
+      });
+    },
+    "tool.execute.after": async (input, output) => {
+      if (EDIT_TOOLS.has(input.tool)) {
+        await hook("stage", {
+          ...base(input.sessionID, "tool.execute.after"),
+          tool_name: input.tool,
+          tool_input: input.args,
+        });
+      } else if (input.tool === "bash" && typeof input.args?.command === "string") {
+        const exit = output.metadata?.exit;
+        turn(input.sessionID).commands.push({
+          command: input.args.command,
+          exit_code: typeof exit === "number" ? exit : null,
+        });
+      }
+    },
+    "experimental.text.complete": async (input, output) => {
+      if (output.text.trim()) turn(input.sessionID).text = output.text;
+    },
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        const sessionID = event.properties.sessionID;
+        const current = turns.get(sessionID);
+        turns.delete(sessionID);
+        await hook("capture", {
+          ...base(sessionID, "session.idle"),
+          ...(current?.text ? { last_assistant_message: current.text } : {}),
+          ...(current?.commands.length ? { shell_commands: current.commands.slice(-20) } : {}),
+        });
+      } else if (event.type === "session.compacted") {
+        await hook("reset", { ...base(event.properties.sessionID, "session.compacted"), source: "compact" });
+      }
+    },
+  };
+};
+`;
+}
+var OPENCODE_PLUGIN_SOURCE = renderOpencodePlugin("full");
+function opencodePluginPath(repositoryRoot) {
+  return join5(resolve4(repositoryRoot), ".opencode", "plugins", "codebuddy.js");
+}
+function plugin2(repositoryRoot, variant = "full") {
+  const path = opencodePluginPath(repositoryRoot);
+  return {
+    marker: OPENCODE_PLUGIN_MARKER,
+    files: [{ path, content: renderOpencodePlugin(variant) }],
+    dirs: [dirname5(path), dirname5(dirname5(path))]
+  };
+}
+function opencodePluginInstalled(repositoryRoot) {
+  return managedPluginInstalled(plugin2(repositoryRoot));
+}
+function setOpencodePlugin(repositoryRoot, enabled, variant = "full") {
+  return setManagedPlugin(plugin2(repositoryRoot, variant), enabled);
+}
+async function opencodePluginVariant(repositoryRoot) {
+  if (!await opencodePluginInstalled(repositoryRoot)) return null;
+  const source = await readFile5(opencodePluginPath(repositoryRoot), "utf8");
+  return source.startsWith(`${OPENCODE_PLUGIN_MARKER} v1 lean`) ? "lean" : "full";
+}
+
+// src/hooks/settings.ts
+import { mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
+import { dirname as dirname6, join as join6, resolve as resolve5 } from "path";
+var HOOK_COMMAND_PREFIX = "codebuddy hooks";
+var TOOL_GUARD_DEF = {
+  event: "PreToolUse",
+  matcher: "Read|Grep",
+  command: `${HOOK_COMMAND_PREFIX} pretool`
+};
+var HOOK_DEFS = [
+  { event: "UserPromptSubmit", command: `${HOOK_COMMAND_PREFIX} context` },
+  {
+    event: "PostToolUse",
+    matcher: "Edit|Write|MultiEdit",
+    command: `${HOOK_COMMAND_PREFIX} stage`
+  },
+  { event: "Stop", command: `${HOOK_COMMAND_PREFIX} capture` },
+  // After compaction or /clear the model no longer holds earlier context, so
+  // capsules the session ledger marked as sent must be sent again.
+  { event: "SessionStart", matcher: "compact|clear", command: `${HOOK_COMMAND_PREFIX} reset` },
+  TOOL_GUARD_DEF
+];
+var LEAN_HOOK_DEFS = [
+  { event: "UserPromptSubmit", command: `${HOOK_COMMAND_PREFIX} lean` },
+  { event: "SessionStart", matcher: "compact|clear", command: `${HOOK_COMMAND_PREFIX} reset` },
+  TOOL_GUARD_DEF
+];
+function claudeSettingsPath(repositoryRoot = process.cwd()) {
+  return join6(resolve5(repositoryRoot), ".claude", "settings.json");
+}
+function upsertHooks(settings, variant = "full") {
+  const defs = variant === "lean" ? LEAN_HOOK_DEFS : HOOK_DEFS;
+  const wanted = new Set(defs.map((def) => def.command));
+  const next = { ...settings, hooks: { ...settings.hooks ?? {} } };
+  const hooks = next.hooks;
+  let changed = false;
+  for (const event of Object.keys(hooks)) {
+    const groups = [];
+    for (const group of hooks[event] ?? []) {
+      const kept = (group.hooks ?? []).filter(
+        (hook) => !hook.command?.startsWith(HOOK_COMMAND_PREFIX) || wanted.has(hook.command)
+      );
+      if (kept.length !== (group.hooks ?? []).length) changed = true;
+      if (kept.length > 0) groups.push({ ...group, hooks: kept });
+    }
+    if (groups.length > 0) hooks[event] = groups;
+    else delete hooks[event];
+  }
+  for (const def of defs) {
+    const groups = [...hooks[def.event] ?? []];
+    const existingIndex = groups.findIndex(
+      (group) => group.hooks?.some((hook) => hook.command === def.command)
+    );
+    if (existingIndex === -1) {
+      groups.push({
+        ...def.matcher ? { matcher: def.matcher } : {},
+        hooks: [{ type: "command", command: def.command }]
+      });
+      changed = true;
+    } else {
+      const existing = groups[existingIndex];
+      if (existing && (def.matcher ?? void 0) !== (existing.matcher ?? void 0)) {
+        const { matcher: _oldMatcher, ...rest } = existing;
+        groups[existingIndex] = def.matcher ? { ...rest, matcher: def.matcher } : rest;
+        changed = true;
+      }
+    }
+    hooks[def.event] = groups;
+  }
+  return { settings: next, changed };
+}
+function removeHooks(settings) {
+  if (!settings.hooks) return { settings, changed: false };
+  const next = { ...settings, hooks: { ...settings.hooks } };
+  const hooks = next.hooks;
+  let changed = false;
+  for (const event of Object.keys(hooks)) {
+    const keptGroups = [];
+    for (const group of hooks[event] ?? []) {
+      const keptHooks = (group.hooks ?? []).filter(
+        (hook) => !hook.command?.startsWith(HOOK_COMMAND_PREFIX)
+      );
+      if (keptHooks.length !== (group.hooks ?? []).length) changed = true;
+      if (keptHooks.length === 0) continue;
+      keptGroups.push({ ...group, hooks: keptHooks });
+    }
+    if (keptGroups.length === 0) delete hooks[event];
+    else hooks[event] = keptGroups;
+  }
+  return { settings: next, changed };
+}
+function hooksInstalled(settings) {
+  const hooks = settings.hooks ?? {};
+  return Object.values(hooks).some(
+    (groups) => groups.some((group) => group.hooks?.some((h) => h.command?.startsWith(HOOK_COMMAND_PREFIX)))
+  );
+}
+function hooksVariant(settings) {
+  if (!hooksInstalled(settings)) return null;
+  const leanCommand = `${HOOK_COMMAND_PREFIX} lean`;
+  const lean = Object.values(settings.hooks ?? {}).some(
+    (groups) => groups.some((group) => group.hooks?.some((hook) => hook.command === leanCommand))
+  );
+  return lean ? "lean" : "full";
+}
+async function readSettings(path) {
+  try {
+    return JSON.parse(await readFile6(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+async function writeSettings(path, settings) {
+  await mkdir4(dirname6(path), { recursive: true });
+  await writeAtomic(path, `${JSON.stringify(settings, null, 2)}
+`, { mode: 420 });
+}
+
+// src/hooks/install.ts
+var SURFACES = {
+  "claude-settings": {
+    path: claudeSettingsPath,
+    installed: async (root) => hooksInstalled(await readSettings(claudeSettingsPath(root))),
+    variant: async (root) => hooksVariant(await readSettings(claudeSettingsPath(root))),
+    set: async (root, enabled, variant) => {
+      const path = claudeSettingsPath(root);
+      const current = await readSettings(path);
+      const { settings, changed } = enabled ? upsertHooks(current, variant) : removeHooks(current);
+      if (changed) await writeSettings(path, settings);
+      return changed;
+    }
+  },
+  "opencode-plugin": {
+    path: opencodePluginPath,
+    installed: opencodePluginInstalled,
+    variant: opencodePluginVariant,
+    set: setOpencodePlugin
+  },
+  "hermes-plugin": {
+    path: hermesPluginDir,
+    installed: hermesPluginInstalled,
+    variant: hermesPluginVariant,
+    set: setHermesPlugin
+  }
+};
+async function setClientHooks(root, client, enabled, variant = "full") {
+  const surface = CLIENT_ADAPTERS[client].hooks;
+  if (!surface) return null;
+  const { path, set } = SURFACES[surface];
+  return { target: path(root), changed: await set(root, enabled, variant) };
+}
+async function clientHooksVariant(root, client) {
+  const surface = CLIENT_ADAPTERS[client].hooks;
+  if (!surface) return void 0;
+  return SURFACES[surface].variant(root);
+}
+async function clientHooksInstalled(root, client) {
+  const surface = CLIENT_ADAPTERS[client].hooks;
+  return surface ? SURFACES[surface].installed(root) : null;
+}
+async function hookedRulesSiblings(root, client) {
+  const file = CLIENT_ADAPTERS[client].rulesFile;
+  const hooked = [];
+  for (const id of CLIENT_IDS) {
+    if (id !== client && CLIENT_ADAPTERS[id].rulesFile === file && await clientHooksInstalled(root, id))
+      hooked.push(id);
+  }
+  return hooked;
+}
+async function rulesFileHooked(root, client) {
+  return await clientHooksInstalled(root, client) === true || (await hookedRulesSiblings(root, client)).length > 0;
+}
+
+// src/templates/workflow.ts
+var WORKFLOW_CLIENTS = CLIENT_IDS;
+var INTRO = [
+  "You have CodeBuddy available as a local, MCP-backed project-context engine.",
+  "Use it to work like a careful senior engineer, not to dump broad context.",
+  ""
+];
+var START_AGENT = [
+  "## At the start of a substantive coding turn",
+  "",
+  "1. When project context is needed, call `context_pack` with the user's task and a token budget (start",
+  "   with 4000). It automatically finds relevant files and returns bounded symbols,",
+  "   plan, policy, incidents, risks, architecture neighbours, and team facts.",
+  "   Reuse evidence already present. For a clearly identified small edit, read the",
+  "   needed source directly; fetch context for unknown dependencies or project constraints.",
+  "   Read missing function bodies before editing. If safety evidence was omitted,",
+  "   narrow the targets or increase the budget before proceeding.",
+  "2. Use `context_bootstrap` only when you need broad project orientation beyond",
+  "   the task pack. Use `context_before_edit` when you already have exact paths",
+  "   or a plan and need a narrower follow-up.",
+  "3. Prior work from earlier chats arrives as `handoffs` with freshness",
+  "   (`changedSince`, `missing`); re-check those files before relying on it.",
+  "4. On repeated context calls in one conversation, pass a stable `sessionId` and",
+  "   the previous response's `delivery.deliveryId` as `ack`. Unchanged sections",
+  "   are then omitted and listed in `delivery.unchanged`. If earlier output is no",
+  "   longer in your context (e.g. after compaction), pass `full: true`.",
+  ""
+];
+var START_HOOKS = [
+  "## At the start of a substantive coding turn",
+  "",
+  "CodeBuddy hooks inject a `CodeBuddy project context (auto-recalled)` block into",
+  "each prompt: project, plan, policies, facts, incidents, handoffs, current",
+  "changes, and risk. Agents without CodeBuddy hooks (no such block in the prompt)",
+  "follow the agent-driven flow: `context_pack` first, `context_after_turn` last.",
+  "",
+  "1. Start from the injected block; do not call `context_bootstrap` for orientation",
+  "   it already covers.",
+  "2. Call `context_pack` (or `context_before_edit` with exact paths) only when the",
+  "   task needs symbols, neighbours, or file-level evidence the block lacks. Pass the",
+  "   block's `session` value as `sessionId` and the previous `delivery.deliveryId`",
+  "   as `ack` so unchanged sections are not resent.",
+  "3. Prior work from earlier chats arrives as handoffs with freshness; re-check",
+  "   those files before relying on it.",
+  ""
+];
+var MIDDLE = [
+  "## While implementing",
+  "",
+  "- Prefer the smallest sufficient set of edits; preserve existing behavior.",
+  "- Honor risk warnings and policy rules for the files you touch; call out risk",
+  "  before editing sensitive areas.",
+  "- Do not re-request broad context if the task pack already suffices.",
+  "",
+  "## Before finalizing",
+  "",
+  "- Consider calling `code_suggestions` (with `paths`, `planId`, or `useGit`) for",
+  "  read-only, evidence-backed quality findings; resolve high-severity ones.",
+  "- Run the smallest relevant verification (tests, lint, typecheck) and fix",
+  "  failures before presenting completion.",
+  ""
+];
+var AFTER_AGENT = [
+  "## After a meaningful turn",
+  "",
+  "- Call `context_after_turn` with a concise `summary`, the `changedFiles`, and a",
+  "  `planId` if one is active, plus `verification` (commands run and results)",
+  "  so the turn's worklog handoff records it. CodeBuddy auto-saves confident facts, decisions,",
+  "  and incidents, queues uncertain or sensitive items for review, and drops",
+  "  chatter. Never paste secrets, tokens, or credentials into the summary.",
+  ""
+];
+var AFTER_HOOKS = [
+  "## After a meaningful turn",
+  "",
+  "- Do not call `context_after_turn`: the turn-end hook captures the turn once, from",
+  "  the real change set and the verification commands you ran. A second capture",
+  "  would record a divergent worklog entry.",
+  "- Never paste secrets, tokens, or credentials into your final message; it is the",
+  "  capture summary.",
+  ""
+];
+var TAIL = [
+  "## If a tool or service is unavailable (degraded mode)",
+  "",
+  "- A CodeBuddy MCP tool errors or is missing: proceed using the repository",
+  "  itself as the source of truth; do not block on it.",
+  "- Postgres is unreachable: the file-based tools (context, plan, risk, map,",
+  "  suggest) still work; recall and embeddings may be degraded \u2014 say so instead",
+  "  of inventing remembered facts.",
+  "- Retrieval returns no context: read the relevant files directly rather than",
+  "  guessing; the working tree is authoritative.",
+  "",
+  "## Never",
+  "",
+  "- Invent behavior the codebase does not support.",
+  "- Ignore failing tests or lint.",
+  "- Make speculative, wide changes without evidence.",
+  "- Save low-confidence project memory as a durable fact."
+];
+function renderBody(mode) {
+  return [
+    ...INTRO,
+    ...mode === "hooks" ? START_HOOKS : START_AGENT,
+    ...MIDDLE,
+    ...mode === "hooks" ? AFTER_HOOKS : AFTER_AGENT,
+    ...TAIL
+  ].join("\n");
+}
+function rulesReaders(file) {
+  return CLIENT_IDS.filter((id) => CLIENT_ADAPTERS[id].rulesFile === file).map((id) => CLIENT_ADAPTERS[id].name).join(", ");
+}
+function renderWorkflowTemplate(client, mode = "agent") {
+  const file = CLIENT_ADAPTERS[client].rulesFile;
+  return [
+    `# CodeBuddy workflow (${rulesReaders(file)})`,
+    "",
+    "This section is managed by CodeBuddy (`codebuddy clients install <client> --mode <mode>`)",
+    `and lives in \`${file}\`. Edit outside the managed markers to customize.`,
+    `Automation mode: \`${mode}\` (${MODE_LABELS[mode]}).`,
+    "",
+    renderBody(mode)
+  ].join("\n");
+}
+function parseWorkflowMode(block) {
+  return block.match(/Automation mode: `(hooks|agent)`/)?.[1] === "hooks" ? "hooks" : "agent";
+}
+function defaultRulesFile(client) {
+  return CLIENT_ADAPTERS[client].rulesFile;
+}
+function clientDisplayName(client) {
+  return CLIENT_ADAPTERS[client].name;
+}
+
+// src/templates/install.ts
+var START_MARKER = "<!-- codebuddy:workflow:start -->";
+var END_MARKER = "<!-- codebuddy:workflow:end -->";
+function renderManagedBlock(client, mode = "agent") {
+  return `${START_MARKER}
+${renderWorkflowTemplate(client, mode)}
+${END_MARKER}
+`;
+}
+async function installWorkflowRules(options) {
+  const projectRoot = resolve6(options.projectRoot ?? process.cwd());
+  const path = options.targetPath ?? join7(projectRoot, defaultRulesFile(options.client));
+  const existing = await readIfPresent(path);
+  const mode = options.mode ?? await defaultRulesMode(options.client, projectRoot);
+  if (options.onlyIfManaged && (existing === null || !hasManagedBlock(existing))) {
+    return { path, client: options.client, action: "unchanged" };
+  }
+  if (mode === "mcp-only") {
+    const content2 = existing === null ? null : removeBlock(existing);
+    if (content2 === null || content2 === existing) {
+      return { path, client: options.client, action: "unchanged" };
+    }
+    if (content2.trim() === "") await rm2(path, { force: true });
+    else await writeAtomic(path, content2, { mode: 420 });
+    return { path, client: options.client, action: "removed" };
+  }
+  const { content, action } = upsertBlock(existing, renderManagedBlock(options.client, mode));
+  if (action === "unchanged") return { path, client: options.client, action };
+  await writeAtomic(path, content, { mode: 420 });
+  return { path, client: options.client, action };
+}
+function upsertBlock(existing, block) {
+  if (existing === null) return { content: block, action: "created" };
+  const start = existing.indexOf(START_MARKER);
+  const end = existing.indexOf(END_MARKER);
+  if (start !== -1 && end !== -1 && end > start) {
+    const before = existing.slice(0, start);
+    const after = existing.slice(end + END_MARKER.length).replace(/^\n/, "");
+    const replaced = `${before}${block}${after}`;
+    return { content: replaced, action: replaced === existing ? "unchanged" : "updated" };
+  }
+  const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return { content: `${existing}${separator}${block}`, action: "added" };
+}
+async function defaultRulesMode(client, projectRoot = process.cwd()) {
+  return await rulesFileHooked(projectRoot, client) ? "hooks" : "agent";
+}
+async function readManagedMode(path) {
+  const existing = await readIfPresent(path);
+  if (existing === null || !hasManagedBlock(existing)) return null;
+  return parseWorkflowMode(existing.slice(existing.indexOf(START_MARKER)));
+}
+function hasManagedBlock(content) {
+  const start = content.indexOf(START_MARKER);
+  return start !== -1 && content.indexOf(END_MARKER) > start;
+}
+function removeBlock(existing) {
+  if (!hasManagedBlock(existing)) return existing;
+  const start = existing.indexOf(START_MARKER);
+  const end = existing.indexOf(END_MARKER) + END_MARKER.length;
+  const before = existing.slice(0, start).replace(/\n\n$/, "\n");
+  const after = existing.slice(end).replace(/^\n/, "");
+  return `${before}${after}`;
+}
+async function readIfPresent(path) {
+  try {
+    return await readFile7(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+// src/clients/cost.ts
+async function mcpSchemaTokens(root, namespace) {
+  const server = new McpServer({ name: "codebuddy", version: VERSION });
+  registerCodeBuddyTools(server, {
+    config: { namespace, projectRoot: root },
+    database: {
+      get: () => Promise.reject(new Error("not used")),
+      status: () => ({ available: false, state: "idle" })
+    }
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "codebuddy-cost", version: VERSION });
+  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+  try {
+    const { tools } = await client.listTools();
+    return {
+      full: estimateTokens(tools),
+      listing: estimateTokens(tools.map((tool) => tool.name).join("\n"))
+    };
+  } finally {
+    await client.close();
+  }
+}
+async function hookBlockTokens(root, namespace) {
+  const bootstrap = await buildBootstrapContext({ repositoryRoot: root, namespace });
+  const beforeEdit = await buildBeforeEditContext({
+    repositoryRoot: root,
+    namespace,
+    useGit: true
+  }).catch(() => null);
+  const scratch = await mkdtemp(join8(tmpdir(), "codebuddy-cost-"));
+  try {
+    const ledger = new SessionCapsuleLedger(scratch);
+    const render = () => renderContextBlock(bootstrap, beforeEdit, ledger, "cost", true);
+    const first = await render();
+    await ledger.markSent("cost", first.emitted);
+    const later = await render();
+    const pointers = (beforeEdit?.targetPaths ?? []).map((path) => ({ path, symbols: [] }));
+    const renderLean = () => renderLeanBlock({ repositoryRoot: root, prompt: "", pointers, ledger, sessionId: "lean" });
+    const leanFirst = await renderLean();
+    await ledger.markSent("lean", leanFirst.emitted);
+    const leanLater = await renderLean();
+    return {
+      first: estimateTokens(first.text),
+      later: estimateTokens(later.text),
+      lean: { first: estimateTokens(leanFirst.text), later: estimateTokens(leanLater.text) }
+    };
+  } finally {
+    await rm3(scratch, { recursive: true, force: true });
+  }
+}
+async function measureClientCosts(projectRoot = process.cwd(), namespace) {
+  const root = resolve7(projectRoot);
+  const ns = namespace ?? await resolveNamespaceFrom(root);
+  const mcpSchema = await mcpSchemaTokens(root, ns);
+  const block = await hookBlockTokens(root, ns);
+  return CLIENT_IDS.flatMap((client) => {
+    const adapter = CLIENT_ADAPTERS[client];
+    return supportedModes(adapter).flatMap((mode) => {
+      if (mode === "mcp-only") return [];
+      if (mode === "lean") {
+        const later2 = adapter.ephemeralContext ? block.lean.first : block.lean.later;
+        return [
+          { client, mode, rules: 0, mcpSchema: 0, firstBlock: block.lean.first, laterBlock: later2 }
+        ];
+      }
+      const hooks = mode === "hooks";
+      const later = adapter.ephemeralContext ? block.first : block.later;
+      return [
+        {
+          client,
+          mode,
+          rules: estimateTokens(renderManagedBlock(client, mode)),
+          mcpSchema: adapter.defersMcpSchemas ? mcpSchema.listing : mcpSchema.full,
+          firstBlock: hooks ? block.first : 0,
+          laterBlock: hooks ? later : 0
+        }
+      ];
+    });
+  });
+}
+
+// src/clients/install.ts
+import { access as access4 } from "fs/promises";
+import { join as join12, resolve as resolve9 } from "path";
+
+// src/integrations/project-mcp.ts
+import { access as access3, mkdir as mkdir5, readFile as readFile8, rm as rm4 } from "fs/promises";
+import { dirname as dirname7, join as join9, resolve as resolve8 } from "path";
+async function writeProjectMcpConfig(options) {
+  const path = join9(options.repositoryRoot, ".mcp.json");
+  const current = await readProjectMcpConfig(path);
+  current.mcpServers ??= {};
+  current.mcpServers[`codebuddy-${options.namespace}`] = codebuddyMcpServer(
+    options.repositoryRoot,
+    options.namespace
+  );
+  if (options.graphify) {
+    current.mcpServers.graphify = {
+      command: "python",
+      args: [
+        "-m",
+        "graphify.serve",
+        resolve8(options.repositoryRoot, options.graphPath ?? "graphify-out/graph.json")
+      ],
+      env: { CODEBUDDY_PROJECT_ROOT: options.repositoryRoot }
+    };
+  } else if (current.mcpServers.graphify) {
+    delete current.mcpServers.graphify;
+  }
+  await writeAtomic(path, `${JSON.stringify(current, null, 2)}
+`, { mode: 420 });
+  return { path, servers: Object.keys(current.mcpServers).sort() };
+}
+var OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+function codebuddyMcpServer(repositoryRoot, namespace) {
+  return {
+    command: "codebuddy",
+    args: ["serve"],
+    env: {
+      CODEBUDDY_PROJECT_ROOT: repositoryRoot,
+      CODEBUDDY_NAMESPACE: namespace,
+      CODEBUDDY_TOOL_PROFILE: "core"
+    }
+  };
+}
+async function projectMcpPath(root, file, format) {
+  const path = join9(root, file);
+  if (format !== "opencode" || await exists(path)) return path;
+  return await exists(`${path}c`) ? `${path}c` : path;
+}
+async function exists(path) {
+  return access3(path).then(
+    () => true,
+    () => false
+  );
+}
+function formatEntry(format, server) {
+  if (format === "mcpServers") return server;
+  return {
+    type: "local",
+    command: [server.command, ...server.args],
+    ...server.env ? { environment: server.env } : {},
+    enabled: true
+  };
+}
+function serversKey(format) {
+  return format === "opencode" ? "mcp" : "mcpServers";
+}
+async function upsertMcpServer(path, format, name, server) {
+  const existed = await exists(path);
+  const { config, comments } = await readConfig(path);
+  const key = serversKey(format);
+  const servers2 = { ...config[key] ?? {} };
+  const entry = formatEntry(format, server);
+  if (JSON.stringify(servers2[name]) === JSON.stringify(entry)) return "unchanged";
+  if (comments) return "manual";
+  servers2[name] = entry;
+  const next = format === "opencode" && !existed ? { $schema: OPENCODE_SCHEMA, ...config, [key]: servers2 } : { ...config, [key]: servers2 };
+  await mkdir5(dirname7(path), { recursive: true });
+  await writeAtomic(path, `${JSON.stringify(next, null, 2)}
+`, { mode: 420 });
+  return existed ? "updated" : "created";
+}
+async function removeMcpServer(path, format, name) {
+  const { config, comments } = await readConfig(path);
+  const key = serversKey(format);
+  const servers2 = { ...config[key] ?? {} };
+  if (!(name in servers2)) return "unchanged";
+  if (comments) return "manual";
+  delete servers2[name];
+  const next = { ...config, [key]: servers2 };
+  const leftover = Object.keys(next).filter((k) => k !== key && k !== "$schema");
+  if (Object.keys(servers2).length === 0 && leftover.length === 0) await rm4(path, { force: true });
+  else await writeAtomic(path, `${JSON.stringify(next, null, 2)}
+`, { mode: 420 });
+  return "removed";
+}
+async function hasMcpServer(path, format, name) {
+  const { config } = await readConfig(path);
+  return name in (config[serversKey(format)] ?? {});
+}
+function parseJsonc(raw) {
+  let comments = false;
+  const json2 = raw.replace(/"(?:[^"\\]|\\.)*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (match) => {
+    if (match.startsWith('"')) return match;
+    comments = true;
+    return " ";
+  }).replace(/"(?:[^"\\]|\\.)*"|,(\s*[}\]])/g, (match, tail) => tail ?? match);
+  return { value: JSON.parse(json2), comments };
+}
+async function readConfig(path) {
+  try {
+    const { value, comments } = parseJsonc(await readFile8(path, "utf8"));
+    const config = value && typeof value === "object" ? value : {};
+    return { config, comments };
+  } catch (error) {
+    if (error.code === "ENOENT") return { config: {}, comments: false };
+    throw new Error(`Could not read ${path}: ${error.message}`);
+  }
+}
+async function readProjectMcpConfig(path) {
+  return (await readConfig(path)).config;
+}
+
+// src/cli/commands/codex.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir6, readFile as readFile9 } from "fs/promises";
+import { homedir } from "os";
+import { dirname as dirname8, join as join10 } from "path";
+function codexConfigPath(home = homedir()) {
+  return join10(home, ".codex", "config.toml");
+}
+async function readCodexConfig(path) {
+  if (!existsSync2(path)) return "";
+  return readFile9(path, "utf8");
+}
+async function writeCodexConfig(path, content) {
+  await mkdir6(dirname8(path), { recursive: true });
+  await writeAtomic(path, content, { mode: 384 });
+}
+async function installCodexEntry(options) {
+  const path = codexConfigPath();
+  const serverKey = options.serverName ?? `codebuddy-${options.namespace}`;
+  const current = await readCodexConfig(path);
+  const existed = hasServerBlock(current, serverKey);
+  const entry = buildEntry(options);
+  if (options.toolProfile)
+    entry.env = { ...entry.env, CODEBUDDY_TOOL_PROFILE: options.toolProfile };
+  const next = upsertServerBlock(current, serverKey, entry);
+  if (next !== current) await writeCodexConfig(path, next);
+  return { path, serverKey, created: !existed, changed: next !== current };
+}
+async function removeCodexEntry(serverKey) {
+  const path = codexConfigPath();
+  const current = await readCodexConfig(path);
+  const next = removeServerBlock(current, serverKey);
+  const removed = next !== current;
+  const trimmed = next.trimEnd();
+  if (removed) await writeCodexConfig(path, trimmed ? `${trimmed}
+` : "");
+  return { removed, path };
+}
+async function listCodexEntries() {
+  const path = codexConfigPath();
+  const config = await readCodexConfig(path);
+  const entries = Array.from(config.matchAll(/^\[mcp_servers\."([^"]+)"\]\s*$/gm)).flatMap((match) => match[1] ? [match[1]] : []).filter((key) => key === "codebuddy" || key.startsWith("codebuddy-")).map((key) => {
+    const block = getServerBlock(config, key);
+    return {
+      key,
+      namespace: readEnvValue(block, "CODEBUDDY_NAMESPACE"),
+      databaseUrl: readEnvValue(block, "DATABASE_URL")
+    };
+  });
+  return { path, entries };
+}
+function upsertServerBlock(config, serverKey, entry) {
+  const trimmed = removeServerBlock(config, serverKey).trimEnd();
+  const block = formatServerBlock(serverKey, entry);
+  return `${trimmed}${trimmed ? "\n\n" : ""}${block}
+`;
+}
+function removeServerBlock(config, serverKey) {
+  const escaped = escapeRegExp(serverKey);
+  const end = String.raw`(?![\s\S])`;
+  const sectionPattern = String.raw`^\[mcp_servers\."${escaped}"\][\s\S]*?(?=^\[[^\]]+\]\s*$|${end})`;
+  const envPattern = String.raw`^\[mcp_servers\."${escaped}"\.env\][\s\S]*?(?=^\[[^\]]+\]\s*$|${end})`;
+  return config.replace(new RegExp(sectionPattern, "gm"), "").replace(new RegExp(envPattern, "gm"), "");
+}
+function getServerBlock(config, serverKey) {
+  const escaped = escapeRegExp(serverKey);
+  const end = String.raw`(?![\s\S])`;
+  const pattern = String.raw`^\[mcp_servers\."${escaped}"\][\s\S]*?(?=^\[mcp_servers\."${escaped}"\.env\][\s\S]*?(?=^\[[^\]]+\]\s*$|${end})|^\[[^\]]+\]\s*$|${end})`;
+  const server = config.match(new RegExp(pattern, "m"))?.[0] ?? "";
+  const env = config.match(
+    new RegExp(
+      String.raw`^\[mcp_servers\."${escaped}"\.env\][\s\S]*?(?=^\[[^\]]+\]\s*$|${end})`,
+      "m"
+    )
+  )?.[0] ?? "";
+  return `${server}
+${env}`;
+}
+function hasServerBlock(config, serverKey) {
+  return new RegExp(String.raw`^\[mcp_servers\."${escapeRegExp(serverKey)}"\]\s*$`, "m").test(
+    config
+  );
+}
+function formatServerBlock(serverKey, entry) {
+  const lines = [
+    `[mcp_servers.${tomlKey(serverKey)}]`,
+    `command = ${tomlString(entry.command)}`,
+    `args = ${tomlArray(entry.args)}`
+  ];
+  if (entry.env && Object.keys(entry.env).length > 0) {
+    lines.push("", `[mcp_servers.${tomlKey(serverKey)}.env]`);
+    for (const [key, value] of Object.entries(entry.env).sort(
+      ([left], [right]) => left.localeCompare(right)
+    )) {
+      lines.push(`${key} = ${tomlString(value)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function readEnvValue(block, key) {
+  return block.match(new RegExp(`^${escapeRegExp(key)}\\s*=\\s*"([^"]*)"`, "m"))?.[1] ?? null;
+}
+function tomlKey(key) {
+  return `"${key.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+function tomlArray(values) {
+  return `[${values.map(tomlString).join(", ")}]`;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/integrations/hermes-config.ts
+import { mkdir as mkdir7, readFile as readFile10 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname9, join as join11 } from "path";
+import { isDeepStrictEqual } from "util";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+function hermesConfigPath(home = homedir2()) {
+  return join11(process.env.HERMES_HOME ?? join11(home, ".hermes"), "config.yaml");
+}
+async function readRaw(path) {
+  try {
+    return await readFile10(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+function parseConfig(raw) {
+  try {
+    const value = parseYaml(raw) ?? {};
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function servers(config) {
+  const value = config.mcp_servers;
+  return value && typeof value === "object" ? value : {};
+}
+var isItem = (line) => line.trim() !== "" && !line.trim().startsWith("#");
+var indentOf = (line) => line.length - line.trimStart().length;
+function editMcpServers(raw, name, entry) {
+  const lines = raw.split("\n");
+  const header = lines.findIndex((line) => /^mcp_servers:\s*(#.*)?$/.test(line));
+  const render = (indent2) => stringifyYaml({ [name]: entry }).trimEnd().split("\n").map((line) => `${" ".repeat(indent2)}${line}`);
+  if (header === -1) {
+    if (entry === null) return raw;
+    const body = raw === "" || raw.endsWith("\n") ? raw : `${raw}
+`;
+    return `${body}mcp_servers:
+${render(2).join("\n")}
+`;
+  }
+  let end = header + 1;
+  while (end < lines.length && !/^\S/.test(lines[end] ?? "")) end++;
+  const block = Array.from({ length: end - header - 1 }, (_, i) => header + 1 + i);
+  const items = block.filter((i) => isItem(lines[i] ?? ""));
+  const indent = items.length > 0 ? indentOf(lines[items[0]] ?? "") : 2;
+  const quoted = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyLine = new RegExp(`^ {${indent}}(?:${quoted}|"${quoted}"|'${quoted}'):\\s*(#.*)?$`);
+  const start = items.find((i) => keyLine.test(lines[i] ?? ""));
+  if (start === void 0) {
+    if (entry === null) return raw;
+    const at = (items.at(-1) ?? header) + 1;
+    lines.splice(at, 0, ...render(indent));
+    return lines.join("\n");
+  }
+  const next = block.find(
+    (i) => i > start && (lines[i] ?? "").trim() !== "" && indentOf(lines[i] ?? "") <= indent
+  );
+  let stop = next ?? end;
+  while (stop > start + 1 && (lines[stop - 1] ?? "").trim() === "") stop--;
+  lines.splice(start, stop - start, ...entry === null ? [] : render(indent));
+  if (entry === null && items.length > 0 && items.every((i) => i >= start && i < stop)) {
+    lines.splice(header, 1);
+  }
+  return lines.join("\n");
+}
+async function setHermesMcpServer(path, name, entry) {
+  const raw = await readRaw(path);
+  const before = parseConfig(raw);
+  if (!before) return "manual";
+  const current = servers(before)[name];
+  if (entry === null ? current === void 0 : isDeepStrictEqual(current, entry)) {
+    return "unchanged";
+  }
+  const nextServers = { ...servers(before) };
+  if (entry === null) delete nextServers[name];
+  else nextServers[name] = entry;
+  const { mcp_servers: _, ...rest } = before;
+  const expected = Object.keys(nextServers).length > 0 ? { ...rest, mcp_servers: nextServers } : rest;
+  const next = editMcpServers(raw, name, entry);
+  if (!isDeepStrictEqual(parseConfig(next), expected)) return "manual";
+  await mkdir7(dirname9(path), { recursive: true });
+  await writeAtomic(path, next, { mode: 384 });
+  return entry === null ? "removed" : current === void 0 ? "created" : "updated";
+}
+async function readHermesConfig(path) {
+  return parseConfig(await readRaw(path));
+}
+async function hasHermesMcpServer(path, name) {
+  const config = await readHermesConfig(path);
+  return config !== null && name in servers(config);
+}
+
+// src/clients/global-mcp.ts
+function globalMcpPath(target) {
+  return target === "codex" ? codexConfigPath() : hermesConfigPath();
+}
+async function setGlobalMcp(target, options) {
+  const { name, root, namespace, enabled } = options;
+  if (target === "hermes") {
+    return setHermesMcpServer(
+      hermesConfigPath(),
+      name,
+      enabled ? codebuddyMcpServer(root, namespace) : null
+    );
+  }
+  if (!enabled) return (await removeCodexEntry(name)).removed ? "removed" : "unchanged";
+  const result = await installCodexEntry({
+    namespace,
+    projectRoot: root,
+    serverName: name,
+    toolProfile: "core"
+  });
+  return result.created ? "created" : result.changed ? "updated" : "unchanged";
+}
+async function hasGlobalMcp(target, name) {
+  if (target === "hermes") return hasHermesMcpServer(hermesConfigPath(), name);
+  return (await listCodexEntries()).entries.some((entry) => entry.key === name);
+}
+
+// src/clients/install.ts
+async function installClient(options) {
+  const adapter = CLIENT_ADAPTERS[options.client];
+  if (!supportedModes(adapter).includes(options.mode)) {
+    throw new Error(
+      `${adapter.name} does not support ${MODE_LABELS[options.mode]} mode: ${adapter.gap ?? "no lifecycle hooks"}.`
+    );
+  }
+  return apply(options, options.mode, options.mode !== "lean");
+}
+async function ensureIndex(root) {
+  const target = join12(root, ".codebuddy", "cache", "index.json");
+  const existed = await access4(target).then(
+    () => true,
+    () => false
+  );
+  if (!existed) await indexRepository({ repositoryRoot: root });
+  return { surface: "index", target, action: existed ? "unchanged" : "built" };
+}
+async function uninstallClient(options) {
+  return apply(options, "mcp-only", false);
+}
+async function apply(options, mode, keepMcp) {
+  const root = resolve9(options.projectRoot ?? process.cwd());
+  const adapter = CLIENT_ADAPTERS[options.client];
+  const steps = [];
+  const notes = [];
+  const namespace = options.namespace ?? await resolveNamespaceFrom(root);
+  const name = `codebuddy-${namespace}`;
+  const shared = sharedRulesReaders(options.client);
+  const liveSiblings = mode === "mcp-only" || mode === "lean" ? await installedWithMcp(root, shared, namespace) : [];
+  if (liveSiblings.length > 0) {
+    const path = join12(root, adapter.rulesFile);
+    steps.push({ surface: "rules", target: path, action: "kept" });
+    notes.push(
+      `Kept the CodeBuddy block in ${adapter.rulesFile}: still used by ${liveSiblings.map((id) => CLIENT_ADAPTERS[id].name).join(", ")}.`
+    );
+  } else {
+    const hooked = mode === "agent" ? await hookedRulesSiblings(root, options.client) : [];
+    const rules = await installWorkflowRules({
+      client: options.client,
+      projectRoot: root,
+      // Lean sends no rules: the block would cost tokens every turn and shadow AGENTS.md.
+      mode: mode === "lean" ? "mcp-only" : hooked.length > 0 ? "hooks" : mode
+    });
+    steps.push({ surface: "rules", target: rules.path, action: rules.action });
+    if (hooked.length > 0) {
+      notes.push(
+        `Kept ${adapter.rulesFile} hook-driven: ${hooked.map((id) => CLIENT_ADAPTERS[id].name).join(", ")} hooks are installed; agents without hooks follow its agent-driven fallback.`
+      );
+    }
+  }
+  if (shared.length > 0) {
+    notes.push(
+      `${adapter.rulesFile} is also read by ${shared.map((id) => CLIENT_ADAPTERS[id].name).join(", ")}.`
+    );
+  }
+  const hooks = await setHooks(
+    root,
+    mode === "hooks" || mode === "lean",
+    options.client,
+    mode === "lean" ? "lean" : "full"
+  );
+  if (hooks) steps.push(hooks);
+  if (mode === "lean") steps.push(await ensureIndex(root));
+  if ("file" in adapter.mcp) {
+    const path = await projectMcpPath(root, adapter.mcp.file, adapter.mcp.format);
+    const action = keepMcp ? await upsertMcpServer(path, adapter.mcp.format, name, codebuddyMcpServer(root, namespace)) : await removeMcpServer(path, adapter.mcp.format, name);
+    steps.push({ surface: "mcp", target: path, action });
+    if (action === "manual") {
+      notes.push(
+        `${path} has comments CodeBuddy will not rewrite; ${keepMcp ? "add" : "remove"} the "${name}" entry under "mcp" by hand${keepMcp ? `: ${JSON.stringify(formatEntry(adapter.mcp.format, codebuddyMcpServer(root, namespace)))}` : ""}.`
+      );
+    }
+  } else if (options.global) {
+    const target = globalMcpPath(adapter.mcp.global);
+    const action = await setGlobalMcp(adapter.mcp.global, {
+      name,
+      root,
+      namespace,
+      enabled: keepMcp
+    });
+    steps.push({ surface: "mcp", target, action });
+    if (action === "manual") {
+      notes.push(
+        `${target} is not a YAML map CodeBuddy can edit safely; ${keepMcp ? "add" : "remove"} the "${name}" entry under mcp_servers by hand.`
+      );
+    }
+  } else {
+    notes.push(
+      `MCP config is global; ${keepMcp ? "add" : "remove"} it with --global, or: ${adapter.mcp.manual}.`
+    );
+  }
+  if (adapter.note && mode !== "mcp-only") notes.push(`${adapter.name}: ${adapter.note}.`);
+  return { client: options.client, steps, notes };
+}
+async function installedWithMcp(root, clients, namespace) {
+  const live = [];
+  for (const id of clients) {
+    if ((await detectClient(id, root, namespace)).mcp) live.push(id);
+  }
+  return live;
+}
+async function setHooks(root, enabled, client = "claude", variant = "full") {
+  const result = await setClientHooks(root, client, enabled, variant);
+  if (!result) return null;
+  const action = result.changed ? enabled ? "installed" : "removed" : "unchanged";
+  return { surface: "hooks", target: result.target, action };
+}
+async function detectClient(client, projectRoot = process.cwd(), namespace) {
+  const root = resolve9(projectRoot);
+  const adapter = CLIENT_ADAPTERS[client];
+  const rulesMode = await readManagedMode(join12(root, adapter.rulesFile));
+  const hooks = await clientHooksInstalled(root, client);
+  const name = `codebuddy-${namespace ?? await resolveNamespaceFrom(root)}`;
+  const mcp = "file" in adapter.mcp ? await hasMcpServer(
+    await projectMcpPath(root, adapter.mcp.file, adapter.mcp.format),
+    adapter.mcp.format,
+    name
+  ) : await hasGlobalMcp(adapter.mcp.global, name).catch(() => false);
+  const warnings = [];
+  if (hooks && rulesMode === "agent") {
+    warnings.push(
+      `hooks are installed but ${adapter.rulesFile} is agent-driven: retrieval and capture run twice. Run \`codebuddy clients install ${client} --mode hooks\`.`
+    );
+  }
+  if (rulesMode === "hooks" && hooks === false) {
+    warnings.push(
+      `${adapter.rulesFile} is hook-driven but hooks are not installed: turns are not captured.`
+    );
+  }
+  const effectiveRules = hooks === null && rulesMode === "hooks" ? "agent" : rulesMode;
+  const mode = hooks ? await clientHooksVariant(root, client) === "lean" ? "lean" : "hooks" : effectiveRules ?? (mcp ? "mcp-only" : "none");
+  return { client, mode, rulesMode, hooks, mcp, warnings };
+}
+
+// src/clients/verify.ts
+import { execFile } from "child_process";
+import { readFile as readFile11, realpath } from "fs/promises";
+import { join as join13, resolve as resolve10 } from "path";
+import { pathToFileURL } from "url";
+var runHost = (bin, args, cwd) => new Promise((done) => {
+  execFile(
+    bin,
+    args,
+    { cwd, timeout: 15e3, maxBuffer: 8 * 1024 * 1024 },
+    (error, stdout) => done({ ok: !error, stdout: String(stdout ?? "") })
+  );
+});
+var pass = (name, detail) => ({ name, status: "pass", detail });
+var fail = (name, detail) => ({ name, status: "fail", detail });
+var skip = (name, detail) => ({ name, status: "skip", detail });
+function json(text3) {
+  try {
+    return JSON.parse(text3);
+  } catch {
+    return null;
+  }
+}
+var CONFORMANCE = {
+  claude: async ({ root, name, run }) => {
+    const hooks = await clientHooksInstalled(root, "claude") ? pass("hooks", ".claude/settings.json has the CodeBuddy hooks") : skip("hooks", "not installed in this repo");
+    const mcp = await run("claude", ["mcp", "get", name], root);
+    return [
+      hooks,
+      mcp.ok ? pass("mcp", `claude mcp get ${name}: ${mcp.stdout.match(/Scope: (.+)/)?.[1] ?? "found"}`) : skip("mcp", `claude mcp get ${name}: not configured`)
+    ];
+  },
+  opencode: async ({ root, name, run }) => {
+    const result = await run("opencode", ["debug", "config"], root);
+    const config = json(result.stdout);
+    if (!config) return [fail("config", "opencode debug config returned no JSON")];
+    const installed = await clientHooksInstalled(root, "opencode");
+    const href = pathToFileURL(
+      join13(await realpath(root).catch(() => root), ".opencode", "plugins", "codebuddy.js")
+    ).href;
+    const loaded = config.plugin?.includes(href) === true;
+    return [
+      installed ? loaded ? pass("plugin", "opencode debug config loads .opencode/plugins/codebuddy.js") : fail("plugin", "plugin file is installed but opencode does not load it") : skip("plugin", "not installed in this repo"),
+      config.mcp?.[name] ? pass("mcp", `opencode resolves the ${name} MCP entry`) : skip("mcp", `no ${name} entry in the resolved config`)
+    ];
+  },
+  codex: async ({ root, name, run }) => {
+    const result = await run("codex", ["mcp", "list", "--json"], root);
+    const servers2 = json(result.stdout);
+    if (!Array.isArray(servers2)) return [fail("mcp", "codex mcp list --json returned no JSON")];
+    return [
+      servers2.some((server) => server.name === name) ? pass("mcp", `codex mcp list has ${name}`) : skip("mcp", `no ${name} entry (clients install codex --global adds it)`)
+    ];
+  },
+  hermes: async ({ root, name, run, env }) => {
+    const checks = [];
+    const listed = await run("hermes", ["mcp", "list"], root);
+    checks.push(
+      listed.ok && listed.stdout.includes(name) ? pass("mcp", `hermes mcp list has ${name}`) : skip("mcp", `no ${name} entry (clients install hermes --global adds it)`)
+    );
+    if (!await hermesPluginInstalled(root)) {
+      checks.push(skip("plugin", "not installed in this repo"));
+      return checks;
+    }
+    const projectPlugins = /^(1|true|yes|on)$/i.test(env.HERMES_ENABLE_PROJECT_PLUGINS ?? "") || /^\s*HERMES_ENABLE_PROJECT_PLUGINS\s*=\s*["']?(1|true|yes|on)/im.test(
+      await readFile11(join13(hermesConfigPath(), "..", ".env"), "utf8").catch(() => "")
+    );
+    const plugins = (await readHermesConfig(hermesConfigPath()))?.plugins;
+    const enabled = Array.isArray(plugins?.enabled) && plugins.enabled.includes("codebuddy");
+    checks.push(
+      projectPlugins ? pass("project-plugins", "HERMES_ENABLE_PROJECT_PLUGINS is set") : fail("project-plugins", "set HERMES_ENABLE_PROJECT_PLUGINS=1 (shell or ~/.hermes/.env)"),
+      enabled ? pass("plugin-enabled", "codebuddy is in plugins.enabled") : fail("plugin-enabled", "add codebuddy to plugins.enabled in ~/.hermes/config.yaml")
+    );
+    return checks;
+  }
+};
+async function verifyClient(client, options = {}) {
+  const root = resolve10(options.root ?? process.cwd());
+  const run = options.run ?? runHost;
+  const adapter = CLIENT_ADAPTERS[client];
+  const version = await run(adapter.host.bin, ["--version"], root);
+  const installed = version.ok ? version.stdout.match(/\d+\.\d+\.\d+/)?.[0] ?? null : null;
+  const events = LIFECYCLE_EVENTS.map((event) => ({
+    event,
+    wired: adapter.hookEvents.includes(event)
+  }));
+  if (!installed) {
+    return {
+      client,
+      installed: null,
+      verified: adapter.host.verified,
+      drift: "not-installed",
+      events,
+      checks: [skip("host", `${adapter.host.bin} not found or printed no version`)]
+    };
+  }
+  const name = `codebuddy-${options.namespace ?? await resolveNamespaceFrom(root)}`;
+  const conformance = CONFORMANCE[client];
+  const checks = conformance ? await conformance({ root, name, run, env: options.env ?? process.env }).catch(
+    (error) => [fail("conformance", error.message)]
+  ) : [];
+  return {
+    client,
+    installed,
+    verified: adapter.host.verified,
+    drift: installed === adapter.host.verified ? "match" : "drift",
+    events,
+    checks: [pass("host", `${adapter.host.bin} ${installed}`), ...checks]
+  };
+}
+
+// src/cli/commands/clients.ts
+function registerClientsCommands(program, runSafely2) {
+  const clients = program.command("clients").description("Client adapters: capabilities and explicit automation modes per coding agent.");
+  clients.command("list").option("--namespace <name>", "Namespace whose MCP entries to look for.").description("Show each client's surfaces, lifecycle coverage, and mode in this repo.").action(async (opts) => {
+    await runSafely2(async () => {
+      for (const client of CLIENT_IDS) {
+        const adapter = CLIENT_ADAPTERS[client];
+        const status = await detectClient(client, process.cwd(), opts.namespace);
+        const mcp = "file" in adapter.mcp ? adapter.mcp.file : "global (--global)";
+        const lifecycle = LIFECYCLE_EVENTS.map(
+          (event) => adapter.hookEvents.includes(event) ? pc2.green(event) : pc2.dim(`${event}\u2717`)
+        ).join(" ");
+        const ruleCost = supportedModes(adapter).flatMap(
+          (mode) => mode === "mcp-only" ? [] : [`${mode} ~${estimateTokens(renderManagedBlock(client, mode))}`]
+        ).join(", ");
+        console.log(
+          `${pc2.bold(adapter.name)} (${client}) ${pc2.dim(`verified ${adapter.host.bin} ${adapter.host.verified}`)}`
+        );
+        console.log(
+          `  rules ${adapter.rulesFile} \xB7 mcp ${mcp} \xB7 modes ${supportedModes(adapter).join("|")}`
+        );
+        console.log(`  lifecycle: ${lifecycle}`);
+        console.log(`  rules block tokens: ${ruleCost}`);
+        console.log(
+          `  this repo: ${status.mode === "none" ? pc2.dim("not installed") : pc2.cyan(status.mode)}`
+        );
+        if (adapter.gap) console.log(pc2.dim(`  missing: ${adapter.gap}`));
+        if (adapter.note) console.log(pc2.dim(`  note: ${adapter.note}`));
+        for (const warning of status.warnings) console.log(pc2.yellow(`  ! ${warning}`));
+      }
+      console.log(pc2.dim("Per-turn token cost per client: codebuddy clients cost"));
+    });
+  });
+  clients.command("install").argument("<client>", `One of: ${CLIENT_IDS.join(", ")}.`).requiredOption("--mode <mode>", `One of: ${AUTOMATION_MODES.join(", ")}.`).option("--namespace <name>", "Namespace for the MCP entry (defaults to config/folder).").option("--global", "Also add the MCP entry to the global config (Codex, Hermes).").description("Apply one automation mode: rules block, hooks, and MCP config.").action(
+    async (client, opts) => {
+      await runSafely2(async () => {
+        const mode = parseMode(opts.mode);
+        const report = await installClient({
+          client: parseClient(client),
+          mode,
+          ...opts.namespace ? { namespace: opts.namespace } : {},
+          ...opts.global ? { global: true } : {}
+        });
+        printReport2(report, `${MODE_LABELS[mode]} mode`);
+      });
+    }
+  );
+  clients.command("uninstall").argument("<client>", `One of: ${CLIENT_IDS.join(", ")}.`).option("--namespace <name>", "Namespace of the MCP entry to remove.").option("--global", "Also remove the MCP entry from the global config (Codex, Hermes).").description("Remove CodeBuddy's rules block, hooks, and MCP entry (user config untouched).").action(async (client, opts) => {
+    await runSafely2(async () => {
+      const report = await uninstallClient({
+        client: parseClient(client),
+        ...opts.namespace ? { namespace: opts.namespace } : {},
+        ...opts.global ? { global: true } : {}
+      });
+      printReport2(report, "uninstalled");
+    });
+  });
+  clients.command("verify").argument("[client]", `One of: ${CLIENT_IDS.join(", ")} (default: all).`).option("--namespace <name>", "Namespace whose MCP entries to look for.").description(
+    "Compare installed hosts with the verified versions; run no-model conformance checks."
+  ).action(async (client, opts) => {
+    await runSafely2(async () => {
+      const targets = client ? [parseClient(client)] : CLIENT_IDS;
+      for (const id of targets) {
+        const report = await verifyClient(
+          id,
+          opts.namespace ? { namespace: opts.namespace } : {}
+        );
+        const drift = report.drift === "match" ? pc2.green("match") : report.drift === "drift" ? pc2.yellow(`drift (installed ${report.installed})`) : pc2.dim("not installed");
+        console.log(
+          `${pc2.bold(CLIENT_ADAPTERS[id].name)}: verified ${report.verified} \xB7 ${drift}`
+        );
+        console.log(
+          `  events: ${report.events.map(({ event, wired }) => wired ? pc2.green(event) : pc2.dim(`${event}\u2717`)).join(" ")}`
+        );
+        for (const check of report.checks) {
+          const label = check.status === "pass" ? pc2.green("pass") : check.status === "fail" ? pc2.red("fail") : pc2.dim("skip");
+          console.log(`  ${label} ${check.name}: ${check.detail}`);
+        }
+      }
+    });
+  });
+  clients.command("cost").option("--namespace <name>", "Namespace to measure (defaults to config/folder).").option("--json", "Print the measurements as JSON.").description("Measured per-turn CodeBuddy token cost per client and mode, for this repo.").action(async (opts) => {
+    await runSafely2(async () => {
+      const costs = await measureClientCosts(process.cwd(), opts.namespace);
+      if (opts.json) {
+        console.log(JSON.stringify(costs, null, 2));
+        return;
+      }
+      console.log(
+        "client     mode    rules  mcp-schema  block(1st)  block(later)  turn(1st)  turn(later)"
+      );
+      for (const cost of costs) {
+        const fixed = cost.rules + cost.mcpSchema;
+        console.log(
+          [
+            cost.client.padEnd(10),
+            cost.mode.padEnd(7),
+            String(cost.rules).padStart(5),
+            String(cost.mcpSchema).padStart(11),
+            String(cost.firstBlock).padStart(11),
+            String(cost.laterBlock).padStart(13),
+            String(fixed + cost.firstBlock).padStart(10),
+            String(fixed + cost.laterBlock).padStart(12)
+          ].join(" ")
+        );
+      }
+      console.log(
+        pc2.dim(
+          "Measured with the cl100k estimator on the generated rules block, the MCP tools/list payload and this repo's hook block. Host framing (host-dependent, not measured):"
+        )
+      );
+      for (const id of CLIENT_IDS) console.log(pc2.dim(`  ${id}: ${CLIENT_ADAPTERS[id].framing}`));
+    });
+  });
+}
+function printReport2(report, title) {
+  console.log(`${pc2.bold(CLIENT_ADAPTERS[report.client].name)}: ${title}`);
+  for (const step of report.steps) {
+    const where = relative(process.cwd(), step.target) || step.target;
+    const label = step.action === "unchanged" ? pc2.dim(step.action) : pc2.green(step.action);
+    console.log(`  ${step.surface.padEnd(5)} ${label} ${where}`);
+  }
+  for (const note3 of report.notes) console.log(pc2.dim(`  ${note3}`));
+}
+
+// src/cli/commands/context.ts
+import pc3 from "picocolors";
+async function resolveTokenBudget(cwd = process.cwd()) {
+  const file = await readConfigFile(cwd);
+  return file.tokenBudget;
+}
+function parsePaths2(value) {
+  return value.split(",").map((path) => path.trim()).filter(Boolean);
+}
+function registerContextCommands(program, runSafely2) {
+  const context = program.command("context").description("Preview the compact project context CodeBuddy would send to an agent.");
+  context.command("bootstrap").option("--json", "Print machine-readable JSON.").description("Show start-of-turn project awareness (plan, policy, incidents, architecture).").action(async (opts) => {
+    await runSafely2(async () => {
+      const [namespace, tokenBudget] = await Promise.all([
+        resolveNamespaceFrom(),
+        resolveTokenBudget()
+      ]);
+      const result = await buildBootstrapContext({
+        namespace,
+        ...tokenBudget !== void 0 ? { tokenBudget } : {}
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      printBootstrap(result);
+    });
+  });
+  context.command("preview").argument("[task...]", "The task you are about to work on.").option("--paths <paths>", "Comma-separated repo-relative paths to target.").option("--plan <id>", "Resolve target files from a CodeBuddy plan.").option("--git", "Resolve target files from current git changes.").option("--json", "Print machine-readable JSON.").description("Show the context CodeBuddy would assemble before editing the given files.").action(
+    async (taskParts, opts) => {
+      await runSafely2(async () => {
+        const result = await runBeforeEdit(taskParts, opts);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        printBeforeEdit(result);
+      });
+    }
+  );
+  context.command("explain").argument("[task...]", "The task you are about to work on.").option("--paths <paths>", "Comma-separated repo-relative paths to target.").option("--plan <id>", "Resolve target files from a CodeBuddy plan.").option("--git", "Resolve target files from current git changes.").description("Explain why each piece of before-edit context was included.").action(async (taskParts, opts) => {
+    await runSafely2(async () => {
+      const result = await runBeforeEdit(taskParts, opts);
+      console.log(pc3.bold(`context for ${result.targetPaths.length} target path(s):`));
+      for (const line of result.explain) console.log(`  ${pc3.dim("\u2022")} ${line}`);
+    });
+  });
+}
+async function runBeforeEdit(taskParts, opts) {
+  const [namespace, tokenBudget] = await Promise.all([
+    resolveNamespaceFrom(),
+    resolveTokenBudget()
+  ]);
+  const task = taskParts.join(" ").trim();
+  return buildBeforeEditContext({
+    namespace,
+    ...task ? { task } : {},
+    ...opts.paths ? { paths: parsePaths2(opts.paths) } : {},
+    ...opts.plan ? { planId: opts.plan } : {},
+    ...opts.git !== void 0 ? { useGit: opts.git } : {},
+    ...tokenBudget !== void 0 ? { tokenBudget } : {}
+  });
+}
+function printBootstrap(ctx) {
+  console.log(`${pc3.bold("project")} ${ctx.project.namespace}  ${pc3.dim(ctx.project.root)}`);
+  console.log(
+    `${pc3.bold("plan")} ${ctx.plan ? `${ctx.plan.title} (${ctx.plan.status})` : pc3.dim("none")}  ${pc3.dim(`policy=${ctx.policy}`)}`
+  );
+  if (ctx.policyRules.length > 0) {
+    console.log(pc3.bold("policy rules:"));
+    for (const rule of ctx.policyRules) {
+      console.log(`  ${rule.id} (${rule.weight}) ${pc3.dim(rule.pattern)}`);
+    }
+  }
+  if (ctx.incidents.length > 0) {
+    console.log(pc3.bold("incident hotspots:"));
+    for (const incident of ctx.incidents) {
+      console.log(
+        `  ${severityColor(incident.severity)} ${incident.subject} ${pc3.dim(incident.summary)}`
+      );
+    }
+  }
+  printMemory(ctx);
+  console.log(
+    `${pc3.bold("architecture")} ${ctx.architecture.moduleCount} modules, ${ctx.architecture.edgeCount} edges`
+  );
+  for (const hotspot of ctx.architecture.hotspots) {
+    console.log(`  ${hotspot.path} ${pc3.dim(`in=${hotspot.inbound} out=${hotspot.outbound}`)}`);
+  }
+  printTokens(ctx);
+}
+function printBeforeEdit(ctx) {
+  console.log(
+    `${pc3.bold("targets")} ${ctx.targetPaths.length} path(s) ${pc3.dim(`(source: ${ctx.pathSource})`)}`
+  );
+  for (const path of ctx.targetPaths) console.log(`  ${path}`);
+  if (ctx.plan) console.log(`${pc3.bold("plan")} ${ctx.plan.title} (${ctx.plan.status})`);
+  if (ctx.policyRules.length > 0) {
+    console.log(pc3.bold("matching policy rules:"));
+    for (const rule of ctx.policyRules) console.log(`  ${rule.id} ${pc3.dim(rule.pattern)}`);
+  }
+  if (ctx.incidents.length > 0) {
+    console.log(pc3.bold("incidents on target paths:"));
+    for (const incident of ctx.incidents) {
+      console.log(`  ${severityColor(incident.severity)} ${incident.subject}`);
+    }
+  }
+  printMemory(ctx);
+  if (ctx.risks.items.length > 0) {
+    console.log(pc3.bold("risk:"));
+    for (const item of ctx.risks.items) {
+      console.log(`  ${item.path} ${scoreColor(item.score)} ${pc3.dim(item.reason)}`);
+    }
+  }
+  if (ctx.neighbours.length > 0) {
+    console.log(pc3.bold("import neighbours:"));
+    for (const neighbour of ctx.neighbours) {
+      console.log(
+        `  ${neighbour.path} ${pc3.dim(`\u2192${neighbour.dependsOn.length} \u2190${neighbour.dependedOnBy.length}`)}`
+      );
+    }
+  }
+  if (ctx.symbols.length > 0) {
+    console.log(pc3.bold("symbols (signatures, in place of full source):"));
+    for (const file of ctx.symbols) {
+      console.log(`  ${file.path} ${pc3.dim(`${file.signatures.length} symbol(s)`)}`);
+    }
+  }
+  if (ctx.diffs.length > 0) {
+    console.log(pc3.bold("changed hunks:"));
+    for (const diff of ctx.diffs) {
+      console.log(`  ${diff.path}${diff.truncated ? pc3.dim(" (truncated)") : ""}`);
+      for (const line of diff.patch.split("\n").slice(-8)) console.log(pc3.dim(`    ${line}`));
+    }
+  }
+  printTokens(ctx);
+}
+function printMemory(ctx) {
+  if (ctx.facts.length > 0) {
+    console.log(pc3.bold("facts:"));
+    for (const fact of ctx.facts) {
+      console.log(`  ${fact.summary} ${pc3.dim(`(${fact.confidence.toFixed(2)}, ${fact.reason})`)}`);
+    }
+  }
+  if (ctx.handoffs.length > 0) {
+    console.log(pc3.bold("prior work:"));
+    for (const handoff of ctx.handoffs) {
+      const drift = handoff.changedSince.length > 0 ? `, ${handoff.changedSince.length} file(s) changed since` : "";
+      console.log(
+        `  ${handoff.summary.replace(/\s+/g, " ").slice(0, 160)} ${pc3.dim(`(${handoff.ageDays}d ago${drift})`)}`
+      );
+    }
+  }
+}
+function printTokens(ctx) {
+  const { returnedEstimate, budget } = ctx.tokens;
+  console.log(pc3.dim(`
+~${returnedEstimate} tokens returned (budget ${budget})`));
+}
+function severityColor(severity) {
+  if (severity === "critical") return pc3.red(severity);
+  if (severity === "high") return pc3.red(severity);
+  if (severity === "medium") return pc3.yellow(severity);
+  return pc3.dim(severity);
+}
+function scoreColor(score) {
+  if (score >= 75) return pc3.red(String(score));
+  if (score >= 50) return pc3.yellow(String(score));
+  return pc3.green(String(score));
+}
+
+// src/cli/commands/eval.ts
+import pc4 from "picocolors";
+
+// src/eval/runner.ts
+import { readFile as readFile12 } from "fs/promises";
+import { dirname as dirname10, isAbsolute, join as join14, resolve as resolve11 } from "path";
+async function runEvaluation(input = {}) {
+  const datasetPath = resolve11(
+    input.datasetPath ?? join14(process.cwd(), "evals", "change-readiness.json")
+  );
+  const dataset = JSON.parse(await readFile12(datasetPath, "utf8"));
+  if (dataset.version !== 1 || !Array.isArray(dataset.cases)) {
+    throw new Error(`Unsupported evaluation dataset: ${datasetPath}`);
+  }
+  const datasetDirectory = dirname10(datasetPath);
+  const results = await Promise.all(
+    dataset.cases.map(async (evaluationCase) => {
+      const fixtureRoot = isAbsolute(evaluationCase.fixture) ? evaluationCase.fixture : resolve11(input.repositoryRoot ?? datasetDirectory, evaluationCase.fixture);
+      const report = await buildChangeReport({
+        repositoryRoot: fixtureRoot,
+        namespace: `eval:${evaluationCase.id}`,
+        paths: evaluationCase.paths,
+        useGit: false
+      });
+      const failures = [];
+      if (report.status !== evaluationCase.expectedStatus) {
+        failures.push(`status expected ${evaluationCase.expectedStatus}, got ${report.status}`);
+      }
+      if (evaluationCase.minimumRisk !== void 0 && report.risk.highestScore < evaluationCase.minimumRisk) {
+        failures.push(
+          `risk expected >= ${evaluationCase.minimumRisk}, got ${report.risk.highestScore}`
+        );
+      }
+      const categories = [
+        ...new Set(report.suggestions.map((suggestion) => suggestion.category))
+      ];
+      for (const category of evaluationCase.requiredCategories ?? []) {
+        if (!categories.includes(category)) failures.push(`missing category ${category}`);
+      }
+      return {
+        id: evaluationCase.id,
+        description: evaluationCase.description,
+        passed: failures.length === 0,
+        expectedStatus: evaluationCase.expectedStatus,
+        actualStatus: report.status,
+        highestRisk: report.risk.highestScore,
+        categories,
+        failures
+      };
+    })
+  );
+  const passed = results.filter((result) => result.passed).length;
+  return {
+    datasetPath,
+    passed: passed === results.length,
+    cases: results,
+    summary: { total: results.length, passed, failed: results.length - passed }
+  };
+}
+
+// src/cli/commands/eval.ts
+function registerEvalCommand(program, runSafely2) {
+  program.command("eval").argument("[dataset]", "Evaluation dataset JSON path.").option("--json", "Print machine-readable JSON.").description("Run the committed change-readiness evaluation dataset.").action(async (dataset, opts) => {
+    await runSafely2(async () => {
+      const result = await runEvaluation(dataset ? { datasetPath: dataset } : {});
+      if (opts.json) console.log(JSON.stringify(result, null, 2));
+      else printEvaluation(result);
+      if (!result.passed) process.exitCode = 1;
+    });
+  });
+}
+function printEvaluation(result) {
+  console.log(
+    `${result.passed ? pc4.green("passed") : pc4.red("failed")} ${result.summary.passed}/${result.summary.total} evaluation cases`
+  );
+  for (const item of result.cases) {
+    console.log(`  ${item.passed ? pc4.green("\u2713") : pc4.red("\xD7")} ${item.id}`);
+    if (!item.passed) for (const failure of item.failures) console.log(pc4.dim(`    ${failure}`));
+  }
+  console.log(pc4.dim(`dataset: ${result.datasetPath}`));
+}
+
+// src/cli/commands/github.ts
+import pc5 from "picocolors";
+function registerGitHubCommands(program, runSafely2) {
+  const github = program.command("github").description("Install GitHub workflow integrations.");
+  github.command("install").option("--force", "Replace an existing CodeBuddy workflow.").description("Install the PR change-safety report workflow.").action(async (opts) => {
+    await runSafely2(async () => {
+      const result = await installGitHubWorkflow(process.cwd(), {
+        ...opts.force !== void 0 ? { force: opts.force } : {}
+      });
+      console.log(`${result.created ? "installed" : "already present"} ${pc5.dim(result.path)}`);
+      if (result.created) console.log("Commit this workflow to enable CodeBuddy PR reports.");
+    });
+  });
+}
+
+// src/cli/commands/hooks.ts
+import { relative as relative2 } from "path";
+import pc6 from "picocolors";
+function registerHooksCommands(program, runSafely2) {
+  const hooks = program.command("hooks").description("Enforce automatic recall/capture via client lifecycle hooks.");
+  hooks.command("install").option(
+    "--client <client>",
+    "Client with a CodeBuddy hook adapter (claude, opencode, hermes).",
+    "claude"
+  ).description(
+    "Add CodeBuddy's recall/capture hooks (.claude/settings.json, .opencode/plugins/codebuddy.js or .hermes/plugins/codebuddy/)."
+  ).action(async (opts) => {
+    await runSafely2(async () => {
+      const client = assertHookClient(opts.client);
+      const step = await setHooks(process.cwd(), true, client);
+      if (!step) return;
+      const where = relative2(process.cwd(), step.target) || step.target;
+      const changed = step.action !== "unchanged";
+      console.log(
+        `${changed ? pc6.green("installed") : pc6.dim("unchanged")} CodeBuddy hooks in ${where}`
+      );
+      await reconcileRules(client, "hooks");
+      console.log(
+        pc6.dim(
+          `  prompt\u2192recall \xB7 edit\u2192stage \xB7 turn end\u2192capture \xB7 compaction\u2192reset. Restart ${CLIENT_ADAPTERS[client].name} to activate.`
+        )
+      );
+    });
+  });
+  hooks.command("uninstall").option(
+    "--client <client>",
+    "Client with a CodeBuddy hook adapter (claude, opencode, hermes).",
+    "claude"
+  ).description("Remove CodeBuddy's hooks for a client (user hooks untouched).").action(async (opts) => {
+    await runSafely2(async () => {
+      const client = assertHookClient(opts.client);
+      const changed = (await setHooks(process.cwd(), false, client))?.action === "removed";
+      console.log(
+        changed ? pc6.yellow("removed CodeBuddy hooks") : pc6.dim("no CodeBuddy hooks found")
+      );
+      await reconcileRules(client, "agent");
+    });
+  });
+  hooks.command("status").option(
+    "--client <client>",
+    "Client with a CodeBuddy hook adapter (claude, opencode, hermes).",
+    "claude"
+  ).description("Report whether CodeBuddy hooks are installed.").action(async (opts) => {
+    await runSafely2(async () => {
+      const installed = await clientHooksInstalled(process.cwd(), parseClient(opts.client));
+      console.log(
+        installed ? pc6.green("CodeBuddy hooks: installed") : pc6.dim("CodeBuddy hooks: not installed")
+      );
+    });
+  });
+  hooks.command("context").description("[hook] Emit compact project context for injection at prompt submit.").action(async () => {
+    await failSoft(async () => {
+      const input = await readHookInput();
+      await runContextHook(input, writeStdout);
+    });
+  });
+  hooks.command("lean").description("[hook] Emit ranked file pointers (lean mode).").action(async () => {
+    await runLeanHookCommand();
+  });
+  hooks.command("stage").description("[hook] Record the files an edit tool just changed.").action(async () => {
+    await failSoft(async () => {
+      const input = await readHookInput();
+      await runStageHook(input);
+    });
+  });
+  hooks.command("capture").description("[hook] Capture durable memory from the turn's change set.").action(async () => {
+    await failSoft(async () => {
+      const input = await readHookInput();
+      const { changedFiles, result } = await runCaptureHook(input);
+      if (result) {
+        process.stderr.write(
+          `codebuddy: captured from ${changedFiles.length} changed file(s) \u2014 ${result.saved.length} saved, ${result.queuedForReview.length} queued
+`
+        );
+      }
+    });
+  });
+  hooks.command("pretool").description(
+    "[hook] Outline large unranged Reads and cap content Greps (never grants permission)."
+  ).action(async () => {
+    await runPreToolHookCommand();
+  });
+  hooks.command("reset").description("[hook] Forget what context was sent this session (after compaction or /clear).").action(async () => {
+    await failSoft(async () => {
+      await runResetHook(await readHookInput());
+    });
+  });
+}
+function assertHookClient(value) {
+  const client = parseClient(value);
+  const adapter = CLIENT_ADAPTERS[client];
+  if (!supportedModes(adapter).includes("hooks")) {
+    throw new Error(
+      `${adapter.name} has no CodeBuddy hook adapter: ${adapter.gap ?? "unsupported"}.`
+    );
+  }
+  return client;
+}
+async function reconcileRules(client, mode) {
+  const result = await installWorkflowRules({ client, mode, onlyIfManaged: true });
+  if (result.action !== "unchanged") {
+    const where = relative2(process.cwd(), result.path) || result.path;
+    console.log(
+      `${pc6.cyan("updated")} ${where} workflow to ${mode === "hooks" ? "hook" : "agent"}-driven mode`
+    );
+  }
+}
+
+// src/cli/commands/indexing.ts
+import pc8 from "picocolors";
+
+// src/cli/commands/llm.ts
+import pc7 from "picocolors";
+import { z } from "zod";
+var KEY_ENV = { groq: "GROQ_API_KEY", openrouter: "OPENROUTER_API_KEY" };
+var WATCH_BATCH = 8;
+async function llmStatusReport(root, env = process.env) {
+  const block = (await readConfigFile(root)).llm;
+  const provider = block?.provider ?? "groq";
+  const config = await resolveLlmConfig(root, env);
+  const model = config.enabled ? config.model : block?.model ?? null;
+  const key = `${provider}:${model}`;
+  const { manifest } = await loadFreshIndex(root);
+  return {
+    enabled: config.enabled,
+    reason: config.enabled ? "on" : config.reason,
+    provider,
+    model,
+    keyEnv: env.CODEBUDDY_LLM_API_KEY ? "CODEBUDDY_LLM_API_KEY" : KEY_ENV[provider],
+    keyPresent: Boolean(env.CODEBUDDY_LLM_API_KEY || env[KEY_ENV[provider]]),
+    features: config.enabled ? config.features : null,
+    usageToday: (await usageToday(root))[key] ?? 0,
+    dailyTokenBudget: config.enabled ? config.dailyTokenBudget : block?.dailyTokenBudget ?? 4e5,
+    cooldownMs: await coolingDown(root, key),
+    summaries: {
+      covered: (await loadLlmSummaries(root, manifest)).size,
+      indexed: Object.keys(manifest.entries).length
+    }
+  };
+}
+function formatLlmStatus(report) {
+  const features = report.features ? Object.entries(report.features).map(([name, on]) => `${name} ${on ? "on" : "off"}`).join(", ") : "-";
+  return [
+    `status:     ${report.enabled ? "on" : `off (${report.reason})`}`,
+    `provider:   ${report.provider}${report.model ? ` ${report.model}` : ""}`,
+    `key:        ${report.keyPresent ? "present" : "missing"} (${report.keyEnv})`,
+    `features:   ${features}`,
+    `usage today: ${report.usageToday} / ${report.dailyTokenBudget} tokens`,
+    ...report.cooldownMs > 0 ? [`cooldown:   rate limited, ${Math.ceil(report.cooldownMs / 1e3)} s left`] : [],
+    `summaries:  ${report.summaries.covered} / ${report.summaries.indexed} files`
+  ].join("\n");
+}
+async function summarizeAfterIndex(root, env = process.env) {
+  const config = await resolveLlmConfig(root, env);
+  if (!config.enabled || !config.features.summaries) return null;
+  return summarizeRepository(root, { config, limit: WATCH_BATCH, pace: false });
+}
+function registerLlmCommands(program, runSafely2) {
+  const llm = program.command("llm").description(
+    "Optional bring-your-own-key small model (Groq/OpenRouter) for summaries, rerank and memory."
+  );
+  llm.command("status", { isDefault: true }).option("--json", "Print machine-readable JSON.").description(
+    "Show provider, key presence (never the key), usage, cooldown and summary coverage."
+  ).action(async (opts) => {
+    await runSafely2(async () => {
+      const report = await llmStatusReport(process.cwd());
+      console.log(opts.json ? JSON.stringify(report, null, 2) : formatLlmStatus(report));
+      if (!report.keyPresent) console.log(pc7.dim(`next: export ${report.keyEnv}=<your key>`));
+    });
+  });
+  llm.command("enable").option("--provider <provider>", "groq or openrouter", "groq").option("--model <model>", "Model id (default: llama-3.1-8b-instant on groq).").description("Turn the layer on in .codebuddy/config.json (the key stays in your environment).").action(async (opts) => {
+    await runSafely2(async () => {
+      if (opts.provider !== "groq" && opts.provider !== "openrouter") {
+        throw new Error("--provider must be groq or openrouter");
+      }
+      await setLlmEnabled(true, {
+        provider: opts.provider,
+        ...opts.model ? { model: opts.model } : {}
+      });
+      console.log(formatLlmStatus(await llmStatusReport(process.cwd())));
+    });
+  });
+  llm.command("disable").description("Turn the layer off; CodeBuddy falls back to deterministic retrieval and capture.").action(async () => {
+    await runSafely2(async () => {
+      await setLlmEnabled(false);
+      console.log("llm layer disabled");
+    });
+  });
+  llm.command("test").description("Send one tiny request and print the model and latency.").action(async () => {
+    await runSafely2(async () => {
+      const config = await resolveLlmConfig(process.cwd());
+      if (!config.enabled) throw new Error(`llm layer is off: ${config.reason}`);
+      const result = await chatJson(config, {
+        system: 'Answer with JSON only: {"ok":true}.',
+        user: "ping",
+        schema: z.object({ ok: z.boolean() }),
+        maxTokens: 10,
+        deadlineMs: 1e4,
+        purpose: "prompt",
+        repositoryRoot: process.cwd()
+      });
+      if (!result.ok) throw new Error(`${result.reason}: ${result.detail}`);
+      console.log(`ok: ${result.model} answered in ${result.latencyMs} ms`);
+    });
+  });
+  llm.command("summarize").option("--limit <n>", "Summarize at most this many files.", Number).description(
+    "Write one-line summaries of changed files now (resumable; paced to the free tier)."
+  ).action(async (opts) => {
+    await runSafely2(async () => {
+      const controller = new AbortController();
+      process.once("SIGINT", () => controller.abort());
+      const result = await summarizeRepository(process.cwd(), {
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        signal: controller.signal,
+        onProgress: (done, total) => console.log(pc7.dim(`summarized ${done}/${total}`))
+      });
+      console.log(
+        `${result.summarized} summarized, ${result.skipped} skipped, ${result.remaining} remaining (${result.stoppedBy})`
+      );
+    });
+  });
+}
+
+// src/cli/commands/indexing.ts
+function registerIndexCommands(program, runSafely2) {
+  program.command("index").option("--full", "Re-summarize every file, ignoring existing content hashes.").option("--json", "Print machine-readable JSON.").description("Index the repository: content hashes and lightweight file summaries.").action(async (opts) => {
+    await runSafely2(async () => {
+      const result = await indexRepository({ ...opts.full ? { full: true } : {} });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      printResult(result);
+    });
+  });
+  program.command("watch").option("--debounce <ms>", "Coalesce file-change bursts within this window.", Number).option("--no-llm", "Do not write BYOK model summaries after index passes.").description("Watch the repository and incrementally re-index on change (Ctrl+C to stop).").action(async (opts) => {
+    await runSafely2(async () => {
+      const controller = new AbortController();
+      const stop = () => controller.abort();
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+      console.log(pc8.dim("watching for changes\u2026 press Ctrl+C to stop"));
+      await watchRepository({
+        ...opts.debounce !== void 0 ? { debounceMs: opts.debounce } : {},
+        signal: controller.signal,
+        onIndex: (result) => {
+          printResult(result, true);
+          if (!opts.llm || result.added + result.changed === 0) return;
+          void summarizeAfterIndex(process.cwd()).then((summary) => {
+            if (summary && summary.summarized > 0)
+              console.log(pc8.dim(`  llm: ${summary.summarized} file(s) summarized`));
+          }).catch((error) => console.error(pc8.red(`llm: ${error.message}`)));
+        },
+        onError: (error) => console.error(pc8.red(error.message))
+      });
+      console.log(pc8.dim("stopped watching"));
+    });
+  });
+}
+function printResult(result, compact = false) {
+  const summary = `${result.totalIndexed} indexed (${pc8.green(`+${result.added}`)} ${pc8.yellow(`~${result.changed}`)} ${pc8.dim(`=${result.unchanged}`)} ${pc8.red(`-${result.removed}`)}) in ${result.durationMs}ms`;
+  console.log(compact ? pc8.dim(summary) : summary);
+  if (result.skipped > 0)
+    console.log(pc8.dim(`  ${result.skipped} skipped (too large or unreadable)`));
+  for (const error of result.errors) console.log(pc8.red(`  ${error.path}: ${error.error}`));
+}
+
+// src/cli/commands/init-wizard.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { confirm, isCancel, log, note, password, spinner, text } from "@clack/prompts";
+
+// src/cli/commands/postgres-docker.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { dirname as dirname11, resolve as resolve12 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function resolveBundledComposeFile() {
+  const here = dirname11(fileURLToPath2(import.meta.url));
+  const candidates = [
+    // installed package: dist/cli/commands/ -> root
+    resolve12(here, "..", "..", "..", "docker-compose.yml"),
+    // source layout:    src/cli/commands/ -> root
+    resolve12(here, "..", "..", "..", "..", "docker-compose.yml"),
+    resolve12(here, "..", "..", "docker-compose.yml"),
+    resolve12(process.cwd(), "docker-compose.yml")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync3(candidate)) return candidate;
+  }
+  throw new Error(`Could not locate docker-compose.yml. Looked in:
+  ${candidates.join("\n  ")}`);
+}
+async function runDockerCompose(args, options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn2;
+  const composeFile = resolveBundledComposeFile();
+  const attempts = [
+    { kind: "v2", bin: "docker", args: ["compose", "-f", composeFile, ...args] },
+    { kind: "v1", bin: "docker-compose", args: ["-f", composeFile, ...args] }
+  ];
+  let lastSpawnError = null;
+  for (const attempt of attempts) {
+    try {
+      return await spawnOnce(spawnImpl, attempt);
+    } catch (error) {
+      const err = error;
+      if (err.code !== "ENOENT") throw err;
+      lastSpawnError = err;
+    }
+  }
+  throw new Error(
+    `Could not find docker. Install Docker Desktop (or docker-compose v1) and ensure it is on your PATH. (${lastSpawnError?.message ?? "spawn ENOENT"})`
+  );
+}
+function spawnOnce(spawnImpl, attempt) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawnImpl(attempt.bin, attempt.args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      rejectPromise(error);
+    });
+    child.on("close", (code) => {
+      resolvePromise({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}
+async function postgresUp(options) {
+  return runDockerCompose(["up", "-d"], options ?? {});
+}
+async function postgresDown(options) {
+  return runDockerCompose(["down"], options ?? {});
+}
+async function postgresStatus(options) {
+  return runDockerCompose(["ps"], options ?? {});
+}
+
+// src/cli/commands/init-wizard.ts
+function bail() {
+  log.warn("Aborted. No config was written.");
+  process.exit(1);
+}
+function unwrap(value) {
+  if (isCancel(value)) bail();
+  return value;
+}
+async function pingOnce(databaseUrl) {
+  const client = createDatabaseClient({ postgresUrl: databaseUrl });
+  try {
+    return await pingDatabase(client);
+  } catch {
+    return false;
+  } finally {
+    await client.close().catch(() => void 0);
+  }
+}
+async function runInitWizard() {
+  const sigintHandler = () => bail();
+  process.on("SIGINT", sigintHandler);
+  try {
+    note(
+      "Sets up your config file, checks Postgres, applies migrations, and (optionally) wires Claude Desktop.",
+      "CodeBuddy init"
+    );
+    const hfToken = unwrap(
+      await password({
+        message: "Hugging Face token (required for embeddings)",
+        validate: (value) => value && value.length > 0 ? void 0 : "HF_TOKEN is required."
+      })
+    );
+    const databaseUrl = unwrap(
+      await text({
+        message: "Postgres URL",
+        initialValue: process.env.DATABASE_URL ?? "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
+        validate: (value) => value && value.length > 0 ? void 0 : "Postgres URL is required."
+      })
+    );
+    const namespace = unwrap(
+      await text({
+        message: "Default namespace",
+        initialValue: process.env.CODEBUDDY_NAMESPACE ?? "default",
+        validate: (value) => value && /^[a-zA-Z0-9_.:-]+$/.test(value) ? void 0 : "Letters, digits, _ . : - only."
+      })
+    );
+    const dbSpinner = spinner();
+    dbSpinner.start("Checking Postgres connection");
+    let connected = await pingOnce(databaseUrl);
+    dbSpinner.stop(connected ? "Postgres reachable." : "Postgres did not respond.");
+    if (!connected) {
+      const startDocker = unwrap(
+        await confirm({
+          message: "Start the bundled Postgres container with docker compose?",
+          initialValue: true
+        })
+      );
+      if (startDocker) {
+        const dockerSpinner = spinner();
+        dockerSpinner.start("docker compose up -d");
+        try {
+          const result = await postgresUp();
+          if (result.code === 0) {
+            dockerSpinner.stop("Postgres container started.");
+            for (let attempt = 0; attempt < 10 && !connected; attempt++) {
+              await new Promise((resolve14) => setTimeout(resolve14, 500));
+              connected = await pingOnce(databaseUrl);
+            }
+            if (!connected) {
+              log.warn("Container started but did not accept connections in time.");
+            }
+          } else {
+            dockerSpinner.stop(`docker compose failed: ${result.stderr || result.stdout}`);
+          }
+        } catch (error) {
+          dockerSpinner.stop(`docker compose failed: ${error.message}`);
+        }
+      }
+    }
+    if (connected) {
+      const migrateSpinner = spinner();
+      migrateSpinner.start("Enabling pgvector and applying migrations");
+      const client = createDatabaseClient({ postgresUrl: databaseUrl });
+      try {
+        await bootstrapDatabase(client.sql);
+        await runMigrations(client);
+        migrateSpinner.stop("Migrations applied.");
+      } catch (error) {
+        migrateSpinner.stop(`Migration error: ${error.message}`);
+      } finally {
+        await client.close().catch(() => void 0);
+      }
+    } else {
+      log.warn("Skipping migrations \u2014 Postgres is not reachable. Run `codebuddy migrate` later.");
+    }
+    const initialised = await initConfigFile();
+    const fileConfig = {
+      postgresUrl: databaseUrl,
+      namespace,
+      provider: { type: "huggingface", apiKey: hfToken },
+      tokenBudget: 4e3
+    };
+    await writeFile2(initialised.path, `${JSON.stringify(fileConfig, null, 2)}
+`, {
+      mode: 384
+    });
+    log.success(`Config written to ${initialised.path}`);
+    let claudeInstalled = false;
+    const wireClaude = unwrap(
+      await confirm({
+        message: "Register this namespace with Claude Desktop now?",
+        initialValue: true
+      })
+    );
+    if (wireClaude) {
+      try {
+        const install = await installClaudeEntry({
+          namespace,
+          hfToken,
+          databaseUrl
+        });
+        claudeInstalled = true;
+        log.success(
+          `Added "${install.serverKey}" to ${install.path}. Restart Claude Desktop (\u2318Q) to activate.`
+        );
+      } catch (error) {
+        log.warn(`Claude Desktop install failed: ${error.message}`);
+      }
+    }
+    return {
+      configPath: configPath(),
+      databaseReady: connected,
+      claudeInstalled
+    };
+  } finally {
+    process.off("SIGINT", sigintHandler);
+  }
+}
+
+// src/cli/commands/learn.ts
+import pc9 from "picocolors";
+
+// src/learning/outcomes.ts
+async function recordChangeOutcome(input) {
+  if (input.paths.length === 0) throw new Error("At least one path is required.");
+  if (!input.summary.trim()) throw new Error("A non-empty outcome summary is required.");
+  const now = input.now ?? /* @__PURE__ */ new Date();
+  const category = input.outcome === "regression" ? "incident" : "general";
+  const id = generateEntityId("fact", now.getTime());
+  const object = input.outcome === "regression" ? "regression observed" : "verified safe";
+  const content = [
+    `Change outcome: ${input.outcome}`,
+    `Paths: ${input.paths.join(", ")}`,
+    `Summary: ${input.summary.trim()}`,
+    ...input.commit ? [`Commit: ${input.commit}`] : []
+  ].join("\n");
+  const store = new MemoryFileStore(input.repositoryRoot);
+  const subject = `change outcome for ${input.paths[0]}`;
+  const predicate = input.outcome === "regression" ? "caused" : "survived";
+  const persisted = redactPersisted({ subject, predicate, object, content });
+  const path = await store.writeFact({
+    id,
+    namespace: input.namespace,
+    subject,
+    predicate,
+    object,
+    confidence: input.outcome === "regression" ? 0.95 : 0.85,
+    createdAt: now.toISOString(),
+    createdByAgent: "codebuddy:learn",
+    sourceInteractionId: null,
+    sourceDeleted: false,
+    category,
+    paths: input.paths,
+    ...input.outcome === "regression" ? { severity: input.severity ?? "high" } : {},
+    ...input.commit ? { introducedBy: input.commit } : {},
+    ...input.planId ? { sourcePlanId: input.planId } : {},
+    verification: ["explicit change outcome recorded by a project owner"],
+    fingerprint: computeFactHash(input.namespace, persisted.content),
+    content
+  });
+  return { id, path, category };
+}
+
+// src/cli/commands/learn.ts
+function registerLearnCommand(program, runSafely2) {
+  const learn = program.command("learn").description("Record verified team change outcomes.");
+  learn.command("outcome").requiredOption("--outcome <outcome>", "safe or regression").requiredOption("--paths <paths>", "Comma-separated repo-relative paths.").requiredOption("--summary <summary>", "What happened and why it matters.").option("--severity <severity>", "Incident severity: low, medium, high, or critical.").option("--commit <sha>", "Commit associated with the outcome.").option("--plan <id>", "Plan associated with the outcome.").description("Write an explicit, reviewable outcome into shared Markdown memory.").action(
+    async (opts) => {
+      await runSafely2(async () => {
+        if (opts.outcome !== "safe" && opts.outcome !== "regression") {
+          throw new Error("--outcome must be safe or regression.");
+        }
+        const result = await recordChangeOutcome({
+          namespace: await resolveNamespaceFrom(),
+          outcome: opts.outcome,
+          paths: opts.paths.split(",").map((path) => path.trim()).filter(Boolean),
+          summary: opts.summary,
+          ...opts.severity ? { severity: opts.severity } : {},
+          ...opts.commit ? { commit: opts.commit } : {},
+          ...opts.plan ? { planId: opts.plan } : {}
+        });
+        console.log(`${pc9.green("recorded")} ${result.id} (${result.category})`);
+        console.log(pc9.dim(result.path));
+      });
+    }
+  );
+}
+
+// src/cli/commands/map.ts
+import pc10 from "picocolors";
+function registerMapCommands(program, runSafely2) {
+  const map = program.command("map").description("Query the lightweight architecture map.");
+  map.command("build").description("Scan the current repository and summarize the module graph.").action(async () => {
+    await runSafely2(async () => {
+      const graph = await buildArchitectureMap();
+      console.log(
+        JSON.stringify({ modules: graph.modules.length, edges: graph.edges.length }, null, 2)
+      );
+    });
+  });
+  map.command("deps").argument("<path>", "Repo-relative module path.").option("--json", "Print machine-readable JSON.").description("List modules imported by a file.").action(async (path, opts) => {
+    await runSafely2(async () => {
+      const graph = await buildArchitectureMap();
+      const edges = queryMap(graph, { from: path });
+      if (opts.json) {
+        console.log(JSON.stringify({ edges }, null, 2));
+        return;
+      }
+      if (edges.length === 0) {
+        console.log(pc10.dim("no dependencies found"));
+        return;
+      }
+      for (const edge of edges) console.log(`${edge.from} -> ${edge.to}`);
+    });
+  });
+  map.command("dependents").argument("<path>", "Repo-relative module path.").option("--json", "Print machine-readable JSON.").description("List modules that import a file.").action(async (path, opts) => {
+    await runSafely2(async () => {
+      const graph = await buildArchitectureMap();
+      const result = neighbours(graph, path, "in");
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      if (result.edges.length === 0) {
+        console.log(pc10.dim("no dependents found"));
+        return;
+      }
+      for (const edge of result.edges) console.log(`${edge.from} -> ${edge.to}`);
+    });
+  });
+}
+
+// src/cli/commands/memory-review.ts
+import { spawn as spawn3 } from "child_process";
+import { relative as relative3 } from "path";
+import pc11 from "picocolors";
+function registerMemoryCommands(program, runSafely2) {
+  const memory = program.command("memory").description("Inspect and curate CodeBuddy memory.");
+  const review = memory.command("review").description("Review memory candidates captured automatically after turns.");
+  review.command("list", { isDefault: true }).option("--json", "Print machine-readable JSON.").description("List pending review candidates.").action(async (opts) => {
+    await runSafely2(async () => {
+      const items = await new ReviewStore().list();
+      if (opts.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+      }
+      if (items.length === 0) {
+        console.log(pc11.dim("no pending review items"));
+        return;
+      }
+      for (const item of items) console.log(renderRow(item));
+      console.log(pc11.dim(`
+${items.length} pending. approve <id> | reject <id> | show <id>`));
+    });
+  });
+  review.command("show").argument("<id>").description("Show a single review candidate.").action(async (id) => {
+    await runSafely2(async () => {
+      console.log(renderItem(await new ReviewStore().read(id)));
+    });
+  });
+  review.command("approve").argument("<id>").option("--incident <id>", "For a queued incident resolution: the incident to resolve.").description("Promote a review candidate to a durable fact and remove it from the queue.").action(async (id, opts) => {
+    await runSafely2(async () => {
+      const factId = await approveReviewItem(id, {
+        ...opts.incident !== void 0 ? { incidentId: opts.incident } : {}
+      });
+      console.log(`${pc11.green("approved")} ${id} \u2192 ${factId}`);
+    });
+  });
+  review.command("reject").argument("<id>").description("Discard a review candidate without saving it.").action(async (id) => {
+    await runSafely2(async () => {
+      const store = new ReviewStore();
+      await store.read(id);
+      await store.delete(id);
+      console.log(`${pc11.yellow("rejected")} ${id}`);
+    });
+  });
+  review.command("edit").argument("<id>").description("Open a review candidate in $EDITOR and re-validate on save.").action(async (id) => {
+    await runSafely2(async () => {
+      const store = new ReviewStore();
+      const item = await store.read(id);
+      await openEditor(item.path);
+      await store.read(id);
+      console.log(pc11.dim("saved and validated"));
+    });
+  });
+}
+function renderRow(item) {
+  const flag = item.sensitive ? pc11.red(" \u26A0 sensitive") : "";
+  return `${classColor(item.class)}  ${pc11.dim(item.id)}  ${truncate(item.content, 70)}${flag}`;
+}
+function renderItem(item) {
+  const lines = [
+    `${classColor(item.class)}  ${pc11.dim(item.id)}`,
+    `${pc11.bold("reason:")} ${item.reason}`,
+    `${pc11.bold("confidence:")} ${item.confidence.toFixed(2)}`,
+    `${pc11.bold("triple:")} ${item.subject} \xB7 ${item.predicate} \xB7 ${item.object}`
+  ];
+  if (item.paths.length > 0) lines.push(`${pc11.bold("paths:")} ${item.paths.join(", ")}`);
+  if (item.severity) lines.push(`${pc11.bold("severity:")} ${item.severity}`);
+  if (item.resolvesIncidents) {
+    lines.push(
+      `${pc11.bold("resolves:")} ${item.resolvesIncidents.join(", ") || "(no candidate; approve with --incident <id>)"}`
+    );
+  }
+  if (item.sensitive) lines.push(pc11.red(`\u26A0 sensitive: ${item.sensitiveReasons.join(", ")}`));
+  lines.push("", item.content, "", pc11.dim(relative3(process.cwd(), item.path)));
+  return lines.join("\n");
+}
+function classColor(memoryClass) {
+  switch (memoryClass) {
+    case "incident":
+      return pc11.red(memoryClass);
+    case "decision":
+      return pc11.cyan(memoryClass);
+    case "fact":
+      return pc11.green(memoryClass);
+    case "note":
+      return pc11.yellow(memoryClass);
+    default:
+      return pc11.dim(memoryClass);
+  }
+}
+function truncate(value, max) {
+  const trimmed = value.trim();
+  return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max - 1)}\u2026`;
+}
+function openEditor(path) {
+  const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn3(editor, [path], { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", () => resolvePromise());
+  });
+}
+
+// src/cli/commands/plan.ts
+import { spawn as spawn4 } from "child_process";
+import { relative as relative4 } from "path";
+import pc12 from "picocolors";
+function makeLifecycle(cwd = process.cwd()) {
+  const store = new PlanFileStore(cwd);
+  return { store, lifecycle: new PlanLifecycle(store) };
+}
+function statusColor(status) {
+  switch (status) {
+    case "draft":
+      return pc12.dim(status);
+    case "approved":
+      return pc12.cyan(status);
+    case "executing":
+      return pc12.yellow(status);
+    case "complete":
+      return pc12.green(status);
+    case "abandoned":
+      return pc12.red(status);
+  }
+}
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(`${pc12.bold(plan.title)}  ${statusColor(plan.status)}`);
+  lines.push(pc12.dim(plan.id));
+  lines.push("");
+  lines.push(`${pc12.bold("Brief:")} ${plan.brief}`);
+  if (plan.filesToTouch.length > 0) {
+    lines.push("");
+    lines.push(pc12.bold("Files to touch:"));
+    for (const file of plan.filesToTouch) {
+      lines.push(`  ${file.action.padEnd(6)} ${file.path}${file.notes ? `  \u2014 ${file.notes}` : ""}`);
+    }
+  }
+  if (plan.testsToAdd.length > 0) {
+    lines.push("");
+    lines.push(pc12.bold("Tests to add:"));
+    for (const test of plan.testsToAdd) {
+      lines.push(`  ${test.path}${test.description ? `  \u2014 ${test.description}` : ""}`);
+    }
+  }
+  if (plan.outOfScope.length > 0) {
+    lines.push("");
+    lines.push(pc12.bold("Out of scope:"));
+    for (const item of plan.outOfScope) lines.push(`  - ${item}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("");
+    lines.push(pc12.bold("Risks:"));
+    for (const item of plan.risks) lines.push(`  - ${item}`);
+  }
+  if (plan.commitSha) {
+    lines.push("");
+    lines.push(`${pc12.bold("Commit:")} ${plan.commitSha}`);
+  }
+  lines.push("");
+  lines.push(pc12.dim("\u2500".repeat(40)));
+  lines.push(plan.body);
+  return lines.join("\n");
+}
+function openEditor2(path) {
+  const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+  return new Promise((resolve14, reject) => {
+    const child = spawn4(editor, [path], { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", () => resolve14());
+  });
+}
+function runGit(args) {
+  return new Promise((resolve14, reject) => {
+    const child = spawn4("git", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => {
+      stdout += String(c);
+    });
+    child.stderr.on("data", (c) => {
+      stderr += String(c);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve14({ code: code ?? 0, stdout, stderr }));
+  });
+}
+function registerPlanCommands(program, runSafely2) {
+  const plan = program.command("plan").description("Author and manage durable Markdown plans.");
+  plan.command("new").argument("<brief...>", "One-line description of the work.").option("--title <title>", "Plan title (defaults to the brief).").option("--no-edit", "Skip opening $EDITOR after creating the draft.").description("Create a draft plan and open it in $EDITOR.").action(async (briefParts, opts) => {
+    await runSafely2(async () => {
+      const { lifecycle } = makeLifecycle();
+      const namespace = await resolveNamespaceFrom();
+      const brief = briefParts.join(" ");
+      const created = await lifecycle.create({
+        namespace,
+        title: opts.title ?? brief,
+        brief
+      });
+      console.log(`${pc12.green("created")} ${created.id} (${statusColor(created.status)})`);
+      if (opts.edit !== false && process.stdin.isTTY) {
+        await openEditor2(created.path);
+        const { store } = makeLifecycle();
+        await store.readPlan(created.id);
+        console.log(pc12.dim("saved and validated"));
+      }
+      console.log(pc12.dim(relative4(process.cwd(), created.path)));
+    });
+  });
+  plan.command("list").option("--status <status>", "Filter by status.").option("--all", "Include completed and abandoned plans.").description("List plans in the current namespace.").action(async (opts) => {
+    await runSafely2(async () => {
+      const { store } = makeLifecycle();
+      const namespace = await resolveNamespaceFrom();
+      let plans = (await store.listPlans()).filter((p) => p.namespace === namespace);
+      if (opts.status) plans = plans.filter((p) => p.status === opts.status);
+      else if (!opts.all)
+        plans = plans.filter((p) => p.status !== "complete" && p.status !== "abandoned");
+      if (plans.length === 0) {
+        console.log(pc12.dim("no plans"));
+        return;
+      }
+      for (const p of plans) {
+        console.log(`${statusColor(p.status).padEnd(20)} ${pc12.bold(p.title)}  ${pc12.dim(p.id)}`);
+      }
+    });
+  });
+  plan.command("show").argument("<id>").description("Show a single plan.").action(async (id) => {
+    await runSafely2(async () => {
+      const { store } = makeLifecycle();
+      console.log(renderPlan(await store.readPlan(id)));
+    });
+  });
+  plan.command("edit").argument("<id>").description("Open a plan in $EDITOR and validate on save.").action(async (id) => {
+    await runSafely2(async () => {
+      const { store } = makeLifecycle();
+      const existing = await store.readPlan(id);
+      await openEditor2(existing.path);
+      await store.readPlan(id);
+      console.log(pc12.dim("saved and validated"));
+    });
+  });
+  plan.command("approve").argument("<id>").description("Promote a draft to approved (one active plan per namespace).").action(async (id) => {
+    await runSafely2(async () => {
+      const { lifecycle } = makeLifecycle();
+      const next = await lifecycle.approve(id);
+      console.log(`${next.id} \u2192 ${statusColor(next.status)}`);
+    });
+  });
+  plan.command("start").argument("<id>").description("Move an approved plan to executing.").action(async (id) => {
+    await runSafely2(async () => {
+      const { lifecycle } = makeLifecycle();
+      const next = await lifecycle.start(id);
+      console.log(`${next.id} \u2192 ${statusColor(next.status)}`);
+    });
+  });
+  plan.command("complete").argument("<id>").option("--commit <sha>", "Git commit the plan was completed in.").option("--notes <text>", "Completion notes.").description("Mark an executing plan complete.").action(async (id, opts) => {
+    await runSafely2(async () => {
+      const { lifecycle } = makeLifecycle();
+      const next = await lifecycle.complete(id, {
+        ...opts.commit ? { commitSha: opts.commit } : {},
+        ...opts.notes ? { notes: opts.notes } : {}
+      });
+      if (!opts.commit) console.log(pc12.yellow("note: no --commit supplied"));
+      console.log(`${next.id} \u2192 ${statusColor(next.status)}`);
+    });
+  });
+  plan.command("abandon").argument("<id>").option("--reason <text>", "Why the plan was abandoned.").description("Abandon a plan without completing it.").action(async (id, opts) => {
+    await runSafely2(async () => {
+      const { lifecycle } = makeLifecycle();
+      const next = await lifecycle.abandon(id, opts.reason ? { reason: opts.reason } : {});
+      console.log(`${next.id} \u2192 ${statusColor(next.status)}`);
+    });
+  });
+  plan.command("diff").argument("<id>").option("--from <ref>", "Git ref to compare from.", "HEAD").option("--to <ref>", "Git ref to compare to.").description("Show the git diff of a plan file between two revisions.").action(async (id, opts) => {
+    await runSafely2(async () => {
+      const { store } = makeLifecycle();
+      const plan2 = await store.readPlan(id);
+      const relPath = relative4(process.cwd(), plan2.path);
+      const args = ["diff", opts.from, ...opts.to ? [opts.to] : [], "--", relPath];
+      const result = await runGit(args);
+      if (result.stdout.trim().length === 0) {
+        console.log(pc12.dim("no changes"));
+      } else {
+        process.stdout.write(result.stdout);
+      }
+      if (result.code !== 0 && result.stderr) process.stderr.write(result.stderr);
+    });
+  });
+  plan.command("policy").argument("[mode]", `One of: ${PLAN_POLICIES.join(", ")}. Omit to read the current value.`).description("Read or set the plan policy (off | suggest | required).").action(async (mode) => {
+    await runSafely2(async () => {
+      if (mode === void 0) {
+        console.log(await loadPlanPolicy());
+        return;
+      }
+      if (!PLAN_POLICIES.includes(mode)) {
+        throw new Error(`Invalid policy "${mode}". Use one of: ${PLAN_POLICIES.join(", ")}.`);
+      }
+      await setPlanPolicy(mode);
+      console.log(`${pc12.green("plan policy")} = ${mode}`);
+    });
+  });
+}
+
+// src/cli/commands/risk.ts
+import pc13 from "picocolors";
+function registerRiskCommands(program, runSafely2) {
+  const risk = program.command("risk").description("Assess evidence-backed change risk.");
+  risk.command("assess").option("--plan <id>", "Assess paths listed in a CodeBuddy plan.").option("--paths <paths>", "Comma-separated repo-relative paths to assess.").option("--git", "Assess staged, unstaged, and untracked git changes.").option("--limit <n>", "Maximum risk items to show.", Number).option("--json", "Print machine-readable JSON.").option("--explain", "Show evidence for each risk item.").description("Assess risk for a plan, explicit paths, or current git changes.").action(
+    async (opts) => {
+      await runSafely2(async () => {
+        const namespace = await resolveNamespaceFrom();
+        const assessment = await assessRisk({
+          namespace,
+          ...opts.plan ? { planId: opts.plan } : {},
+          ...opts.paths ? { paths: parsePaths3(opts.paths) } : {},
+          ...opts.git !== void 0 ? { useGit: opts.git } : {},
+          ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+        });
+        if (opts.json) {
+          console.log(JSON.stringify(assessment, null, 2));
+          return;
+        }
+        printAssessment(assessment, opts.explain ?? false);
+      });
+    }
+  );
+}
+function parsePaths3(value) {
+  return value.split(",").map((path) => path.trim()).filter(Boolean);
+}
+function printAssessment(assessment, explain) {
+  if (assessment.items.length === 0) {
+    console.log(pc13.dim("no risk evidence found"));
+    return;
+  }
+  for (const item of assessment.items) {
+    console.log(
+      `${pc13.bold(item.path)}  score ${scoreColor2(item.score)}  category ${pc13.cyan(item.category)}`
+    );
+    console.log(`  ${item.reason}`);
+    if (explain) {
+      for (const evidence of item.evidence) console.log(`  \u21B3 ${formatEvidence(evidence)}`);
+    } else {
+      console.log(pc13.dim(`  ${item.evidence.length} evidence item(s)`));
+    }
+  }
+  console.log(
+    pc13.dim(
+      `
+${assessment.stats.itemsProduced} item(s), ${assessment.stats.signalsRun} signal(s), ${assessment.stats.pathsConsidered} path(s) considered`
+    )
+  );
+}
+function scoreColor2(score) {
+  if (score >= 75) return pc13.red(String(score));
+  if (score >= 50) return pc13.yellow(String(score));
+  return pc13.green(String(score));
+}
+function formatEvidence(evidence) {
+  switch (evidence.kind) {
+    case "memory_fact":
+      return `memory ${evidence.factId}: ${truncate2(evidence.content, 90)}`;
+    case "git_commit":
+      return `commit ${evidence.sha.slice(0, 7)} ${evidence.ts}: ${evidence.message}`;
+    case "policy_rule":
+      return `policy ${evidence.ruleId}: ${evidence.pattern}`;
+    case "dependent_module":
+      return `dependent ${evidence.path} depth=${evidence.depth}`;
+    case "ci_failure":
+      return `ci ${evidence.runId} ${evidence.conclusion} ${evidence.ts}`;
+  }
+}
+function truncate2(value, max) {
+  return value.length <= max ? value : `${value.slice(0, max - 1)}\u2026`;
+}
+
+// src/cli/commands/rules.ts
+import { relative as relative5 } from "path";
+import pc14 from "picocolors";
+async function resolveMode(client, value) {
+  if (value) {
+    const mode = parseMode(value);
+    if (!supportedModes(CLIENT_ADAPTERS[client]).includes(mode)) {
+      throw new Error(`${clientDisplayName(client)} does not support --mode ${mode}.`);
+    }
+    return mode;
+  }
+  return defaultRulesMode(client);
+}
+function registerRulesCommands(program, runSafely2) {
+  const rules = program.command("rules").description("Print or install the client workflow templates (CLAUDE.md / AGENTS.md).");
+  rules.command("show").option("--client <client>", `One of: ${WORKFLOW_CLIENTS.join(", ")}.`, "claude").option("--mode <mode>", "agent or hooks (default: follows installed hooks).").description("Print the workflow template for a client.").action(async (opts) => {
+    await runSafely2(async () => {
+      const client = parseClient(opts.client);
+      const mode = await resolveMode(client, opts.mode);
+      if (mode === "mcp-only") {
+        console.log("MCP-only mode installs no workflow rules.");
+        return;
+      }
+      console.log(renderWorkflowTemplate(client, mode));
+    });
+  });
+  rules.command("install").option("--client <client>", `One of: ${WORKFLOW_CLIENTS.join(", ")}.`, "claude").option("--path <file>", "Override the target rules file.").option(
+    "--mode <mode>",
+    `One of: ${AUTOMATION_MODES.join(", ")} (default: follows installed hooks; mcp-only removes the block).`
+  ).description("Install/update the workflow template in the client's rules file (managed block).").action(async (opts) => {
+    await runSafely2(async () => {
+      const client = parseClient(opts.client);
+      const result = await installWorkflowRules({
+        client,
+        mode: await resolveMode(client, opts.mode),
+        ...opts.path ? { targetPath: opts.path } : {}
+      });
+      const where = relative5(process.cwd(), result.path) || result.path;
+      console.log(
+        `${actionLabel(result.action)} ${clientDisplayName(client)} workflow in ${where}`
+      );
+      if (result.action !== "unchanged") {
+        console.log(pc14.dim("  managed block between codebuddy:workflow markers; safe to re-run"));
+      }
+    });
+  });
+}
+function actionLabel(action) {
+  switch (action) {
+    case "created":
+      return pc14.green("created");
+    case "added":
+      return pc14.green("added");
+    case "updated":
+      return pc14.cyan("updated");
+    case "removed":
+      return pc14.yellow("removed");
+    default:
+      return pc14.dim("unchanged");
+  }
+}
+
+// src/cli/commands/suggest.ts
+import pc15 from "picocolors";
+function parsePaths4(value) {
+  return value.split(",").map((path) => path.trim()).filter(Boolean);
+}
+function registerSuggestCommand(program, runSafely2) {
+  program.command("suggest").option("--paths <paths>", "Comma-separated repo-relative paths to review.").option("--plan <id>", "Review the files listed in a plan.").option("--git", "Review current git changes.").option("--limit <n>", "Maximum suggestions to show.", Number).option("--json", "Print machine-readable JSON.").description("Suggest evidence-backed, read-only code-quality improvements.").action(
+    async (opts) => {
+      await runSafely2(async () => {
+        const namespace = await resolveNamespaceFrom();
+        const result = await generateSuggestions({
+          namespace,
+          ...opts.paths ? { paths: parsePaths4(opts.paths) } : {},
+          ...opts.plan ? { planId: opts.plan } : {},
+          ...opts.git !== void 0 ? { useGit: opts.git } : {},
+          ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+        });
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        printSuggestions(result.suggestions);
+        console.log(
+          pc15.dim(
+            `
+${result.stats.produced} suggestion(s) across ${result.stats.pathsConsidered} path(s)`
+          )
+        );
+      });
+    }
+  );
+}
+function printSuggestions(suggestions) {
+  if (suggestions.length === 0) {
+    console.log(pc15.dim("no suggestions \u2014 nothing high-signal to report"));
+    return;
+  }
+  for (const suggestion of suggestions) {
+    console.log(`${severityBadge2(suggestion.severity)} ${pc15.bold(suggestion.title)}`);
+    console.log(`  ${suggestion.detail}`);
+    for (const evidence of suggestion.evidence) {
+      console.log(pc15.dim(`  \u21B3 ${evidence.kind}: ${evidence.detail}`));
+    }
+    if (suggestion.commandHint) console.log(pc15.dim(`  \u2192 ${suggestion.commandHint}`));
+  }
+}
+function severityBadge2(severity) {
+  switch (severity) {
+    case "high":
+      return pc15.red("[high]");
+    case "medium":
+      return pc15.yellow("[med ]");
+    case "low":
+      return pc15.cyan("[low ]");
+    default:
+      return pc15.dim("[info]");
+  }
+}
+
+// src/cli/commands/symbols.ts
+import { readFile as readFile13 } from "fs/promises";
+import { resolve as resolve13 } from "path";
+import pc16 from "picocolors";
+function registerSymbolsCommand(program, runSafely2) {
+  program.command("symbols").argument("<path>", "Repo-relative or absolute path to a code file.").option("--json", "Print machine-readable JSON.").description("List a file's top-level symbols (functions, classes, types, exports).").action(async (path, opts) => {
+    await runSafely2(async () => {
+      if (!supportsSymbols(path)) {
+        console.log(pc16.dim(`no symbol extraction for ${path} (unsupported language)`));
+        return;
+      }
+      const content = await readFile13(resolve13(path), "utf8");
+      const table = extractSymbolTable(content);
+      if (opts.json) {
+        console.log(JSON.stringify({ path, symbols: table }, null, 2));
+        return;
+      }
+      if (table.length === 0) {
+        console.log(pc16.dim("no top-level symbols found"));
+        return;
+      }
+      for (const symbol of table) {
+        const badge = symbol.exported ? pc16.green("export") : pc16.dim("local ");
+        console.log(
+          `${badge} ${pc16.cyan(symbol.kind.padEnd(9))} ${pc16.bold(symbol.name)} ${pc16.dim(`L${symbol.startLine}-${symbol.endLine}`)}`
+        );
+      }
+      console.log(pc16.dim(`
+${table.length} symbol(s)`));
+    });
+  });
+}
+
+// src/cli/commands/use-command.ts
+import { basename } from "path";
+import { confirm as confirm2, isCancel as isCancel2, log as log2, note as note2, password as password2, spinner as spinner2, text as text2 } from "@clack/prompts";
+import pc17 from "picocolors";
+
+// src/core/global-config.ts
+import { chmod, mkdir as mkdir8, readFile as readFile14, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname12, join as join15 } from "path";
+import { z as z2 } from "zod";
+var GLOBAL_DIR = ".codebuddy";
+var GLOBAL_FILE = "global.json";
+var globalConfigSchema = z2.object({
+  hfToken: z2.string().min(1).optional(),
+  databaseUrl: z2.string().min(1).optional(),
+  // Where the codebuddy install lives on this machine. Cached so future
+  // `codebuddy use` calls in unrelated projects can find the CLI entry
+  // without re-resolving via process.argv every time.
+  installPath: z2.string().optional()
+});
+function globalConfigPath(home = homedir3()) {
+  return join15(home, GLOBAL_DIR, GLOBAL_FILE);
+}
+async function readGlobalConfig(home = homedir3()) {
+  const path = globalConfigPath(home);
+  try {
+    const raw = await readFile14(path, "utf8");
+    return globalConfigSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+async function writeGlobalConfig(next, home = homedir3()) {
+  const path = globalConfigPath(home);
+  await mkdir8(dirname12(path), { recursive: true, mode: 448 });
+  await writeFile3(path, `${JSON.stringify(next, null, 2)}
+`, { mode: 384 });
+  await chmod(path, 384);
+  return { path };
+}
+async function mergeGlobalConfig(patch, home = homedir3()) {
+  const current = await readGlobalConfig(home);
+  const merged = { ...current, ...patch };
+  const { path } = await writeGlobalConfig(merged, home);
+  return { path, merged };
+}
+
+// src/cli/commands/docker-autostart.ts
+import { spawn as spawn5 } from "child_process";
+async function isDockerDaemonRunning() {
+  return new Promise((resolve14) => {
+    const child = spawn5("docker", ["info"], { stdio: "ignore" });
+    child.on("error", () => resolve14(false));
+    child.on("close", (code) => resolve14(code === 0));
+  });
+}
+async function tryStartDockerDesktop() {
+  if (process.platform !== "darwin") return { started: false };
+  return new Promise((resolve14) => {
+    const child = spawn5("open", ["-ga", "Docker"], { stdio: "ignore" });
+    child.on("error", () => resolve14({ started: false }));
+    child.on("close", (code) => resolve14({ started: code === 0 }));
+  });
+}
+async function waitForDockerDaemon(timeoutMs = 6e4) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isDockerDaemonRunning()) return true;
+    await new Promise((resolve14) => setTimeout(resolve14, 1e3));
+  }
+  return false;
+}
+
+// src/cli/commands/use-command.ts
+function bail2() {
+  log2.warn("Aborted.");
+  process.exit(1);
+}
+function unwrap2(value) {
+  if (isCancel2(value)) bail2();
+  return value;
+}
+async function pingOnce2(databaseUrl) {
+  const client = createDatabaseClient({ postgresUrl: databaseUrl });
+  try {
+    return await pingDatabase(client);
+  } catch {
+    return false;
+  } finally {
+    await client.close().catch(() => void 0);
+  }
+}
+function sanitizeNamespace(input) {
+  return input.replace(/[^a-zA-Z0-9_.:-]/g, "-").slice(0, 128) || "default";
+}
+var DEFAULT_DB_URL = "postgres://codebuddy:codebuddy@localhost:5432/codebuddy";
+async function runUseCommand(options = {}) {
+  const sigintHandler = () => bail2();
+  process.on("SIGINT", sigintHandler);
+  try {
+    const folderName = basename(process.cwd());
+    const namespace = sanitizeNamespace(options.namespace ?? folderName);
+    await initProjectScaffold();
+    const graphifyEnabled = options.graphify ?? unwrap2(
+      await confirm2({
+        message: "Set up Graphify for richer architecture context?",
+        initialValue: true
+      })
+    );
+    note2(
+      `Project folder: ${pc17.bold(process.cwd())}
+Namespace:      ${pc17.bold(namespace)}`,
+      "codebuddy use"
+    );
+    const stored = await readGlobalConfig();
+    let hfToken;
+    if (process.env.HF_TOKEN) {
+      hfToken = process.env.HF_TOKEN;
+      log2.info("Using HF_TOKEN from environment.");
+    } else if (stored.hfToken) {
+      hfToken = stored.hfToken;
+      log2.info(`Reusing saved Hugging Face token (${pc17.dim("~/.codebuddy/global.json")}).`);
+    } else {
+      hfToken = unwrap2(
+        await password2({
+          message: "Hugging Face token (optional; press Enter for local-only mode)"
+        })
+      );
+      if (!hfToken)
+        log2.info("No Hugging Face token supplied; local file context remains available.");
+    }
+    const initialUrl = options.postgresUrl ?? process.env.DATABASE_URL ?? stored.databaseUrl ?? DEFAULT_DB_URL;
+    const databaseUrl = unwrap2(
+      await text2({
+        message: "Postgres URL (press Enter to accept)",
+        initialValue: initialUrl,
+        validate: (value) => value && value.length > 0 ? void 0 : "Postgres URL is required."
+      })
+    );
+    const dbSpinner = spinner2();
+    dbSpinner.start("Checking Postgres");
+    let connected = await pingOnce2(databaseUrl);
+    if (connected) dbSpinner.stop("Local Postgres reachable.");
+    if (!connected && databaseUrl === DEFAULT_DB_URL) {
+      dbSpinner.stop("Postgres unreachable on the default local URL.");
+    }
+    const shouldUseDocker = !connected && databaseUrl === DEFAULT_DB_URL && (options.useDocker ?? unwrap2(
+      await confirm2({
+        message: "Postgres is unavailable. Start the bundled Docker database now?",
+        initialValue: true
+      })
+    ));
+    if (shouldUseDocker) {
+      if (!await isDockerDaemonRunning()) {
+        const dockerSpinner = spinner2();
+        dockerSpinner.start("Starting Docker Desktop");
+        await tryStartDockerDesktop();
+        const ready = await waitForDockerDaemon(6e4);
+        if (!ready) {
+          dockerSpinner.stop("Docker daemon did not start in 60s. Aborting.");
+          bail2();
+        }
+        dockerSpinner.stop("Docker daemon is up.");
+      }
+      const composeSpinner = spinner2();
+      composeSpinner.start("docker compose up -d");
+      try {
+        const result = await postgresUp();
+        if (result.code === 0) {
+          composeSpinner.stop("Postgres container started.");
+          for (let attempt = 0; attempt < 12 && !connected; attempt++) {
+            await new Promise((resolve14) => setTimeout(resolve14, 500));
+            connected = await pingOnce2(databaseUrl);
+          }
+          if (!connected) {
+            log2.warn("Container running but Postgres did not accept connections in time.");
+          }
+        } else {
+          composeSpinner.stop(`docker compose failed: ${result.stderr || result.stdout}`);
+        }
+      } catch (error) {
+        composeSpinner.stop(`docker compose failed: ${error.message}`);
+      }
+    } else if (!connected) {
+      dbSpinner.stop(connected ? "Postgres reachable." : "Postgres unreachable at this URL.");
+      log2.warn(
+        "Local Postgres is required. Start it, set DATABASE_URL, pass --postgres-url, or allow the bundled Docker database."
+      );
+      bail2();
+    }
+    if (!connected) bail2();
+    const migrateSpinner = spinner2();
+    migrateSpinner.start("Enabling pgvector + applying migrations");
+    {
+      const client = createDatabaseClient({ postgresUrl: databaseUrl });
+      try {
+        await bootstrapDatabase(client.sql);
+        await runMigrations(client);
+        migrateSpinner.stop("Database ready.");
+      } catch (error) {
+        migrateSpinner.stop(`Migration error: ${error.message}`);
+        bail2();
+      } finally {
+        await client.close().catch(() => void 0);
+      }
+    }
+    await mergeGlobalConfig({
+      ...hfToken ? { hfToken } : {},
+      databaseUrl,
+      installPath: process.argv[1] ?? void 0
+    });
+    const existingConfig = await readConfigFile();
+    const indexSpinner = spinner2();
+    indexSpinner.start("Indexing the existing repository");
+    try {
+      const result = await indexRepository({ repositoryRoot: process.cwd() });
+      indexSpinner.stop(`Repository indexed (${result.totalIndexed} files).`);
+    } catch (error) {
+      indexSpinner.stop(`Repository indexing skipped: ${error.message}`);
+    }
+    const graphifySetup = graphifyEnabled ? await setupGraphify({ repositoryRoot: process.cwd() }) : null;
+    const graphifyConfigured = graphifySetup?.available === true && graphifySetup.generated;
+    await writeConfigFile({
+      ...existingConfig,
+      postgresUrl: databaseUrl,
+      namespace,
+      provider: { type: "huggingface", ...hfToken ? { apiKey: hfToken } : {} },
+      tokenBudget: existingConfig.tokenBudget ?? 4e3,
+      graphify: { enabled: graphifyConfigured, graphPath: "graphify-out/graph.json" }
+    });
+    const graphifyMessage = graphifySetup?.message ?? "Graphify disabled; CodeBuddy MCP remains available.";
+    await writeProjectMcpConfig({
+      repositoryRoot: process.cwd(),
+      namespace,
+      graphify: graphifyConfigured,
+      ...graphifySetup?.graphPath ? { graphPath: graphifySetup.graphPath } : {}
+    });
+    await installWorkflowRules({ client: "claude", projectRoot: process.cwd() });
+    await installWorkflowRules({ client: "codex", projectRoot: process.cwd() });
+    if (!options.skipClaude) {
+      try {
+        const install = await installClaudeEntry({
+          namespace,
+          projectRoot: process.cwd(),
+          hfToken,
+          databaseUrl
+        });
+        log2.success(
+          `Registered ${pc17.bold(install.serverKey)} in Claude Desktop. Restart with \u2318Q to activate.`
+        );
+      } catch (error) {
+        log2.warn(`Claude Desktop registration skipped: ${error.message}`);
+      }
+    }
+    if (!options.skipCodex) {
+      try {
+        const install = await installCodexEntry({
+          namespace,
+          projectRoot: process.cwd(),
+          hfToken,
+          databaseUrl
+        });
+        log2.success(
+          `Registered ${pc17.bold(install.serverKey)} in Codex. Restart Codex to activate.`
+        );
+      } catch (error) {
+        log2.warn(`Codex registration skipped: ${error.message}`);
+      }
+    }
+    note2(
+      [
+        `${pc17.green("\u2713")} CodeBuddy is ready for ${pc17.bold(folderName)}.`,
+        `${pc17.green("\u2713")} Scaffolded ${pc17.cyan(".codebuddy/policies.yaml")} for project-specific guardrails.`,
+        `${pc17.green("\u2713")} ${graphifyMessage}`,
+        `${pc17.green("\u2713")} Added agent workflow instructions to ${pc17.cyan("CLAUDE.md")} and ${pc17.cyan("AGENTS.md")}.`,
+        ``,
+        `Next:`,
+        `  1. Restart Claude Desktop and Codex.`,
+        `  2. Ask Claude or Codex to use the ${pc17.cyan("context_pack")} tool for each coding task.`,
+        `  3. Indexing, Graphify, Markdown memory import, and embeddings now update automatically while the MCP server is running.`,
+        `  4. Run ${pc17.cyan("codebuddy doctor")} or ${pc17.cyan("codebuddy db doctor")} if you want a full health check.`,
+        ``,
+        `Manage:`,
+        `  codebuddy claude list           ${pc17.dim("# see every project wired up")}`,
+        `  codebuddy codex list            ${pc17.dim("# see Codex entries")}`,
+        `  codebuddy db test               ${pc17.dim("# quick Postgres connectivity check")}`,
+        `  codebuddy claude remove codebuddy-${namespace}`,
+        `  codebuddy codex remove codebuddy-${namespace}`,
+        `  codebuddy postgres down         ${pc17.dim("# stop the DB (data preserved)")}`
+      ].join("\n"),
+      "Done"
+    );
+  } finally {
+    process.off("SIGINT", sigintHandler);
+  }
+}
+
+// src/cli/commands/worklog.ts
+import { relative as relative6 } from "path";
+import pc18 from "picocolors";
+function registerWorklogCommands(program, runSafely2) {
+  const worklog = program.command("worklog").description("Inspect the cross-chat worklog of completed turns.");
+  worklog.command("list", { isDefault: true }).option("--limit <n>", "Maximum entries to show.", "20").option("--json", "Print machine-readable JSON.").description("List worklog entries, newest first.").action(async (opts) => {
+    await runSafely2(async () => {
+      const entries = (await new WorklogStore().list()).slice(0, Number(opts.limit) || 20);
+      if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+      }
+      if (entries.length === 0) {
+        console.log(pc18.dim("no worklog entries yet"));
+        return;
+      }
+      for (const entry of entries) console.log(renderRow2(entry));
+    });
+  });
+  worklog.command("show").argument("<id>").description("Show a single worklog entry.").action(async (id) => {
+    await runSafely2(async () => {
+      console.log(renderEntry(await new WorklogStore().read(id)));
+    });
+  });
+  worklog.command("latest").description("Show the most recent worklog entry.").action(async () => {
+    await runSafely2(async () => {
+      const [entry] = await new WorklogStore().list();
+      console.log(entry ? renderEntry(entry) : pc18.dim("no worklog entries yet"));
+    });
+  });
+}
+function renderRow2(entry) {
+  const summary = entry.summary.replace(/\s+/g, " ");
+  const short = summary.length <= 70 ? summary : `${summary.slice(0, 69)}\u2026`;
+  return `${pc18.dim(entry.createdAt.slice(0, 16))}  ${pc18.dim(entry.id)}  ${short}  ${pc18.dim(`(${entry.files.length} file(s))`)}`;
+}
+function renderEntry(entry) {
+  const lines = [`${pc18.bold(entry.id)}  ${pc18.dim(entry.createdAt)}  ${pc18.dim(entry.namespace)}`];
+  if (entry.sourceSessionId) lines.push(`${pc18.bold("session:")} ${entry.sourceSessionId}`);
+  if (entry.sourcePlanId) lines.push(`${pc18.bold("plan:")} ${entry.sourcePlanId}`);
+  if (entry.commitSha) lines.push(`${pc18.bold("commit:")} ${entry.commitSha}`);
+  if (entry.files.length > 0) lines.push(`${pc18.bold("files:")} ${entry.files.join(", ")}`);
+  if (entry.verification.length > 0) {
+    lines.push(`${pc18.bold("verification:")}`, ...entry.verification.map((line) => `  - ${line}`));
+  }
+  if (entry.savedMemory.length > 0) {
+    lines.push(`${pc18.bold("saved memory:")} ${entry.savedMemory.join(", ")}`);
+  }
+  if (entry.queuedForReview.length > 0) {
+    lines.push(`${pc18.bold("queued for review:")} ${entry.queuedForReview.join(", ")}`);
+  }
+  lines.push("", entry.summary, "", pc18.dim(relative6(process.cwd(), entry.path)));
+  return lines.join("\n");
+}
+
+// src/cli/commands/zvec.ts
+import pc19 from "picocolors";
+function registerZvecCommands(program, runSafely2) {
+  const zvec = program.command("zvec").description("Optional zvec-grep semantic file discovery for the context tools.");
+  zvec.command("status", { isDefault: true }).option("--json", "Print machine-readable JSON.").description("Show whether zvec-grep is enabled, installed, supported and indexed.").action(async (opts) => {
+    await runSafely2(async () => {
+      const report = await zvecStatus(process.cwd());
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+      const mark = (ok) => ok ? pc19.green("yes") : pc19.yellow("no");
+      console.log(`enabled:      ${mark(report.enabled)}`);
+      console.log(`binary:       ${report.binary}`);
+      console.log(
+        `version:      ${report.version ?? pc19.yellow("not found")}${report.version && !report.supported ? pc19.yellow(" (unsupported; need 0.2.x)") : ""}`
+      );
+      console.log(`index ready:  ${mark(report.indexReady)}`);
+      console.log(
+        `zg server:    ${report.server} ${pc19.dim("(running = faster queries; optional)")}`
+      );
+      console.log(`status:       ${report.reason}`);
+      if (!report.version) console.log(pc19.dim("install: npm install -g @zvec/zvec-grep"));
+      else if (report.supported && !report.indexReady)
+        console.log(pc19.dim("next: codebuddy zvec index"));
+      else if (report.indexReady && !report.enabled)
+        console.log(pc19.dim("next: codebuddy zvec enable"));
+    });
+  });
+  zvec.command("index").option("--model <model>", "Embedding model for a new index.", DEFAULT_ZVEC_MODEL).option("--rebuild", "Rebuild the index from scratch (e.g. after changing model).").description("Build or refresh the zg index for this repository (explicit; never automatic).").action(async (opts) => {
+    await runSafely2(async () => {
+      const code = await buildZvecIndex(process.cwd(), {
+        model: opts.model,
+        ...opts.rebuild ? { rebuild: true } : {}
+      });
+      if (code !== 0) throw new Error(`zg index exited with code ${code}`);
+      console.log(
+        pc19.dim("tip: add .zvec-grep/ to .gitignore; enable with `codebuddy zvec enable`")
+      );
+    });
+  });
+  zvec.command("enable").description("Use zvec-grep candidates in context_pack / context_before_edit.").action(async () => {
+    await runSafely2(async () => {
+      await setZvecEnabled(true);
+      console.log(
+        `${pc19.green("enabled")} zvec-grep retrieval (falls back to keywords if unavailable)`
+      );
+    });
+  });
+  zvec.command("disable").description("Stop using zvec-grep; keyword ranking only.").action(async () => {
+    await runSafely2(async () => {
+      await setZvecEnabled(false);
+      console.log(`${pc19.yellow("disabled")} zvec-grep retrieval`);
+    });
+  });
+}
+
+// src/cli/main.ts
+function createCli() {
+  const program = new Command();
+  program.name("codebuddy").description(
+    "Local-first MCP memory and automatic project-context engine for multi-agent coding."
+  ).version(VERSION);
+  program.action(async () => {
+    await runSafely(async () => {
+      await runUseCommand();
+    });
+  });
+  program.command("use").description(
+    "One-command setup for the current project folder. Reuses saved HF token + DB URL, auto-starts Docker, runs migrations, and wires Claude Desktop."
+  ).argument("[namespace]", "Override the namespace (defaults to current folder name).").option("--postgres-url <url>", "Postgres URL to use for this project.").option("--skip-claude", "Do not register with Claude Desktop.").option("--skip-codex", "Do not register with Codex.").option("--graphify", "Enable Graphify setup without prompting.").option("--no-graphify", "Skip Graphify setup without prompting.").option(
+    "--docker",
+    "Start CodeBuddy's bundled Postgres container when the default DB is unavailable."
+  ).option("--no-docker", "Do not offer to start CodeBuddy's bundled Postgres container.").action(
+    async (namespace, opts) => {
+      await runSafely(async () => {
+        await runUseCommand({
+          ...namespace !== void 0 ? { namespace } : {},
+          ...opts.postgresUrl !== void 0 ? { postgresUrl: opts.postgresUrl } : {},
+          ...opts.skipClaude !== void 0 ? { skipClaude: opts.skipClaude } : {},
+          ...opts.skipCodex !== void 0 ? { skipCodex: opts.skipCodex } : {},
+          ...opts.graphify !== void 0 ? { graphify: opts.graphify } : {},
+          ...opts.docker !== void 0 ? { useDocker: opts.docker } : {}
+        });
+      });
+    }
+  );
+  program.command("init").description("Interactive setup: config file, Postgres, migrations, Claude Desktop.").option("--non-interactive", "Skip the wizard; just create .codebuddy/config.json.").option("--github-action", "Install the GitHub PR change-safety workflow.").action(async (opts) => {
+    await runSafely(async () => {
+      if (opts.nonInteractive || !process.stdin.isTTY) {
+        const result = await initConfigFile();
+        console.log(`${result.created ? "created" : "updated permissions"} ${result.path}`);
+        if (opts.githubAction) {
+          const workflow = await installGitHubWorkflow();
+          console.log(`${workflow.created ? "installed" : "already present"} ${workflow.path}`);
+        }
+        return;
+      }
+      await runInitWizard();
+      if (opts.githubAction) {
+        const workflow = await installGitHubWorkflow();
+        console.log(`${workflow.created ? "installed" : "already present"} ${workflow.path}`);
+      }
+    });
+  });
+  const graphify = program.command("graphify").description("Build the local Graphify repository graph.");
+  graphify.command("index").argument("[projectRoot]", "Project root (defaults to the current directory).").option("--graph <path>", "Graph path relative to the project root.").description("Generate or incrementally update graphify-out/graph.json.").action(async (projectRoot, opts) => {
+    await runSafely(async () => {
+      const root = projectRoot ?? process.cwd();
+      const result = await generateGraphifyGraph({
+        repositoryRoot: root,
+        ...opts.graph ? { graphPath: opts.graph } : {}
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+  });
+  const migrate = program.command("migrate").description("Apply pending database migrations.").action(async () => {
+    await runSafely(async () => {
+      const config = await loadRuntimeConfig();
+      const client = createDatabaseClient({ postgresUrl: config.postgresUrl });
+      try {
+        await bootstrapDatabase(client.sql);
+        await runMigrations(client);
+        console.log("migrations applied");
+      } finally {
+        await client.close();
+      }
+    });
+  });
+  migrate.command("to-files").description("Preview or write existing facts and summaries as Markdown files.").option("--write", "Write files. Without this flag the command is a dry run.").action(async (opts) => {
+    await withRuntime(async (runtime) => {
+      const config = await loadRuntimeConfig();
+      const result = await migrateMemoryToFiles({
+        repository: runtime.repository,
+        store: new MemoryFileStore(config.projectRoot ?? process.cwd()),
+        namespace: config.namespace,
+        write: opts.write ?? false
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+  });
+  program.command("reindex").description("Rebuild fact and summary records from Markdown files.").option("--full", "Scan every Markdown memory file.").action(async (_opts) => {
+    await withRuntime(async (runtime) => {
+      console.log(JSON.stringify(await runtime.memory.reindexMemory(), null, 2));
+    });
+  });
+  const postgres = program.command("postgres").description("Manage the bundled Postgres container.");
+  postgres.command("up").description("Start the bundled Postgres container (docker compose up -d).").action(async () => {
+    await runSafely(async () => {
+      const result = await postgresUp();
+      process.stdout.write(result.stdout);
+      if (result.code !== 0) {
+        process.stderr.write(result.stderr);
+        process.exitCode = result.code;
+      }
+    });
+  });
+  const db = program.command("db").description("Check database connectivity and setup health.");
+  db.command("doctor").description("Check Postgres reachability, pgvector, and namespace assumptions.").action(async () => {
+    await runSafely(async () => {
+      const report = await runDoctor({ skipModelCheck: true });
+      printDbDoctor(report);
+      if (!report.db.ok || !report.pgvector.ok || !report.namespace.ok) process.exitCode = 1;
+    });
+  });
+  db.command("test").description("Run a simple database connectivity test.").action(async () => {
+    await runSafely(async () => {
+      const report = await runDoctor({ skipModelCheck: true });
+      if (!report.db.ok) {
+        console.log("database test: fail");
+        if (report.db.error) console.log(`  ${report.db.error}`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log("database test: ok");
+    });
+  });
+  postgres.command("down").description("Stop the bundled Postgres container (data volume preserved).").action(async () => {
+    await runSafely(async () => {
+      const result = await postgresDown();
+      process.stdout.write(result.stdout);
+      if (result.code !== 0) {
+        process.stderr.write(result.stderr);
+        process.exitCode = result.code;
+      }
+    });
+  });
+  postgres.command("status").description("docker compose ps for the bundled Postgres container.").action(async () => {
+    await runSafely(async () => {
+      const result = await postgresStatus();
+      process.stdout.write(result.stdout);
+      if (result.code !== 0) {
+        process.stderr.write(result.stderr);
+        process.exitCode = result.code;
+      }
+    });
+  });
+  const claude = program.command("claude").description("Register CodeBuddy as an MCP server in Claude Desktop.");
+  claude.command("install").option("--namespace <name>", "Namespace for this Claude Desktop entry.").option("--server-name <name>", "Override the server key. Defaults to codebuddy-<namespace>.").description("Add or update a codebuddy MCP entry in Claude Desktop's config.").action(async (opts) => {
+    await runSafely(async () => {
+      const config = await loadRuntimeConfig();
+      const namespace = opts.namespace ?? config.namespace ?? "default";
+      const install = await installClaudeEntry({
+        namespace,
+        projectRoot: process.cwd(),
+        ...config.provider.apiKey ? { hfToken: config.provider.apiKey } : {},
+        ...process.env.GROQ_API_KEY ? { groqApiKey: process.env.GROQ_API_KEY } : {},
+        databaseUrl: config.postgresUrl,
+        ...opts.serverName ? { serverName: opts.serverName } : {}
+      });
+      console.log(
+        `${install.created ? "added" : "updated"} ${install.serverKey} in ${install.path}`
+      );
+      console.log("Restart Claude Desktop (\u2318Q) to activate.");
+    });
+  });
+  claude.command("list").description("List codebuddy entries currently registered in Claude Desktop.").action(async () => {
+    await runSafely(async () => {
+      const result = await listClaudeEntries();
+      if (result.entries.length === 0) {
+        console.log(`No codebuddy entries in ${result.path}.`);
+        return;
+      }
+      console.log(`Claude Desktop config: ${result.path}`);
+      for (const entry of result.entries) {
+        console.log(
+          `  ${entry.key}  namespace=${entry.namespace ?? "?"}  db=${entry.databaseUrl ?? "?"}`
+        );
+      }
+    });
+  });
+  claude.command("remove").argument("<serverKey>", "e.g. codebuddy-work").description("Remove a codebuddy entry from Claude Desktop's config.").action(async (serverKey) => {
+    await runSafely(async () => {
+      const result = await removeClaudeEntry(serverKey);
+      if (result.removed) {
+        console.log(`removed ${serverKey} from ${result.path}`);
+        console.log("Restart Claude Desktop (\u2318Q) for the change to take effect.");
+      } else {
+        console.log(`no entry "${serverKey}" found in ${result.path}`);
+        process.exitCode = 1;
+      }
+    });
+  });
+  const codex = program.command("codex").description("Register CodeBuddy as an MCP server in Codex.");
+  codex.command("install").option("--namespace <name>", "Namespace for this Codex entry.").option("--server-name <name>", "Override the server key. Defaults to codebuddy-<namespace>.").description("Add or update a codebuddy MCP entry in ~/.codex/config.toml.").action(async (opts) => {
+    await runSafely(async () => {
+      const config = await loadRuntimeConfig();
+      const namespace = opts.namespace ?? config.namespace ?? "default";
+      const install = await installCodexEntry({
+        namespace,
+        projectRoot: process.cwd(),
+        ...config.provider.apiKey ? { hfToken: config.provider.apiKey } : {},
+        databaseUrl: config.postgresUrl,
+        ...opts.serverName ? { serverName: opts.serverName } : {}
+      });
+      console.log(
+        `${install.created ? "added" : "updated"} ${install.serverKey} in ${install.path}`
+      );
+      console.log("Restart Codex to activate.");
+    });
+  });
+  codex.command("list").description("List codebuddy entries currently registered in Codex.").action(async () => {
+    await runSafely(async () => {
+      const result = await listCodexEntries();
+      if (result.entries.length === 0) {
+        console.log(`No codebuddy entries in ${result.path}.`);
+        return;
+      }
+      console.log(`Codex config: ${result.path}`);
+      for (const entry of result.entries) {
+        console.log(
+          `  ${entry.key}  namespace=${entry.namespace ?? "?"}  db=${entry.databaseUrl ?? "?"}`
+        );
+      }
+    });
+  });
+  codex.command("remove").argument("<serverKey>", "e.g. codebuddy-work").description("Remove a codebuddy entry from Codex config.").action(async (serverKey) => {
+    await runSafely(async () => {
+      const result = await removeCodexEntry(serverKey);
+      if (result.removed) {
+        console.log(`removed ${serverKey} from ${result.path}`);
+        console.log("Restart Codex for the change to take effect.");
+      } else {
+        console.log(`no entry "${serverKey}" found in ${result.path}`);
+        process.exitCode = 1;
+      }
+    });
+  });
+  program.command("serve").description("Start the CodeBuddy MCP stdio server.").action(async () => runSafely(() => startMcpServer()));
+  program.command("inspect").argument("[namespace]").description("Inspect namespaces or a namespace.").action(async (namespace) => {
+    await withRuntime(async (runtime) => {
+      console.log(JSON.stringify(await inspectNamespace(runtime.repository, namespace), null, 2));
+    });
+  });
+  program.command("namespaces").description("List namespaces.").action(async () => {
+    await withRuntime(async (runtime) => {
+      console.log(
+        JSON.stringify({ namespaces: await runtime.repository.listNamespaces() }, null, 2)
+      );
+    });
+  });
+  program.command("prune").requiredOption("--older-than <duration>", "Duration such as 30d, 12h, or 60m.").description("Delete memories older than a duration.").action(async (opts) => {
+    await withRuntime(async (runtime) => {
+      const durationMs = parseDuration(opts.olderThan);
+      if (!Number.isFinite(durationMs) || durationMs <= 0) {
+        throw new Error("--older-than must be a positive duration (e.g. 30d, 12h, 60m).");
+      }
+      const cutoff = new Date(Date.now() - durationMs);
+      console.log(JSON.stringify(await runtime.repository.pruneBefore(cutoff), null, 2));
+    });
+  });
+  program.command("export").argument("<namespace>").description("Export facts from a namespace as JSON.").action(async (namespace) => {
+    await withRuntime(async (runtime) => {
+      const row = await runtime.repository.getNamespaceByName(namespace);
+      if (!row) throw new Error(`Namespace ${namespace} does not exist.`);
+      const facts = await runtime.repository.listFacts({ namespaceId: row.id, limit: 1e4 });
+      console.log(JSON.stringify({ namespace, facts }, null, 2));
+    });
+  });
+  program.command("stats").description("Show CodeBuddy storage and usage stats.").action(async () => {
+    await withRuntime(async (runtime) => {
+      console.log(JSON.stringify(await runtime.repository.getStats(), null, 2));
+    });
+  });
+  program.command("doctor").description("Check CodeBuddy environment health.").option("--skip-model-check", "Do not call Hugging Face models.").action(async (opts) => {
+    await runSafely(async () => {
+      const report = await runDoctor({ skipModelCheck: opts.skipModelCheck ?? true });
+      printDoctor(report);
+      if (!report.db.ok || !report.pgvector.ok || report.config.warning || !report.scaffold.policies.ok || !report.scaffold.codebuddyDir.ok || !report.namespace.ok) {
+        process.exitCode = 1;
+      }
+    });
+  });
+  program.command("list-facts").option("--subject <subject>").option("--limit <limit>", "Maximum facts to print.", Number).option("--cursor <cursor>").description("List facts from the configured namespace.").action(async (opts) => {
+    await withRuntime(async (runtime) => {
+      console.log(
+        JSON.stringify(await listFactsPage(runtime.memory, runtime.repository, opts), null, 2)
+      );
+    });
+  });
+  registerPlanCommands(program, runSafely);
+  registerChangeCommand(program, runSafely);
+  registerRiskCommands(program, runSafely);
+  registerMapCommands(program, runSafely);
+  registerContextCommands(program, runSafely);
+  registerEvalCommand(program, runSafely);
+  registerIndexCommands(program, runSafely);
+  registerLearnCommand(program, runSafely);
+  registerMemoryCommands(program, runSafely);
+  registerWorklogCommands(program, runSafely);
+  registerZvecCommands(program, runSafely);
+  registerLlmCommands(program, runSafely);
+  registerSuggestCommand(program, runSafely);
+  registerRulesCommands(program, runSafely);
+  registerHooksCommands(program, runSafely);
+  registerClientsCommands(program, runSafely);
+  registerGitHubCommands(program, runSafely);
+  registerSymbolsCommand(program, runSafely);
+  program.action(async () => {
+    await runSafely(() => runUseCommand());
+  });
+  return program;
+}
+async function withRuntime(fn) {
+  await runSafely(async () => {
+    const runtime = await createRuntime(await loadRuntimeConfig());
+    try {
+      await fn(runtime);
+    } finally {
+      await runtime.close();
+    }
+  });
+}
+async function runSafely(fn) {
+  try {
+    await fn();
+  } catch (error) {
+    console.error(pc20.red(String(redactSecrets(error.message))));
+    process.exitCode = 1;
+  }
+}
+function parseDuration(value) {
+  const match = /^(\d+)([dhm])$/.exec(value);
+  if (!match) throw new Error("--older-than must look like 30d, 12h, or 60m.");
+  const amount = Number(match[1]);
+  const unit = match[2];
+  if (unit === "d") return amount * 24 * 60 * 60 * 1e3;
+  if (unit === "h") return amount * 60 * 60 * 1e3;
+  return amount * 60 * 1e3;
+}
+function printDoctor(report) {
+  const ok = pc20.green("ok");
+  const bad = pc20.red("fail");
+  const warn = pc20.yellow("warn");
+  console.log(`scaffold root: ${report.scaffold.codebuddyDir.ok ? ok : bad}`);
+  if (report.scaffold.codebuddyDir.warning)
+    console.log(`  ${report.scaffold.codebuddyDir.warning}`);
+  console.log(`policy scaffold: ${report.scaffold.policies.ok ? ok : bad}`);
+  if (report.scaffold.policies.warning) console.log(`  ${report.scaffold.policies.warning}`);
+  console.log(`DB connectivity: ${report.db.ok ? ok : bad}`);
+  if (report.db.error) console.log(`  ${report.db.error}`);
+  console.log(`pgvector: ${report.pgvector.ok ? ok : bad}`);
+  if (report.pgvector.error) console.log(`  ${report.pgvector.error}`);
+  console.log(`namespace: ${report.namespace.ok ? ok : warn}`);
+  console.log(
+    `  runtime=${report.namespace.runtime ?? "unset"} default=${report.namespace.expectedDefault}`
+  );
+  if (report.namespace.warning) console.log(`  ${report.namespace.warning}`);
+  console.log(
+    `vectors: ${report.vectors.count} index=${report.vectors.index ?? "missing"} tuning=${report.vectors.needsTuning ? "recommended" : "not-needed"}`
+  );
+  console.log(
+    `recent calls: 60s=${report.usage.last60s} hour=${report.usage.lastHour} 24h=${report.usage.last24h}`
+  );
+  console.log(`estimated daily cap remaining: ${report.usage.estimatedDailyCapRemaining}`);
+  if (report.usage.warning80Percent)
+    console.log(pc20.yellow("usage warning: daily cap is over 80% used"));
+  console.log(
+    `config permissions: ${report.config.exists ? report.config.mode : "missing"} ${report.config.ok ? ok : warn}`
+  );
+  if (report.config.warning) console.log(`  ${report.config.warning}`);
+  for (const model of report.models) {
+    console.log(`model ${model.id}: ${model.status}${model.error ? ` (${model.error})` : ""}`);
+  }
+}
+function printDbDoctor(report) {
+  const ok = pc20.green("ok");
+  const bad = pc20.red("fail");
+  const warn = pc20.yellow("warn");
+  console.log(`DB connectivity: ${report.db.ok ? ok : bad}`);
+  if (report.db.postgresUrlSource) console.log(`  url source: ${report.db.postgresUrlSource}`);
+  if (report.db.error) console.log(`  ${report.db.error}`);
+  console.log(`pgvector: ${report.pgvector.ok ? ok : bad}`);
+  if (report.pgvector.error) console.log(`  ${report.pgvector.error}`);
+  console.log(`namespace: ${report.namespace.ok ? ok : warn}`);
+  console.log(`  runtime=${report.namespace.runtime ?? "unset"}`);
+  if (report.namespace.warning) console.log(`  ${report.namespace.warning}`);
+}
+export {
+  createCli
+};
+//# sourceMappingURL=main-ZZ3EQLYA.js.map