@vibgrate/cli 2026.715.1 → 2026.718.2

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/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, 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 } from './chunk-D4BPWARI.js';
-import { resolvedGrammarFiles, grammarSetVersion, canonicalize } from './chunk-VFO5UDAT.js';
-import { loadAdvancedScanHook, baselineCommand } from './chunk-6DKWB2OI.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-C5AVF7PT.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, readStoredCredentials, projectCredentialsPath, homeCredentialsPath, SKIP_DIRS, SKIP_FILES } from './chunk-H5M7CXE6.js';
+import { resolvedGrammarFiles, grammarSetVersion, hashString, canonicalize, hashBytes } from './chunk-VFO5UDAT.js';
+import { loadAdvancedScanHook, baselineCommand } from './chunk-BFXDF6ZE.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-RME7BFMU.js';
 import './chunk-RXP66R2E.js';
 import { pathExists as pathExists$1, parseExcludePatterns } from './chunk-GI6W53LM.js';
-import * as fs7 from 'fs';
-import fs7__default, { realpathSync } from 'fs';
+import * as fs8 from 'fs';
+import fs8__default, { realpathSync } from 'fs';
 import * as path from 'path';
 import path__default from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -16,7 +16,7 @@ import * as crypto from 'crypto';
 import { randomUUID } from 'crypto';
 import chalk8 from 'chalk';
 import * as os from 'os';
-import * as fs13 from 'fs/promises';
+import * as fs15 from 'fs/promises';
 import * as readline from 'readline';
 import semver from 'semver';
 
@@ -178,14 +178,14 @@ async function signGraphAttestation(root, graph, opts) {
   const explicitKey = opts.key ?? process.env.VG_ATTEST_KEY;
   const keyPath = explicitKey ? path.resolve(explicitKey) : path.join(root, ".vibgrate", DEFAULT_KEY);
   let keyGeneratedAt;
-  if (!fs7.existsSync(keyPath)) {
+  if (!fs8.existsSync(keyPath)) {
     if (explicitKey) {
       throw new CliError(`signing key not found: ${explicitKey}`, ExitCode.USAGE_ERROR);
     }
     const kp = generateKeypair();
-    fs7.mkdirSync(path.dirname(keyPath), { recursive: true });
-    fs7.writeFileSync(keyPath, kp.privatePem, { mode: 384 });
-    fs7.writeFileSync(`${keyPath}.pub`, kp.publicPem);
+    fs8.mkdirSync(path.dirname(keyPath), { recursive: true });
+    fs8.writeFileSync(keyPath, kp.privatePem, { mode: 384 });
+    fs8.writeFileSync(`${keyPath}.pub`, kp.publicPem);
     keyGeneratedAt = keyPath;
     notices.push(
       `minted a new Ed25519 signing key at ${rel(root, keyPath)} (keyid ${kp.keyid}) \u2014 keep it, add it to .gitignore, and reuse it to re-sign reproducibly`
@@ -193,7 +193,7 @@ async function signGraphAttestation(root, graph, opts) {
   }
   let privateKey;
   try {
-    privateKey = crypto.createPrivateKey(fs7.readFileSync(keyPath, "utf8"));
+    privateKey = crypto.createPrivateKey(fs8.readFileSync(keyPath, "utf8"));
   } catch {
     throw new CliError(`could not read an Ed25519 private key from ${rel(root, keyPath)}`, ExitCode.USAGE_ERROR);
   }
@@ -207,8 +207,8 @@ async function signGraphAttestation(root, graph, opts) {
   const statement = buildStatement(graph, { commit });
   const envelope = signStatement(statement, privateKey);
   const outPath = opts.attestation ? path.resolve(opts.attestation) : path.join(root, ".vibgrate", DEFAULT_ATTESTATION);
-  fs7.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs7.writeFileSync(outPath, serializeEnvelope(envelope));
+  fs8.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs8.writeFileSync(outPath, serializeEnvelope(envelope));
   return {
     summary: {
       keyid: envelope.signatures[0]?.keyid ?? "",
@@ -223,7 +223,7 @@ async function signGraphAttestation(root, graph, opts) {
 }
 function verifyGraphAttestation(root, opts) {
   const bundlePath = opts.attestation ? path.resolve(opts.attestation) : path.join(root, ".vibgrate", DEFAULT_ATTESTATION);
-  if (!fs7.existsSync(bundlePath)) {
+  if (!fs8.existsSync(bundlePath)) {
     if (opts.attestation || opts.pub) {
       throw new CliError(
         `no attestation at ${rel(root, bundlePath)} \u2014 sign one with \`vg build --attest\``,
@@ -232,8 +232,8 @@ function verifyGraphAttestation(root, opts) {
     }
     return { bundlePath, missing: true };
   }
-  const envelope = parseEnvelope(fs7.readFileSync(bundlePath, "utf8"));
-  const publicKeyPem = opts.pub ? fs7.readFileSync(path.resolve(opts.pub), "utf8") : void 0;
+  const envelope = parseEnvelope(fs8.readFileSync(bundlePath, "utf8"));
+  const publicKeyPem = opts.pub ? fs8.readFileSync(path.resolve(opts.pub), "utf8") : void 0;
   const graph = loadGraph(root) ?? void 0;
   return { bundlePath, missing: false, result: verifyEnvelope(envelope, { publicKeyPem, graph }) };
 }
@@ -584,8 +584,8 @@ function writeExport(graph, target) {
         ExitCode.USAGE_ERROR
       );
   }
-  fs7.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
-  fs7.writeFileSync(target, content);
+  fs8.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+  fs8.writeFileSync(target, content);
 }
 function collect(value, prev) {
   return [...prev, value];
@@ -604,7 +604,7 @@ async function runStatus(global) {
   const root = path.resolve(global.cwd ?? ".");
   const graphPath = global.graph ?? defaultGraphPath(root);
   const graph = loadGraph(root, graphPath);
-  const hasCache = fs7.existsSync(path.join(cacheDir(root), "parse-cache.json"));
+  const hasCache = fs8.existsSync(path.join(cacheDir(root), "parse-cache.json"));
   let stale = null;
   let staleExact = false;
   if (graph) {
@@ -1287,16 +1287,40 @@ 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 = fs7.readFileSync(INSTALL_ID_FILE, "utf8").trim();
+    const existing = fs8.readFileSync(INSTALL_ID_FILE, "utf8").trim();
     if (isUuid(existing)) return existing;
   } catch {
   }
   const id = randomUuid();
   try {
-    fs7.mkdirSync(INSTALL_ID_DIR, { recursive: true });
-    fs7.writeFileSync(INSTALL_ID_FILE, id + "\n", { mode: 384 });
+    fs8.mkdirSync(INSTALL_ID_DIR, { recursive: true });
+    fs8.writeFileSync(INSTALL_ID_FILE, id + "\n", { mode: 384 });
   } catch {
   }
   return id;
@@ -1320,7 +1344,7 @@ function ledgerFilePath(root) {
 }
 function readOffset(root) {
   try {
-    const raw = JSON.parse(fs7.readFileSync(offsetPath(root), "utf8"));
+    const raw = JSON.parse(fs8.readFileSync(offsetPath(root), "utf8"));
     return typeof raw.offset === "number" && raw.offset >= 0 ? raw.offset : 0;
   } catch {
     return 0;
@@ -1328,8 +1352,8 @@ function readOffset(root) {
 }
 function writeOffset(root, offset) {
   try {
-    fs7.mkdirSync(cacheDir(root), { recursive: true });
-    fs7.writeFileSync(offsetPath(root), JSON.stringify({ offset }) + "\n");
+    fs8.mkdirSync(cacheDir(root), { recursive: true });
+    fs8.writeFileSync(offsetPath(root), JSON.stringify({ offset }) + "\n");
   } catch {
   }
 }
@@ -1337,7 +1361,7 @@ function buildBatch(root, fromOffset, id = installId()) {
   const file = ledgerFilePath(root);
   let size = 0;
   try {
-    size = fs7.statSync(file).size;
+    size = fs8.statSync(file).size;
   } catch {
     return { batch: null, newOffset: 0 };
   }
@@ -1345,13 +1369,13 @@ function buildBatch(root, fromOffset, id = installId()) {
   if (start >= size) return { batch: null, newOffset: size };
   let text = "";
   try {
-    const fd = fs7.openSync(file, "r");
+    const fd = fs8.openSync(file, "r");
     try {
       const buf = Buffer.alloc(size - start);
-      fs7.readSync(fd, buf, 0, buf.length, start);
+      fs8.readSync(fd, buf, 0, buf.length, start);
       text = buf.toString("utf8");
     } finally {
-      fs7.closeSync(fd);
+      fs8.closeSync(fd);
     }
   } catch {
     return { batch: null, newOffset: fromOffset };
@@ -1374,8 +1398,8 @@ function buildBatch(root, fromOffset, id = installId()) {
     const source = e.source ?? "mcp";
     const client = e.client ?? "unknown";
     const outcome = e.outcome ?? "complete";
-    const key = `${source}|${client}|${e.tool}|${outcome}`;
-    const row = rows.get(key) ?? {
+    const key2 = `${source}|${client}|${e.tool}|${outcome}`;
+    const row = rows.get(key2) ?? {
       source,
       client,
       tool: e.tool,
@@ -1387,7 +1411,7 @@ function buildBatch(root, fromOffset, id = installId()) {
     row.calls++;
     row.vgTokens += e.vgTokens ?? 0;
     row.baselineTokens += e.baselineTokens ?? 0;
-    rows.set(key, row);
+    rows.set(key2, row);
     total++;
     if (typeof e.ts === "number") {
       if (e.ts < minTs) minTs = e.ts;
@@ -1463,6 +1487,27 @@ 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/commands/serve.ts
 var SHARE_FLUSH_INTERVAL_MS = 5 * 60 * 1e3;
 function registerServe(program) {
@@ -1472,9 +1517,14 @@ 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 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,
@@ -1483,6 +1533,8 @@ function registerServe(program) {
     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 freshness = refresh ? "auto-refresh" : "as built";
@@ -1497,7 +1549,7 @@ function registerServe(program) {
 }
 async function ensureServableGraph(root, graphPath, global, refresh, opts = {}) {
   if (refresh) {
-    if (!fs7.existsSync(graphPath)) {
+    if (!fs8.existsSync(graphPath)) {
       info(c.dim("vg \xB7 no map found \u2014 building it before serving\u2026"));
       await runBuild(
         [],
@@ -1514,7 +1566,7 @@ async function ensureServableGraph(root, graphPath, global, refresh, opts = {})
       }
     }
   }
-  if (!fs7.existsSync(graphPath)) {
+  if (!fs8.existsSync(graphPath)) {
     throw new CliError(
       `no map found at ${graphPath} \u2014 run \`vg\` to build one first`,
       ExitCode.NOT_FOUND
@@ -1555,6 +1607,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);
@@ -1780,6 +1839,318 @@ function endOfLine(text, line) {
   const lines = text.split(/\r?\n/);
   return (lines[line] ?? "").length;
 }
+var CACHE_VERSION = "vg-lsp-scan-cache/2";
+function cachePath(root) {
+  return path.join(cacheDir(root), "lsp-scan.json");
+}
+function manifestHash(root) {
+  const files = [];
+  const walk2 = (dir) => {
+    let entries;
+    try {
+      entries = fs8.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk2(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const base = entry.name.toLowerCase();
+      if (!isManifest(abs) && !SKIP_FILES.has(base)) continue;
+      try {
+        const rel3 = path.relative(root, abs).split(path.sep).join("/");
+        files.push({ rel: rel3, hash: hashBytes(fs8.readFileSync(abs)) });
+      } catch {
+      }
+    }
+  };
+  walk2(root);
+  files.sort((a, b) => a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0);
+  return hashString(canonicalize(files));
+}
+function loadScanCache(root, key2) {
+  try {
+    const raw = JSON.parse(fs8.readFileSync(cachePath(root), "utf8"));
+    if (raw.version === CACHE_VERSION && raw.manifestHash === key2.manifestHash && raw.toolVersion === key2.toolVersion && raw.offline === key2.offline && raw.artifact) {
+      return { manifestHash: raw.manifestHash, artifact: raw.artifact };
+    }
+  } catch {
+  }
+  return null;
+}
+function writeScanCache(root, key2, artifact) {
+  try {
+    fs8.mkdirSync(cacheDir(root), { recursive: true });
+    fs8.writeFileSync(
+      cachePath(root),
+      stableStringify(
+        { version: CACHE_VERSION, manifestHash: key2.manifestHash, toolVersion: key2.toolVersion, offline: key2.offline, artifact },
+        0
+      )
+    );
+  } catch {
+  }
+}
+
+// src/lsp/graph-query.ts
+async function runGraphQuery(graph, params, ctx) {
+  switch (params.mode) {
+    case "ask":
+      return runAsk(graph, params, ctx);
+    case "areas":
+      return runAreas(graph, params);
+    case "hubs":
+      return runHubs(graph, params);
+    case "impact":
+      return runImpact(graph, params);
+    case "path":
+      return runPath(graph, params);
+    case "show":
+      return runShow(graph, params);
+    case "tree":
+      return runTree(graph, params);
+    default:
+      return { ok: false, mode: params.mode, error: "bad-request", message: `unknown mode "${String(params.mode)}"` };
+  }
+}
+async function runAsk(graph, params, ctx) {
+  const question = (params.question ?? "").trim();
+  if (!question) return { ok: false, mode: "ask", error: "bad-request", message: "question is required" };
+  const budget = params.budget ?? 2e3;
+  const wantSemantic = !!params.semantic && !ctx.offline && ctx.semantic !== false;
+  let result;
+  let mode = "lexical";
+  let note;
+  if (wantSemantic) {
+    let reason;
+    const embedder = await loadEmbedder({ onUnavailable: (r) => reason = r });
+    if (embedder) {
+      const vectors = await getNodeEmbeddings(graph, embedder, ctx.root);
+      result = await queryGraphSemantic(graph, question, { budget, embedder, nodeVectors: vectors });
+      mode = `semantic (${embedder.id})`;
+    } else {
+      result = queryGraph(graph, question, { budget });
+      note = reason ? unavailableMessage(reason) : "semantic unavailable; used lexical";
+    }
+  } else {
+    result = queryGraph(graph, question, { budget });
+    if (params.semantic && ctx.semantic === false) note = "semantic search is turned off \u2014 used lexical";
+    else if (params.semantic && ctx.offline) note = "semantic skipped \u2014 Vibgrate is running offline";
+  }
+  return {
+    ok: true,
+    mode: "ask",
+    data: {
+      question: result.question,
+      mode,
+      note,
+      tokensEstimate: result.tokensEstimate,
+      matches: result.matches.map((m) => ({
+        name: m.node.qualifiedName,
+        kind: m.node.kind,
+        file: m.node.file,
+        line: m.node.span.start,
+        score: m.score,
+        why: m.why
+      })),
+      context: result.context
+    }
+  };
+}
+function runAreas(graph, params) {
+  const limit = params.limit ?? 30;
+  const list = [...graph.areas].sort((a, b) => b.size - a.size || a.id - b.id).slice(0, limit);
+  return { ok: true, mode: "areas", data: list };
+}
+function runHubs(graph, params) {
+  const limit = params.limit ?? 20;
+  const list = graph.nodes.filter((n) => n.kind !== "file" && n.kind !== "external").sort((a, b) => b.importance - a.importance || a.qualifiedName.localeCompare(b.qualifiedName)).slice(0, limit).map(nodeSummary2);
+  return { ok: true, mode: "hubs", data: list };
+}
+function nodeSummary2(n) {
+  return {
+    id: n.id,
+    name: n.qualifiedName,
+    kind: n.kind,
+    file: n.file,
+    line: n.span.start,
+    importance: n.importance,
+    isHub: n.isHub,
+    area: n.area
+  };
+}
+function resolveOrError(graph, name, mode) {
+  const { node, candidates } = resolveOne(graph, name);
+  if (node) return { node };
+  if (candidates.length === 0) {
+    return { ok: false, mode, error: "not-found", message: `no node matches "${name}"` };
+  }
+  return {
+    ok: false,
+    mode,
+    error: "ambiguous",
+    message: `"${name}" is ambiguous`,
+    candidates: candidates.slice(0, 10).map((n) => ({ name: n.qualifiedName, kind: n.kind, file: n.file, line: n.span.start }))
+  };
+}
+function runImpact(graph, params) {
+  const name = (params.name ?? "").trim();
+  if (!name) return { ok: false, mode: "impact", error: "bad-request", message: "name is required" };
+  const resolved = resolveOrError(graph, name, "impact");
+  if (!("node" in resolved)) return resolved;
+  const result = impactOf(graph, resolved.node.id, { depth: params.depth ?? 4 });
+  return { ok: true, mode: "impact", data: result };
+}
+function runPath(graph, params) {
+  const a = (params.a ?? "").trim();
+  const b = (params.b ?? "").trim();
+  if (!a || !b) return { ok: false, mode: "path", error: "bad-request", message: "a and b are required" };
+  const ra = resolveOrError(graph, a, "path");
+  if (!("node" in ra)) return ra;
+  const rb = resolveOrError(graph, b, "path");
+  if (!("node" in rb)) return rb;
+  const result = shortestPath(graph, ra.node.id, rb.node.id);
+  if (!result) {
+    return {
+      ok: false,
+      mode: "path",
+      error: "not-found",
+      message: `no path between ${ra.node.qualifiedName} and ${rb.node.qualifiedName}`
+    };
+  }
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const names = result.ids.map((id) => byId.get(id)?.qualifiedName ?? id);
+  return {
+    ok: true,
+    mode: "path",
+    data: { from: ra.node.qualifiedName, to: rb.node.qualifiedName, hops: names.length - 1, direction: result.direction, path: names }
+  };
+}
+function runShow(graph, params) {
+  const name = (params.name ?? "").trim();
+  if (!name) return { ok: false, mode: "show", error: "bad-request", message: "name is required" };
+  const resolved = resolveOrError(graph, name, "show");
+  if (!("node" in resolved)) return resolved;
+  const node = resolved.node;
+  const index = indexFor(graph);
+  const callees = dedupeNodes(index.callees(node.id).map((x) => x.node));
+  const callers = dedupeNodes(index.callers(node.id).map((x) => x.node));
+  const extendsEdges = index.out(node.id, "extends").concat(index.out(node.id, "implements"));
+  const supertypes = extendsEdges.map((e) => index.node(e.dst)?.qualifiedName).filter(Boolean);
+  const area = graph.areas.find((a) => a.id === node.area);
+  return {
+    ok: true,
+    mode: "show",
+    data: {
+      id: node.id,
+      name: node.qualifiedName,
+      kind: node.kind,
+      file: node.file,
+      line: node.span.start,
+      signature: node.signature ?? null,
+      importance: node.importance,
+      centrality: node.centrality,
+      isHub: node.isHub,
+      area: node.area,
+      areaLabel: area?.label ?? null,
+      tested: node.tested,
+      calls: callees.map((n) => n.qualifiedName),
+      calledBy: callers.map((n) => n.qualifiedName),
+      extends: supertypes
+    }
+  };
+}
+function dedupeNodes(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const out2 = [];
+  for (const n of nodes) {
+    if (seen.has(n.id)) continue;
+    seen.add(n.id);
+    out2.push(n);
+  }
+  return out2;
+}
+function runTree(graph, params) {
+  const name = (params.name ?? "").trim();
+  if (!name) return { ok: false, mode: "tree", error: "bad-request", message: "name is required" };
+  const resolved = resolveOrError(graph, name, "tree");
+  if (!("node" in resolved)) return resolved;
+  const index = indexFor(graph);
+  const direction = params.callers ? "callers" : "callees";
+  const maxDepth = Math.max(1, params.depth ?? 3);
+  const data = toJsonTree(index, resolved.node, direction, maxDepth, /* @__PURE__ */ new Set());
+  return { ok: true, mode: "tree", data };
+}
+
+// src/lsp/enrich.ts
+var OSV_QUERY_URL = "https://api.osv.dev/v1/query";
+var cache = /* @__PURE__ */ new Map();
+function key(ecosystem, name, version) {
+  return `${ecosystem}:${name}@${version}`;
+}
+function severityOf(v) {
+  const dbSpecific = v.database_specific;
+  const label = typeof dbSpecific?.severity === "string" ? dbSpecific.severity.toLowerCase() : "";
+  if (label.includes("critical")) return "critical";
+  if (label.includes("high")) return "high";
+  if (label.includes("moderate") || label.includes("medium")) return "moderate";
+  if (label.includes("low")) return "low";
+  const sev = Array.isArray(v.severity) ? v.severity : [];
+  const cvss = sev.find((s) => typeof s.score === "string" && String(s.type).startsWith("CVSS"));
+  if (cvss) {
+    const m = /\/AV:.*$/.test(String(cvss.score)) ? null : Number(cvss.score);
+    if (m != null && !Number.isNaN(m)) {
+      if (m >= 9) return "critical";
+      if (m >= 7) return "high";
+      if (m >= 4) return "moderate";
+      if (m > 0) return "low";
+    }
+  }
+  return "unknown";
+}
+function toSummary(raw) {
+  const v = raw ?? {};
+  const aliases = Array.isArray(v.aliases) ? v.aliases.map(String) : [];
+  const details = typeof v.details === "string" ? v.details : "";
+  const summary = typeof v.summary === "string" && v.summary || (details ? details.split("\n")[0].slice(0, 140) : "") || "Advisory";
+  return {
+    id: String(v.id ?? "unknown"),
+    cves: aliases.filter((a) => a.startsWith("CVE-")),
+    summary,
+    severity: severityOf(v)
+  };
+}
+async function enrichVulns(ecosystem, name, version, opts = { offline: false }) {
+  if (!ecosystem || !version) return { vulns: [], cveCount: 0, source: "error" };
+  if (opts.offline) return { vulns: [], cveCount: 0, source: "offline" };
+  const k = key(ecosystem, name, version);
+  const cached = cache.get(k);
+  if (cached) return { ...cached, source: "cache" };
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8e3);
+    const res = await fetch(OSV_QUERY_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ version, package: { name, ecosystem } }),
+      signal: controller.signal
+    }).finally(() => clearTimeout(timer));
+    if (!res.ok) return { vulns: [], cveCount: 0, source: "error" };
+    const data = await res.json();
+    const vulns = (data.vulns ?? []).map(toSummary);
+    const cveCount = new Set(vulns.flatMap((v) => v.cves)).size;
+    const result = { vulns, cveCount, source: "osv" };
+    cache.set(k, result);
+    return result;
+  } catch {
+    return { vulns: [], cveCount: 0, source: "error" };
+  }
+}
 
 // src/lsp/server.ts
 function bandForDependency(dep) {
@@ -1816,6 +2187,8 @@ var VibgrateLanguageServer = class {
   queued = false;
   debounce = null;
   shuttingDown = false;
+  graph = null;
+  graphBuilding = false;
   register() {
     this.conn.onRequest("initialize", () => ({
       capabilities: {
@@ -1830,7 +2203,10 @@ var VibgrateLanguageServer = class {
       },
       serverInfo: { name: "Vibgrate", version: VERSION }
     }));
-    this.conn.onNotification("initialized", () => this.scheduleScan(0));
+    this.conn.onNotification("initialized", () => {
+      this.scheduleScan(0);
+      void this.ensureGraph();
+    });
     this.conn.onNotification("textDocument/didOpen", (_m, params) => {
       const p = params;
       const uri = p.textDocument?.uri;
@@ -1859,6 +2235,9 @@ var VibgrateLanguageServer = class {
     });
     this.conn.onRequest("textDocument/hover", (_m, params) => this.onHover(params));
     this.conn.onRequest("textDocument/codeLens", (_m, params) => this.onCodeLens(params));
+    this.conn.onRequest("vibgrate/graph/query", (_m, params) => this.onGraphQuery(params));
+    this.conn.onRequest("vibgrate/score/forFile", (_m, params) => this.onScoreForFile(params));
+    this.conn.onRequest("vibgrate/enrich", (_m, params) => this.onEnrich(params));
     this.conn.onRequest("workspace/executeCommand", (_m, params) => {
       const p = params;
       if (p.command === "vibgrate.rescan") {
@@ -1888,20 +2267,27 @@ var VibgrateLanguageServer = class {
     }
     this.scanning = true;
     try {
-      const scanOpts = {
-        format: "json",
-        concurrency: 8,
-        offline: this.opts.offline,
-        noLocalArtifacts: true,
-        // an editor scan must not litter the repo
-        noGraph: true,
-        // the code map is not needed to score drift; skip the cost
-        quiet: true,
-        // no spinners, no artifact dump — an editor is not a terminal
-        vibgrateVersion: VERSION
-      };
-      const advanced = await loadAdvancedScanHook();
-      this.artifact = await runCoreScan(this.opts.root, scanOpts, advanced);
+      const cacheKey = { manifestHash: manifestHash(this.opts.root), toolVersion: VERSION, offline: this.opts.offline };
+      const cached = loadScanCache(this.opts.root, cacheKey);
+      if (cached) {
+        this.artifact = cached.artifact;
+      } else {
+        const scanOpts = {
+          format: "json",
+          concurrency: 8,
+          offline: this.opts.offline,
+          noLocalArtifacts: true,
+          // an editor scan must not litter the repo
+          noGraph: true,
+          // the code map is not needed to score drift; skip the cost
+          quiet: true,
+          // no spinners, no artifact dump — an editor is not a terminal
+          vibgrateVersion: VERSION
+        };
+        const advanced = await loadAdvancedScanHook();
+        this.artifact = await runCoreScan(this.opts.root, scanOpts, advanced);
+        writeScanCache(this.opts.root, cacheKey, this.artifact);
+      }
       this.publishScore();
       for (const uri of this.docs.keys()) this.publishForDoc(uri);
     } catch (err) {
@@ -1943,12 +2329,15 @@ var VibgrateLanguageServer = class {
       band,
       // v3 §2.4: `estimated` means "no timestamps at all" — it is NOT an
       // offline marker. An air-gapped scan against a dated snapshot is Verified.
-      mode: hasReleaseDates(a) ? "verified" : "estimated",
+      // The score now carries the authoritative provenance (driftscore-3.0
+      // envelope); fall back to the artifact heuristic for pre-v3 engines.
+      mode: a.drift.mode ?? (hasReleaseDates(a) ? "verified" : "estimated"),
       methodology: a.drift.methodologyVersion ?? "unknown",
       scale: "0 best, 100 worst",
       counts: { behind, eol, unmaintained, total },
       rootPath: a.rootPath,
-      scannedAt: a.timestamp
+      scannedAt: a.timestamp,
+      ...buildBreakdown(a.drift, a.projects ?? []) ? { breakdown: buildBreakdown(a.drift, a.projects ?? []) } : {}
     };
     this.conn.notify("vibgrate/score", payload);
   }
@@ -2009,8 +2398,9 @@ var VibgrateLanguageServer = class {
       (d) => findPackageLine(text, d.package, kind) === line
     );
     if (!dep) return null;
+    const contribution = a.drift.dependencyDrift?.top.find((t) => t.package === dep.package)?.drift ?? null;
     return {
-      contents: { kind: "markdown", value: hoverMarkdown(dep) }
+      contents: { kind: "markdown", value: hoverMarkdown(dep, contribution) }
     };
   }
   onCodeLens(params) {
@@ -2027,7 +2417,8 @@ var VibgrateLanguageServer = class {
     const eol = (a.findings ?? []).filter(
       (f) => f.ruleId === "vibgrate/runtime-eol" || f.ruleId === "vibgrate/eol"
     ).length;
-    const mode = hasReleaseDates(a) ? "" : "~";
+    const estimated = (a.drift.mode ?? (hasReleaseDates(a) ? "verified" : "estimated")) === "estimated";
+    const mode = estimated ? "~" : "";
     const title = `Vibgrate \xB7 drift ${mode}${a.drift.score} (${a.drift.riskLevel}) \xB7 ${behind} behind \xB7 ${eol} EOL`;
     return [
       {
@@ -2036,6 +2427,78 @@ var VibgrateLanguageServer = class {
       }
     ];
   }
+  // ── Graph ────────────────────────────────────────────────────────────────
+  /**
+   * Load the committed map if one exists, else build it once (this is the
+   * "first activation sets up the graph" step). Fire-and-forget from
+   * `initialized` so it never blocks the drift score; a query that arrives
+   * mid-build awaits the same in-flight promise via the `graphBuilding` guard.
+   */
+  async ensureGraph() {
+    if (!this.opts.graph) {
+      this.conn.notify("vibgrate/graph/status", { state: "disabled" });
+      return;
+    }
+    if (this.graph || this.graphBuilding) return;
+    this.graphBuilding = true;
+    try {
+      const existing = loadGraph(this.opts.root);
+      if (existing) {
+        this.graph = existing;
+        this.conn.notify("vibgrate/graph/status", { state: "ready" });
+        return;
+      }
+      this.conn.notify("vibgrate/graph/status", { state: "building" });
+      const result = await buildGraph({ root: this.opts.root });
+      writeArtifacts(result.graph, { root: this.opts.root, html: false, report: false });
+      writeSnapshot(this.opts.root, result.graph.provenance.corpusHash, result.fileStats, {});
+      this.graph = result.graph;
+      this.conn.notify("vibgrate/graph/status", { state: "ready" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.conn.notify("window/logMessage", { type: 3, message: `Vibgrate graph build failed: ${message}` });
+      this.conn.notify("vibgrate/graph/status", { state: "error", message });
+    } finally {
+      this.graphBuilding = false;
+    }
+  }
+  /** The graph, refreshed if the working tree drifted since the last build (same probe `vg ask` uses). */
+  async graphForQuery() {
+    await this.ensureGraph();
+    if (!this.graph) return null;
+    const refreshed = await refreshIfStale(this.opts.root);
+    if (refreshed.status === "refreshed" && refreshed.wrote) {
+      const reloaded = loadGraph(this.opts.root);
+      if (reloaded) this.graph = reloaded;
+    }
+    return this.graph;
+  }
+  async onGraphQuery(params) {
+    const p = params;
+    if (!this.opts.graph) {
+      return { ok: false, mode: p.mode, error: "disabled", message: "the local Vibgrate Graph is turned off" };
+    }
+    const graph = await this.graphForQuery();
+    if (!graph) {
+      return { ok: false, mode: p.mode, error: "not-found", message: "no code map yet \u2014 it is still building" };
+    }
+    return runGraphQuery(graph, p, { root: this.opts.root, offline: this.opts.offline, semantic: this.opts.semantic });
+  }
+  /**
+   * `vibgrate/enrich` — lazy vulnerability enrichment for one expanded package,
+   * straight from OSV.dev (never our API). Honours the server's offline flag.
+   */
+  onEnrich(params) {
+    const p = params ?? {};
+    return enrichVulns(p.ecosystem ?? null, p.package ?? "", p.version ?? null, { offline: this.opts.offline });
+  }
+  onScoreForFile(params) {
+    const p = params;
+    const a = this.artifact;
+    if (!a || !p.uri) return null;
+    const project = projectForFile(this.opts.root, a, uriToPath(p.uri));
+    return project ? scoreForProject(a, project) : null;
+  }
 };
 function uriToPath(uri) {
   try {
@@ -2068,6 +2531,99 @@ function hasReleaseDates(a) {
   }
   return false;
 }
+function scoreForProject(a, proj) {
+  if (!proj.drift) return null;
+  let behind = 0;
+  let total = 0;
+  for (const dep of proj.dependencies ?? []) {
+    total++;
+    if (dep.drift === "major-behind" || dep.drift === "minor-behind") behind++;
+  }
+  const projFindings = (a.findings ?? []).filter((f) => sameProject(f.location, proj.path));
+  const eol = projFindings.filter((f) => f.ruleId === "vibgrate/runtime-eol" || f.ruleId === "vibgrate/eol").length;
+  const unmaintained = projFindings.filter(
+    (f) => f.ruleId === "vibgrate/unmaintained" || f.ruleId === "vibgrate/abandoned"
+  ).length;
+  const hasDates = (proj.dependencies ?? []).some((d) => d.ageDays !== null && d.ageDays !== void 0);
+  return {
+    score: proj.drift.score,
+    band: proj.drift.riskLevel ?? "low",
+    mode: proj.drift.mode ?? (hasDates ? "verified" : "estimated"),
+    methodology: proj.drift.methodologyVersion ?? a.drift.methodologyVersion ?? "unknown",
+    scale: "0 best, 100 worst",
+    counts: { behind, eol, unmaintained, total },
+    rootPath: proj.path,
+    scannedAt: a.timestamp,
+    ...buildBreakdown(proj.drift, [proj]) ? { breakdown: buildBreakdown(proj.drift, [proj]) } : {}
+  };
+}
+function bandForScore(n) {
+  if (n <= 30) return "low";
+  if (n <= 60) return "moderate";
+  return "high";
+}
+function buildBreakdown(drift, projects) {
+  const top = drift.dependencyDrift?.top;
+  if (!top || top.length === 0) return void 0;
+  const byPkg = /* @__PURE__ */ new Map();
+  for (const p of projects) {
+    const ecosystem = osvEcosystem(p.type);
+    for (const d of p.dependencies ?? []) if (!byPkg.has(d.package)) byPkg.set(d.package, { row: d, ecosystem });
+  }
+  const items = top.filter((t) => t.drift > 0).map((t) => {
+    const found = byPkg.get(t.package);
+    const row = found?.row;
+    return {
+      package: t.package,
+      section: row?.section ?? "dependencies",
+      ecosystem: found?.ecosystem ?? null,
+      drift: t.drift,
+      band: bandForScore(t.drift),
+      currentSpec: row?.currentSpec ?? "",
+      resolvedVersion: row?.resolvedVersion ?? null,
+      latestStable: row?.latestStable ?? null,
+      majorsBehind: row?.majorsBehind ?? null,
+      ageDays: row?.ageDays ?? null,
+      mode: t.mode,
+      unsupported: t.unsupported,
+      abandoned: t.flags.includes("abandoned-floor"),
+      flags: t.flags
+    };
+  });
+  return items.length > 0 ? items : void 0;
+}
+function osvEcosystem(type) {
+  switch (type) {
+    case "node":
+    case "typescript":
+      return "npm";
+    case "python":
+      return "PyPI";
+    case "java":
+    case "kotlin":
+    case "scala":
+    case "groovy":
+      return "Maven";
+    case "go":
+      return "Go";
+    case "rust":
+      return "crates.io";
+    case "ruby":
+      return "RubyGems";
+    case "php":
+      return "Packagist";
+    case "dotnet":
+      return "NuGet";
+    case "dart":
+      return "Pub";
+    case "swift":
+      return "SwiftURL";
+    case "elixir":
+      return "Hex";
+    default:
+      return null;
+  }
+}
 function inlineLabel(dep) {
   const bits = [];
   if (dep.drift === "major-behind") {
@@ -2082,16 +2638,42 @@ function inlineLabel(dep) {
   }
   return bits.join(" \xB7 ");
 }
-function hoverMarkdown(dep) {
+function commandUri(command, args) {
+  return `command:${command}?${encodeURIComponent(JSON.stringify([args]))}`;
+}
+function driftBadge(dep) {
+  if (dep.drift === "major-behind") {
+    const n = dep.majorsBehind ?? 1;
+    return `${n} major${n === 1 ? "" : "s"} behind`;
+  }
+  if (dep.drift === "minor-behind") return "minor behind";
+  return null;
+}
+function versionJourney(yours, latest) {
+  const from = Number(/^(\d+)/.exec(yours)?.[1]);
+  const to = Number(/^(\d+)/.exec(latest)?.[1]);
+  if (!Number.isFinite(from) || !Number.isFinite(to) || to <= from) return null;
+  const majors = [];
+  for (let m = from; m <= to; m++) majors.push(m);
+  const shown = majors.length > 5 ? [majors[0], majors[1], -1, majors[majors.length - 2], majors[majors.length - 1]] : majors;
+  return shown.map((m) => m === -1 ? "\u2026" : `${m}.x`).join(" \u2192 ");
+}
+function hoverMarkdown(dep, contribution) {
   const lines = [];
-  lines.push(`**${dep.package}**`);
+  const badge = driftBadge(dep);
+  const contributionText = contribution != null ? ` \xB7 contributes +${Math.round(contribution)} to drift` : "";
+  lines.push(badge ? `**${dep.package}**  \`${badge}\`${contributionText}` : `**${dep.package}**`);
   lines.push("");
   const yours = dep.resolvedVersion ?? dep.currentSpec;
+  const drifted = dep.drift === "major-behind" || dep.drift === "minor-behind";
   if (dep.latestStable && dep.latestStable !== yours) {
+    lines.push("**Currency**");
     lines.push(`| | |`);
     lines.push(`|---|---|`);
     lines.push(`| yours | \`${yours}\` |`);
     lines.push(`| latest | \`${dep.latestStable}\` |`);
+    const journey = versionJourney(yours, dep.latestStable);
+    if (journey) lines.push(`| journey | ${journey} |`);
     if (dep.majorsBehind) lines.push(`| majors behind | ${dep.majorsBehind} |`);
     if (dep.ageDays != null && dep.ageDays >= 1) {
       lines.push(`| age | ${Math.round(dep.ageDays).toLocaleString("en-US")} days |`);
@@ -2104,12 +2686,31 @@ function hoverMarkdown(dep) {
   } else {
     lines.push(`\`${yours}\` \u2014 current.`);
   }
+  if (dep.unsupported || dep.abandoned) {
+    lines.push("");
+    lines.push("**Maintenance**");
+    if (dep.unsupported) lines.push("$(warning) Unsupported / deprecated \u2014 floored at 70.");
+    if (dep.abandoned) lines.push("$(warning) Abandoned \u2014 no recent releases \u2014 floored at 50.");
+  }
+  if (drifted) {
+    lines.push("");
+    lines.push("---");
+    const routeFixUri = commandUri("vibgrate.routeFix", {
+      package: dep.package,
+      from: yours,
+      to: dep.latestStable ?? yours,
+      majorsBehind: dep.majorsBehind ?? 0
+    });
+    const explainUri = commandUri("vibgrate.explain", { package: dep.package });
+    lines.push(`[Route this fix \u2192](${routeFixUri}) \xB7 [Explain this drift](${explainUri})`);
+  }
   lines.push("");
+  lines.push("---");
   lines.push("$(shield) Resolved locally from your lockfile. No source uploaded.");
   return lines.join("\n");
 }
 function startLanguageServer(opts) {
-  if (!fs7.existsSync(opts.root)) {
+  if (!fs8.existsSync(opts.root)) {
     process.stderr.write(`vg lsp: root does not exist: ${opts.root}
 `);
     process.exit(1);
@@ -2134,7 +2735,7 @@ function registerLsp(program) {
     "--diagnostics",
     "also publish Problems-panel diagnostics (EOL runtime, unmaintained, license change). Off by default: drift is not a defect, and the Problems panel is not ours to fill",
     false
-  ).action(async function(opts) {
+  ).option("--no-graph", "skip the local Vibgrate Graph entirely: no background build, and graph queries report it as turned off").option("--no-semantic", "never use semantic search for graph queries (lexical only; the embedding model is not downloaded)").action(async function(opts) {
     const global = readGlobal(this);
     const root = rootOf(global);
     startLanguageServer({
@@ -2142,7 +2743,9 @@ function registerLsp(program) {
       // `--local` is the established air-gap flag across the CLI; honour it
       // here too, so an offline editor session stays offline.
       offline: global.local === true,
-      diagnostics: opts.diagnostics === true
+      diagnostics: opts.diagnostics === true,
+      graph: opts.graph !== false,
+      semantic: opts.semantic !== false
     });
     await new Promise(() => {
     });
@@ -2153,10 +2756,25 @@ function registerLsp(program) {
 // src/commands/install.ts
 var SMALL_REPO_FILES = 150;
 function registerInstall(program) {
-  const install = program.command("install").description("add vg to your AI assistant(s): skill + MCP + advisory nudge").argument("[tools...]", `assistant ids: ${ASSISTANTS.map((a) => a.id).join(", ")}`).option("--all", "install for every supported assistant").option("--list", "show the support matrix and exit").option("--no-hook", "skip the advisory nudge").action(function(tools, opts) {
+  const install = program.command("install").description("add vg to your AI assistant(s): skill + MCP + advisory nudge").argument("[tools...]", `assistant ids: ${ASSISTANTS.map((a) => a.id).join(", ")}`).option("--all", "install for every supported assistant").option("--detect", "detect assistants in use (repo footprint, home config, PATH) and install for those; with --list, only report what was detected").option("--list", "show the support matrix and exit").option("--no-hook", "skip the advisory nudge").action(function(tools, opts) {
     const global = readGlobal(this);
     const root = rootOf(global);
+    const detected = opts.detect ? detectAssistants(root) : [];
     if (opts.list) {
+      if (opts.detect) {
+        if (global.json) {
+          json(detected.map((d) => ({ id: d.assistant.id, label: d.assistant.label, via: d.via, marker: d.marker })));
+        } else if (detected.length === 0) {
+          info(`${c.cyan("vg install")} \xB7 no AI assistants detected here`);
+        } else {
+          info(`${c.cyan("vg install")} \xB7 detected assistants`);
+          const pad4 = Math.max(...detected.map((d) => d.assistant.id.length)) + 2;
+          for (const d of detected) {
+            info(`  ${c.bold(d.assistant.id.padEnd(pad4))} ${d.assistant.label}  ${c.dim(`via ${d.via}: ${d.marker}`)}`);
+          }
+        }
+        return;
+      }
       if (global.json) {
         json(ASSISTANTS.map((a) => ({ id: a.id, label: a.label, mcp: !!a.mcp, skill: !!a.skill, nudge: !!a.nudge })));
       } else {
@@ -2168,8 +2786,15 @@ function registerInstall(program) {
       }
       return;
     }
-    const targets = opts.all ? ASSISTANTS : tools.map(resolve6);
-    if (targets.length === 0) throw usageError("name an assistant (e.g. `vg install claude`) or use --all / --list");
+    const targets = opts.all ? ASSISTANTS : opts.detect ? detected.map((d) => d.assistant) : tools.map(resolve6);
+    if (targets.length === 0) {
+      if (opts.detect) {
+        if (global.json) json({ root, detected: [], results: [] });
+        else info(`${c.cyan("vg install")} \xB7 no AI assistants detected here \u2014 name one (e.g. \`vg install claude\`) or use --all`);
+        return;
+      }
+      throw usageError("name an assistant (e.g. `vg install claude`) or use --all / --detect / --list");
+    }
     const graph = loadGraph(root, global.graph);
     const fileCount = graph ? graph.nodes.filter((n) => n.kind === "file").length : 0;
     const smallRepo = graph !== null && fileCount > 0 && fileCount < SMALL_REPO_FILES;
@@ -2224,7 +2849,7 @@ function registerShare(program) {
     const global = readGlobal(this);
     const root = rootOf(global);
     const gitDir = path.join(root, ".git");
-    if (!fs7.existsSync(gitDir)) {
+    if (!fs8.existsSync(gitDir)) {
       throw new CliError("not a git repository \u2014 run `vg share` inside a git repo", ExitCode.USAGE_ERROR);
     }
     if (opts.undo) {
@@ -2246,22 +2871,22 @@ function registerShare(program) {
 }
 function writeVibgrateGitignore(root, reports) {
   const dir = path.join(root, ".vibgrate");
-  fs7.mkdirSync(dir, { recursive: true });
+  fs8.mkdirSync(dir, { recursive: true });
   const lines = ["# Managed by `vg share` \u2014 keep graph.json committed, ignore the rest", "cache/", "facts.jsonl"];
   if (!reports) lines.push("graph.html", "GRAPH_REPORT.md");
-  fs7.writeFileSync(path.join(dir, ".gitignore"), `${lines.join("\n")}
+  fs8.writeFileSync(path.join(dir, ".gitignore"), `${lines.join("\n")}
 `);
 }
 function writeGitAttributes(root) {
   const file = path.join(root, ".gitattributes");
   const line = ".vibgrate/graph.json merge=vg";
-  let content = fs7.existsSync(file) ? fs7.readFileSync(file, "utf8") : "";
+  let content = fs8.existsSync(file) ? fs8.readFileSync(file, "utf8") : "";
   if (!content.split("\n").some((l) => l.trim() === line)) {
     content = content.length ? `${content.replace(/\s*$/, "")}
 ${line}
 ` : `${line}
 `;
-    fs7.writeFileSync(file, content);
+    fs8.writeFileSync(file, content);
   }
 }
 function configureMergeDriver(root) {
@@ -2270,7 +2895,7 @@ function configureMergeDriver(root) {
 }
 function installPreCommitHook(root) {
   const hooksDir = hookDir(root);
-  fs7.mkdirSync(hooksDir, { recursive: true });
+  fs8.mkdirSync(hooksDir, { recursive: true });
   const file = path.join(hooksDir, "pre-commit");
   const block = [
     HOOK_BEGIN,
@@ -2280,7 +2905,7 @@ function installPreCommitHook(root) {
     "fi",
     HOOK_END
   ].join("\n");
-  let content = fs7.existsSync(file) ? fs7.readFileSync(file, "utf8") : "#!/bin/sh\n";
+  let content = fs8.existsSync(file) ? fs8.readFileSync(file, "utf8") : "#!/bin/sh\n";
   const re = new RegExp(`${escapeRe(HOOK_BEGIN)}[\\s\\S]*?${escapeRe(HOOK_END)}`);
   if (re.test(content)) content = content.replace(re, block);
   else content = `${content.replace(/\s*$/, "")}
@@ -2289,21 +2914,21 @@ ${block}
 `;
   if (!content.startsWith("#!")) content = `#!/bin/sh
 ${content}`;
-  fs7.writeFileSync(file, content);
-  fs7.chmodSync(file, 493);
+  fs8.writeFileSync(file, content);
+  fs8.chmodSync(file, 493);
 }
 function undo(root) {
   const hookFile = path.join(hookDir(root), "pre-commit");
-  if (fs7.existsSync(hookFile)) {
+  if (fs8.existsSync(hookFile)) {
     const re = new RegExp(`\\n*${escapeRe(HOOK_BEGIN)}[\\s\\S]*?${escapeRe(HOOK_END)}\\n*`);
-    const next2 = fs7.readFileSync(hookFile, "utf8").replace(re, "\n");
-    if (next2.trim() === "#!/bin/sh") fs7.rmSync(hookFile);
-    else fs7.writeFileSync(hookFile, next2);
+    const next2 = fs8.readFileSync(hookFile, "utf8").replace(re, "\n");
+    if (next2.trim() === "#!/bin/sh") fs8.rmSync(hookFile);
+    else fs8.writeFileSync(hookFile, next2);
   }
   const attr = path.join(root, ".gitattributes");
-  if (fs7.existsSync(attr)) {
-    const next2 = fs7.readFileSync(attr, "utf8").split("\n").filter((l) => l.trim() !== ".vibgrate/graph.json merge=vg").join("\n");
-    fs7.writeFileSync(attr, next2);
+  if (fs8.existsSync(attr)) {
+    const next2 = fs8.readFileSync(attr, "utf8").split("\n").filter((l) => l.trim() !== ".vibgrate/graph.json merge=vg").join("\n");
+    fs8.writeFileSync(attr, next2);
   }
   try {
     git(root, ["config", "--remove-section", "merge.vg"]);
@@ -2436,7 +3061,7 @@ function grepBaselineTokens(term, files) {
     if (f.size > 512 * 1024) continue;
     let content = "";
     try {
-      content = fs7.readFileSync(f.abs, "utf8");
+      content = fs8.readFileSync(f.abs, "utf8");
     } catch {
       continue;
     }
@@ -2446,7 +3071,7 @@ function grepBaselineTokens(term, files) {
 }
 function safeSize(abs) {
   try {
-    return fs7.statSync(abs).size;
+    return fs8.statSync(abs).size;
   } catch {
     return 0;
   }
@@ -2768,9 +3393,9 @@ function normalizeStandards(raw) {
     const name = asString(r.name);
     if (!name) continue;
     const ecosystem = asString(r.ecosystem)?.toLowerCase();
-    const key = `${ecosystem ?? "*"}\0${name.toLowerCase()}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
+    const key2 = `${ecosystem ?? "*"}\0${name.toLowerCase()}`;
+    if (seen.has(key2)) continue;
+    seen.add(key2);
     banned.push({ name, ...ecosystem ? { ecosystem } : {}, ...asString(r.use) ? { use: asString(r.use) } : {}, ...asString(r.reason) ? { reason: asString(r.reason) } : {} });
   }
   return { banned };
@@ -2780,7 +3405,7 @@ function loadStandards(root) {
     const p = path__default.join(root, rel3);
     let text;
     try {
-      text = fs7__default.readFileSync(p, "utf8");
+      text = fs8__default.readFileSync(p, "utf8");
     } catch {
       continue;
     }
@@ -2948,7 +3573,7 @@ function printBreakdown(usage) {
   info(c.dim(`    avg success across commands: ${usage.avgSuccessPct}%`));
 }
 function printSplit(usage) {
-  const label = (key) => key === "mcp" ? "MCP tools" : key === "cli" ? "vg CLI" : key;
+  const label = (key2) => key2 === "mcp" ? "MCP tools" : key2 === "cli" ? "vg CLI" : key2;
   if (usage.sources.length) {
     info("");
     info(c.bold("  by source") + c.dim("  (how the call arrived)"));
@@ -3018,7 +3643,7 @@ async function addCmd(root, rest, opts, asJson) {
 }
 function readPackageVersion(root) {
   try {
-    const pkg = JSON.parse(fs7__default.readFileSync(path__default.join(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(fs8__default.readFileSync(path__default.join(root, "package.json"), "utf8"));
     return typeof pkg.version === "string" ? pkg.version : void 0;
   } catch {
     return void 0;
@@ -3026,7 +3651,7 @@ function readPackageVersion(root) {
 }
 function readOptionalFile(p) {
   try {
-    const t = fs7__default.readFileSync(p, "utf8");
+    const t = fs8__default.readFileSync(p, "utf8");
     return t.trim() ? t : void 0;
   } catch {
     return void 0;
@@ -3172,8 +3797,8 @@ function registerExport(program) {
       out(content.trimEnd());
       return;
     }
-    fs7.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
-    fs7.writeFileSync(file, content);
+    fs8.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    fs8.writeFileSync(file, content);
     info(`${c.green("\u2714")} wrote ${file} ${c.dim(`(${format})`)}`);
   });
   applyGlobalOptions(cmd);
@@ -3196,24 +3821,24 @@ function registerBundle(program) {
     } catch {
       throw new CliError("no grammars found to bundle (run a build first)", ExitCode.ERROR);
     }
-    fs7.mkdirSync(path.join(outDir, "grammars"), { recursive: true });
+    fs8.mkdirSync(path.join(outDir, "grammars"), { recursive: true });
     let grammarCount = 0;
     for (const { fileName, absPath } of grammarFiles) {
-      fs7.copyFileSync(absPath, path.join(outDir, "grammars", fileName));
+      fs8.copyFileSync(absPath, path.join(outDir, "grammars", fileName));
       grammarCount++;
     }
     const included = [`grammars/ (${grammarCount} .wasm)`];
     const graphSrc = global.graph ?? defaultGraphPath(root);
-    if (fs7.existsSync(graphSrc)) {
-      fs7.copyFileSync(graphSrc, path.join(outDir, "graph.json"));
+    if (fs8.existsSync(graphSrc)) {
+      fs8.copyFileSync(graphSrc, path.join(outDir, "graph.json"));
       included.push("graph.json");
     }
     const cat = catalogPath(root);
-    if (fs7.existsSync(cat)) {
-      fs7.copyFileSync(cat, path.join(outDir, "vibgrate.lib.json"));
+    if (fs8.existsSync(cat)) {
+      fs8.copyFileSync(cat, path.join(outDir, "vibgrate.lib.json"));
       included.push("vibgrate.lib.json");
-      if (fs7.existsSync(libDir(root))) {
-        fs7.cpSync(libDir(root), path.join(outDir, "lib"), { recursive: true });
+      if (fs8.existsSync(libDir(root))) {
+        fs8.cpSync(libDir(root), path.join(outDir, "lib"), { recursive: true });
         included.push("lib/");
       }
     }
@@ -3225,7 +3850,7 @@ function registerBundle(program) {
       included,
       usage: "Run `vg build --grammars <this dir>/grammars` to build fully offline."
     };
-    fs7.writeFileSync(path.join(outDir, "MANIFEST.json"), `${stableStringify(manifest, 2)}
+    fs8.writeFileSync(path.join(outDir, "MANIFEST.json"), `${stableStringify(manifest, 2)}
 `);
     if (global.json) {
       json({ out: path.relative(root, outDir), ...manifest });
@@ -3237,6 +3862,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");
@@ -3250,7 +3994,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-BTLZWSNS.js');
+    const { runBaseline } = await import('./baseline-DKPQWOQ6.js');
     await runBaseline(rootDir);
   }
   console.log("");
@@ -3360,9 +4104,9 @@ async function fileReferencesIdentifier(rootDir, relFile, identifier, readFile3)
 }
 async function defaultReadFile(absPath) {
   try {
-    const stat2 = await fs13.stat(absPath);
+    const stat2 = await fs15.stat(absPath);
     if (!stat2.isFile() || stat2.size > MAX_FILE_BYTES) return null;
-    return await fs13.readFile(absPath, "utf8");
+    return await fs15.readFile(absPath, "utf8");
   } catch {
     return null;
   }
@@ -3391,11 +4135,11 @@ async function analyzeReachability(input) {
   const importedModules = [];
   const seenPackages = /* @__PURE__ */ new Set();
   for (const dep of input.dependencies) {
-    const key = `${dep.ecosystem}|${dep.package}`;
-    if (seenPackages.has(key)) continue;
-    seenPackages.add(key);
+    const key2 = `${dep.ecosystem}|${dep.package}`;
+    if (seenPackages.has(key2)) continue;
+    seenPackages.add(key2);
     const evidence = collectPackageImports(input.graph, dep.ecosystem, dep.package);
-    evidenceByPackage.set(key, evidence);
+    evidenceByPackage.set(key2, evidence);
     if (evidence.supported && importedModules.length < MAX_IMPORTED_MODULE_PACKAGES) {
       importedModules.push({
         ecosystem: dep.ecosystem,
@@ -3410,8 +4154,8 @@ async function analyzeReachability(input) {
   );
   const findings = [];
   for (const entry of input.manifest) {
-    const key = `${entry.ecosystem}|${entry.package}`;
-    const evidence = evidenceByPackage.get(key) ?? collectPackageImports(input.graph, entry.ecosystem, entry.package);
+    const key2 = `${entry.ecosystem}|${entry.package}`;
+    const evidence = evidenceByPackage.get(key2) ?? collectPackageImports(input.graph, entry.ecosystem, entry.package);
     const baseConfidence = ECOSYSTEM_MATCH_CONFIDENCE[entry.ecosystem] ?? 0;
     if (!evidence.supported) {
       findings.push({
@@ -3509,9 +4253,9 @@ function collectPreflightDependencies(projects, projectTypeToEcosystem) {
     for (const dep of project.dependencies) {
       const version = dep.resolvedVersion || normalizeVersionSpec(dep.currentSpec);
       if (!version) continue;
-      const key = `${ecosystem}:${dep.package}:${version}`;
-      if (!deduped.has(key)) {
-        deduped.set(key, { ecosystem, package: dep.package, version });
+      const key2 = `${ecosystem}:${dep.package}:${version}`;
+      if (!deduped.has(key2)) {
+        deduped.set(key2, { ecosystem, package: dep.package, version });
       }
     }
   }
@@ -3986,7 +4730,7 @@ var WATCHED_FILES = /* @__PURE__ */ new Set([
   "packages.lock.json"
 ]);
 var WATCHED_EXT = /\.(cs|fs)proj$/i;
-var SKIP_DIRS = /* @__PURE__ */ new Set([
+var SKIP_DIRS2 = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
   "dist",
@@ -4007,7 +4751,7 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
 function scanStaleness(rootDir, artifactPath) {
   let ref;
   try {
-    ref = fs7.statSync(artifactPath).mtimeMs;
+    ref = fs8.statSync(artifactPath).mtimeMs;
   } catch {
     return { stale: false };
   }
@@ -4019,7 +4763,7 @@ function scanStaleness(rootDir, artifactPath) {
     if (depth > 8 || scanned > MAX_ENTRIES) return;
     let entries;
     try {
-      entries = fs7.readdirSync(dir, { withFileTypes: true });
+      entries = fs8.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -4027,14 +4771,14 @@ function scanStaleness(rootDir, artifactPath) {
       scanned++;
       if (scanned > MAX_ENTRIES) break;
       if (e.isDirectory()) {
-        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) walk2(path.join(dir, e.name), depth + 1);
+        if (!SKIP_DIRS2.has(e.name) && !e.name.startsWith(".")) walk2(path.join(dir, e.name), depth + 1);
         continue;
       }
       if (!WATCHED_FILES.has(e.name) && !WATCHED_EXT.test(e.name)) continue;
       const abs = path.join(dir, e.name);
       let mtimeMs;
       try {
-        mtimeMs = fs7.statSync(abs).mtimeMs;
+        mtimeMs = fs8.statSync(abs).mtimeMs;
       } catch {
         continue;
       }
@@ -4101,7 +4845,7 @@ function extractContracts(content, pkg, ecosystem) {
 }
 
 // src/reporting/planning/usage.ts
-var SKIP_DIRS2 = /* @__PURE__ */ new Set([
+var SKIP_DIRS3 = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
   "dist",
@@ -4168,7 +4912,7 @@ function analyzeTree(root, packages) {
     if (depth > MAX_DEPTH || filesSeen >= MAX_FILES) return;
     let entries;
     try {
-      entries = fs7.readdirSync(dir, { withFileTypes: true });
+      entries = fs8.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -4176,7 +4920,7 @@ function analyzeTree(root, packages) {
     for (const entry of entries) {
       if (filesSeen >= MAX_FILES) return;
       if (entry.isDirectory()) {
-        if (SKIP_DIRS2.has(entry.name) || entry.name.startsWith(".")) continue;
+        if (SKIP_DIRS3.has(entry.name) || entry.name.startsWith(".")) continue;
         walk2(path.join(dir, entry.name), depth + 1);
         continue;
       }
@@ -4186,8 +4930,8 @@ function analyzeTree(root, packages) {
       const full = path.join(dir, entry.name);
       let content;
       try {
-        if (fs7.statSync(full).size > MAX_FILE_BYTES2) continue;
-        content = fs7.readFileSync(full, "utf8");
+        if (fs8.statSync(full).size > MAX_FILE_BYTES2) continue;
+        content = fs8.readFileSync(full, "utf8");
       } catch {
         continue;
       }
@@ -4283,9 +5027,6 @@ function planBlock(plan, recommended) {
   if (plan.upgrades.length > shown.length) {
     lines.push(chalk8.dim(`      \u2026 and ${plan.upgrades.length - shown.length} more`));
   }
-  if (plan.upgrades.length === 0) {
-    lines.push(chalk8.dim("      (no upgrades in this plan)"));
-  }
   return lines.join("\n");
 }
 function dataNote(report) {
@@ -4312,9 +5053,15 @@ function renderText(report) {
     out2.push(chalk8.red(`\u26A0 ${report.exploitability.kevPackages} package(s) carry a KNOWN-EXPLOITED (KEV) advisory${epss} \u2014 prioritise these.`));
   }
   out2.push("");
-  for (const plan of report.plans) {
-    out2.push(planBlock(plan, plan.tier === report.recommended));
+  const visiblePlans = report.plans.filter((plan) => plan.upgrades.length > 0);
+  if (visiblePlans.length === 0) {
+    out2.push(chalk8.green("\u2714 Nothing to upgrade \u2014 every tracked dependency is current."));
     out2.push("");
+  } else {
+    for (const plan of visiblePlans) {
+      out2.push(planBlock(plan, plan.tier === report.recommended));
+      out2.push("");
+    }
   }
   out2.push(chalk8.bold("Recommendation"));
   out2.push(`  ${chalk8.green(report.plans.find((p) => p.tier === report.recommended)?.label ?? report.recommended)} \u2014 ${report.rationale}`);
@@ -4337,7 +5084,12 @@ function renderMarkdown(report) {
     out2.push(`_${report.vulnerabilityData === "unavailable" ? "Advisory data was unavailable \u2014 vulnerability impact is not shown." : "Advisory data was partial \u2014 some ecosystems were not checked."}_`);
   }
   out2.push("");
-  for (const plan of report.plans) {
+  const visiblePlans = report.plans.filter((plan) => plan.upgrades.length > 0);
+  if (visiblePlans.length === 0) {
+    out2.push("\u2714 Nothing to upgrade \u2014 every tracked dependency is current.");
+    out2.push("");
+  }
+  for (const plan of visiblePlans) {
     const rec = plan.tier === report.recommended ? " \u2705 **recommended**" : "";
     out2.push(`## ${plan.label}${rec}`);
     out2.push("");
@@ -4350,14 +5102,12 @@ function renderMarkdown(report) {
       out2.push(`- \u26A0 Introduces advisories in target versions: ${deltaSummary(plan.introduces)}`);
     }
     out2.push("");
-    if (plan.upgrades.length) {
-      out2.push("| Package | From | To | Kind | Reason |");
-      out2.push("|---|---|---|---|---|");
-      for (const u of plan.upgrades) {
-        out2.push(`| \`${u.package}\` | ${u.from ?? "?"} | ${u.to ?? "?"} | ${u.kind} | ${u.reason} |`);
-      }
-      out2.push("");
+    out2.push("| Package | From | To | Kind | Reason |");
+    out2.push("|---|---|---|---|---|");
+    for (const u of plan.upgrades) {
+      out2.push(`| \`${u.package}\` | ${u.from ?? "?"} | ${u.to ?? "?"} | ${u.kind} | ${u.reason} |`);
     }
+    out2.push("");
   }
   out2.push("## Recommendation");
   out2.push("");
@@ -4370,6 +5120,29 @@ function renderMarkdown(report) {
   return out2.join("\n");
 }
 
+// src/reporting/planning/dedupe.ts
+var TIER_ORDER = ["safe", "balanced", "aggressive"];
+function upgradeSetKey(plan) {
+  return plan.upgrades.map((u) => `${u.ecosystem}\0${u.package}\0${u.from ?? ""}\0${u.to ?? ""}`).sort().join("\n");
+}
+function dedupePlans(plans) {
+  const byTier = (plan) => {
+    const i = TIER_ORDER.indexOf(plan.tier);
+    return i === -1 ? TIER_ORDER.length : i;
+  };
+  const ordered = [...plans].sort((a, b) => byTier(a) - byTier(b));
+  const survivorByKey = /* @__PURE__ */ new Map();
+  const canonicalTier = /* @__PURE__ */ new Map();
+  for (const plan of ordered) {
+    const key2 = upgradeSetKey(plan);
+    const survivor = survivorByKey.get(key2) ?? plan;
+    if (!survivorByKey.has(key2)) survivorByKey.set(key2, plan);
+    canonicalTier.set(plan.tier, survivor.tier);
+  }
+  const survivors = new Set(survivorByKey.values());
+  return { plans: plans.filter((p) => survivors.has(p)), canonicalTier };
+}
+
 // src/reporting/planning/expected-drift.ts
 function estimateDriftScore(artifact, upgraded) {
   const projects = JSON.parse(JSON.stringify(artifact.projects ?? []));
@@ -4526,22 +5299,56 @@ async function fetchLatestVersion() {
 }
 async function writeCache(data) {
   try {
-    await fs13.mkdir(CACHE_DIR, { recursive: true });
-    await fs13.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 {
   }
 }
 
 // src/reporting/commands/update.ts
-function detectGlobalInstall() {
-  const execPath = process.argv[1] || "";
-  if (execPath.includes("/lib/node_modules/") || execPath.includes("\\node_modules\\")) {
-    if (!execPath.includes(process.cwd())) {
-      if (execPath.includes("pnpm")) return "pnpm";
-      if (execPath.includes("yarn")) return "yarn";
-      if (execPath.includes("bun")) return "bun";
-      return "npm";
+var PACKAGE_NAME = "@vibgrate/cli";
+function detectGlobalInstall(execPath = process.argv[1] || "", cwd = process.cwd()) {
+  if (!execPath) return null;
+  let resolved = execPath;
+  try {
+    resolved = fs8.realpathSync(execPath);
+  } catch {
+  }
+  const p = resolved.replace(/\\/g, "/");
+  if (!p.includes("/node_modules/")) return null;
+  if (p.includes("/_npx/") || p.includes("/dlx-") || p.includes("/.bunx/")) return null;
+  const workdir = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+  if (workdir && (p === workdir || p.startsWith(workdir + "/"))) return null;
+  if (p.includes("/pnpm/")) return "pnpm";
+  if (p.includes("/yarn/") || p.includes("/.yarn/")) return "yarn";
+  if (p.includes("/.bun/")) return "bun";
+  return "npm";
+}
+var defaultRunner = (cmd) => execSync(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 15e3 });
+async function findGlobalInstall(pkg = PACKAGE_NAME, run = defaultRunner) {
+  const tryRun = (cmd) => {
+    try {
+      const out2 = run(cmd).trim().split("\n")[0]?.trim();
+      return out2 || null;
+    } catch {
+      return null;
     }
+  };
+  const probes = [
+    { pm: "npm", root: () => tryRun("npm root -g") },
+    { pm: "pnpm", root: () => tryRun("pnpm root -g") },
+    {
+      pm: "yarn",
+      root: () => {
+        const dir = tryRun("yarn global dir");
+        return dir ? path.join(dir, "node_modules") : null;
+      }
+    },
+    { pm: "bun", root: () => path.join(os.homedir(), ".bun", "install", "global", "node_modules") }
+  ];
+  for (const probe of probes) {
+    const root = probe.root();
+    if (root && await pathExists(path.join(root, pkg))) return probe.pm;
   }
   return null;
 }
@@ -4591,15 +5398,16 @@ function getInstallCommand(pm, pkg, version, isDev, opts = {}) {
       return isDev ? `npm install --save-dev ${spec}` : `npm install ${spec}`;
   }
 }
-async function isDevDependency(cwd) {
+async function getLocalDependencyState(cwd, pkg = PACKAGE_NAME) {
   try {
     const pkgPath = path.join(cwd, "package.json");
     const raw = await (await import('fs/promises')).readFile(pkgPath, "utf-8");
-    const pkg = JSON.parse(raw);
-    return Boolean(pkg.devDependencies?.["@vibgrate/cli"]);
+    const parsed = JSON.parse(raw);
+    if (parsed.devDependencies?.[pkg]) return "dev";
+    if (parsed.dependencies?.[pkg]) return "prod";
   } catch {
-    return true;
   }
+  return null;
 }
 async function confirmWorkspaceRoot(pm) {
   if (!(process.stdin.isTTY && process.stdout.isTTY)) return false;
@@ -4632,15 +5440,29 @@ var updateCommand = new Command("update").description("Update vibgrate to the la
       return;
     }
     const cwd = process.cwd();
-    const globalPm = detectGlobalInstall();
-    const isGlobal = opts.global || globalPm !== null;
-    const pm = opts.pm || (globalPm ?? await detectPackageManager(cwd));
+    const runtimeGlobalPm = detectGlobalInstall();
+    let globalPm = runtimeGlobalPm;
+    let isGlobal = Boolean(opts.global) || runtimeGlobalPm !== null;
+    let localState = null;
+    if (!isGlobal) {
+      localState = await getLocalDependencyState(cwd);
+      if (localState === null) {
+        globalPm = await findGlobalInstall();
+        if (globalPm) {
+          isGlobal = true;
+          console.log(
+            chalk8.dim(`Found a global ${globalPm} installation of ${PACKAGE_NAME} \u2014 updating it instead of this project.`)
+          );
+        }
+      }
+    }
+    const pm = opts.pm || globalPm || await detectPackageManager(cwd);
     let cmd;
     if (isGlobal) {
-      cmd = getGlobalUpdateCommand(pm, "@vibgrate/cli", latest);
+      cmd = getGlobalUpdateCommand(pm, PACKAGE_NAME, latest);
       console.log(chalk8.dim(`Updating global installation with ${pm}: ${cmd}`));
     } else {
-      const isDev = await isDevDependency(cwd);
+      const isDev = localState !== "prod";
       let workspaceRoot = false;
       if (pm === "pnpm" && await detectWorkspaceRoot(cwd)) {
         console.log(
@@ -4648,19 +5470,19 @@ var updateCommand = new Command("update").description("Update vibgrate to the la
         );
         const proceed = opts.yes || opts.workspaceRoot || await confirmWorkspaceRoot(pm);
         if (!proceed) {
-          const rootCmd = getInstallCommand(pm, "@vibgrate/cli", latest, isDev, { workspaceRoot: true });
+          const rootCmd = getInstallCommand(pm, PACKAGE_NAME, latest, isDev, { workspaceRoot: true });
           console.log(chalk8.dim(`Skipped. To update the workspace root, run: ${rootCmd}`));
           console.log(chalk8.dim('or re-run "vg update --yes" (or --workspace-root) to let vg do it.'));
           return;
         }
         workspaceRoot = true;
       }
-      cmd = getInstallCommand(pm, "@vibgrate/cli", latest, isDev, { workspaceRoot });
+      cmd = getInstallCommand(pm, PACKAGE_NAME, latest, isDev, { workspaceRoot });
       console.log(chalk8.dim(`Using ${pm}: ${cmd}`));
     }
     try {
       execSync(cmd, { cwd, stdio: "inherit" });
-      console.log(chalk8.green("\u2714") + ` Updated to @vibgrate/cli@${latest}`);
+      console.log(chalk8.green("\u2714") + ` Updated to ${PACKAGE_NAME}@${latest}`);
     } catch {
       console.error(chalk8.red(`Update failed. Run manually: ${cmd}`));
       process.exit(1);
@@ -4684,11 +5506,11 @@ function collectCandidates(artifact) {
   for (const project of artifact.projects ?? []) {
     const ecosystem = ecosystemId(project.type);
     for (const dep of project.dependencies ?? []) {
-      const key = `${ecosystem}\0${dep.package}`;
-      if (seen.has(key)) continue;
+      const key2 = `${ecosystem}\0${dep.package}`;
+      if (seen.has(key2)) continue;
       if (!dep.latestStable || dep.latestStable === dep.resolvedVersion) continue;
       if (dep.drift === "current" || dep.drift === "unknown") continue;
-      seen.add(key);
+      seen.add(key2);
       out2.push({
         package: dep.package,
         ecosystem,
@@ -4826,6 +5648,9 @@ var fixCommand = new Command("fix").description("Get ranked, risk-tiered upgrade
     if (response.requestId) console.error(chalk8.dim(`  (ref ${response.requestId})`));
     process.exit(1);
   }
+  const { plans: dedupedPlans, canonicalTier } = dedupePlans(response.plans);
+  response.plans = dedupedPlans;
+  response.recommended = canonicalTier.get(response.recommended) ?? response.recommended;
   const currentDrift = artifact.drift?.score;
   if (typeof currentDrift === "number") {
     response.currentDriftScore = currentDrift;
@@ -4838,7 +5663,7 @@ var fixCommand = new Command("fix").description("Get ranked, risk-tiered upgrade
   }
   emit(response, opts.format);
   if (opts.format === "text" && opts.apply !== false) {
-    await runApplyFlow(rootDir, artifact, response, opts);
+    await runApplyFlow(rootDir, artifact, response, opts, canonicalTier);
   }
   if (failOn) {
     const recommended = response.plans.find((p) => p.tier === response.recommended);
@@ -4847,7 +5672,8 @@ var fixCommand = new Command("fix").description("Get ranked, risk-tiered upgrade
     for (const sev of Object.keys(SEVERITY_RANK)) {
       if (SEVERITY_RANK[sev] < threshold) continue;
       const open = response.unresolved.bySeverity[sev] ?? 0;
-      const notFixedByRecommended = (response.plans.find((p) => p.tier === "aggressive")?.fixes.bySeverity[sev] ?? 0) - (recommended?.fixes.bySeverity[sev] ?? 0);
+      const maxFixable = Math.max(0, ...response.plans.map((p) => p.fixes.bySeverity[sev] ?? 0));
+      const notFixedByRecommended = maxFixable - (recommended?.fixes.bySeverity[sev] ?? 0);
       stillOpen += open + Math.max(0, notFixedByRecommended);
     }
     if (stillOpen > 0) {
@@ -4904,8 +5730,8 @@ async function buildTargetResolver(rootDir, artifact) {
     const ecosystem = ecosystemId(project.type);
     const dir = relProjectDir(rootDir, project.path);
     for (const dep of project.dependencies ?? []) {
-      const key = `${ecosystem}\0${dep.package}`;
-      (owners.get(key) ?? owners.set(key, /* @__PURE__ */ new Set()).get(key)).add(dir);
+      const key2 = `${ecosystem}\0${dep.package}`;
+      (owners.get(key2) ?? owners.set(key2, /* @__PURE__ */ new Set()).get(key2)).add(dir);
     }
   }
   const rootFallback = [{ dir: ".", isWorkspaceRoot: rootIsWorkspace }];
@@ -4946,7 +5772,7 @@ function promptPlanSelection(response) {
     });
   });
 }
-async function runApplyFlow(rootDir, artifact, response, opts) {
+async function runApplyFlow(rootDir, artifact, response, opts, canonicalTier) {
   const nonEmpty = response.plans.filter((p) => p.upgrades.length > 0);
   if (nonEmpty.length === 0) {
     console.log(chalk8.green("\n\u2714 Nothing to upgrade \u2014 every tracked dependency is current."));
@@ -4954,7 +5780,8 @@ async function runApplyFlow(rootDir, artifact, response, opts) {
   }
   let chosen;
   if (opts.plan) {
-    chosen = response.plans.find((p) => p.tier === opts.plan);
+    const tier = canonicalTier?.get(opts.plan) ?? opts.plan;
+    chosen = response.plans.find((p) => p.tier === tier);
     if (!chosen) {
       console.error(chalk8.red(`Unknown plan '${opts.plan}'. Use safe, balanced, or aggressive.`));
       process.exit(1);
@@ -6199,21 +7026,21 @@ function formatDeltaText(base, current) {
   const added = [];
   const removed = [];
   const changed = [];
-  for (const [key, dep] of currentMap.entries()) {
-    if (!baseMap.has(key)) {
-      added.push(`${key} @ ${dep.resolvedVersion ?? dep.currentSpec}`);
+  for (const [key2, dep] of currentMap.entries()) {
+    if (!baseMap.has(key2)) {
+      added.push(`${key2} @ ${dep.resolvedVersion ?? dep.currentSpec}`);
       continue;
     }
-    const prev = baseMap.get(key);
+    const prev = baseMap.get(key2);
     const prevVersion = prev.resolvedVersion ?? prev.currentSpec;
     const nowVersion = dep.resolvedVersion ?? dep.currentSpec;
     if (prevVersion !== nowVersion || prev.majorsBehind !== dep.majorsBehind) {
-      changed.push(`${key} ${prevVersion} -> ${nowVersion} (majorsBehind ${prev.majorsBehind ?? "unknown"} -> ${dep.majorsBehind ?? "unknown"})`);
+      changed.push(`${key2} ${prevVersion} -> ${nowVersion} (majorsBehind ${prev.majorsBehind ?? "unknown"} -> ${dep.majorsBehind ?? "unknown"})`);
     }
   }
-  for (const [key, dep] of baseMap.entries()) {
-    if (!currentMap.has(key)) {
-      removed.push(`${key} @ ${dep.resolvedVersion ?? dep.currentSpec}`);
+  for (const [key2, dep] of baseMap.entries()) {
+    if (!currentMap.has(key2)) {
+      removed.push(`${key2} @ ${dep.resolvedVersion ?? dep.currentSpec}`);
     }
   }
   const lines = [
@@ -6300,6 +7127,7 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "oddities",
   "serve",
   "lsp",
+  "doctor",
   "install",
   "uninstall",
   "share",
@@ -6355,6 +7183,7 @@ ${aliasNote}Docs: https://vibgrate.com/help`;
   registerLib(program);
   registerExport(program);
   registerBundle(program);
+  registerDoctor(program);
   program.addCommand(initCommand);
   program.addCommand(scanCommand);
   program.addCommand(fixCommand);
@@ -6422,7 +7251,7 @@ function dispatch(argv, cwd) {
   }
   const looksLikeQuestion = /\s/.test(first) || first.endsWith("?");
   if (looksLikeQuestion) return ["ask", ...args];
-  if (fs7.existsSync(path.resolve(cwd, first))) {
+  if (fs8.existsSync(path.resolve(cwd, first))) {
     return [hasBuildOnlyFlag(args) ? "build" : "scan", ...args];
   }
   const moved = MOVED_COMMANDS[first];