@vibgrate/cli 2026.717.1 → 2026.720.1

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { resolveDsn, resolveIngestHost, dashHostForIngestHost, resolveCliInvocation, availableRegionIds, createWorkspaceDsn, writeStoredCredentials, credentialsPath, findGitRoot, ensureGitignored, gitignoreEntryForCredentials, clearStoredCredentials, inventory, uploadScanArtifact, ingestHostForRegionId, dsnCommand, pushCommand, CliError, ExitCode, NPX_INVOCATION, refreshIfStale, driftCount, embeddingsCached, resolveEmbedModel, loadEmbedder, getNodeEmbeddings, queryGraphSemantic, queryGraph, unavailableMessage, recordCliCall, CLI_TOOL_ALIASES, countPending, resolveOne, indexFor, countTokens, shortestPath, renderReport, impactOf, testsToRun, detectRunner, defaultGraphPath, serveStdio, ASSISTANTS, detectAssistants, usageError, loadGraph, detectServeLaunch, installAssistant, writeNavigationConfig, uninstallAssistant, coveringTests, FREE_PACK, readScanArtifact, enrichOnline, ECOSYSTEMS, discoverModels, readSavings, readUsage, exportGraph, catalogPath, libDir, stableStringify, buildGraph, writeArtifacts, writeSnapshot, UsageError, ResourceLimitError, epistemicBreakdown, cacheDir, probeFreshness, discover, vibgrateDir, modelCacheInfo, clearModelCache, GraphSource, createServer, assistantById, serializeGraph, resolveLimits, loadCatalog, driftFor, addLibrary, parseDsn as parseDsn$1, publishPrivateLibrary, resolveLib, libId, resolveVersion, readDoc, localPackageDocs, localApiSurface, assessDocQuality, symbolsFromApi, fetchHostedDocsCached, selectForBudget, formatForExt, verifyDeterminism, renderHtml, isModelReady, SKIP_DIRS, SKIP_FILES } from './chunk-L42NVMD6.js';
+import { resolveDsn, resolveIngestHost, dashHostForIngestHost, resolveCliInvocation, availableRegionIds, createWorkspaceDsn, writeStoredCredentials, credentialsPath, findGitRoot, ensureGitignored, gitignoreEntryForCredentials, clearStoredCredentials, inventory, uploadScanArtifact, ingestHostForRegionId, dsnCommand, pushCommand, CliError, ExitCode, NPX_INVOCATION, refreshIfStale, driftCount, embeddingsCached, resolveEmbedModel, loadEmbedder, getNodeEmbeddings, queryGraphSemantic, queryGraph, unavailableMessage, recordCliCall, CLI_TOOL_ALIASES, countPending, resolveOne, indexFor, countTokens, shortestPath, renderReport, impactOf, testsToRun, detectRunner, defaultGraphPath, serveStdio, ASSISTANTS, detectAssistants, usageError, loadGraph, detectServeLaunch, installAssistant, writeNavigationConfig, uninstallAssistant, coveringTests, FREE_PACK, readScanArtifact, enrichOnline, ECOSYSTEMS, discoverModels, readSavings, readUsage, exportGraph, catalogPath, libDir, stableStringify, buildGraph, writeArtifacts, writeSnapshot, UsageError, ResourceLimitError, epistemicBreakdown, cacheDir, probeFreshness, discover, vibgrateDir, modelCacheInfo, clearModelCache, GraphSource, createServer, assistantById, serializeGraph, resolveLimits, loadCatalog, driftFor, addLibrary, parseDsn as parseDsn$1, publishPrivateLibrary, resolveLib, libId, resolveVersion, readDoc, localPackageDocs, localApiSurface, assessDocQuality, symbolsFromApi, fetchHostedDocsCached, selectForBudget, formatForExt, hostedBase, verifyDeterminism, renderHtml, isModelReady, SAVINGS_TOOLS, DEFAULT_RATE_LABEL, readStoredCredentials, projectCredentialsPath, DEFAULT_RATE_PER_M, homeCredentialsPath, SKIP_DIRS, SKIP_FILES } from './chunk-VQLOVQZP.js';
 import { resolvedGrammarFiles, grammarSetVersion, hashString, canonicalize, hashBytes } from './chunk-VFO5UDAT.js';
-import { loadAdvancedScanHook, baselineCommand } from './chunk-WZNIDXZP.js';
-import { ensureDir, pathExists, writeDefaultConfig, parseDsn, detectVcs, computeRepoFingerprint, resolveRepositoryName, fetchScanPreflight, runCoreScan, VERSION, readJsonFile, writeTextFile, loadConfig, prepareCompressedUpload, computeDriftScore, titleBox, projectTypeToVulnEcosystem, driftBar, gitHistoryAvailable, buildVersionTimelines, findPackageAnyEcosystem, normalizeConstraint, findVersionCrossings, versionSatisfies, PROJECT_TYPE_TO_OSV_ECOSYSTEM, fetchRiskySymbols, brandProgressBar, resolveHead, workingTreeDirty } from './chunk-M62BGJMK.js';
+import { loadAdvancedScanHook, baselineCommand } from './chunk-VYSTOEAK.js';
+import { ensureDir, pathExists, writeDefaultConfig, parseDsn, detectVcs, computeRepoFingerprint, resolveRepositoryName, fetchScanPreflight, runCoreScan, VERSION, readJsonFile, writeTextFile, loadConfig, prepareCompressedUpload, computeDriftScore, titleBox, projectTypeToVulnEcosystem, driftBar, gitHistoryAvailable, buildVersionTimelines, findPackageAnyEcosystem, normalizeConstraint, findVersionCrossings, versionSatisfies, PROJECT_TYPE_TO_OSV_ECOSYSTEM, fetchRiskySymbols, brandProgressBar, resolveHead, workingTreeDirty } from './chunk-AJDUMRVI.js';
 import './chunk-RXP66R2E.js';
 import { pathExists as pathExists$1, parseExcludePatterns } from './chunk-GI6W53LM.js';
 import * as fs8 from 'fs';
@@ -16,7 +16,7 @@ import * as crypto from 'crypto';
 import { randomUUID } from 'crypto';
 import chalk8 from 'chalk';
 import * as os from 'os';
-import * as fs14 from 'fs/promises';
+import * as fs15 from 'fs/promises';
 import * as readline from 'readline';
 import semver from 'semver';
 
@@ -288,21 +288,23 @@ var ROBOT = [
   "  " + c.dim("\u2524") + teal("\u2502") + "  " + c.dim("\u2581\u2581") + "  " + teal("\u2502") + c.dim("\u251C"),
   "   " + teal("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u256F")
 ];
-function logoLines(root) {
+function logoLines(root, opts = {}) {
+  const product = opts.product ?? "Graph";
+  const tagline = opts.tagline ?? "Code Intelligence Engine";
   return [
     "",
     `  ${ROBOT[0]}`,
     `  ${ROBOT[1]}`,
     `  ${ROBOT[2]}`,
     `  ${ROBOT[3]}`,
-    `  ${c.bold.white("Vibgrate")} ${teal("Graph")}  ${c.dim(`\xB7 Code Intelligence Engine \xB7 v${VERSION}`)}`,
+    `  ${c.bold.white("Vibgrate")} ${teal(product)}  ${c.dim(`\xB7 ${tagline} \xB7 v${VERSION}`)}`,
     ...root ? [`  ${c.dim(root)}`] : [],
     ""
   ];
 }
-function printLogo(root) {
+function printLogo(root, opts = {}) {
   if (!process.stderr.isTTY) return;
-  process.stderr.write(`${logoLines(root).join("\n")}
+  process.stderr.write(`${logoLines(root, opts).join("\n")}
 `);
 }
 
@@ -1287,7 +1289,31 @@ var OFFSET_FILE = "stats-share.json";
 var INSTALL_ID_DIR = path.join(os.homedir(), ".vibgrate");
 var INSTALL_ID_FILE = path.join(INSTALL_ID_DIR, "install-id");
 var SEND_TIMEOUT_MS = 4e3;
-function installId() {
+function telemetryOptOut(env = process.env) {
+  const dnt = (env.DO_NOT_TRACK ?? "").trim().toLowerCase();
+  if (dnt !== "" && dnt !== "0" && dnt !== "false") return "DO_NOT_TRACK";
+  const vt = (env.VIBGRATE_TELEMETRY ?? "").trim().toLowerCase();
+  if (vt === "0" || vt === "false" || vt === "off") return "VIBGRATE_TELEMETRY";
+  return null;
+}
+var CI_ENV_VARS = [
+  "CI",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "CIRCLECI",
+  "TRAVIS",
+  "BUILDKITE",
+  "JENKINS_URL",
+  "TF_BUILD"
+];
+function isCI(env = process.env) {
+  return CI_ENV_VARS.some((v) => {
+    const val = (env[v] ?? "").trim().toLowerCase();
+    return val !== "" && val !== "0" && val !== "false";
+  });
+}
+function installId(env = process.env) {
+  if (telemetryOptOut(env) !== null || isCI(env)) return randomUuid();
   try {
     const existing = fs8.readFileSync(INSTALL_ID_FILE, "utf8").trim();
     if (isUuid(existing)) return existing;
@@ -1463,6 +1489,241 @@ var StatsSharer = class {
   }
 };
 
+// src/util/origin.ts
+function originAllowed(origin, allowlist) {
+  if (origin === void 0 || origin === "") return true;
+  const allowed = (allowlist ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (allowed.includes("*")) return true;
+  if (allowed.includes(origin)) return true;
+  return isLoopbackOrigin(origin);
+}
+function isLoopbackOrigin(origin) {
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  const host = url.hostname;
+  if (host === "localhost" || host === "[::1]" || host === "::1") return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+// src/mcp/serve-stats.ts
+function zeroRow(key2) {
+  return { key: key2, calls: 0, complete: 0, partial: 0, miss: 0, totalMs: 0, vgTokens: 0, baselineTokens: 0 };
+}
+var SessionStats = class {
+  startedAt;
+  revision = 0;
+  lastCallAt = null;
+  totals = zeroRow("total");
+  byClient = /* @__PURE__ */ new Map();
+  byTool = /* @__PURE__ */ new Map();
+  constructor(now2 = Date.now()) {
+    this.startedAt = now2;
+  }
+  record(sample, now2 = Date.now()) {
+    this.revision++;
+    this.lastCallAt = now2;
+    for (const row of [this.totals, this.rowFor(this.byClient, sample.client), this.rowFor(this.byTool, sample.tool)]) {
+      row.calls++;
+      row[sample.outcome]++;
+      row.totalMs += sample.ms;
+      row.vgTokens += sample.vgTokens;
+      row.baselineTokens += sample.baselineTokens;
+    }
+  }
+  snapshot() {
+    const sorted = (m) => [...m.values()].map((r) => ({ ...r })).sort((a, b) => b.calls - a.calls || a.key.localeCompare(b.key));
+    return {
+      startedAt: this.startedAt,
+      revision: this.revision,
+      lastCallAt: this.lastCallAt,
+      totals: { ...this.totals },
+      clients: sorted(this.byClient),
+      tools: sorted(this.byTool)
+    };
+  }
+  rowFor(m, key2) {
+    let row = m.get(key2);
+    if (!row) {
+      row = zeroRow(key2);
+      m.set(key2, row);
+    }
+    return row;
+  }
+};
+function fmtUptime(ms) {
+  const s = Math.max(0, Math.floor(ms / 1e3));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${String(m % 60).padStart(2, "0")}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${String(h % 24).padStart(2, "0")}h`;
+}
+function fmtTokens(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+  return String(n);
+}
+function fmtAvgMs(row) {
+  if (row.calls === 0) return "\u2014";
+  const avg = row.totalMs / row.calls;
+  return avg >= 1e3 ? `${(avg / 1e3).toFixed(1)}s` : `${Math.round(avg)}ms`;
+}
+var teal2 = (s) => c.hex("#3FB0A4")(s);
+var mint2 = (s) => c.hex("#4FE3C1")(s);
+var SPINNER = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var MAX_TOOL_ROWS = 8;
+function serveStatusLines(snap, now2, tick = 0) {
+  const spinner = mint2(SPINNER[tick % SPINNER.length]);
+  const up = fmtUptime(now2 - snap.startedAt);
+  const lines = [];
+  if (snap.totals.calls === 0) {
+    lines.push(
+      `  ${spinner} ${c.bold.white("vg serve")} ${c.dim("\xB7")} up ${teal2(up)} ${c.dim("\xB7 waiting for your assistant\u2019s first tool call\u2026")}`
+    );
+    return lines;
+  }
+  const t = snap.totals;
+  const answered = Math.round((t.complete + t.partial) / t.calls * 100);
+  const ago = snap.lastCallAt === null ? "" : c.dim(` \xB7 last call ${fmtUptime(now2 - snap.lastCallAt)} ago`);
+  lines.push(
+    `  ${spinner} ${c.bold.white("vg serve")} ${c.dim("\xB7")} up ${teal2(up)} ${c.dim("\xB7")} ${c.bold.white(String(t.calls))} call${t.calls === 1 ? "" : "s"} ${c.dim("\xB7")} ${mint2(`${answered}%`)} answered${ago}`
+  );
+  lines.push(
+    `    ${c.dim("clients")}  ` + snap.clients.map((cl) => `${c.white(cl.key)} ${teal2(String(cl.calls))}${c.dim(` (avg ${fmtAvgMs(cl)})`)}`).join(c.dim(" \xB7 "))
+  );
+  const shown = snap.tools.slice(0, MAX_TOOL_ROWS);
+  const nameW = Math.max(...shown.map((r) => r.key.length));
+  for (const row of shown) {
+    let line = `    ${c.white(row.key.padEnd(nameW))}  ${teal2(String(row.calls).padStart(4))} ${c.dim("\xB7")} ` + c.dim(`avg ${fmtAvgMs(row)}`);
+    if (SAVINGS_TOOLS.has(row.key) && row.baselineTokens > 0) {
+      line += c.dim(" \xB7 ctx ") + c.white(fmtTokens(row.vgTokens)) + c.dim(` vs \u2248${fmtTokens(row.baselineTokens)} grep/read`);
+    }
+    if (row.miss > 0) line += c.dim(" \xB7 ") + c.yellow(`${row.miss} miss`);
+    lines.push(line);
+  }
+  if (snap.tools.length > shown.length) {
+    lines.push(`    ${c.dim(`\u2026 +${snap.tools.length - shown.length} more tools`)}`);
+  }
+  if (t.baselineTokens > 0) {
+    const savedTokens = Math.max(0, t.baselineTokens - t.vgTokens);
+    const savedUsd = savedTokens / 1e6 * DEFAULT_RATE_PER_M;
+    const ratio = t.vgTokens > 0 ? (t.baselineTokens / t.vgTokens).toFixed(1) : "\u2014";
+    lines.push(
+      `    ${c.dim("session")}  ctx ${c.bold.white(fmtTokens(t.vgTokens))} ` + c.dim(`vs grep/read \u2248${fmtTokens(t.baselineTokens)} \u2192 `) + mint2(`${ratio}\xD7 fewer`)
+    );
+    lines.push(
+      `    ${c.dim("est. saved \u2248")} ${mint2(`${fmtTokens(savedTokens)} tokens ($${savedUsd.toFixed(2)})`)} ` + c.dim(`(${DEFAULT_RATE_LABEL}; estimate)`)
+    );
+  }
+  return lines;
+}
+function serveHeartbeatLine(snap, now2) {
+  const up = fmtUptime(now2 - snap.startedAt);
+  const t = snap.totals;
+  if (t.calls === 0) return c.dim(`vg \xB7 serving for ${up} \u2014 no tool calls yet`);
+  const clients = snap.clients.map((cl) => `${cl.key} ${cl.calls}`).join(", ");
+  let line = `vg \xB7 serving for ${up} \u2014 ${t.calls} call${t.calls === 1 ? "" : "s"} (${clients})`;
+  if (t.baselineTokens > 0) {
+    const savedTokens = Math.max(0, t.baselineTokens - t.vgTokens);
+    line += ` \xB7 ctx ${fmtTokens(t.vgTokens)} vs \u2248${fmtTokens(t.baselineTokens)} grep/read \xB7 est. saved \u2248 ${fmtTokens(savedTokens)} tokens`;
+  }
+  return c.dim(line);
+}
+var TTY_INTERVAL_MS = 1e3;
+var HEARTBEAT_INTERVAL_MS = 15 * 60 * 1e3;
+var ServeStatusDisplay = class {
+  constructor(stats, stream = process.stderr) {
+    this.stats = stats;
+    this.stream = stream;
+    this.isTTY = (stream.isTTY ?? false) && process.env.VIBGRATE_PROGRESS_MODE !== "plain";
+  }
+  stats;
+  stream;
+  timer = null;
+  tick = 0;
+  lastRowCount = 0;
+  lastFrame = "";
+  lastHeartbeatRevision = -1;
+  cursorHidden = false;
+  isTTY;
+  start() {
+    if (this.timer) return;
+    if (this.isTTY) {
+      this.hideCursor();
+      process.on("exit", this.restoreCursor);
+      process.once("SIGINT", () => {
+        this.restoreCursor();
+        process.exit(130);
+      });
+      process.once("SIGTERM", () => {
+        this.restoreCursor();
+        process.exit(143);
+      });
+      this.timer = setInterval(() => this.renderTTY(), TTY_INTERVAL_MS);
+      this.renderTTY();
+    } else {
+      this.timer = setInterval(() => this.renderHeartbeat(), HEARTBEAT_INTERVAL_MS);
+    }
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.isTTY) {
+      let buf = "";
+      if (this.lastRowCount > 0) buf += `\x1B[${this.lastRowCount}A\x1B[J`;
+      this.stream.write(buf);
+      this.lastRowCount = 0;
+      this.restoreCursor();
+    }
+  }
+  renderTTY() {
+    this.tick++;
+    const lines = serveStatusLines(this.stats.snapshot(), Date.now(), this.tick);
+    const content = lines.join("\n") + "\n";
+    if (content === this.lastFrame) return;
+    this.lastFrame = content;
+    let buf = "";
+    if (this.lastRowCount > 0) buf += `\x1B[${this.lastRowCount}A\x1B[J`;
+    buf += content;
+    this.stream.write(buf);
+    this.lastRowCount = this.countRows(lines);
+  }
+  renderHeartbeat() {
+    const snap = this.stats.snapshot();
+    if (snap.revision === this.lastHeartbeatRevision) return;
+    this.lastHeartbeatRevision = snap.revision;
+    this.stream.write(serveHeartbeatLine(snap, Date.now()) + "\n");
+  }
+  /** Terminal rows the frame occupies, accounting for line wrap. */
+  countRows(lines) {
+    const columns = Math.max(this.stream.columns ?? 80, 20);
+    return lines.reduce((total, line) => {
+      const visible = line.replace(/\x1b\[[0-9;]*m/g, "").length;
+      return total + Math.max(1, Math.ceil(visible / columns));
+    }, 0);
+  }
+  hideCursor() {
+    if (this.cursorHidden) return;
+    this.stream.write("\x1B[?25l");
+    this.cursorHidden = true;
+  }
+  restoreCursor = () => {
+    if (!this.cursorHidden) return;
+    this.stream.write("\x1B[?25h");
+    this.cursorHidden = false;
+  };
+};
+
 // src/commands/serve.ts
 var SHARE_FLUSH_INTERVAL_MS = 5 * 60 * 1e3;
 function registerServe(program) {
@@ -1472,25 +1733,40 @@ function registerServe(program) {
     const graphPath = global.graph ?? defaultGraphPath(root);
     const refresh = opts.refresh !== false && !global.graph;
     const local = global.local === true;
-    const shareStats = opts.shareStats === true && !local;
+    const optOut = telemetryOptOut();
+    const shareStats = opts.shareStats === true && !local && optOut === null;
+    const quiet = global.quiet === true;
+    const stats = quiet ? void 0 : new SessionStats();
+    if (!quiet) {
+      printLogo(root, { product: "AI Context", tagline: "Local-first MCP for your AI" });
+    }
     const serveOpts = {
-      savings: opts.savings === true || shareStats,
+      // A *requested* --share-stats always implies local recording, even when
+      // the upload itself is suppressed (--local / env opt-out) — the local
+      // ledger never leaves the machine, and the disclosure messages below
+      // promise "recording locally".
+      savings: opts.savings === true || opts.shareStats === true,
       shareStats,
       local,
       dedup: opts.dedup === true,
-      refresh
+      refresh,
+      stats
     };
     await ensureServableGraph(root, graphPath, global, refresh);
     if (opts.shareStats === true && local) {
       info(c.dim("vg \xB7 --share-stats ignored under --local (air-gapped): recording locally, not uploading."));
+    } else if (opts.shareStats === true && optOut !== null) {
+      info(c.dim(`vg \xB7 --share-stats disabled by ${optOut}: recording locally, not uploading.`));
     }
     if (shareStats) startSharing(root);
+    const display = stats ? new ServeStatusDisplay(stats) : void 0;
     const freshness = refresh ? "auto-refresh" : "as built";
     if (opts.http) {
-      await serveHttp(graphPath, opts.host ?? "127.0.0.1", Number(opts.port) || 7437, serveOpts, freshness);
+      await serveHttp(graphPath, opts.host ?? "127.0.0.1", Number(opts.port) || 7437, serveOpts, freshness, () => display?.start());
     } else {
       info(c.dim(`vg \xB7 MCP server on stdio (read-only, ${freshness}). Connect your assistant to this process.`));
       await serveStdio(graphPath, serveOpts);
+      display?.start();
     }
   });
   applyGlobalOptions(cmd);
@@ -1546,7 +1822,7 @@ function startSharing(root) {
   });
   process.once("beforeExit", finalFlush);
 }
-async function serveHttp(graphPath, host, port, opts, freshness) {
+async function serveHttp(graphPath, host, port, opts, freshness, onReady) {
   const { createServer: createHttp } = await import('http');
   const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
   const source = new GraphSource(graphPath, opts.refresh !== false);
@@ -1555,6 +1831,13 @@ async function serveHttp(graphPath, host, port, opts, freshness) {
       res.writeHead(404).end("not found");
       return;
     }
+    const origin = req.headers.origin;
+    if (!originAllowed(origin, process.env.VIBGRATE_ALLOWED_ORIGINS)) {
+      res.writeHead(403, { "Content-Type": "text/plain" }).end(
+        "forbidden origin \u2014 vg serve only accepts browser requests from loopback origins. Set VIBGRATE_ALLOWED_ORIGINS to allow others."
+      );
+      return;
+    }
     try {
       const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
       const server = createServer(source, opts);
@@ -1571,6 +1854,7 @@ async function serveHttp(graphPath, host, port, opts, freshness) {
   });
   await new Promise((resolve17) => httpServer.listen(port, host, resolve17));
   info(c.dim(`vg \xB7 MCP server on http://${host}:${port}/mcp (read-only, local, ${freshness})`));
+  onReady?.();
   await new Promise(() => {
   });
 }
@@ -3499,17 +3783,18 @@ function printBreakdown(usage) {
   info("");
   info(c.bold("  by command") + c.dim("  (complete = full result \xB7 partial = capped/paginated \xB7 miss = no result)"));
   const nameW = Math.max(7, ...usage.commands.map((cmd) => cmd.tool.length));
-  const header = "    " + "command".padEnd(nameW) + ["calls", "complete", "partial", "miss", "success%"].map((h) => h.padStart(9)).join("");
+  const header = "    " + "command".padEnd(nameW) + ["calls", "complete", "partial", "miss", "success%", "avg ms"].map((h) => h.padStart(9)).join("");
   info(c.dim(header));
   for (const cmd of usage.commands) {
     info(
-      "    " + cmd.tool.padEnd(nameW) + String(cmd.calls).padStart(9) + String(cmd.complete).padStart(9) + String(cmd.partial).padStart(9) + String(cmd.miss).padStart(9) + `${cmd.successPct}%`.padStart(9)
+      "    " + cmd.tool.padEnd(nameW) + String(cmd.calls).padStart(9) + String(cmd.complete).padStart(9) + String(cmd.partial).padStart(9) + String(cmd.miss).padStart(9) + `${cmd.successPct}%`.padStart(9) + // Absent ≠ zero: calls recorded before timing existed show '—'.
+      (cmd.avgMs === null ? "\u2014" : String(cmd.avgMs)).padStart(9)
     );
   }
   const t = usage.totals;
-  info(c.dim("    " + "\u2500".repeat(nameW + 45)));
+  info(c.dim("    " + "\u2500".repeat(nameW + 54)));
   info(
-    "    " + c.bold("total".padEnd(nameW)) + String(t.calls).padStart(9) + String(t.complete).padStart(9) + String(t.partial).padStart(9) + String(t.miss).padStart(9) + "".padStart(9)
+    "    " + c.bold("total".padEnd(nameW)) + String(t.calls).padStart(9) + String(t.complete).padStart(9) + String(t.partial).padStart(9) + String(t.miss).padStart(9) + "".padStart(9) + "".padStart(9)
   );
   info(c.dim(`    avg success across commands: ${usage.avgSuccessPct}%`));
 }
@@ -3803,6 +4088,125 @@ function registerBundle(program) {
   });
   applyGlobalOptions(cmd);
 }
+function registerDoctor(program) {
+  const cmd = program.command("doctor").description("diagnose your setup: config, credentials, map freshness, hosted reachability, MCP launch").action(async function() {
+    await runDoctor(readGlobal(this));
+  });
+  applyGlobalOptions(cmd);
+}
+var REACH_TIMEOUT_MS = 3e3;
+var CONFIG_BASENAMES = ["vibgrate.config.ts", "vibgrate.config.js", "vibgrate.config.json"];
+async function runDoctor(global) {
+  const root = rootOf(global);
+  const local = global.local === true;
+  const graphPath = global.graph ?? defaultGraphPath(root);
+  const configFile = CONFIG_BASENAMES.find((f) => fs8.existsSync(path.join(root, f))) ?? null;
+  const graph = loadGraph(root, graphPath);
+  let staleFiles = null;
+  if (graph) {
+    const probe = probeFreshness(root);
+    if (probe) staleFiles = driftCount(probe.drift);
+  }
+  const catalog = loadCatalog(root);
+  const libCount = Object.keys(catalog.libraries).length;
+  const creds = diagnoseCredentials(root);
+  const base = hostedBase();
+  const reachable = local ? null : await probeReachable(base);
+  const launch = detectServeLaunch();
+  const optOut = telemetryOptOut();
+  const d = {
+    version: VERSION,
+    node: process.version,
+    platform: `${process.platform}/${process.arch}`,
+    root,
+    configFile,
+    map: {
+      path: path.relative(root, graphPath),
+      built: graph !== null,
+      generatedAt: graph?.generatedAt ?? null,
+      staleFiles
+    },
+    libCatalog: {
+      path: path.relative(root, catalogPath(root)),
+      present: fs8.existsSync(catalogPath(root)),
+      libraries: libCount
+    },
+    credentials: creds,
+    hosted: { base, checked: !local, reachable },
+    mcpLaunch: { command: launch.command, args: launch.args, note: launch.note ?? null },
+    telemetry: { optOut, ci: isCI(), endpoint: statsEndpoint() }
+  };
+  if (global.json) {
+    json(d);
+    return;
+  }
+  info(`${c.cyan("vg")} doctor \xB7 v${d.version} \xB7 node ${d.node} \xB7 ${d.platform}`);
+  info(`  root       ${d.root}`);
+  info(`  config     ${d.configFile ? c.green(d.configFile) : c.dim("none (defaults) \u2014 `vg init` writes one")}`);
+  if (!d.map.built) {
+    info(`  map        ${c.yellow("none")} \u2014 run ${c.bold("vg")} to build ${c.dim(d.map.path)}`);
+  } else {
+    const fresh = d.map.staleFiles == null ? c.dim("freshness unknown (no snapshot)") : d.map.staleFiles === 0 ? c.green("up to date") : c.yellow(`${d.map.staleFiles} file(s) stale \u2014 auto-refreshes on next query`);
+    info(`  map        ${c.green("built")} ${c.dim(d.map.generatedAt ?? "")} \xB7 ${fresh}`);
+  }
+  info(
+    `  lib        ${d.libCatalog.present ? `${c.green(String(d.libCatalog.libraries))} librar${d.libCatalog.libraries === 1 ? "y" : "ies"} in ${d.libCatalog.path}` : c.dim("no catalog \u2014 `vg lib add <source>` starts one; `vg lib <name>` works without it")}`
+  );
+  if (d.credentials.source === "none") {
+    info(`  auth       ${c.dim("anonymous \u2014 fine for everything local; `vg login` enables push/publish")}`);
+  } else {
+    info(
+      `  auth       ${c.green(d.credentials.source)} ${c.dim(d.credentials.path ?? "")} \xB7 workspace ${d.credentials.workspaceId ?? "?"} \xB7 ${d.credentials.host ?? "?"}`
+    );
+  }
+  if (!d.hosted.checked) {
+    info(`  hosted     ${c.dim(`skipped under --local (${d.hosted.base})`)}`);
+  } else {
+    info(
+      `  hosted     ${d.hosted.base} \xB7 ${d.hosted.reachable ? c.green("reachable") : c.yellow("unreachable \u2014 local answers still work")}`
+    );
+  }
+  info(
+    `  mcp        ${c.bold(`${d.mcpLaunch.command} ${d.mcpLaunch.args.join(" ")}`)}${d.mcpLaunch.note ? c.dim(` (${d.mcpLaunch.note})`) : ""}`
+  );
+  const tel = d.telemetry.optOut ? c.green(`opted out via ${d.telemetry.optOut}`) : "off by default \u2014 only `vg serve --share-stats` ever uploads";
+  info(`  telemetry  ${tel}${d.telemetry.ci ? c.dim(" \xB7 CI detected") : ""}`);
+}
+function diagnoseCredentials(root) {
+  const none = { source: "none", path: null, host: null, workspaceId: null };
+  if (process.env.VIBGRATE_DSN) {
+    const parsed2 = parseDsn$1(process.env.VIBGRATE_DSN);
+    return { source: "env", path: null, host: parsed2?.host ?? null, workspaceId: parsed2?.workspaceId ?? null };
+  }
+  const stored = readStoredCredentials({ cwd: root });
+  if (!stored) return none;
+  const file = credentialsPath({ cwd: root });
+  const source = process.env.VIBGRATE_CREDENTIALS ? "env" : file === projectCredentialsPath(root) ? "project" : "home";
+  const parsed = parseDsn$1(stored.dsn);
+  return {
+    source,
+    path: shortenHome(file),
+    host: stored.ingestHost ?? parsed?.host ?? null,
+    workspaceId: stored.workspaceId ?? parsed?.workspaceId ?? null
+  };
+}
+function shortenHome(p) {
+  const home = homeCredentialsPath().slice(0, -"/.vibgrate/credentials.json".length);
+  return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+async function probeReachable(base) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REACH_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    await fetch(base, { method: "HEAD", signal: controller.signal });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 var initCommand = new Command("init").description("Initialize vibgrate in a project").argument("[path]", "Path to initialize", ".").option("--baseline", "Create initial baseline after init").option("--yes", "Skip confirmation prompts").action(async (targetPath, opts) => {
   const rootDir = path.resolve(targetPath);
   const vibgrateDir2 = path.join(rootDir, ".vibgrate");
@@ -3816,7 +4220,7 @@ var initCommand = new Command("init").description("Initialize vibgrate in a proj
     console.log(chalk8.green("\u2714") + ` Created ${chalk8.bold("vibgrate.config.ts")}`);
   }
   if (opts.baseline) {
-    const { runBaseline } = await import('./baseline-YWGSHCKW.js');
+    const { runBaseline } = await import('./baseline-5QPV6API.js');
     await runBaseline(rootDir);
   }
   console.log("");
@@ -3926,9 +4330,9 @@ async function fileReferencesIdentifier(rootDir, relFile, identifier, readFile3)
 }
 async function defaultReadFile(absPath) {
   try {
-    const stat2 = await fs14.stat(absPath);
+    const stat2 = await fs15.stat(absPath);
     if (!stat2.isFile() || stat2.size > MAX_FILE_BYTES) return null;
-    return await fs14.readFile(absPath, "utf8");
+    return await fs15.readFile(absPath, "utf8");
   } catch {
     return null;
   }
@@ -4121,22 +4525,22 @@ async function detectAiAssistant(rootDir) {
   return null;
 }
 function printAiContextPrompt(detectedAssistant) {
-  const teal2 = chalk8.hex("#3FB0A4");
-  const mint2 = chalk8.hex("#4FE3C1");
+  const teal3 = chalk8.hex("#3FB0A4");
+  const mint3 = chalk8.hex("#4FE3C1");
   const cli = resolveCliInvocation();
   const installArgs = detectedAssistant ? `install ${detectedAssistant}` : "install --all";
   const installCmd = `${cli} ${installArgs}`;
   const detectedNote = detectedAssistant ? chalk8.dim(`  (${detectedAssistant} config detected)`) : "";
   console.log("");
-  console.log(teal2("  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"));
-  console.log(teal2("  \u2502") + "  " + mint2("\u25C6") + "  " + chalk8.bold.white("Get AI-aware answers in your editor") + "          " + teal2("\u2502"));
-  console.log(teal2("  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
+  console.log(teal3("  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"));
+  console.log(teal3("  \u2502") + "  " + mint3("\u25C6") + "  " + chalk8.bold.white("Get AI-aware answers in your editor") + "          " + teal3("\u2502"));
+  console.log(teal3("  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
   console.log("");
   console.log("  " + chalk8.bold.white(installCmd) + detectedNote);
   console.log("");
-  console.log("  " + teal2("\xB7") + " " + chalk8.white("Code map in your assistant") + chalk8.dim(" \u2014 call trees, impact surfaces, import paths"));
-  console.log("  " + teal2("\xB7") + " " + chalk8.white("Offline drift") + chalk8.dim(" \u2014 DriftScore and upgrade priorities, right inside your editor"));
-  console.log("  " + teal2("\xB7") + " " + chalk8.white("Version-correct library docs") + chalk8.dim(" \u2014 pinned to your lockfile, no hallucinated APIs"));
+  console.log("  " + teal3("\xB7") + " " + chalk8.white("Code map in your assistant") + chalk8.dim(" \u2014 call trees, impact surfaces, import paths"));
+  console.log("  " + teal3("\xB7") + " " + chalk8.white("Offline drift") + chalk8.dim(" \u2014 DriftScore and upgrade priorities, right inside your editor"));
+  console.log("  " + teal3("\xB7") + " " + chalk8.white("Version-correct library docs") + chalk8.dim(" \u2014 pinned to your lockfile, no hallucinated APIs"));
   console.log("");
 }
 
@@ -5121,8 +5525,8 @@ async function fetchLatestVersion() {
 }
 async function writeCache(data) {
   try {
-    await fs14.mkdir(CACHE_DIR, { recursive: true });
-    await fs14.writeFile(CACHE_FILE, JSON.stringify(data), "utf-8");
+    await fs15.mkdir(CACHE_DIR, { recursive: true });
+    await fs15.writeFile(CACHE_FILE, JSON.stringify(data), "utf-8");
   } catch {
   }
 }
@@ -5662,15 +6066,15 @@ Applied the ${chosen.label} plan:`));
 }
 function formatText(artifact) {
   const lines = [];
-  const teal2 = chalk8.hex("#3FB0A4");
-  const mint2 = chalk8.hex("#4FE3C1");
+  const teal3 = chalk8.hex("#3FB0A4");
+  const mint3 = chalk8.hex("#4FE3C1");
   lines.push("");
-  lines.push("   " + teal2("\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u256E") + mint2("\u279C"));
-  lines.push("  " + chalk8.dim("\u2524") + teal2("\u2502") + " " + mint2("\u25FC") + "  " + mint2("\u25FC") + " " + teal2("\u2502") + chalk8.dim("\u251C") + "  " + chalk8.bold.white("vibgrate"));
-  lines.push("  " + chalk8.dim("\u2524") + teal2("\u2502") + "  " + chalk8.dim("\u2581\u2581") + "  " + teal2("\u2502") + chalk8.dim("\u251C") + "  " + chalk8.dim(`Code Intelligence Engine v${VERSION}`));
-  lines.push("   " + teal2("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
+  lines.push("   " + teal3("\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u256E") + mint3("\u279C"));
+  lines.push("  " + chalk8.dim("\u2524") + teal3("\u2502") + " " + mint3("\u25FC") + "  " + mint3("\u25FC") + " " + teal3("\u2502") + chalk8.dim("\u251C") + "  " + chalk8.bold.white("vibgrate"));
+  lines.push("  " + chalk8.dim("\u2524") + teal3("\u2502") + "  " + chalk8.dim("\u2581\u2581") + "  " + teal3("\u2502") + chalk8.dim("\u251C") + "  " + chalk8.dim(`Code Intelligence Engine v${VERSION}`));
+  lines.push("   " + teal3("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
   lines.push("");
-  lines.push(...titleBox("Vibgrate Drift Report", teal2));
+  lines.push(...titleBox("Vibgrate Drift Report", teal3));
   lines.push("");
   for (const project of artifact.projects) {
     lines.push(chalk8.bold(`  \u2500\u2500 ${project.name} `) + chalk8.dim(`(${project.type}) ${project.path}`));
@@ -6949,6 +7353,7 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "oddities",
   "serve",
   "lsp",
+  "doctor",
   "install",
   "uninstall",
   "share",
@@ -7004,6 +7409,7 @@ ${aliasNote}Docs: https://vibgrate.com/help`;
   registerLib(program);
   registerExport(program);
   registerBundle(program);
+  registerDoctor(program);
   program.addCommand(initCommand);
   program.addCommand(scanCommand);
   program.addCommand(fixCommand);