@orquentra/codebuddy 2.4.1 → 2.5.0

package/dist/{main-BFDVQHKO.js → main-BDVQAGAS.js}

@@ -1,7 +1,16 @@
+import {
+  loadLlmSummaries,
+  summarizeRepository
+} from "./chunk-PCE4STAY.js";
+import {
+  chatJson,
+  coolingDown,
+  usageToday
+} from "./chunk-UFZD3JAA.js";
 import {
   renderLeanBlock,
   runLeanHookCommand
-} from "./chunk-DSN5CEHO.js";
+} from "./chunk-ROQTT5ZO.js";
 import {
   runPreToolHookCommand
 } from "./chunk-WHZSVY2L.js";
@@ -11,7 +20,6 @@ import {
   writeStdout
 } from "./chunk-PYLH4MH5.js";
 import {
-  MemoryFileStore,
   PlanFileStore,
   PlanLifecycle,
   ReviewStore,
@@ -19,43 +27,30 @@ import {
   WorklogStore,
   approveReviewItem,
   assessRisk,
-  bootstrapDatabase,
   buildBeforeEditContext,
   buildBootstrapContext,
-  createDatabaseClient,
-  createRuntime,
   generateSuggestions,
-  inspectNamespace,
-  listFactsPage,
   migrateMemoryToFiles,
-  pingDatabase,
+  openHookSemantics,
+  parseTraceLines,
+  readTraces,
   registerCodeBuddyTools,
   renderContextBlock,
   resolveRiskPaths,
   runCaptureHook,
   runContextHook,
-  runDoctor,
-  runMigrations,
   runResetHook,
   runStageHook,
+  runSyncHook,
   startMcpServer,
+  tracePath,
   watchRepository
-} from "./chunk-OLFCOR4U.js";
+} from "./chunk-Z5QB367W.js";
+import "./chunk-IHQM2ZDV.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";
+  estimateTokens
+} from "./chunk-CQPCHMBS.js";
 import {
   buildArchitectureMap,
   generateGraphifyGraph,
@@ -65,23 +60,49 @@ import {
   neighbours,
   queryMap,
   setupGraphify
-} from "./chunk-IBMJYIEP.js";
+} from "./chunk-L5AYZC3F.js";
 import {
   extractSymbolTable,
   supportsSymbols
 } from "./chunk-PQK3GKZH.js";
-import "./chunk-IHQM2ZDV.js";
 import {
-  chatJson,
-  coolingDown,
-  usageToday
-} from "./chunk-IE2OUO54.js";
+  MemoryFileStore,
+  bootstrapDatabase,
+  buildProviderFromConfig,
+  createDatabaseClient,
+  createRuntime,
+  embeddingSpaceKey,
+  inspectNamespace,
+  listFactsPage,
+  pingDatabase,
+  runDoctor,
+  runMigrations
+} from "./chunk-JDZ3VK26.js";
 import {
   redactPersisted
 } from "./chunk-GDJH7XJC.js";
+import {
+  computeFactHash,
+  generateEntityId
+} from "./chunk-4BYGTEJT.js";
+import "./chunk-KYK6RPAJ.js";
+import {
+  modelCacheDir
+} from "./chunk-3XYQGFPB.js";
+import {
+  DEFAULT_CLOUD_EMBEDDING_MODELS,
+  DEFAULT_RERANK_MODELS,
+  LOCAL_EMBEDDING_MODEL,
+  getModelDefinition
+} from "./chunk-JMWJ7V6Y.js";
+import {
+  DEFAULT_ZVEC_MODEL,
+  buildZvecIndex,
+  zvecStatus
+} from "./chunk-QDBDYCM2.js";
 import {
   resolveLlmConfig
-} from "./chunk-ITGRANYW.js";
+} from "./chunk-6MKEIDX5.js";
 import {
   PLAN_POLICIES,
   configPath,
@@ -92,17 +113,18 @@ import {
   readConfigFile,
   redactSecrets,
   resolveNamespaceFrom,
+  setConfigBlock,
   setLlmEnabled,
   setPlanPolicy,
   setZvecEnabled,
   writeAtomic,
   writeConfigFile
-} from "./chunk-K63EOA4B.js";
+} from "./chunk-776EQXDV.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/cli/main.ts
 import { Command } from "commander";
-import pc20 from "picocolors";
+import pc22 from "picocolors";
 
 // src/integrations/github.ts
 import { constants } from "fs";
@@ -2432,14 +2454,21 @@ async function runBeforeEdit(taskParts, opts) {
     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 } : {}
-  });
+  const semantics = task ? await openHookSemantics(process.cwd()) : null;
+  try {
+    return await buildBeforeEditContext({
+      namespace,
+      ...task ? { task } : {},
+      ...semantics?.semanticRanker ? { semanticRanker: semantics.semanticRanker } : {},
+      ...semantics?.reranker ? { reranker: semantics.reranker } : {},
+      ...opts.paths ? { paths: parsePaths2(opts.paths) } : {},
+      ...opts.plan ? { planId: opts.plan } : {},
+      ...opts.git !== void 0 ? { useGit: opts.git } : {},
+      ...tokenBudget !== void 0 ? { tokenBudget } : {}
+    });
+  } finally {
+    await semantics?.close();
+  }
 }
 function printBootstrap(ctx) {
   console.log(`${pc3.bold("project")} ${ctx.project.namespace}  ${pc3.dim(ctx.project.root)}`);
@@ -2549,9 +2578,479 @@ function scoreColor(score) {
   return pc3.green(String(score));
 }
 
-// src/cli/commands/eval.ts
+// src/cli/commands/dashboard.ts
+import { spawn as spawn2 } from "child_process";
 import pc4 from "picocolors";
 
+// src/dashboard/server.ts
+import { unwatchFile, watchFile } from "fs";
+import { open, stat } from "fs/promises";
+import { createServer } from "http";
+import { basename } from "path";
+
+// src/dashboard/page.ts
+var DASHBOARD_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CodeBuddy Traces</title>
+<style>
+:root {
+  --bg: #f3f5f7; --panel: #ffffff; --fg: #141a21; --muted: #5d6874; --line: #dde3e8;
+  --recall: #0a8f80; --tool: #c2410c; --recall-soft: #e0f2ef; --tool-soft: #fbeae2;
+  --bad: #b42318; --bad-soft: #fdecea; --capture: #4b5563;
+  --sans: ui-sans-serif, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+}
+@media (prefers-color-scheme: dark) { :root {
+  --bg: #0e1116; --panel: #161b22; --fg: #e6eaee; --muted: #94a0ad; --line: #28303a;
+  --recall: #0d9488; --tool: #ea580c; --recall-soft: #10302c; --tool-soft: #3a1e12;
+  --bad: #f97066; --bad-soft: #3b1715; --capture: #9aa4ae; color-scheme: dark } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 var(--sans); }
+.wrap { max-width: 1280px; margin: 0 auto; padding: 20px 20px 48px; display: grid; gap: 16px; }
+header { display: flex; flex-wrap: wrap; align-items: center; gap: 12px 20px; }
+h1 { font-size: 18px; margin: 0; letter-spacing: -.01em; }
+h1 small { font: 500 13px var(--mono); color: var(--muted); margin-left: 8px; }
+h2 { font-size: 13px; margin: 0 0 10px; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); font-weight: 600; }
+.live { display: inline-flex; align-items: center; gap: 6px; font: 12px var(--mono); color: var(--muted); }
+.dot { width: 8px; height: 8px; border-radius: 50%; background: var(--muted); }
+.live.on .dot { background: var(--recall); box-shadow: 0 0 0 3px var(--recall-soft); }
+.spacer { flex: 1; }
+.seg { display: inline-flex; border: 1px solid var(--line); border-radius: 8px; overflow: hidden; background: var(--panel); }
+.seg button { border: 0; background: none; color: var(--muted); font: 500 12px var(--sans); padding: 6px 12px; cursor: pointer; }
+.seg button + button { border-left: 1px solid var(--line); }
+.seg button[aria-pressed="true"] { background: var(--fg); color: var(--bg); }
+.seg button:focus-visible { outline: 2px solid var(--recall); outline-offset: -2px; }
+.wrap > * { min-width: 0; }
+.kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 12px; }
+.kpi { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
+.kpi .label { font-size: 12px; color: var(--muted); }
+.kpi .value { font: 600 24px/1.2 var(--mono); font-variant-numeric: tabular-nums; margin-top: 4px; }
+.kpi .sub { font-size: 12px; color: var(--muted); margin-top: 2px; }
+.panel { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; min-width: 0; }
+.cols { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 16px; }
+@media (max-width: 900px) { .cols { grid-template-columns: 1fr; } }
+.legend { display: flex; gap: 16px; font-size: 12px; color: var(--muted); margin-bottom: 6px; }
+.sw { display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 6px; vertical-align: -1px; }
+svg text { fill: var(--muted); font: 11px var(--mono); }
+.scroll { overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th { text-align: left; font: 600 11px var(--sans); text-transform: uppercase; letter-spacing: .06em; color: var(--muted); padding: 6px 8px; border-bottom: 1px solid var(--line); white-space: nowrap; }
+td { padding: 7px 8px; border-bottom: 1px solid var(--line); vertical-align: top; }
+tr:last-child td { border-bottom: 0; }
+td.n { font-family: var(--mono); font-variant-numeric: tabular-nums; text-align: right; white-space: nowrap; }
+th.n { text-align: right; }
+.chip { display: inline-block; font: 600 10px var(--mono); text-transform: uppercase; letter-spacing: .06em; padding: 2px 6px; border-radius: 4px; }
+.chip.recall { background: var(--recall-soft); color: var(--recall); }
+.chip.tool { background: var(--tool-soft); color: var(--tool); }
+.chip.capture, .chip.sync, .chip.kw { background: var(--line); color: var(--capture); }
+.chip.err { background: var(--bad-soft); color: var(--bad); }
+.feed { display: grid; gap: 10px; max-height: 520px; overflow: auto; }
+.prompt { border: 1px solid var(--line); border-radius: 8px; padding: 10px 12px; }
+.prompt .q { font-weight: 500; overflow-wrap: anywhere; }
+.prompt .meta { font: 12px var(--mono); color: var(--muted); margin-top: 4px; display: flex; flex-wrap: wrap; gap: 4px 12px; overflow-wrap: anywhere; }
+.prompt ul { margin: 6px 0 0; padding-left: 18px; font-size: 13px; }
+.prompt .none { font-size: 13px; color: var(--muted); margin-top: 6px; }
+.mono { font-family: var(--mono); }
+.muted { color: var(--muted); }
+.empty { padding: 40px 16px; text-align: center; color: var(--muted); }
+.empty code { font-family: var(--mono); background: var(--line); padding: 2px 6px; border-radius: 4px; color: var(--fg); }
+.log { max-height: 420px; overflow: auto; }
+@media (prefers-reduced-motion: no-preference) { tr.fresh td { animation: flash 1.2s ease-out; } }
+@keyframes flash { from { background: var(--recall-soft); } to { background: transparent; } }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>CodeBuddy traces<small id="project"></small></h1>
+    <span class="live" id="live"><span class="dot"></span><span id="liveText">connecting</span></span>
+    <span class="spacer"></span>
+    <div class="seg" role="group" aria-label="Time range" id="range">
+      <button data-range="3600000">1 hour</button>
+      <button data-range="86400000" aria-pressed="true">24 hours</button>
+      <button data-range="604800000">7 days</button>
+      <button data-range="0">All</button>
+    </div>
+  </header>
+
+  <section class="kpis" id="kpis" aria-label="Summary"></section>
+
+  <section class="panel">
+    <h2>Tokens delivered to the agent</h2>
+    <div class="legend"><span><span class="sw" style="background:var(--recall)"></span>prompt recall (hook)</span><span><span class="sw" style="background:var(--tool)"></span>MCP tool results</span></div>
+    <div class="scroll" id="chart"></div>
+  </section>
+
+  <div class="cols">
+    <section class="panel">
+      <h2>Recent prompts and what was recalled</h2>
+      <div class="feed" id="feed"></div>
+    </section>
+    <section class="panel">
+      <h2>MCP tools</h2>
+      <div class="scroll" id="tools"></div>
+    </section>
+  </div>
+
+  <section class="panel">
+    <h2>Activity</h2>
+    <div class="log scroll" id="log"></div>
+  </section>
+  <p class="muted" style="margin:0;font-size:12px;overflow-wrap:anywhere">Token counts are cl100k estimates of the text exchanged. Traces stay on this machine in <span class="mono" id="path"></span>. Turn them off with <span class="mono">CODEBUDDY_TRACE=0</span>.</p>
+</div>
+<script>
+(function () {
+  var events = [];
+  var range = 86400000;
+  var fresh = new Set();
+  var pending = false;
+
+  function esc(value) {
+    return String(value == null ? "" : value).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+  function num(n) { return Math.round(n).toLocaleString(); }
+  function compact(n) { return n >= 1e6 ? (n / 1e6).toFixed(1) + "M" : n >= 1e4 ? (n / 1e3).toFixed(1) + "k" : num(n); }
+  function pct(sorted, p) { if (!sorted.length) return 0; return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))]; }
+  function ms(n) { return n >= 1000 ? (n / 1000).toFixed(1) + " s" : Math.round(n) + " ms"; }
+  function ago(ts) {
+    var s = Math.max(0, (Date.now() - Date.parse(ts)) / 1000);
+    return s < 60 ? Math.floor(s) + "s ago" : s < 3600 ? Math.floor(s / 60) + "m ago" : s < 86400 ? Math.floor(s / 3600) + "h ago" : Math.floor(s / 86400) + "d ago";
+  }
+  function visible() {
+    if (!range) return events;
+    var since = Date.now() - range;
+    return events.filter(function (e) { return Date.parse(e.ts) >= since; });
+  }
+
+  function kpis(list) {
+    var recalls = list.filter(function (e) { return e.kind === "recall"; });
+    var tools = list.filter(function (e) { return e.kind === "tool"; });
+    var delivered = list.reduce(function (s, e) { return s + (e.kind === "recall" || e.kind === "tool" ? e.tokensOut || 0 : 0); }, 0);
+    var withFacts = recalls.filter(function (e) { return e.detail && e.detail.facts && e.detail.facts.length; });
+    var factCount = withFacts.reduce(function (s, e) { return s + e.detail.facts.length; }, 0);
+    var dense = recalls.reduce(function (s, e) { return s + ((e.detail && e.detail.dense) || 0); }, 0);
+    var lat = recalls.map(function (e) { return e.ms; }).sort(function (a, b) { return a - b; });
+    var errors = list.filter(function (e) { return !e.ok; }).length;
+    var captures = list.filter(function (e) { return e.kind === "capture"; });
+    var saved = captures.reduce(function (s, e) { return s + ((e.detail && e.detail.saved) || 0); }, 0);
+    var tiles = [
+      ["Prompts recalled", num(recalls.length), recalls.length ? Math.round(100 * withFacts.length / recalls.length) + "% got facts" : "no prompts yet"],
+      ["Facts injected", num(factCount), factCount ? Math.round(100 * dense / factCount) + "% matched by meaning" : "-"],
+      ["Tokens delivered", compact(delivered), recalls.length + tools.length ? "\u2248 " + num(delivered / (recalls.length + tools.length)) + " per event" : "-"],
+      ["MCP tool calls", num(tools.length), tools.length ? new Set(tools.map(function (e) { return e.name; })).size + " distinct tools" : "-"],
+      ["Recall latency", lat.length ? ms(pct(lat, 0.5)) : "-", lat.length ? "p95 " + ms(pct(lat, 0.95)) : "-"],
+      ["Memories saved", num(saved), captures.length + " capture" + (captures.length === 1 ? "" : "s")],
+      ["Errors", num(errors), errors ? "see Activity" : "all good"],
+    ];
+    document.getElementById("kpis").innerHTML = tiles.map(function (t) {
+      return '<div class="kpi"><div class="label">' + esc(t[0]) + '</div><div class="value">' + esc(t[1]) + '</div><div class="sub">' + esc(t[2]) + "</div></div>";
+    }).join("");
+  }
+
+  function chart(list) {
+    var el = document.getElementById("chart");
+    var points = list.filter(function (e) { return (e.kind === "recall" || e.kind === "tool") && e.tokensOut; });
+    if (!points.length) { el.innerHTML = '<div class="empty">No tokens delivered in this range yet.</div>'; return; }
+    var end = Date.now();
+    // Zoom to the data: a few minutes of traces should not be one sliver of a 24-hour axis.
+    var first = Date.parse(points[0].ts);
+    var start = Math.max(range ? end - range : first, first - 60000);
+    var buckets = 48, size = Math.max(10000, (end - start) / buckets);
+    buckets = Math.ceil((end - start) / size);
+    var rows = [];
+    for (var i = 0; i < buckets; i++) rows.push({ recall: 0, tool: 0, n: 0 });
+    points.forEach(function (e) {
+      var i = Math.min(buckets - 1, Math.max(0, Math.floor((Date.parse(e.ts) - start) / size)));
+      rows[i][e.kind] += e.tokensOut; rows[i].n += 1;
+    });
+    var max = Math.max.apply(null, rows.map(function (r) { return r.recall + r.tool; })) || 1;
+    var W = 960, H = 200, L = 52, B = 22, T = 8, plotW = W - L - 8, plotH = H - B - T;
+    var bw = plotW / buckets;
+    var step = Math.pow(10, Math.floor(Math.log10(max)));
+    var tick = max / step > 5 ? step * 2 : step;
+    var svg = '<svg viewBox="0 0 ' + W + " " + H + '" style="width:100%;min-width:560px;height:auto" role="img" aria-label="Tokens delivered over time">';
+    for (var v = 0; v <= max; v += tick) {
+      var y = T + plotH - (v / max) * plotH;
+      svg += '<line x1="' + L + '" x2="' + (W - 8) + '" y1="' + y + '" y2="' + y + '" stroke="var(--line)"/><text x="' + (L - 6) + '" y="' + (y + 4) + '" text-anchor="end">' + compact(v) + "</text>";
+    }
+    rows.forEach(function (r, i) {
+      var x = L + i * bw + 1, w = Math.max(1, bw - 2);
+      var hr = (r.recall / max) * plotH, ht = (r.tool / max) * plotH;
+      var when = new Date(start + i * size);
+      var label = when.toLocaleString() + ": " + num(r.recall) + " recall + " + num(r.tool) + " tool tokens (" + r.n + " events)";
+      if (r.recall) svg += '<rect x="' + x + '" y="' + (T + plotH - hr) + '" width="' + w + '" height="' + hr + '" rx="2" fill="var(--recall)"><title>' + esc(label) + "</title></rect>";
+      if (r.tool) svg += '<rect x="' + x + '" y="' + (T + plotH - hr - ht - (r.recall ? 2 : 0)) + '" width="' + w + '" height="' + ht + '" rx="2" fill="var(--tool)"><title>' + esc(label) + "</title></rect>";
+    });
+    [0, Math.floor(buckets / 2), buckets - 1].forEach(function (i) {
+      var d = new Date(start + i * size);
+      var text = end - start <= 86400000 ? d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : d.toLocaleDateString([], { month: "short", day: "numeric" });
+      svg += '<text x="' + (L + i * bw + bw / 2) + '" y="' + (H - 6) + '" text-anchor="middle">' + esc(text) + "</text>";
+    });
+    el.innerHTML = svg + "</svg>";
+  }
+
+  function feed(list) {
+    var recalls = list.filter(function (e) { return e.kind === "recall"; }).slice(-30).reverse();
+    var el = document.getElementById("feed");
+    if (!recalls.length) {
+      el.innerHTML = '<div class="empty">No prompts yet. Run <code>codebuddy hooks install</code>, restart your agent, and send a prompt.</div>';
+      return;
+    }
+    el.innerHTML = recalls.map(function (e) {
+      var d = e.detail || {};
+      var facts = d.facts || [];
+      return '<div class="prompt"><div class="q">' + (esc(d.prompt) || '<span class="muted">(no prompt text)</span>') + '</div>' +
+        '<div class="meta"><span>' + ago(e.ts) + "</span><span>" + ms(e.ms) + "</span><span>\u2248" + num(e.tokensOut || 0) + " tokens injected</span>" +
+        (d.dense ? '<span class="chip recall">' + d.dense + " by meaning</span>" : "") +
+        (d.lexical ? '<span class="chip kw">' + d.lexical + " by keyword</span>" : "") +
+        (e.ok ? "" : '<span class="chip err">' + esc(d.dropped || "dropped") + "</span>") + "</div>" +
+        (facts.length ? "<ul>" + facts.map(function (f) { return "<li>" + esc(f) + "</li>"; }).join("") + "</ul>" : '<div class="none">No new facts: nothing matched, or already sent this session.</div>') +
+        (d.files && d.files.length ? '<div class="meta">files: ' + d.files.map(esc).join(", ") + "</div>" : "") +
+        "</div>";
+    }).join("");
+  }
+
+  function tools(list) {
+    var by = {};
+    list.filter(function (e) { return e.kind === "tool"; }).forEach(function (e) {
+      var t = by[e.name] || (by[e.name] = { calls: 0, errors: 0, lat: [], out: 0 });
+      t.calls++; if (!e.ok) t.errors++; t.lat.push(e.ms); t.out += e.tokensOut || 0;
+    });
+    var names = Object.keys(by).sort(function (a, b) { return by[b].calls - by[a].calls; });
+    var el = document.getElementById("tools");
+    if (!names.length) { el.innerHTML = '<div class="empty">No MCP tool calls in this range.</div>'; return; }
+    el.innerHTML = '<table><thead><tr><th>Tool</th><th class="n">Calls</th><th class="n">p50</th><th class="n">p95</th><th class="n">Tokens out</th><th class="n">Errors</th></tr></thead><tbody>' +
+      names.map(function (n) {
+        var t = by[n], lat = t.lat.sort(function (a, b) { return a - b; });
+        return '<tr><td class="mono">' + esc(n) + '</td><td class="n">' + t.calls + '</td><td class="n">' + ms(pct(lat, 0.5)) + '</td><td class="n">' + ms(pct(lat, 0.95)) + '</td><td class="n">' + compact(t.out) + '</td><td class="n">' + (t.errors ? '<span class="chip err">' + t.errors + "</span>" : "0") + "</td></tr>";
+      }).join("") + "</tbody></table>";
+  }
+
+  function summary(e) {
+    var d = e.detail || {};
+    if (e.kind === "recall") return (d.facts ? d.facts.length : 0) + " fact(s), " + (d.files ? d.files.length : 0) + " file(s)";
+    if (e.kind === "capture") return (d.saved || 0) + " saved, " + (d.queued || 0) + " queued, " + (d.changedFiles || 0) + " changed file(s)";
+    if (e.kind === "sync") return (d.imported || 0) + " new, " + (d.updated || 0) + " updated" + (d.reembedding ? ", " + d.reembedding + " re-embedding" : "");
+    return e.session ? "session " + e.session.slice(0, 12) : "";
+  }
+
+  function log(list) {
+    var rows = list.slice(-200).reverse();
+    var el = document.getElementById("log");
+    if (!rows.length) { el.innerHTML = '<div class="empty">Nothing recorded in this range.</div>'; return; }
+    el.innerHTML = '<table><thead><tr><th>When</th><th>Kind</th><th>Name</th><th>Details</th><th class="n">Time</th><th class="n">In</th><th class="n">Out</th></tr></thead><tbody>' +
+      rows.map(function (e) {
+        var key = e.ts + e.name;
+        return '<tr class="' + (fresh.has(key) ? "fresh" : "") + '"><td class="mono muted" title="' + esc(e.ts) + '">' + ago(e.ts) + '</td><td><span class="chip ' + (e.ok ? esc(e.kind) : "err") + '">' + esc(e.ok ? e.kind : e.kind + " failed") + '</span></td><td class="mono">' + esc(e.name) + "</td><td>" + esc(summary(e)) + '</td><td class="n">' + ms(e.ms) + '</td><td class="n">' + num(e.tokensIn || 0) + '</td><td class="n">' + num(e.tokensOut || 0) + "</td></tr>";
+      }).join("") + "</tbody></table>";
+    fresh.clear();
+  }
+
+  function render() {
+    pending = false;
+    var list = visible();
+    kpis(list); chart(list); feed(list); tools(list); log(list);
+  }
+  function schedule() { if (!pending) { pending = true; requestAnimationFrame(render); } }
+
+  function load() {
+    return fetch("/api/traces?limit=10000").then(function (r) { return r.json(); }).then(function (data) {
+      events = data.events || [];
+      document.getElementById("project").textContent = data.project || "";
+      document.getElementById("path").textContent = data.path || "";
+      document.title = "CodeBuddy Traces \xB7 " + (data.project || "");
+      schedule();
+    });
+  }
+
+  document.getElementById("range").addEventListener("click", function (event) {
+    var button = event.target.closest("button");
+    if (!button) return;
+    range = Number(button.dataset.range);
+    this.querySelectorAll("button").forEach(function (b) { b.setAttribute("aria-pressed", String(b === button)); });
+    schedule();
+  });
+
+  function connect() {
+    var live = document.getElementById("live"), text = document.getElementById("liveText");
+    var source = new EventSource("/events");
+    source.onopen = function () { live.classList.add("on"); text.textContent = "live"; };
+    source.onerror = function () { live.classList.remove("on"); text.textContent = "reconnecting"; };
+    source.addEventListener("trace", function (message) {
+      var e = JSON.parse(message.data);
+      events.push(e); fresh.add(e.ts + e.name);
+      if (events.length > 10000) events = events.slice(-10000);
+      schedule();
+    });
+    source.addEventListener("reset", function () { load(); });
+  }
+
+  load().then(connect);
+  // Relative times ("2m ago") keep moving even when nothing new arrives.
+  setInterval(schedule, 30000);
+})();
+</script>
+</body>
+</html>`;
+
+// src/dashboard/server.ts
+async function startDashboard(options) {
+  const { repositoryRoot } = options;
+  const path = tracePath(repositoryRoot);
+  const clients = /* @__PURE__ */ new Set();
+  let offset = (await stat(path).catch(() => null))?.size ?? 0;
+  let reading = false;
+  const onChange = async () => {
+    if (reading) return;
+    reading = true;
+    try {
+      const size = (await stat(path).catch(() => null))?.size ?? 0;
+      if (size < offset) {
+        offset = 0;
+        broadcast("reset", "{}");
+      }
+      if (size > offset) {
+        const handle = await open(path, "r");
+        try {
+          const buffer = Buffer.alloc(size - offset);
+          await handle.read(buffer, 0, buffer.length, offset);
+          const text3 = buffer.toString("utf8");
+          const complete = text3.slice(0, text3.lastIndexOf("\n") + 1);
+          offset += Buffer.byteLength(complete);
+          for (const event of parseTraceLines(complete)) broadcast("trace", JSON.stringify(event));
+        } finally {
+          await handle.close();
+        }
+      }
+    } finally {
+      reading = false;
+    }
+  };
+  const broadcast = (event, data) => {
+    for (const client of clients) client.write(`event: ${event}
+data: ${data}
+
+`);
+  };
+  watchFile(path, { interval: options.pollMs ?? 1e3 }, () => void onChange());
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", "http://localhost");
+    if (request.method !== "GET") {
+      response.writeHead(405).end();
+      return;
+    }
+    if (url.pathname === "/") {
+      response.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store"
+      });
+      response.end(DASHBOARD_HTML);
+      return;
+    }
+    if (url.pathname === "/api/traces") {
+      const limit = Math.min(1e4, Math.max(1, Number(url.searchParams.get("limit")) || 2e3));
+      response.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+      response.end(
+        JSON.stringify({
+          project: basename(repositoryRoot),
+          path,
+          events: await readTraces(repositoryRoot, limit)
+        })
+      );
+      return;
+    }
+    if (url.pathname === "/events") {
+      response.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-store",
+        connection: "keep-alive"
+      });
+      response.write(": connected\n\n");
+      clients.add(response);
+      request.on("close", () => clients.delete(response));
+      return;
+    }
+    response.writeHead(404, { "content-type": "text/plain" }).end("Not found");
+  });
+  const port = await listen(server, options.port ?? 4777);
+  const heartbeat = setInterval(() => {
+    for (const client of clients) client.write(": ping\n\n");
+  }, 25e3);
+  heartbeat.unref();
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    close: () => new Promise((resolve14) => {
+      clearInterval(heartbeat);
+      unwatchFile(path);
+      for (const client of clients) client.end();
+      server.closeAllConnections();
+      server.close(() => resolve14());
+    })
+  };
+}
+async function listen(server, port) {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const candidate = port === 0 ? 0 : port + attempt;
+    try {
+      await new Promise((resolve14, reject) => {
+        server.once("error", reject);
+        server.listen(candidate, "127.0.0.1", () => {
+          server.off("error", reject);
+          resolve14();
+        });
+      });
+      return server.address().port;
+    } catch (error) {
+      if (error.code !== "EADDRINUSE" || port === 0) throw error;
+    }
+  }
+  throw new Error(`Ports ${port}-${port + 9} are in use; pass --port.`);
+}
+
+// src/cli/commands/dashboard.ts
+function openBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    spawn2(command, args, { detached: true, stdio: "ignore" }).on("error", () => void 0).unref();
+  } catch {
+  }
+}
+function registerDashboardCommand(program, runSafely2) {
+  program.command("dashboard").description("Open a live local page of prompts recalled, MCP tool calls, tokens and latency.").option(
+    "--port <port>",
+    "Port on 127.0.0.1 (the next free one is used if taken).",
+    Number,
+    4777
+  ).option("--no-open", "Print the URL without opening a browser.").action(async (opts) => {
+    await runSafely2(async () => {
+      const root = process.cwd();
+      const dashboard = await startDashboard({ repositoryRoot: root, port: opts.port });
+      const recorded = (await readTraces(root)).length;
+      console.log(`${pc4.green("\u25CF")} CodeBuddy dashboard ${pc4.bold(dashboard.url)}`);
+      console.log(
+        pc4.dim(
+          recorded > 0 ? `  ${recorded} event(s) in ${tracePath(root)}; new ones appear live.` : "  No traces yet: they appear as your agent uses CodeBuddy (hooks or MCP tools)."
+        )
+      );
+      console.log(pc4.dim("  Ctrl+C to stop."));
+      if (opts.open) openBrowser(dashboard.url);
+      await new Promise((resolve14) => {
+        const stop = () => void dashboard.close().then(resolve14);
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+      });
+    });
+  });
+}
+
+// src/cli/commands/eval.ts
+import pc5 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";
@@ -2622,17 +3121,17 @@ function registerEvalCommand(program, runSafely2) {
 }
 function printEvaluation(result) {
   console.log(
-    `${result.passed ? pc4.green("passed") : pc4.red("failed")} ${result.summary.passed}/${result.summary.total} evaluation cases`
+    `${result.passed ? pc5.green("passed") : pc5.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(`  ${item.passed ? pc5.green("\u2713") : pc5.red("\xD7")} ${item.id}`);
+    if (!item.passed) for (const failure of item.failures) console.log(pc5.dim(`    ${failure}`));
   }
-  console.log(pc4.dim(`dataset: ${result.datasetPath}`));
+  console.log(pc5.dim(`dataset: ${result.datasetPath}`));
 }
 
 // src/cli/commands/github.ts
-import pc5 from "picocolors";
+import pc6 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) => {
@@ -2640,15 +3139,16 @@ function registerGitHubCommands(program, runSafely2) {
       const result = await installGitHubWorkflow(process.cwd(), {
         ...opts.force !== void 0 ? { force: opts.force } : {}
       });
-      console.log(`${result.created ? "installed" : "already present"} ${pc5.dim(result.path)}`);
+      console.log(`${result.created ? "installed" : "already present"} ${pc6.dim(result.path)}`);
       if (result.created) console.log("Commit this workflow to enable CodeBuddy PR reports.");
     });
   });
 }
 
 // src/cli/commands/hooks.ts
+import { spawn as spawn3 } from "child_process";
 import { relative as relative2 } from "path";
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 function registerHooksCommands(program, runSafely2) {
   const hooks = program.command("hooks").description("Enforce automatic recall/capture via client lifecycle hooks.");
   hooks.command("install").option(
@@ -2665,11 +3165,12 @@ function registerHooksCommands(program, runSafely2) {
       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}`
+        `${changed ? pc7.green("installed") : pc7.dim("unchanged")} CodeBuddy hooks in ${where}`
       );
       await reconcileRules(client, "hooks");
+      syncInBackground(process.cwd());
       console.log(
-        pc6.dim(
+        pc7.dim(
           `  prompt\u2192recall \xB7 edit\u2192stage \xB7 turn end\u2192capture \xB7 compaction\u2192reset. Restart ${CLIENT_ADAPTERS[client].name} to activate.`
         )
       );
@@ -2684,7 +3185,7 @@ function registerHooksCommands(program, runSafely2) {
       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")
+        changed ? pc7.yellow("removed CodeBuddy hooks") : pc7.dim("no CodeBuddy hooks found")
       );
       await reconcileRules(client, "agent");
     });
@@ -2697,7 +3198,7 @@ function registerHooksCommands(program, runSafely2) {
     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")
+        installed ? pc7.green("CodeBuddy hooks: installed") : pc7.dim("CodeBuddy hooks: not installed")
       );
     });
   });
@@ -2725,9 +3226,21 @@ function registerHooksCommands(program, runSafely2) {
           `codebuddy: captured from ${changedFiles.length} changed file(s) \u2014 ${result.saved.length} saved, ${result.queuedForReview.length} queued
 `
         );
+        if (result.saved.length > 0) syncInBackground(input.cwd ?? process.cwd());
       }
     });
   });
+  hooks.command("sync").description(
+    "[hook] Reindex Markdown memory into PostgreSQL and embed it locally (runs detached after capture)."
+  ).action(async () => {
+    await failSoft(async () => {
+      const result = await runSyncHook(process.cwd());
+      process.stderr.write(
+        result ? `codebuddy: synced ${result.reindex.facts.imported} new / ${result.reindex.facts.updated} updated fact(s)${result.reindex.reembedding ? `, ${result.reindex.reembedding} re-embedding` : ""}${result.drained ? "" : " (embeddings still pending)"}
+` : "codebuddy: no PostgreSQL configured; nothing to sync\n"
+      );
+    });
+  });
   hooks.command("pretool").description(
     "[hook] Outline large unranged Reads and cap content Greps (never grants permission)."
   ).action(async () => {
@@ -2754,16 +3267,28 @@ async function reconcileRules(client, mode) {
   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`
+      `${pc7.cyan("updated")} ${where} workflow to ${mode === "hooks" ? "hook" : "agent"}-driven mode`
     );
   }
 }
+function syncInBackground(cwd) {
+  const entry = process.argv[1];
+  if (!entry) return;
+  try {
+    spawn3(process.execPath, [...process.execArgv, entry, "hooks", "sync"], {
+      cwd,
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+  } catch {
+  }
+}
 
 // src/cli/commands/indexing.ts
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 
 // src/cli/commands/llm.ts
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 import { z } from "zod";
 var KEY_ENV = { groq: "GROQ_API_KEY", openrouter: "OPENROUTER_API_KEY" };
 var WATCH_BATCH = 8;
@@ -2818,7 +3343,7 @@ function registerLlmCommands(program, runSafely2) {
     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>`));
+      if (!report.keyPresent) console.log(pc8.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) => {
@@ -2865,7 +3390,7 @@ function registerLlmCommands(program, runSafely2) {
       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}`))
+        onProgress: (done, total) => console.log(pc8.dim(`summarized ${done}/${total}`))
       });
       console.log(
         `${result.summarized} summarized, ${result.skipped} skipped, ${result.remaining} remaining (${result.stoppedBy})`
@@ -2892,7 +3417,7 @@ function registerIndexCommands(program, runSafely2) {
       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"));
+      console.log(pc9.dim("watching for changes\u2026 press Ctrl+C to stop"));
       await watchRepository({
         ...opts.debounce !== void 0 ? { debounceMs: opts.debounce } : {},
         signal: controller.signal,
@@ -2901,21 +3426,21 @@ function registerIndexCommands(program, runSafely2) {
           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}`)));
+              console.log(pc9.dim(`  llm: ${summary.summarized} file(s) summarized`));
+          }).catch((error) => console.error(pc9.red(`llm: ${error.message}`)));
         },
-        onError: (error) => console.error(pc8.red(error.message))
+        onError: (error) => console.error(pc9.red(error.message))
       });
-      console.log(pc8.dim("stopped watching"));
+      console.log(pc9.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);
+  const summary = `${result.totalIndexed} indexed (${pc9.green(`+${result.added}`)} ${pc9.yellow(`~${result.changed}`)} ${pc9.dim(`=${result.unchanged}`)} ${pc9.red(`-${result.removed}`)}) in ${result.durationMs}ms`;
+  console.log(compact ? pc9.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}`));
+    console.log(pc9.dim(`  ${result.skipped} skipped (too large or unreadable)`));
+  for (const error of result.errors) console.log(pc9.red(`  ${error.path}: ${error.error}`));
 }
 
 // src/cli/commands/init-wizard.ts
@@ -2923,7 +3448,7 @@ 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 { spawn as spawn4 } from "child_process";
 import { existsSync as existsSync3 } from "fs";
 import { dirname as dirname11, resolve as resolve12 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -2944,7 +3469,7 @@ function resolveBundledComposeFile() {
   ${candidates.join("\n  ")}`);
 }
 async function runDockerCompose(args, options = {}) {
-  const spawnImpl = options.spawnImpl ?? spawn2;
+  const spawnImpl = options.spawnImpl ?? spawn4;
   const composeFile = resolveBundledComposeFile();
   const attempts = [
     { kind: "v2", bin: "docker", args: ["compose", "-f", composeFile, ...args] },
@@ -3024,8 +3549,7 @@ async function runInitWizard() {
     );
     const hfToken = unwrap(
       await password({
-        message: "Hugging Face token (required for embeddings)",
-        validate: (value) => value && value.length > 0 ? void 0 : "HF_TOKEN is required."
+        message: "Hugging Face token (optional; only for hosted embeddings)"
       })
     );
     const databaseUrl = unwrap(
@@ -3095,7 +3619,7 @@ async function runInitWizard() {
     const fileConfig = {
       postgresUrl: databaseUrl,
       namespace,
-      provider: { type: "huggingface", apiKey: hfToken },
+      provider: { type: "local", ...hfToken ? { apiKey: hfToken } : {} },
       tokenBudget: 4e3
     };
     await writeFile2(initialised.path, `${JSON.stringify(fileConfig, null, 2)}
@@ -3136,7 +3660,7 @@ async function runInitWizard() {
 }
 
 // src/cli/commands/learn.ts
-import pc9 from "picocolors";
+import pc10 from "picocolors";
 
 // src/learning/outcomes.ts
 async function recordChangeOutcome(input) {
@@ -3197,15 +3721,15 @@ function registerLearnCommand(program, runSafely2) {
           ...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));
+        console.log(`${pc10.green("recorded")} ${result.id} (${result.category})`);
+        console.log(pc10.dim(result.path));
       });
     }
   );
 }
 
 // src/cli/commands/map.ts
-import pc10 from "picocolors";
+import pc11 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 () => {
@@ -3225,7 +3749,7 @@ function registerMapCommands(program, runSafely2) {
         return;
       }
       if (edges.length === 0) {
-        console.log(pc10.dim("no dependencies found"));
+        console.log(pc11.dim("no dependencies found"));
         return;
       }
       for (const edge of edges) console.log(`${edge.from} -> ${edge.to}`);
@@ -3240,7 +3764,7 @@ function registerMapCommands(program, runSafely2) {
         return;
       }
       if (result.edges.length === 0) {
-        console.log(pc10.dim("no dependents found"));
+        console.log(pc11.dim("no dependents found"));
         return;
       }
       for (const edge of result.edges) console.log(`${edge.from} -> ${edge.to}`);
@@ -3249,9 +3773,9 @@ function registerMapCommands(program, runSafely2) {
 }
 
 // src/cli/commands/memory-review.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 import { relative as relative3 } from "path";
-import pc11 from "picocolors";
+import pc12 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.");
@@ -3263,11 +3787,11 @@ function registerMemoryCommands(program, runSafely2) {
         return;
       }
       if (items.length === 0) {
-        console.log(pc11.dim("no pending review items"));
+        console.log(pc12.dim("no pending review items"));
         return;
       }
       for (const item of items) console.log(renderRow(item));
-      console.log(pc11.dim(`
+      console.log(pc12.dim(`
 ${items.length} pending. approve <id> | reject <id> | show <id>`));
     });
   });
@@ -3281,7 +3805,7 @@ ${items.length} pending. approve <id> | reject <id> | show <id>`));
       const factId = await approveReviewItem(id, {
         ...opts.incident !== void 0 ? { incidentId: opts.incident } : {}
       });
-      console.log(`${pc11.green("approved")} ${id} \u2192 ${factId}`);
+      console.log(`${pc12.green("approved")} ${id} \u2192 ${factId}`);
     });
   });
   review.command("reject").argument("<id>").description("Discard a review candidate without saving it.").action(async (id) => {
@@ -3289,7 +3813,7 @@ ${items.length} pending. approve <id> | reject <id> | show <id>`));
       const store = new ReviewStore();
       await store.read(id);
       await store.delete(id);
-      console.log(`${pc11.yellow("rejected")} ${id}`);
+      console.log(`${pc12.yellow("rejected")} ${id}`);
     });
   });
   review.command("edit").argument("<id>").description("Open a review candidate in $EDITOR and re-validate on save.").action(async (id) => {
@@ -3298,44 +3822,44 @@ ${items.length} pending. approve <id> | reject <id> | show <id>`));
       const item = await store.read(id);
       await openEditor(item.path);
       await store.read(id);
-      console.log(pc11.dim("saved and validated"));
+      console.log(pc12.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}`;
+  const flag = item.sensitive ? pc12.red(" \u26A0 sensitive") : "";
+  return `${classColor(item.class)}  ${pc12.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}`
+    `${classColor(item.class)}  ${pc12.dim(item.id)}`,
+    `${pc12.bold("reason:")} ${item.reason}`,
+    `${pc12.bold("confidence:")} ${item.confidence.toFixed(2)}`,
+    `${pc12.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.paths.length > 0) lines.push(`${pc12.bold("paths:")} ${item.paths.join(", ")}`);
+  if (item.severity) lines.push(`${pc12.bold("severity:")} ${item.severity}`);
   if (item.resolvesIncidents) {
     lines.push(
-      `${pc11.bold("resolves:")} ${item.resolvesIncidents.join(", ") || "(no candidate; approve with --incident <id>)"}`
+      `${pc12.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)));
+  if (item.sensitive) lines.push(pc12.red(`\u26A0 sensitive: ${item.sensitiveReasons.join(", ")}`));
+  lines.push("", item.content, "", pc12.dim(relative3(process.cwd(), item.path)));
   return lines.join("\n");
 }
 function classColor(memoryClass) {
   switch (memoryClass) {
     case "incident":
-      return pc11.red(memoryClass);
+      return pc12.red(memoryClass);
     case "decision":
-      return pc11.cyan(memoryClass);
+      return pc12.cyan(memoryClass);
     case "fact":
-      return pc11.green(memoryClass);
+      return pc12.green(memoryClass);
     case "note":
-      return pc11.yellow(memoryClass);
+      return pc12.yellow(memoryClass);
     default:
-      return pc11.dim(memoryClass);
+      return pc12.dim(memoryClass);
   }
 }
 function truncate(value, max) {
@@ -3345,16 +3869,422 @@ function truncate(value, max) {
 function openEditor(path) {
   const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
   return new Promise((resolvePromise, reject) => {
-    const child = spawn3(editor, [path], { stdio: "inherit" });
+    const child = spawn5(editor, [path], { stdio: "inherit" });
     child.on("error", reject);
     child.on("close", () => resolvePromise());
   });
 }
 
+// src/cli/commands/models.ts
+import { existsSync as existsSync4 } from "fs";
+import { join as join15 } from "path";
+import { spinner as spinner2 } from "@clack/prompts";
+import pc13 from "picocolors";
+
+// evals/fact-relevance.json
+var fact_relevance_default = {
+  version: 1,
+  note: "Task prompts vs durable project facts. Queries are paraphrased so most share few or no words with their fact; every unlisted (query, fact) pair is irrelevant.",
+  facts: {
+    cookie: "OAuth callback breaks unless the session cookie is SameSite=Lax; Strict drops it on the cross-site redirect.",
+    pool: "Postgres connections go through one bounded pool of 10; never open ad-hoc clients in request handlers.",
+    release: "npm releases are published from CI with provenance; never publish from a laptop.",
+    biome: "Biome owns formatting and import order; run biome check --write before committing.",
+    hook: "Prompt hooks must answer within 15 seconds or the host drops the injected block.",
+    migration: "Migrations must create the pgvector extension before 0003 adds the vector column.",
+    redaction: "Secrets are redacted before a memory is written; the content hash is computed after redaction.",
+    ledger: "The session ledger keeps the last 8 acknowledged versions per section so a task switch back is not resent.",
+    zvec: "zvec-grep is optional; any failure falls back to keyword ranking with a retrieval explain line.",
+    tests: "Integration tests skip unless CODEBUDDY_TEST_DATABASE_URL points at a live Postgres.",
+    esm: "Source imports use .js specifiers even for TypeScript files because the package is ESM.",
+    stdout: "Never log to stdout in the MCP server: stdout carries JSON-RPC and any stray line corrupts it.",
+    budget: "The BYOK LLM layer stops background calls at 70% of the daily budget and backs off after a 429.",
+    worktree: "Use a temporary WIP commit instead of git stash; the stash stack is shared across worktrees.",
+    rateLimit: "The public API allows 100 requests per minute per token; bursts above it get HTTP 429.",
+    timezone: "All timestamps are stored in UTC and converted to the user's zone only for display.",
+    avatar: "Profile images are resized to 256px and stored as WebP in the media bucket.",
+    flags: "Feature flags are read once at boot; changing one requires a restart of the worker.",
+    pagination: "List endpoints use cursor pagination with an opaque base64url cursor of createdAt and id.",
+    i18n: "UI strings live in locales/en.json; never hard-code user-facing text in components."
+  },
+  queries: [
+    {
+      q: "users get bounced back to sign-in forever after the identity provider returns",
+      relevant: ["cookie"]
+    },
+    { q: "handlers are exhausting connections to the database under load", relevant: ["pool"] },
+    { q: "cut a new version and push the package to the registry", relevant: ["release"] },
+    { q: "the injected block sometimes never shows up in the chat", relevant: ["hook"] },
+    { q: "fresh database setup fails on the embedding column", relevant: ["migration"] },
+    { q: "an API key ended up in a saved note", relevant: ["redaction"] },
+    { q: "context is sent again after I switch tasks and come back", relevant: ["ledger"] },
+    { q: "semantic code search crashes and the agent gets no files", relevant: ["zvec"] },
+    { q: "why do the db tests not run on my machine", relevant: ["tests"] },
+    { q: "module not found when importing a sibling ts file at runtime", relevant: ["esm"] },
+    { q: "Claude Desktop says Unexpected token in the server response", relevant: ["stdout"] },
+    { q: "the summarizer quietly stopped calling Groq in the afternoon", relevant: ["budget"] },
+    { q: "my uncommitted changes vanished after another session ran", relevant: ["worktree"] },
+    {
+      q: "clients see too many requests errors during the import job",
+      relevant: ["rateLimit"]
+    },
+    { q: "meeting times show up one hour off for users in Berlin", relevant: ["timezone"] },
+    { q: "uploaded profile pictures look blurry", relevant: ["avatar"] },
+    { q: "I toggled the new checkout switch but nothing changed", relevant: ["flags"] },
+    { q: "infinite scroll repeats items on the second page", relevant: ["pagination"] },
+    { q: "translate the onboarding screen to German", relevant: ["i18n"] },
+    { q: "format the code before I commit", relevant: ["biome"] },
+    { q: "make the sidebar collapsible", relevant: [] },
+    { q: "add dark mode to the dashboard", relevant: [] },
+    { q: "write a haiku about the project", relevant: [] },
+    { q: "rename the button label on the settings page", relevant: [] }
+  ]
+};
+
+// src/providers/calibration.ts
+async function calibrateEmbedder(embed) {
+  const data = fact_relevance_default;
+  const factIds = Object.keys(data.facts);
+  const factVectors = await embed(Object.values(data.facts));
+  const queryVectors = await embed(data.queries.map(({ q }) => q));
+  const dot = (a, b) => a.reduce((sum, value, index) => sum + value * (b[index] ?? 0), 0);
+  const scores = queryVectors.map((query) => factVectors.map((fact) => dot(query, fact)));
+  const relevant = (qi, fi) => data.queries[qi]?.relevant.includes(factIds[fi] ?? "") ?? false;
+  const positives = [];
+  const negatives = [];
+  for (const [qi, row2] of scores.entries()) {
+    for (const [fi, score] of row2.entries()) (relevant(qi, fi) ? positives : negatives).push(score);
+  }
+  const auc = positives.reduce((wins, p) => wins + negatives.filter((n) => p > n).length, 0) / (positives.length * negatives.length);
+  let hits = 0;
+  let reciprocal = 0;
+  let answerable = 0;
+  for (const [qi, row2] of scores.entries()) {
+    if (!data.queries[qi]?.relevant.length) continue;
+    answerable += 1;
+    const order = row2.map((score, fi) => ({ score, fi })).sort((a, b) => b.score - a.score);
+    const rank = order.findIndex(({ fi }) => relevant(qi, fi)) + 1;
+    if (rank === 1) hits += 1;
+    reciprocal += 1 / rank;
+  }
+  const at = (floor) => {
+    let tp = 0;
+    let fp = 0;
+    let abstained = 0;
+    let unrelated = 0;
+    for (const [qi, row2] of scores.entries()) {
+      const admitted = row2.flatMap((score, fi) => score >= floor ? [fi] : []);
+      for (const fi of admitted) {
+        if (relevant(qi, fi)) tp += 1;
+        else fp += 1;
+      }
+      if (!data.queries[qi]?.relevant.length) {
+        unrelated += 1;
+        if (admitted.length === 0) abstained += 1;
+      }
+    }
+    const precision = tp + fp === 0 ? 1 : tp / (tp + fp);
+    const recall = tp / positives.length;
+    const f05 = precision + recall === 0 ? 0 : 1.25 * precision * recall / (0.25 * precision + recall);
+    return { floor, precision, recall, f05, abstain: abstained / unrelated };
+  };
+  const sweep = Array.from({ length: 96 }, (_, i) => at(Math.round((0.05 + i * 0.01) * 100) / 100));
+  const best = sweep.reduce((left, right) => right.f05 > left.f05 ? right : left);
+  return { auc, recallAt1: hits / answerable, mrr: reciprocal / answerable, best, at };
+}
+
+// src/cli/commands/models.ts
+var EMBEDDERS = ["local", "huggingface", "openrouter"];
+var RERANKERS = ["off", "local", "huggingface", "openrouter"];
+var KEY_ENV2 = { huggingface: "HF_TOKEN", openrouter: "OPENROUTER_API_KEY" };
+var ok = (text3) => `${pc13.green("\u2713")} ${text3}`;
+var warn = (text3) => `${pc13.yellow("!")} ${text3}`;
+var row = (label, value) => `  ${pc13.dim(label.padEnd(11))}${value}`;
+async function withSpinner(label, work, done) {
+  const progress = spinner2();
+  progress.start(label);
+  try {
+    const value = await work();
+    progress.stop(done(value));
+    return value;
+  } catch (error) {
+    progress.stop(pc13.red(`\u2717 ${label}`), 1);
+    throw error;
+  }
+}
+function keyPresent(provider, apiKey) {
+  return Boolean(process.env[KEY_ENV2[provider]] || provider === "huggingface" && apiKey);
+}
+function localModelDownloaded(id, revision) {
+  const dir = join15(modelCacheDir(), id, ...revision ? [revision] : []);
+  return existsSync4(join15(dir, "onnx", "model_quantized.onnx"));
+}
+async function vectorCounts(postgresUrl, namespace, space) {
+  const client = createDatabaseClient({ postgresUrl, maxConnections: 1, connectTimeoutSeconds: 3 });
+  try {
+    const [counts] = await client.sql`
+      select
+        count(*) filter (where e.status = 'ready' and e.embedding_space = ${space ?? ""})::int as ready,
+        count(*) filter (where e.status in ('pending', 'processing'))::int as pending,
+        count(*) filter (where e.status = 'failed')::int as failed,
+        count(*) filter (where e.status = 'ready' and e.embedding_space is distinct from ${space ?? ""})::int as other
+      from embeddings e join namespaces n on n.id = e.namespace_id
+      where n.name = ${namespace}
+    `;
+    return counts ?? { ready: 0, pending: 0, failed: 0, other: 0 };
+  } catch (error) {
+    return String(redactSecrets(error.message)).split("\n")[0] ?? "unreachable";
+  } finally {
+    await client.close().catch(() => void 0);
+  }
+}
+async function printStatus() {
+  const file = await readConfigFile();
+  const config = await loadRuntimeConfig(process.cwd(), { requireDatabase: false });
+  const provider = config.provider;
+  const embedder = buildProviderFromConfig(config.provider);
+  const space = embedder.space;
+  const model = provider.type === "local" ? LOCAL_EMBEDDING_MODEL.id : provider.model ?? DEFAULT_CLOUD_EMBEDDING_MODELS[provider.type];
+  const floor = provider.relevanceFloor ?? getModelDefinition(model)?.relevanceFloor;
+  const next = [];
+  console.log(pc13.bold("Embeddings"));
+  console.log(row("provider", `${provider.type}  ${pc13.dim(model)}`));
+  if (provider.type === "local") {
+    const ready = localModelDownloaded(LOCAL_EMBEDDING_MODEL.id, LOCAL_EMBEDDING_MODEL.revision);
+    console.log(
+      row(
+        "model",
+        ready ? ok(`downloaded ${pc13.dim(modelCacheDir())}`) : warn("not downloaded yet (~90 MB)")
+      )
+    );
+    if (!ready) next.push("codebuddy models pull");
+  } else {
+    const present = keyPresent(provider.type, provider.apiKey);
+    console.log(
+      row(
+        "key",
+        present ? ok(KEY_ENV2[provider.type]) : warn(`${KEY_ENV2[provider.type]} is not set`)
+      )
+    );
+    if (!present) next.push(`export ${KEY_ENV2[provider.type]}=\u2026`);
+  }
+  console.log(
+    row(
+      "floor",
+      floor !== void 0 ? `${floor} ${pc13.dim(provider.relevanceFloor !== void 0 ? "(calibrated for this project)" : "(built-in)")}` : warn("not calibrated: dense recall is off for this model")
+    )
+  );
+  if (floor === void 0) next.push("codebuddy models calibrate");
+  const rerank = file.rerank?.provider ?? "off";
+  console.log(pc13.bold("Reranker"));
+  if (rerank === "off") {
+    console.log(
+      row("provider", `off ${pc13.dim("(default: no reranker beat dense order in evals)")}`)
+    );
+  } else {
+    console.log(
+      row(
+        "provider",
+        `${rerank}  ${pc13.dim(file.rerank?.model ?? DEFAULT_RERANK_MODELS[rerank].id)}`
+      )
+    );
+    if (rerank !== "local") {
+      const present = keyPresent(rerank, file.provider?.apiKey);
+      console.log(
+        row(
+          "key",
+          present ? ok(KEY_ENV2[rerank]) : warn(`${KEY_ENV2[rerank]} is not set; reranking is skipped`)
+        )
+      );
+    }
+  }
+  console.log(pc13.bold("Memory index"));
+  if (process.env.CODEBUDDY_SEMANTIC === "0") {
+    console.log(row("recall", warn("CODEBUDDY_SEMANTIC=0: lexical only")));
+  }
+  if (!config.postgresUrl) {
+    console.log(row("postgres", warn("not configured: recall is lexical only")));
+    next.push("codebuddy use   (sets up PostgreSQL)");
+  } else {
+    const counts = await vectorCounts(
+      config.postgresUrl,
+      config.namespace,
+      space ? embeddingSpaceKey(space) : void 0
+    );
+    if (typeof counts === "string") {
+      console.log(row("postgres", warn(`unreachable: ${counts}`)));
+      next.push("codebuddy postgres up");
+    } else {
+      console.log(row("postgres", ok(`namespace ${config.namespace}`)));
+      console.log(
+        row(
+          "vectors",
+          `${counts.ready} ready` + (counts.pending ? `, ${counts.pending} pending` : "") + (counts.failed ? pc13.red(`, ${counts.failed} failed`) : "") + (counts.other ? pc13.yellow(`, ${counts.other} from another model`) : "")
+        )
+      );
+      if (counts.pending || counts.other)
+        next.push("codebuddy hooks sync   (embeds pending and re-embeds old vectors)");
+    }
+  }
+  console.log(
+    next.length > 0 ? `
+${pc13.bold("Next")}
+${next.map((step) => `  ${pc13.cyan(step)}`).join("\n")}` : `
+${ok("Semantic recall is ready.")} ${pc13.dim('Try: codebuddy context preview "<task>"')}`
+  );
+}
+function registerModelsCommands(program, runSafely2) {
+  const models = program.command("models").description("Embedding model and reranker behind per-prompt memory recall.").action(async () => runSafely2(printStatus));
+  models.command("status").description("Show the embedding model, reranker, keys and vector index health.").action(async () => runSafely2(printStatus));
+  models.command("use").argument("<provider>", `Embedding provider: ${EMBEDDERS.join(" | ")}.`).option("--model <id>", "Hosted model id (must return 384-d vectors).").option(
+    "--floor <cosine>",
+    "Relevance floor; otherwise built-in or `models calibrate`.",
+    Number
+  ).description("Choose where embeddings run: local (default, no key) or a hosted API.").addHelpText(
+    "after",
+    `
+Examples:
+  codebuddy models use local
+  codebuddy models use openrouter                       # ${DEFAULT_CLOUD_EMBEDDING_MODELS.openrouter}, needs OPENROUTER_API_KEY
+  codebuddy models use openrouter --model nvidia/nemotron-3.5-embed-1b:free
+  codebuddy models use huggingface                      # ${DEFAULT_CLOUD_EMBEDDING_MODELS.huggingface}, needs HF_TOKEN`
+  ).action(async (choice, opts) => {
+    await runSafely2(async () => {
+      if (!EMBEDDERS.includes(choice)) {
+        throw new Error(`Unknown provider "${choice}". Use one of: ${EMBEDDERS.join(", ")}.`);
+      }
+      const type = choice;
+      if (type === "local" && opts.model) {
+        throw new Error(
+          "The local provider has one built-in model; --model is for hosted providers."
+        );
+      }
+      const current = (await readConfigFile()).provider;
+      await setConfigBlock("provider", {
+        type,
+        ...current?.apiKey ? { apiKey: current.apiKey } : {},
+        ...opts.model ? { model: opts.model } : {},
+        ...opts.floor !== void 0 ? { relevanceFloor: opts.floor } : {}
+      });
+      const model = type === "local" ? LOCAL_EMBEDDING_MODEL.id : opts.model ?? DEFAULT_CLOUD_EMBEDDING_MODELS[type];
+      console.log(ok(`Embeddings: ${type} ${pc13.dim(model)}`));
+      const missingKey = type !== "local" && !keyPresent(type, current?.apiKey);
+      if (missingKey) {
+        console.log(
+          warn(
+            `Set ${KEY_ENV2[type]} in your shell (keys are never stored in config), then run ${pc13.cyan("codebuddy hooks sync")}.`
+          )
+        );
+        console.log(pc13.dim("  Existing vectors keep working until the new model can embed."));
+      }
+      if (opts.floor === void 0 && getModelDefinition(model)?.relevanceFloor === void 0) {
+        console.log(
+          warn(
+            `No floor for ${model} yet: run ${pc13.cyan("codebuddy models calibrate")} to turn on dense recall.`
+          )
+        );
+      }
+      if (!missingKey) {
+        syncInBackground(process.cwd());
+        console.log(
+          pc13.dim("  Re-embedding existing memory in the background (codebuddy hooks sync).")
+        );
+      }
+    });
+  });
+  models.command("rerank").argument("<provider>", `Reranker: ${RERANKERS.join(" | ")}.`).option("--model <id>", "Cross-encoder model id.").description("Optionally reorder recalled facts with a cross-encoder (off by default).").addHelpText(
+    "after",
+    `
+Defaults: local ${DEFAULT_RERANK_MODELS.local.id} \xB7 huggingface ${DEFAULT_RERANK_MODELS.huggingface.id}
+          openrouter ${DEFAULT_RERANK_MODELS.openrouter.id} (paid per search)
+In CodeBuddy's eval, no reranker beat the dense order; measure on your data
+before keeping one on. A reranker never admits a fact, it only orders them.`
+  ).action(async (choice, opts) => {
+    await runSafely2(async () => {
+      if (!RERANKERS.includes(choice)) {
+        throw new Error(`Unknown reranker "${choice}". Use one of: ${RERANKERS.join(", ")}.`);
+      }
+      await setConfigBlock("rerank", {
+        provider: choice,
+        ...opts.model ? { model: opts.model } : {}
+      });
+      if (choice === "off") {
+        console.log(ok("Reranker off: facts keep their fused (keyword + vector) order."));
+        return;
+      }
+      const reranker = choice;
+      console.log(
+        ok(`Reranker: ${reranker} ${pc13.dim(opts.model ?? DEFAULT_RERANK_MODELS[reranker].id)}`)
+      );
+      if (reranker !== "local" && !keyPresent(reranker, (await readConfigFile()).provider?.apiKey)) {
+        console.log(warn(`Set ${KEY_ENV2[reranker]}; without it reranking is skipped.`));
+      }
+      if (reranker === "local")
+        console.log(pc13.dim("  Run codebuddy models pull to download it now."));
+    });
+  });
+  models.command("pull").description("Download the local models now instead of on first use.").action(async () => {
+    await runSafely2(async () => {
+      const { LocalModelProvider, rerankLocally } = await import("./local-3NGNESNB.js");
+      const file = await readConfigFile();
+      let started = Date.now();
+      await withSpinner(
+        `Downloading ${LOCAL_EMBEDDING_MODEL.id}`,
+        () => new LocalModelProvider().embed({ input: "warm up" }),
+        () => ok(`${LOCAL_EMBEDDING_MODEL.id} ready ${pc13.dim(`${Date.now() - started} ms`)}`)
+      );
+      if (file.rerank?.provider === "local") {
+        const id = file.rerank.model ?? DEFAULT_RERANK_MODELS.local.id;
+        const revision = id === DEFAULT_RERANK_MODELS.local.id ? DEFAULT_RERANK_MODELS.local.revision : void 0;
+        started = Date.now();
+        await withSpinner(
+          `Downloading ${id}`,
+          () => rerankLocally({ id, ...revision ? { revision } : {} }, "warm", ["up"]),
+          () => ok(`${id} ready ${pc13.dim(`${Date.now() - started} ms`)}`)
+        );
+      }
+      console.log(pc13.dim(`  Cache: ${modelCacheDir()}`));
+    });
+  });
+  models.command("calibrate").option("--dry-run", "Measure only; do not save the floor.").description(
+    "Measure the configured embedder on a built-in task set and save its recall floor."
+  ).action(async (opts) => {
+    await runSafely2(async () => {
+      const config = await loadRuntimeConfig(process.cwd(), { requireDatabase: false });
+      const embedder = buildProviderFromConfig(config.provider);
+      const result = await withSpinner(
+        `Embedding 44 calibration texts with ${embedder.space?.model ?? config.provider.type}`,
+        () => calibrateEmbedder(async (texts) => (await embedder.embed({ input: texts })).vectors),
+        () => ok("Measured")
+      );
+      const pct = (value) => `${Math.round(value * 100)}%`;
+      console.log(
+        row(
+          "ranking",
+          `AUC ${result.auc.toFixed(3)} \xB7 right fact first ${pct(result.recallAt1)}`
+        )
+      );
+      console.log(
+        row(
+          "floor",
+          `${result.best.floor}: precision ${pct(result.best.precision)}, recall ${pct(result.best.recall)}, silent on ${pct(result.best.abstain)} of unrelated tasks`
+        )
+      );
+      if (opts.dryRun) return;
+      const file = await readConfigFile();
+      await setConfigBlock("provider", {
+        ...file.provider ?? { type: config.provider.type },
+        relevanceFloor: result.best.floor
+      });
+      console.log(ok(`Saved relevanceFloor ${result.best.floor} to .codebuddy/config.json`));
+    });
+  });
+}
+
 // src/cli/commands/plan.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 import { relative as relative4 } from "path";
-import pc12 from "picocolors";
+import pc14 from "picocolors";
 function makeLifecycle(cwd = process.cwd()) {
   const store = new PlanFileStore(cwd);
   return { store, lifecycle: new PlanLifecycle(store) };
@@ -3362,67 +4292,67 @@ function makeLifecycle(cwd = process.cwd()) {
 function statusColor(status) {
   switch (status) {
     case "draft":
-      return pc12.dim(status);
+      return pc14.dim(status);
     case "approved":
-      return pc12.cyan(status);
+      return pc14.cyan(status);
     case "executing":
-      return pc12.yellow(status);
+      return pc14.yellow(status);
     case "complete":
-      return pc12.green(status);
+      return pc14.green(status);
     case "abandoned":
-      return pc12.red(status);
+      return pc14.red(status);
   }
 }
 function renderPlan(plan) {
   const lines = [];
-  lines.push(`${pc12.bold(plan.title)}  ${statusColor(plan.status)}`);
-  lines.push(pc12.dim(plan.id));
+  lines.push(`${pc14.bold(plan.title)}  ${statusColor(plan.status)}`);
+  lines.push(pc14.dim(plan.id));
   lines.push("");
-  lines.push(`${pc12.bold("Brief:")} ${plan.brief}`);
+  lines.push(`${pc14.bold("Brief:")} ${plan.brief}`);
   if (plan.filesToTouch.length > 0) {
     lines.push("");
-    lines.push(pc12.bold("Files to touch:"));
+    lines.push(pc14.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:"));
+    lines.push(pc14.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:"));
+    lines.push(pc14.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:"));
+    lines.push(pc14.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(`${pc14.bold("Commit:")} ${plan.commitSha}`);
   }
   lines.push("");
-  lines.push(pc12.dim("\u2500".repeat(40)));
+  lines.push(pc14.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" });
+    const child = spawn6(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"] });
+    const child = spawn6("git", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (c) => {
@@ -3447,14 +4377,14 @@ function registerPlanCommands(program, runSafely2) {
         title: opts.title ?? brief,
         brief
       });
-      console.log(`${pc12.green("created")} ${created.id} (${statusColor(created.status)})`);
+      console.log(`${pc14.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(pc14.dim("saved and validated"));
       }
-      console.log(pc12.dim(relative4(process.cwd(), created.path)));
+      console.log(pc14.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) => {
@@ -3466,11 +4396,11 @@ function registerPlanCommands(program, runSafely2) {
       else if (!opts.all)
         plans = plans.filter((p) => p.status !== "complete" && p.status !== "abandoned");
       if (plans.length === 0) {
-        console.log(pc12.dim("no plans"));
+        console.log(pc14.dim("no plans"));
         return;
       }
       for (const p of plans) {
-        console.log(`${statusColor(p.status).padEnd(20)} ${pc12.bold(p.title)}  ${pc12.dim(p.id)}`);
+        console.log(`${statusColor(p.status).padEnd(20)} ${pc14.bold(p.title)}  ${pc14.dim(p.id)}`);
       }
     });
   });
@@ -3486,7 +4416,7 @@ function registerPlanCommands(program, runSafely2) {
       const existing = await store.readPlan(id);
       await openEditor2(existing.path);
       await store.readPlan(id);
-      console.log(pc12.dim("saved and validated"));
+      console.log(pc14.dim("saved and validated"));
     });
   });
   plan.command("approve").argument("<id>").description("Promote a draft to approved (one active plan per namespace).").action(async (id) => {
@@ -3510,7 +4440,7 @@ function registerPlanCommands(program, runSafely2) {
         ...opts.commit ? { commitSha: opts.commit } : {},
         ...opts.notes ? { notes: opts.notes } : {}
       });
-      if (!opts.commit) console.log(pc12.yellow("note: no --commit supplied"));
+      if (!opts.commit) console.log(pc14.yellow("note: no --commit supplied"));
       console.log(`${next.id} \u2192 ${statusColor(next.status)}`);
     });
   });
@@ -3529,7 +4459,7 @@ function registerPlanCommands(program, runSafely2) {
       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"));
+        console.log(pc14.dim("no changes"));
       } else {
         process.stdout.write(result.stdout);
       }
@@ -3546,13 +4476,13 @@ function registerPlanCommands(program, runSafely2) {
         throw new Error(`Invalid policy "${mode}". Use one of: ${PLAN_POLICIES.join(", ")}.`);
       }
       await setPlanPolicy(mode);
-      console.log(`${pc12.green("plan policy")} = ${mode}`);
+      console.log(`${pc14.green("plan policy")} = ${mode}`);
     });
   });
 }
 
 // src/cli/commands/risk.ts
-import pc13 from "picocolors";
+import pc15 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(
@@ -3580,31 +4510,31 @@ function parsePaths3(value) {
 }
 function printAssessment(assessment, explain) {
   if (assessment.items.length === 0) {
-    console.log(pc13.dim("no risk evidence found"));
+    console.log(pc15.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)}`
+      `${pc15.bold(item.path)}  score ${scoreColor2(item.score)}  category ${pc15.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(pc15.dim(`  ${item.evidence.length} evidence item(s)`));
     }
   }
   console.log(
-    pc13.dim(
+    pc15.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));
+  if (score >= 75) return pc15.red(String(score));
+  if (score >= 50) return pc15.yellow(String(score));
+  return pc15.green(String(score));
 }
 function formatEvidence(evidence) {
   switch (evidence.kind) {
@@ -3626,7 +4556,7 @@ function truncate2(value, max) {
 
 // src/cli/commands/rules.ts
 import { relative as relative5 } from "path";
-import pc14 from "picocolors";
+import pc16 from "picocolors";
 async function resolveMode(client, value) {
   if (value) {
     const mode = parseMode(value);
@@ -3666,7 +4596,7 @@ function registerRulesCommands(program, runSafely2) {
         `${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"));
+        console.log(pc16.dim("  managed block between codebuddy:workflow markers; safe to re-run"));
       }
     });
   });
@@ -3674,20 +4604,20 @@ function registerRulesCommands(program, runSafely2) {
 function actionLabel(action) {
   switch (action) {
     case "created":
-      return pc14.green("created");
+      return pc16.green("created");
     case "added":
-      return pc14.green("added");
+      return pc16.green("added");
     case "updated":
-      return pc14.cyan("updated");
+      return pc16.cyan("updated");
     case "removed":
-      return pc14.yellow("removed");
+      return pc16.yellow("removed");
     default:
-      return pc14.dim("unchanged");
+      return pc16.dim("unchanged");
   }
 }
 
 // src/cli/commands/suggest.ts
-import pc15 from "picocolors";
+import pc17 from "picocolors";
 function parsePaths4(value) {
   return value.split(",").map((path) => path.trim()).filter(Boolean);
 }
@@ -3709,7 +4639,7 @@ function registerSuggestCommand(program, runSafely2) {
         }
         printSuggestions(result.suggestions);
         console.log(
-          pc15.dim(
+          pc17.dim(
             `
 ${result.stats.produced} suggestion(s) across ${result.stats.pathsConsidered} path(s)`
           )
@@ -3720,40 +4650,40 @@ ${result.stats.produced} suggestion(s) across ${result.stats.pathsConsidered} pa
 }
 function printSuggestions(suggestions) {
   if (suggestions.length === 0) {
-    console.log(pc15.dim("no suggestions \u2014 nothing high-signal to report"));
+    console.log(pc17.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(`${severityBadge2(suggestion.severity)} ${pc17.bold(suggestion.title)}`);
     console.log(`  ${suggestion.detail}`);
     for (const evidence of suggestion.evidence) {
-      console.log(pc15.dim(`  \u21B3 ${evidence.kind}: ${evidence.detail}`));
+      console.log(pc17.dim(`  \u21B3 ${evidence.kind}: ${evidence.detail}`));
     }
-    if (suggestion.commandHint) console.log(pc15.dim(`  \u2192 ${suggestion.commandHint}`));
+    if (suggestion.commandHint) console.log(pc17.dim(`  \u2192 ${suggestion.commandHint}`));
   }
 }
 function severityBadge2(severity) {
   switch (severity) {
     case "high":
-      return pc15.red("[high]");
+      return pc17.red("[high]");
     case "medium":
-      return pc15.yellow("[med ]");
+      return pc17.yellow("[med ]");
     case "low":
-      return pc15.cyan("[low ]");
+      return pc17.cyan("[low ]");
     default:
-      return pc15.dim("[info]");
+      return pc17.dim("[info]");
   }
 }
 
 // src/cli/commands/symbols.ts
 import { readFile as readFile13 } from "fs/promises";
 import { resolve as resolve13 } from "path";
-import pc16 from "picocolors";
+import pc18 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)`));
+        console.log(pc18.dim(`no symbol extraction for ${path} (unsupported language)`));
         return;
       }
       const content = await readFile13(resolve13(path), "utf8");
@@ -3763,30 +4693,30 @@ function registerSymbolsCommand(program, runSafely2) {
         return;
       }
       if (table.length === 0) {
-        console.log(pc16.dim("no top-level symbols found"));
+        console.log(pc18.dim("no top-level symbols found"));
         return;
       }
       for (const symbol of table) {
-        const badge = symbol.exported ? pc16.green("export") : pc16.dim("local ");
+        const badge = symbol.exported ? pc18.green("export") : pc18.dim("local ");
         console.log(
-          `${badge} ${pc16.cyan(symbol.kind.padEnd(9))} ${pc16.bold(symbol.name)} ${pc16.dim(`L${symbol.startLine}-${symbol.endLine}`)}`
+          `${badge} ${pc18.cyan(symbol.kind.padEnd(9))} ${pc18.bold(symbol.name)} ${pc18.dim(`L${symbol.startLine}-${symbol.endLine}`)}`
         );
       }
-      console.log(pc16.dim(`
+      console.log(pc18.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";
+import { basename as basename2 } from "path";
+import { confirm as confirm2, isCancel as isCancel2, log as log2, note as note2, password as password2, select, spinner as spinner3, text as text2 } from "@clack/prompts";
+import pc19 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 { dirname as dirname12, join as join16 } from "path";
 import { z as z2 } from "zod";
 var GLOBAL_DIR = ".codebuddy";
 var GLOBAL_FILE = "global.json";
@@ -3799,7 +4729,7 @@ var globalConfigSchema = z2.object({
   installPath: z2.string().optional()
 });
 function globalConfigPath(home = homedir3()) {
-  return join15(home, GLOBAL_DIR, GLOBAL_FILE);
+  return join16(home, GLOBAL_DIR, GLOBAL_FILE);
 }
 async function readGlobalConfig(home = homedir3()) {
   const path = globalConfigPath(home);
@@ -3827,10 +4757,10 @@ async function mergeGlobalConfig(patch, home = homedir3()) {
 }
 
 // src/cli/commands/docker-autostart.ts
-import { spawn as spawn5 } from "child_process";
+import { spawn as spawn7 } from "child_process";
 async function isDockerDaemonRunning() {
   return new Promise((resolve14) => {
-    const child = spawn5("docker", ["info"], { stdio: "ignore" });
+    const child = spawn7("docker", ["info"], { stdio: "ignore" });
     child.on("error", () => resolve14(false));
     child.on("close", (code) => resolve14(code === 0));
   });
@@ -3838,7 +4768,7 @@ async function isDockerDaemonRunning() {
 async function tryStartDockerDesktop() {
   if (process.platform !== "darwin") return { started: false };
   return new Promise((resolve14) => {
-    const child = spawn5("open", ["-ga", "Docker"], { stdio: "ignore" });
+    const child = spawn7("open", ["-ga", "Docker"], { stdio: "ignore" });
     child.on("error", () => resolve14({ started: false }));
     child.on("close", (code) => resolve14({ started: code === 0 }));
   });
@@ -3879,7 +4809,7 @@ async function runUseCommand(options = {}) {
   const sigintHandler = () => bail2();
   process.on("SIGINT", sigintHandler);
   try {
-    const folderName = basename(process.cwd());
+    const folderName = basename2(process.cwd());
     const namespace = sanitizeNamespace(options.namespace ?? folderName);
     await initProjectScaffold();
     const graphifyEnabled = options.graphify ?? unwrap2(
@@ -3889,26 +4819,61 @@ async function runUseCommand(options = {}) {
       })
     );
     note2(
-      `Project folder: ${pc17.bold(process.cwd())}
-Namespace:      ${pc17.bold(namespace)}`,
+      `Project folder: ${pc19.bold(process.cwd())}
+Namespace:      ${pc19.bold(namespace)}`,
       "codebuddy use"
     );
     const stored = await readGlobalConfig();
+    const projectConfig = await readConfigFile();
+    let embeddings = projectConfig.provider?.type;
+    if (embeddings) {
+      log2.info(`Embeddings: ${embeddings} (change with ${pc19.cyan("codebuddy models use")}).`);
+    } else {
+      embeddings = unwrap2(
+        await select({
+          message: "Where should memory embeddings run?",
+          initialValue: "local",
+          options: [
+            {
+              value: "local",
+              label: "On this machine",
+              hint: "recommended \xB7 no key \xB7 ~90 MB once"
+            },
+            {
+              value: "openrouter",
+              label: "OpenRouter",
+              hint: "OPENROUTER_API_KEY \xB7 free models listed"
+            },
+            {
+              value: "huggingface",
+              label: "Hugging Face",
+              hint: "HF_TOKEN \xB7 small free monthly credit"
+            }
+          ]
+        })
+      );
+      if (embeddings === "openrouter" && !process.env.OPENROUTER_API_KEY) {
+        log2.warn(
+          "Export OPENROUTER_API_KEY before your agent starts; keys are never stored in config."
+        );
+      }
+    }
     let hfToken;
-    if (process.env.HF_TOKEN) {
+    if (embeddings !== "huggingface") {
+      hfToken = process.env.HF_TOKEN ?? stored.hfToken;
+    } else 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")}).`);
+      log2.info(`Reusing saved Hugging Face token (${pc19.dim("~/.codebuddy/global.json")}).`);
     } else {
       hfToken = unwrap2(
         await password2({
-          message: "Hugging Face token (optional; press Enter for local-only mode)"
+          message: "Hugging Face token (for hosted embeddings)"
         })
       );
-      if (!hfToken)
-        log2.info("No Hugging Face token supplied; local file context remains available.");
+      if (!hfToken) log2.warn("No token: hosted embeddings will fail until HF_TOKEN is set.");
     }
     const initialUrl = options.postgresUrl ?? process.env.DATABASE_URL ?? stored.databaseUrl ?? DEFAULT_DB_URL;
     const databaseUrl = unwrap2(
@@ -3918,7 +4883,7 @@ Namespace:      ${pc17.bold(namespace)}`,
         validate: (value) => value && value.length > 0 ? void 0 : "Postgres URL is required."
       })
     );
-    const dbSpinner = spinner2();
+    const dbSpinner = spinner3();
     dbSpinner.start("Checking Postgres");
     let connected = await pingOnce2(databaseUrl);
     if (connected) dbSpinner.stop("Local Postgres reachable.");
@@ -3933,7 +4898,7 @@ Namespace:      ${pc17.bold(namespace)}`,
     ));
     if (shouldUseDocker) {
       if (!await isDockerDaemonRunning()) {
-        const dockerSpinner = spinner2();
+        const dockerSpinner = spinner3();
         dockerSpinner.start("Starting Docker Desktop");
         await tryStartDockerDesktop();
         const ready = await waitForDockerDaemon(6e4);
@@ -3943,7 +4908,7 @@ Namespace:      ${pc17.bold(namespace)}`,
         }
         dockerSpinner.stop("Docker daemon is up.");
       }
-      const composeSpinner = spinner2();
+      const composeSpinner = spinner3();
       composeSpinner.start("docker compose up -d");
       try {
         const result = await postgresUp();
@@ -3970,7 +4935,7 @@ Namespace:      ${pc17.bold(namespace)}`,
       bail2();
     }
     if (!connected) bail2();
-    const migrateSpinner = spinner2();
+    const migrateSpinner = spinner3();
     migrateSpinner.start("Enabling pgvector + applying migrations");
     {
       const client = createDatabaseClient({ postgresUrl: databaseUrl });
@@ -3991,7 +4956,7 @@ Namespace:      ${pc17.bold(namespace)}`,
       installPath: process.argv[1] ?? void 0
     });
     const existingConfig = await readConfigFile();
-    const indexSpinner = spinner2();
+    const indexSpinner = spinner3();
     indexSpinner.start("Indexing the existing repository");
     try {
       const result = await indexRepository({ repositoryRoot: process.cwd() });
@@ -4005,7 +4970,11 @@ Namespace:      ${pc17.bold(namespace)}`,
       ...existingConfig,
       postgresUrl: databaseUrl,
       namespace,
-      provider: { type: "huggingface", ...hfToken ? { apiKey: hfToken } : {} },
+      provider: {
+        ...existingConfig.provider,
+        type: embeddings,
+        ...hfToken ? { apiKey: hfToken } : {}
+      },
       tokenBudget: existingConfig.tokenBudget ?? 4e3,
       graphify: { enabled: graphifyConfigured, graphPath: "graphify-out/graph.json" }
     });
@@ -4023,11 +4992,11 @@ Namespace:      ${pc17.bold(namespace)}`,
         const install = await installClaudeEntry({
           namespace,
           projectRoot: process.cwd(),
-          hfToken,
+          ...hfToken ? { hfToken } : {},
           databaseUrl
         });
         log2.success(
-          `Registered ${pc17.bold(install.serverKey)} in Claude Desktop. Restart with \u2318Q to activate.`
+          `Registered ${pc19.bold(install.serverKey)} in Claude Desktop. Restart with \u2318Q to activate.`
         );
       } catch (error) {
         log2.warn(`Claude Desktop registration skipped: ${error.message}`);
@@ -4038,11 +5007,11 @@ Namespace:      ${pc17.bold(namespace)}`,
         const install = await installCodexEntry({
           namespace,
           projectRoot: process.cwd(),
-          hfToken,
+          ...hfToken ? { hfToken } : {},
           databaseUrl
         });
         log2.success(
-          `Registered ${pc17.bold(install.serverKey)} in Codex. Restart Codex to activate.`
+          `Registered ${pc19.bold(install.serverKey)} in Codex. Restart Codex to activate.`
         );
       } catch (error) {
         log2.warn(`Codex registration skipped: ${error.message}`);
@@ -4050,24 +5019,24 @@ Namespace:      ${pc17.bold(namespace)}`,
     }
     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")}.`,
+        `${pc19.green("\u2713")} CodeBuddy is ready for ${pc19.bold(folderName)}.`,
+        `${pc19.green("\u2713")} Scaffolded ${pc19.cyan(".codebuddy/policies.yaml")} for project-specific guardrails.`,
+        `${pc19.green("\u2713")} ${graphifyMessage}`,
+        `${pc19.green("\u2713")} Added agent workflow instructions to ${pc19.cyan("CLAUDE.md")} and ${pc19.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.`,
+        `  2. Ask Claude or Codex to use the ${pc19.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.`,
+        `  4. Run ${pc19.cyan("codebuddy doctor")} or ${pc19.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 list           ${pc19.dim("# see every project wired up")}`,
+        `  codebuddy codex list            ${pc19.dim("# see Codex entries")}`,
+        `  codebuddy db test               ${pc19.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)")}`
+        `  codebuddy postgres down         ${pc19.dim("# stop the DB (data preserved)")}`
       ].join("\n"),
       "Done"
     );
@@ -4078,7 +5047,7 @@ Namespace:      ${pc17.bold(namespace)}`,
 
 // src/cli/commands/worklog.ts
 import { relative as relative6 } from "path";
-import pc18 from "picocolors";
+import pc20 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) => {
@@ -4089,7 +5058,7 @@ function registerWorklogCommands(program, runSafely2) {
         return;
       }
       if (entries.length === 0) {
-        console.log(pc18.dim("no worklog entries yet"));
+        console.log(pc20.dim("no worklog entries yet"));
         return;
       }
       for (const entry of entries) console.log(renderRow2(entry));
@@ -4103,36 +5072,36 @@ function registerWorklogCommands(program, runSafely2) {
   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"));
+      console.log(entry ? renderEntry(entry) : pc20.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))`)}`;
+  return `${pc20.dim(entry.createdAt.slice(0, 16))}  ${pc20.dim(entry.id)}  ${short}  ${pc20.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(", ")}`);
+  const lines = [`${pc20.bold(entry.id)}  ${pc20.dim(entry.createdAt)}  ${pc20.dim(entry.namespace)}`];
+  if (entry.sourceSessionId) lines.push(`${pc20.bold("session:")} ${entry.sourceSessionId}`);
+  if (entry.sourcePlanId) lines.push(`${pc20.bold("plan:")} ${entry.sourcePlanId}`);
+  if (entry.commitSha) lines.push(`${pc20.bold("commit:")} ${entry.commitSha}`);
+  if (entry.files.length > 0) lines.push(`${pc20.bold("files:")} ${entry.files.join(", ")}`);
   if (entry.verification.length > 0) {
-    lines.push(`${pc18.bold("verification:")}`, ...entry.verification.map((line) => `  - ${line}`));
+    lines.push(`${pc20.bold("verification:")}`, ...entry.verification.map((line) => `  - ${line}`));
   }
   if (entry.savedMemory.length > 0) {
-    lines.push(`${pc18.bold("saved memory:")} ${entry.savedMemory.join(", ")}`);
+    lines.push(`${pc20.bold("saved memory:")} ${entry.savedMemory.join(", ")}`);
   }
   if (entry.queuedForReview.length > 0) {
-    lines.push(`${pc18.bold("queued for review:")} ${entry.queuedForReview.join(", ")}`);
+    lines.push(`${pc20.bold("queued for review:")} ${entry.queuedForReview.join(", ")}`);
   }
-  lines.push("", entry.summary, "", pc18.dim(relative6(process.cwd(), entry.path)));
+  lines.push("", entry.summary, "", pc20.dim(relative6(process.cwd(), entry.path)));
   return lines.join("\n");
 }
 
 // src/cli/commands/zvec.ts
-import pc19 from "picocolors";
+import pc21 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) => {
@@ -4142,22 +5111,22 @@ function registerZvecCommands(program, runSafely2) {
         console.log(JSON.stringify(report, null, 2));
         return;
       }
-      const mark = (ok) => ok ? pc19.green("yes") : pc19.yellow("no");
+      const mark = (ok2) => ok2 ? pc21.green("yes") : pc21.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)") : ""}`
+        `version:      ${report.version ?? pc21.yellow("not found")}${report.version && !report.supported ? pc21.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)")}`
+        `zg server:    ${report.server} ${pc21.dim("(running = faster queries; optional)")}`
       );
       console.log(`status:       ${report.reason}`);
-      if (!report.version) console.log(pc19.dim("install: npm install -g @zvec/zvec-grep"));
+      if (!report.version) console.log(pc21.dim("install: npm install -g @zvec/zvec-grep"));
       else if (report.supported && !report.indexReady)
-        console.log(pc19.dim("next: codebuddy zvec index"));
+        console.log(pc21.dim("next: codebuddy zvec index"));
       else if (report.indexReady && !report.enabled)
-        console.log(pc19.dim("next: codebuddy zvec enable"));
+        console.log(pc21.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) => {
@@ -4168,7 +5137,7 @@ function registerZvecCommands(program, runSafely2) {
       });
       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`")
+        pc21.dim("tip: add .zvec-grep/ to .gitignore; enable with `codebuddy zvec enable`")
       );
     });
   });
@@ -4176,14 +5145,14 @@ function registerZvecCommands(program, runSafely2) {
     await runSafely2(async () => {
       await setZvecEnabled(true);
       console.log(
-        `${pc19.green("enabled")} zvec-grep retrieval (falls back to keywords if unavailable)`
+        `${pc21.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`);
+      console.log(`${pc21.yellow("disabled")} zvec-grep retrieval`);
     });
   });
 }
@@ -4192,7 +5161,7 @@ function registerZvecCommands(program, runSafely2) {
 function createCli() {
   const program = new Command();
   program.name("codebuddy").description(
-    "Local-first MCP memory and automatic project-context engine for multi-agent coding."
+    "Project memory and context for AI coding agents: recalls the right facts, files and risks on every prompt."
   ).version(VERSION);
   program.action(async () => {
     await runSafely(async () => {
@@ -4200,7 +5169,7 @@ function createCli() {
     });
   });
   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."
+    "One-command setup for this folder: PostgreSQL (starts Docker if needed), migrations, embeddings, and agent wiring."
   ).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."
@@ -4444,9 +5413,9 @@ function createCli() {
   });
   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 });
+      const row2 = await runtime.repository.getNamespaceByName(namespace);
+      if (!row2) throw new Error(`Namespace ${namespace} does not exist.`);
+      const facts = await runtime.repository.listFacts({ namespaceId: row2.id, limit: 1e4 });
       console.log(JSON.stringify({ namespace, facts }, null, 2));
     });
   });
@@ -4486,14 +5455,64 @@ function createCli() {
   registerSuggestCommand(program, runSafely);
   registerRulesCommands(program, runSafely);
   registerHooksCommands(program, runSafely);
+  registerModelsCommands(program, runSafely);
+  registerDashboardCommand(program, runSafely);
   registerClientsCommands(program, runSafely);
   registerGitHubCommands(program, runSafely);
   registerSymbolsCommand(program, runSafely);
   program.action(async () => {
     await runSafely(() => runUseCommand());
   });
+  groupHelp(program);
   return program;
 }
+var HELP_GROUPS = [
+  ["Get started:", ["use", "init", "doctor", "hooks", "clients", "models", "dashboard"]],
+  [
+    "Daily work:",
+    ["context", "plan", "change", "risk", "suggest", "memory", "worklog", "map", "symbols"]
+  ],
+  ["Indexing and search:", ["index", "watch", "reindex", "zvec", "graphify", "llm"]],
+  [
+    "Database:",
+    [
+      "postgres",
+      "db",
+      "migrate",
+      "stats",
+      "inspect",
+      "namespaces",
+      "list-facts",
+      "export",
+      "prune"
+    ]
+  ],
+  ["Integrations:", ["serve", "claude", "codex", "github", "rules", "learn", "eval"]]
+];
+function groupHelp(program) {
+  const groupOf = new Map(
+    HELP_GROUPS.flatMap(([group, names]) => names.map((name) => [name, group]))
+  );
+  for (const command of program.commands) {
+    command.helpGroup(groupOf.get(command.name()) ?? "Other:");
+  }
+  const position = new Map(
+    HELP_GROUPS.flatMap(([, names]) => names).map((name, index) => [name, index])
+  );
+  program.commands.sort(
+    (a, b) => (position.get(a.name()) ?? 999) - (position.get(b.name()) ?? 999)
+  );
+  program.addHelpText(
+    "after",
+    `
+Quick start:
+  codebuddy                      set up this project (PostgreSQL, hooks, agent)
+  codebuddy models               check the embedding model and memory index
+  codebuddy dashboard            live page of recalls, tool calls and tokens
+  codebuddy context preview "fix the login redirect"
+                                 see exactly what an agent would be given`
+  );
+}
 async function withRuntime(fn) {
   await runSafely(async () => {
     const runtime = await createRuntime(await loadRuntimeConfig());
@@ -4508,7 +5527,7 @@ async function runSafely(fn) {
   try {
     await fn();
   } catch (error) {
-    console.error(pc20.red(String(redactSecrets(error.message))));
+    console.error(pc22.red(String(redactSecrets(error.message))));
     process.exitCode = 1;
   }
 }
@@ -4522,19 +5541,19 @@ function parseDuration(value) {
   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}`);
+  const ok2 = pc22.green("ok");
+  const bad = pc22.red("fail");
+  const warn2 = pc22.yellow("warn");
+  console.log(`scaffold root: ${report.scaffold.codebuddyDir.ok ? ok2 : bad}`);
   if (report.scaffold.codebuddyDir.warning)
     console.log(`  ${report.scaffold.codebuddyDir.warning}`);
-  console.log(`policy scaffold: ${report.scaffold.policies.ok ? ok : bad}`);
+  console.log(`policy scaffold: ${report.scaffold.policies.ok ? ok2 : bad}`);
   if (report.scaffold.policies.warning) console.log(`  ${report.scaffold.policies.warning}`);
-  console.log(`DB connectivity: ${report.db.ok ? ok : bad}`);
+  console.log(`DB connectivity: ${report.db.ok ? ok2 : bad}`);
   if (report.db.error) console.log(`  ${report.db.error}`);
-  console.log(`pgvector: ${report.pgvector.ok ? ok : bad}`);
+  console.log(`pgvector: ${report.pgvector.ok ? ok2 : bad}`);
   if (report.pgvector.error) console.log(`  ${report.pgvector.error}`);
-  console.log(`namespace: ${report.namespace.ok ? ok : warn}`);
+  console.log(`namespace: ${report.namespace.ok ? ok2 : warn2}`);
   console.log(
     `  runtime=${report.namespace.runtime ?? "unset"} default=${report.namespace.expectedDefault}`
   );
@@ -4547,9 +5566,9 @@ function printDoctor(report) {
   );
   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(pc22.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}`
+    `config permissions: ${report.config.exists ? report.config.mode : "missing"} ${report.config.ok ? ok2 : warn2}`
   );
   if (report.config.warning) console.log(`  ${report.config.warning}`);
   for (const model of report.models) {
@@ -4557,19 +5576,19 @@ function printDoctor(report) {
   }
 }
 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}`);
+  const ok2 = pc22.green("ok");
+  const bad = pc22.red("fail");
+  const warn2 = pc22.yellow("warn");
+  console.log(`DB connectivity: ${report.db.ok ? ok2 : 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}`);
+  console.log(`pgvector: ${report.pgvector.ok ? ok2 : bad}`);
   if (report.pgvector.error) console.log(`  ${report.pgvector.error}`);
-  console.log(`namespace: ${report.namespace.ok ? ok : warn}`);
+  console.log(`namespace: ${report.namespace.ok ? ok2 : warn2}`);
   console.log(`  runtime=${report.namespace.runtime ?? "unset"}`);
   if (report.namespace.warning) console.log(`  ${report.namespace.warning}`);
 }
 export {
   createCli
 };
-//# sourceMappingURL=main-BFDVQHKO.js.map
+//# sourceMappingURL=main-BDVQAGAS.js.map