@vibgrate/cli 2026.703.7 → 2026.704.3

package/dist/{chunk-WGXDYBAN.js → chunk-JL7FIC6W.js}

@@ -1,9 +1,10 @@
-import { langById, shortId, canonicalize, grammarSetVersion, hashBytes, hashString, langForExtension, setGrammarsOverride, parseSource } from './chunk-X5YT263H.js';
-import { writeTextFile, pathExists, readJsonFile, VERSION, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem } from './chunk-QWS7M7DG.js';
+import { hashString, langById, shortId, canonicalize, grammarSetVersion, hashBytes, langForExtension, setGrammarsOverride, parseSource } from './chunk-X5YT263H.js';
+import { writeTextFile, pathExists, readJsonFile, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem, VERSION } from './chunk-YN5OGRWU.js';
 import * as fs18 from 'fs';
 import { execFileSync } from 'child_process';
 import * as path18 from 'path';
 import ignore from 'ignore';
+import * as v8 from 'v8';
 import Graph from 'graphology';
 import pagerank from 'graphology-metrics/centrality/pagerank.js';
 import betweenness from 'graphology-metrics/centrality/betweenness.js';
@@ -45,47 +46,174 @@ function isOwnBinary(binPath) {
     return false;
   }
 }
+function isEphemeralNpxBinary(binPath) {
+  const NPX_SEGMENT = /[\\/]_npx[\\/]/;
+  if (NPX_SEGMENT.test(binPath)) return true;
+  try {
+    return NPX_SEGMENT.test(fs18.realpathSync(binPath));
+  } catch {
+    return false;
+  }
+}
+function isInstalledOwnBinary(binPath) {
+  return isOwnBinary(binPath) && !isEphemeralNpxBinary(binPath);
+}
 var cached;
 function resolveCliInvocation(which) {
   if (!which && cached !== void 0) return cached;
   const lookup = which ?? whichOnPath;
   const vg = lookup("vg");
   let result;
-  if (vg && isOwnBinary(vg)) {
+  if (vg && isInstalledOwnBinary(vg)) {
     result = "vg";
   } else {
     const vibgrate = lookup("vibgrate");
-    result = vibgrate && isOwnBinary(vibgrate) ? "vibgrate" : NPX_INVOCATION;
+    result = vibgrate && isInstalledOwnBinary(vibgrate) ? "vibgrate" : NPX_INVOCATION;
   }
   if (!which) cached = result;
   return result;
 }
 var SKIP_DIRS = /* @__PURE__ */ new Set([
+  // Version control, IDE & tool metadata
   ".git",
-  "node_modules",
+  ".svn",
+  ".hg",
+  ".idea",
+  ".vscode",
+  ".vs",
   ".vibgrate",
+  ".wrangler",
+  ".turbo",
+  ".cache",
+  // JavaScript / Node — installed dependency trees
+  "node_modules",
+  "bower_components",
+  "jspm_packages",
+  "web_modules",
+  ".pnpm-store",
+  ".yarn",
+  // JS/TS meta-framework & bundler build output
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  ".astro",
+  ".vercel",
+  ".netlify",
+  ".angular",
+  ".parcel-cache",
+  ".docusaurus",
+  "storybook-static",
+  // Generic build / dist / coverage output
   "dist",
   "build",
   "out",
   "coverage",
-  ".next",
-  ".nuxt",
-  ".svelte-kit",
-  ".turbo",
-  ".cache",
+  // Vendored third-party source trees
   "vendor",
-  "target",
-  // rust / java
-  "bin",
-  "obj",
-  // .NET
-  "__pycache__",
+  "Pods",
+  "Carthage",
+  // Python — virtualenvs & tool caches
   ".venv",
   "venv",
+  "virtualenv",
   ".tox",
+  ".nox",
+  "__pycache__",
+  ".mypy_cache",
+  ".pytest_cache",
+  ".ruff_cache",
+  ".eggs",
+  ".ipynb_checkpoints",
+  // Ruby
+  ".bundle",
+  // Rust / Maven / sbt / Clojure — all build into target/
+  "target",
+  // JVM (Gradle / Maven) & .NET build output
   ".gradle",
-  ".idea",
-  ".vscode"
+  "bin",
+  "obj",
+  "TestResults",
+  // Swift / Xcode
+  ".build",
+  ".swiftpm",
+  "DerivedData",
+  // Dart / Flutter
+  ".dart_tool",
+  // Elixir / Erlang
+  "_build",
+  "deps",
+  // Haskell (Cabal / Stack)
+  "dist-newstyle",
+  ".stack-work",
+  // Infrastructure-as-code build/state
+  ".terraform",
+  ".serverless",
+  "cdk.out",
+  ".aws-sam"
+]);
+var SKIP_FILES = /* @__PURE__ */ new Set([
+  // JavaScript / Node
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "bun.lockb",
+  "bun.lock",
+  "deno.lock",
+  ".pnp.cjs",
+  ".pnp.data.json",
+  ".pnp.loader.mjs",
+  // Python
+  "poetry.lock",
+  "pipfile.lock",
+  "pdm.lock",
+  "uv.lock",
+  "pylock.toml",
+  "conda-lock.yml",
+  // Ruby
+  "gemfile.lock",
+  // PHP
+  "composer.lock",
+  // Rust
+  "cargo.lock",
+  // Go
+  "go.sum",
+  "go.work.sum",
+  "gopkg.lock",
+  "glide.lock",
+  // .NET
+  "packages.lock.json",
+  // Java / JVM (Gradle)
+  "gradle.lockfile",
+  // Swift / Xcode
+  "package.resolved",
+  // Dart / Flutter
+  "pubspec.lock",
+  // Elixir
+  "mix.lock",
+  // Haskell (Cabal / Stack)
+  "cabal.project.freeze",
+  "stack.yaml.lock",
+  // Julia
+  "manifest.toml",
+  // R
+  "renv.lock",
+  // Perl (Carton)
+  "cpanfile.snapshot",
+  // CocoaPods / Carthage
+  "podfile.lock",
+  "cartfile.resolved",
+  // Terraform / IaC
+  ".terraform.lock.hcl",
+  // Helm
+  "chart.lock",
+  // C / C++ (Conan)
+  "conan.lock",
+  // Bazel
+  "module.bazel.lock",
+  // Nix
+  "flake.lock"
 ]);
 function toPosix(p) {
   return p.split(path18.sep).join("/");
@@ -115,6 +243,7 @@ function discover(options) {
     const rel2 = toPosix(path18.relative(root, abs));
     if (rel2.startsWith("..")) return;
     if (rel2 === "" || rootIg.ignores(rel2)) return;
+    if (SKIP_FILES.has(path18.basename(abs).toLowerCase())) return;
     const lang = langForExtension(path18.extname(abs));
     if (!lang || !allowLang(lang)) return;
     found.set(rel2, { rel: rel2, abs, lang });
@@ -152,6 +281,58 @@ var UsageError = class extends Error {
     this.name = "UsageError";
   }
 };
+var MIB = 1024 * 1024;
+var DEFAULT_MAX_FILE_BYTES = 2 * MIB;
+var DEFAULT_MAX_FILES = 1e5;
+var DEFAULT_TSC_MAX_FILES = 1e4;
+var HEAP_GUARD_FRACTION = 0.9;
+var ResourceLimitError = class extends Error {
+  isResourceLimitError = true;
+  constructor(message) {
+    super(message);
+    this.name = "ResourceLimitError";
+  }
+};
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+function envIntOptional(name) {
+  const n = envInt(name, 0);
+  return n > 0 ? n : void 0;
+}
+function defaultMemoryBudgetMb() {
+  return Math.floor(v8.getHeapStatistics().heap_size_limit / MIB * HEAP_GUARD_FRACTION);
+}
+function resolveLimits(overrides = {}) {
+  return {
+    maxFileBytes: overrides.maxFileBytes ?? envInt("VG_MAX_FILE_BYTES", DEFAULT_MAX_FILE_BYTES),
+    maxFiles: overrides.maxFiles ?? envInt("VG_MAX_FILES", DEFAULT_MAX_FILES),
+    tscMaxFiles: overrides.tscMaxFiles ?? envInt("VG_TSC_MAX_FILES", DEFAULT_TSC_MAX_FILES),
+    memoryBudgetMb: overrides.memoryBudgetMb ?? envInt("VG_MEMORY_BUDGET_MB", defaultMemoryBudgetMb())
+  };
+}
+function envJobs() {
+  return envIntOptional("VG_JOBS");
+}
+function envWorkerHeapMb() {
+  return envIntOptional("VG_WORKER_HEAP_MB");
+}
+function checkMemoryBudget(phase, budgetMb) {
+  if (budgetMb <= 0) return;
+  const usedMb = process.memoryUsage().heapUsed / MIB;
+  if (usedMb <= budgetMb) return;
+  throw new ResourceLimitError(
+    `graph build stopped during ${phase}: heap use ${Math.round(usedMb)} MiB exceeds the ${budgetMb} MiB budget. Narrow the build (scope to sub-paths, add --exclude globs, or --only <langs>), raise the Node heap (NODE_OPTIONS=--max-old-space-size=8192), or set VG_MEMORY_BUDGET_MB (0 disables this safeguard).`
+  );
+}
+function formatBytes(n) {
+  if (n >= MIB) return `${(n / MIB).toFixed(1)} MiB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  return `${n} B`;
+}
 var JS_TS_EXT = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 var OTHER_EXT = [
   ".py",
@@ -1293,18 +1474,18 @@ var DEFAULT_INLINE_THRESHOLD = 24;
 async function parseFiles(files, options = {}) {
   const threshold = options.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;
   const cores = Math.max(1, os.cpus()?.length ?? 1);
-  const jobs = Math.max(1, options.jobs ?? (Math.min(cores - 1, files.length) || 1));
+  const jobs = Math.max(1, options.jobs ?? envJobs() ?? (Math.min(cores - 1, files.length) || 1));
   const workerFile = resolveWorkerFile();
   const useInline = options.inline === true || jobs <= 1 || files.length < threshold || workerFile === null;
   if (useInline) {
     if (options.grammarsDir) setGrammarsOverride(options.grammarsDir);
-    return sortByRel(await parseInline(files, options.onProgress));
+    return sortByRel(await parseInline(files, options));
   }
-  return sortByRel(
-    await parsePooled(files, jobs, workerFile, options.onProgress, options.grammarsDir)
-  );
+  return sortByRel(await parsePooled(files, jobs, workerFile, options));
 }
-async function parseInline(files, onProgress) {
+var MEM_CHECK_EVERY = 64;
+async function parseInline(files, options) {
+  const { onProgress, memoryBudgetMb = 0 } = options;
   const out = [];
   onProgress?.(0, files.length);
   for (const file of files) {
@@ -1315,12 +1496,20 @@ async function parseInline(files, onProgress) {
       out.push(emptyParse(file, `parse failed: ${err.message}`));
     }
     onProgress?.(out.length, files.length);
+    if (out.length % MEM_CHECK_EVERY === 0) checkMemoryBudget("parse", memoryBudgetMb);
   }
   return out;
 }
-async function parsePooled(files, jobs, workerFile, onProgress, grammarsDir) {
+async function parsePooled(files, jobs, workerFile, options) {
+  const { onProgress, grammarsDir, memoryBudgetMb = 0 } = options;
   const { default: Tinypool } = await import('tinypool');
-  const pool = new Tinypool({ filename: workerFile, maxThreads: jobs, minThreads: 1 });
+  const workerHeapMb = envWorkerHeapMb();
+  const pool = new Tinypool({
+    filename: workerFile,
+    maxThreads: jobs,
+    minThreads: 1,
+    ...workerHeapMb ? { resourceLimits: { maxOldGenerationSizeMb: workerHeapMb } } : {}
+  });
   try {
     const total = files.length;
     const buckets = chunk(
@@ -1334,15 +1523,27 @@ async function parsePooled(files, jobs, workerFile, onProgress, grammarsDir) {
         (b) => pool.run({ tasks: b, grammarsDir }).then((r) => {
           done += b.length;
           onProgress?.(done, total);
+          checkMemoryBudget("parse", memoryBudgetMb);
           return r;
         })
       )
     );
     return results.flat();
+  } catch (err) {
+    if (isWorkerOom(err)) {
+      throw new ResourceLimitError(
+        `graph build stopped: a parse worker exceeded its ${workerHeapMb ?? "?"} MiB heap cap (VG_WORKER_HEAP_MB). Raise the cap, exclude the offending files (--exclude), or run single-threaded with --jobs 1.`
+      );
+    }
+    throw err;
   } finally {
     await pool.destroy();
   }
 }
+function isWorkerOom(err) {
+  const e = err;
+  return e?.code === "ERR_WORKER_OUT_OF_MEMORY" || /out of memory/i.test(e?.message ?? "");
+}
 function resolveWorkerFile() {
   const here = path18.dirname(fileURLToPath(import.meta.url));
   const candidate = path18.join(here, "parse-worker.js");
@@ -1845,6 +2046,13 @@ async function buildGraph(options) {
     exclude: options.exclude,
     paths: options.paths
   });
+  const limits = resolveLimits(options.limits);
+  if (limits.maxFiles > 0 && files.length > limits.maxFiles) {
+    throw new ResourceLimitError(
+      `graph build stopped: ${files.length.toLocaleString()} files exceed the ${limits.maxFiles.toLocaleString()}-file limit. Scope the build (pass sub-paths, add --exclude globs, or --only <langs>), or set VG_MAX_FILES to raise the limit (0 disables it).`
+    );
+  }
+  checkMemoryBudget("discovery", limits.memoryBudgetMb);
   const grammars = grammarSetVersion();
   const cache = loadCache(root, {
     toolVersion: VERSION,
@@ -1855,11 +2063,28 @@ async function buildGraph(options) {
   const fileStats = [];
   const toParse = [];
   const reused = [];
+  const buildWarnings = [];
   for (const file of files) {
-    let hash = "";
     let stat;
     try {
       stat = fs18.statSync(file.abs);
+    } catch {
+      continue;
+    }
+    if (limits.maxFileBytes > 0 && stat.size > limits.maxFileBytes) {
+      fileStats.push({
+        rel: file.rel,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        hash: hashString(`vg:oversize:${stat.size}`)
+      });
+      buildWarnings.push(
+        `${file.rel}: skipped \u2014 ${formatBytes(stat.size)} exceeds the ${formatBytes(limits.maxFileBytes)} per-file limit (set VG_MAX_FILE_BYTES to raise it, 0 to disable)`
+      );
+      continue;
+    }
+    let hash = "";
+    try {
       hash = hashBytes(fs18.readFileSync(file.abs));
     } catch {
       continue;
@@ -1874,8 +2099,10 @@ async function buildGraph(options) {
     jobs: options.jobs,
     inline: options.inline,
     onProgress: options.onParseProgress,
-    grammarsDir: options.grammarsDir
+    grammarsDir: options.grammarsDir,
+    memoryBudgetMb: limits.memoryBudgetMb
   });
+  checkMemoryBudget("parse", limits.memoryBudgetMb);
   for (const p of parsedNew) cache.set(p.rel, p);
   const currentRels = new Set(files.map((f) => f.rel));
   cache.prune(currentRels);
@@ -1883,14 +2110,21 @@ async function buildGraph(options) {
   const parses = [...reused, ...parsedNew].sort(
     (a, b) => a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0
   );
-  const warnings = parses.flatMap((p) => p.warnings ?? []);
+  const warnings = [...buildWarnings, ...parses.flatMap((p) => p.warnings ?? [])];
   const moduleResolver = buildModuleResolver(root, new Set(parses.map((p) => p.rel)));
   const resolved = resolve4(parses, moduleResolver);
+  checkMemoryBudget("resolve", limits.memoryBudgetMb);
   const nodeFileById = new Map(resolved.nodes.map((n) => [n.id, n.file]));
   let edges = resolved.edges;
   const resolvers = [...resolved.stats.resolvers];
   let tscStats;
-  const tsFiles = options.noTsc ? [] : files.filter((f) => f.lang.id === "ts" || f.lang.id === "tsx" || f.lang.id === "js").map((f) => ({ rel: f.rel, abs: f.abs }));
+  let tsFiles = options.noTsc ? [] : files.filter((f) => (f.lang.id === "ts" || f.lang.id === "tsx" || f.lang.id === "js") && hashes.has(f.rel)).map((f) => ({ rel: f.rel, abs: f.abs }));
+  if (limits.tscMaxFiles > 0 && tsFiles.length > limits.tscMaxFiles) {
+    warnings.push(
+      `typescript resolver skipped \u2014 ${tsFiles.length.toLocaleString()} TS/JS files exceed the ${limits.tscMaxFiles.toLocaleString()}-file limit; calls use the heuristic resolver (set VG_TSC_MAX_FILES to raise it, 0 to disable)`
+    );
+    tsFiles = [];
+  }
   if (tsFiles.length) {
     const res = tsResolveEdges(root, tsFiles, resolved.nodes);
     if (res.stats.files > 0) {
@@ -1898,6 +2132,7 @@ async function buildGraph(options) {
       if (!resolvers.includes("tsc")) resolvers.unshift("tsc");
       tscStats = res.stats;
     }
+    checkMemoryBudget("typescript resolution", limits.memoryBudgetMb);
   }
   const scip = options.noScip ? null : loadScipIndex(root, options.scip);
   let scipStats;
@@ -1912,6 +2147,7 @@ async function buildGraph(options) {
   const coverage = options.noCoverage ? null : loadCoverage(root, options.coverage);
   if (coverage) nodes = applyCoverage(nodes, coverage);
   const analysis = analyze(nodes, linked.edges, { cluster: options.cluster });
+  checkMemoryBudget("analysis", limits.memoryBudgetMb);
   const languages = [...new Set(parses.map((p) => p.lang))].sort();
   const edgeKinds = [...new Set(analysis.edges.map((e) => e.kind))].sort();
   const corpusHash = computeCorpusHash(parses, hashes);
@@ -5173,33 +5409,144 @@ function boundList(items, max) {
   return { items: items.slice(0, max), total: items.length };
 }
 var NODE_EDGE_CAP = 50;
+var IGNORE_DIRS = /* @__PURE__ */ new Set([".git", ".vibgrate", "node_modules", "dist", "build", "out", "target", "vendor", "__pycache__"]);
+var MAX_FILE_BYTES = 1e6;
+var MAX_FILES_SCANNED = 2e4;
+var PREVIEW_CHARS = 120;
+function searchSymbols(graph, root, query, limit) {
+  const q2 = query.trim();
+  if (!q2) return { matches: [], moreAvailable: false, hint: "query is required" };
+  const nodes = findNodes(graph, q2).filter((n) => n.kind !== "file");
+  const symbolHits = nodes.slice(0, limit).map((n, i) => ({
+    kind: n.kind,
+    name: n.qualifiedName,
+    file: n.file,
+    line: n.span.start,
+    score: Math.round((1 - i / Math.max(nodes.length, 1)) * 100) / 100
+  }));
+  const spare = limit - symbolHits.length;
+  const textHits = [];
+  let truncatedScan = false;
+  if (spare > 0) {
+    const seen = new Set(symbolHits.map((h) => `${h.file}:${h.line}`));
+    truncatedScan = scanFiles(root, q2, spare, seen, textHits);
+  }
+  const matches = [...symbolHits, ...textHits];
+  if (matches.length === 0) {
+    return {
+      matches,
+      moreAvailable: false,
+      hint: "no symbol or text match \u2014 for meaning-level questions (symptoms, relationships, what-breaks-if) use query_graph"
+    };
+  }
+  return { matches, moreAvailable: nodes.length > symbolHits.length || truncatedScan };
+}
+function scanFiles(root, needle, budget, seen, out) {
+  const lower = needle.toLowerCase();
+  let scanned = 0;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs18.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (e.name.startsWith(".") || IGNORE_DIRS.has(e.name)) continue;
+      const abs = path18.join(dir, e.name);
+      if (e.isDirectory()) {
+        stack.push(abs);
+        continue;
+      }
+      if (++scanned > MAX_FILES_SCANNED) return true;
+      let text;
+      try {
+        if (fs18.statSync(abs).size > MAX_FILE_BYTES) continue;
+        text = fs18.readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      if (!text.toLowerCase().includes(lower)) continue;
+      const rel2 = path18.relative(root, abs);
+      const lines = text.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].toLowerCase().includes(lower)) continue;
+        const key = `${rel2}:${i + 1}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ kind: "text", file: rel2, line: i + 1, preview: lines[i].trim().slice(0, PREVIEW_CHARS) });
+        if (out.length >= budget) return true;
+      }
+    }
+  }
+  return false;
+}
 
 // src/mcp/tools.ts
-var embedderPromise;
-function sharedEmbedder(local) {
-  if (!embedderPromise) embedderPromise = loadEmbedder({ local });
-  return embedderPromise;
+var warmEmbedder = null;
+var bgWarmStarted = false;
+function warmEmbedderInBackground(local) {
+  if (local || bgWarmStarted || isModelReady()) return;
+  bgWarmStarted = true;
+  loadEmbedder({}).then((e) => {
+    if (e) warmEmbedder = Promise.resolve(e);
+  }).catch(() => {
+    bgWarmStarted = false;
+  });
 }
+function readyEmbedder(local) {
+  if (warmEmbedder) return warmEmbedder;
+  if (local) return warmEmbedder = loadEmbedder({ local, noDownload: true });
+  if (isModelReady()) return warmEmbedder = loadEmbedder({ noDownload: true });
+  warmEmbedderInBackground(local);
+  return Promise.resolve(null);
+}
+async function retrieve(graph, question, budget, ctx) {
+  let mode = "lexical";
+  try {
+    const q2 = await withTimeout(
+      (async () => {
+        const embedder = await readyEmbedder(ctx.local);
+        if (!embedder) return null;
+        const nodeVectors = await getNodeEmbeddings(graph, embedder, ctx.root);
+        const r = await queryGraphSemantic(graph, question, { budget, embedder, nodeVectors });
+        mode = `semantic (${embedder.id})`;
+        return r;
+      })(),
+      SEMANTIC_BUDGET_MS,
+      "semantic path over budget"
+    );
+    if (q2) return { q: q2, mode };
+  } catch {
+  }
+  return { q: queryGraph(graph, question, { budget }), mode: "lexical" };
+}
+var SEMANTIC_BUDGET_MS = (() => {
+  const n = Number(process.env.VG_SEMANTIC_BUDGET_MS);
+  return Number.isFinite(n) && n > 0 ? n : 4e3;
+})();
 var obj = (properties, required = []) => ({
   type: "object",
   properties,
-  required,
+  ...required.length ? { required } : {},
   additionalProperties: false
 });
+var RESPONSE_FORMAT = { type: "string", enum: ["concise", "detailed"] };
+var isDetailed = (args) => args.response_format === "detailed";
+var CONCISE_MATCHES = 5;
 var TOOLS = [
-  {
-    name: "get_graph_summary",
-    description: "High-level summary of the code map: counts, languages, clustering, top areas and hubs.",
-    inputSchema: obj({}),
-    handler: (graph) => summarize(graph)
-  },
   {
     name: "orient",
-    description: "ONE-SHOT orientation before changing code: the map summary + the most relevant nodes for your question + the blast radius of the top hit, in a single call. Prefer this over separate get_graph_summary + query_graph + impact_of \u2014 same answer, far fewer round-trips (each round-trip re-bills the whole conversation).",
+    description: "Start here: one call returns the map overview, ranked matches for your question, and the top hit\u2019s blast radius \u2014 replaces summary+query+impact round-trips.",
     inputSchema: obj(
       {
-        question: { type: "string", description: "what you are about to do or look for" },
-        budget: { type: "number", description: "approx token budget for the context block (default 1500)" }
+        question: { type: "string", maxLength: 300 },
+        scope: { type: "string", description: "path prefix to orient within" },
+        budget: { type: "number", description: "token budget in detailed mode (default 1500)" },
+        response_format: RESPONSE_FORMAT
       },
       ["question"]
     ),
@@ -5207,67 +5554,93 @@ var TOOLS = [
       const question = String(args.question ?? "");
       if (!question) return { error: "bad_request", message: "question is required" };
       const budget = numOr(args.budget, 1500);
-      const embedder = await sharedEmbedder(ctx.local);
-      let q2;
-      let mode = "lexical";
-      if (embedder) {
-        const nodeVectors = await getNodeEmbeddings(graph, embedder, ctx.root);
-        q2 = await queryGraphSemantic(graph, question, { budget, embedder, nodeVectors });
-        mode = `semantic (${embedder.id})`;
-      } else {
-        q2 = queryGraph(graph, question, { budget });
-      }
+      const { q: q2, mode } = await retrieve(graph, question, budget, ctx);
+      const rawScope = String(args.scope ?? "").trim();
+      const scope = rawScope === "." || rawScope === "./" ? "" : rawScope.replace(/^\.\//, "");
+      const scoped = scope ? q2.matches.filter((m) => m.node.file.startsWith(scope)) : q2.matches;
+      const detailed = isDetailed(args);
       let topImpact = null;
-      const top = q2.matches[0]?.node;
-      if (top) {
+      const top = scoped[0]?.node;
+      if (detailed && top) {
         const r = impactOf(graph, top.id, { depth: 3 });
         topImpact = { node: top.qualifiedName, direct: r.direct, transitive: r.transitive, affected: r.affected.slice(0, 10).map(stripId) };
       }
+      const shown = detailed ? scoped : scoped.slice(0, CONCISE_MATCHES);
       return {
-        summary: summarize(graph),
+        summary: summarize(graph, detailed ? 10 : CONCISE_MATCHES),
         mode,
-        context: q2.context,
-        matches: q2.matches.map((m) => ({ name: m.node.qualifiedName, kind: m.node.kind, file: m.node.file, line: m.node.span.start, score: m.score })),
-        topImpact
+        // The fact-annotated context block is detail: concise callers navigate
+        // by the ranked matches and fetch nodes on demand (plan P2).
+        ...detailed ? { context: q2.context } : {},
+        matches: shown.map((m) => ({ name: m.node.qualifiedName, kind: m.node.kind, file: m.node.file, line: m.node.span.start, score: m.score })),
+        // A neutral availability flag, not a directive to keep querying: a
+        // retrieval tool that coaches "narrow the question / see more" nudges the
+        // over-navigation that re-bills the whole context on every extra step.
+        ...scoped.length > shown.length ? { moreAvailable: true } : {},
+        ...detailed ? { topImpact } : {}
       };
     }
   },
+  {
+    name: "search_symbols",
+    description: "Find a known name or string fast: ranked symbol lookup with literal file-search fallthrough. Use first for most discovery; use query_graph for meaning.",
+    inputSchema: obj(
+      {
+        query: { type: "string", maxLength: 120 },
+        limit: { type: "number", description: "default 8, max 20" }
+      },
+      ["query"]
+    ),
+    handler: (graph, args, ctx) => {
+      const limit = Math.min(20, numOr(args.limit, 8));
+      return searchSymbols(graph, ctx.root, String(args.query ?? ""), limit);
+    }
+  },
   {
     name: "query_graph",
-    description: "Ask the map a natural-language question; returns a budget-bounded, fact-annotated context block plus ranked matches.",
+    description: "Find code by meaning when you don\u2019t know the name: symptoms, relationships, what-breaks-if. For a known name or literal string use search_symbols.",
     inputSchema: obj(
       {
-        question: { type: "string", description: "the question" },
-        budget: { type: "number", description: "approx token budget (default 2000)" }
+        question: { type: "string", maxLength: 300 },
+        limit: { type: "number", description: "ranked matches to return (default 5)" },
+        offset: { type: "number" },
+        budget: { type: "number", description: "context-block token budget in detailed mode (default 2000)" },
+        response_format: RESPONSE_FORMAT
       },
       ["question"]
     ),
     handler: async (graph, args, ctx) => {
       const question = String(args.question ?? "");
       const budget = numOr(args.budget, 2e3);
-      let r;
-      let mode = "lexical";
-      const embedder = await sharedEmbedder(ctx.local);
-      if (embedder) {
-        const nodeVectors = await getNodeEmbeddings(graph, embedder, ctx.root);
-        r = await queryGraphSemantic(graph, question, { budget, embedder, nodeVectors });
-        mode = `semantic (${embedder.id})`;
-      } else {
-        r = queryGraph(graph, question, { budget });
+      const { q: r, mode } = await retrieve(graph, question, budget, ctx);
+      if (r.matches.length === 0) {
+        return { mode, matches: [], hint: "no semantic match \u2014 for a known name or literal string use search_symbols; otherwise rephrase around the behaviour you observe" };
       }
+      const limit = numOr(args.limit, CONCISE_MATCHES);
+      const offset = Math.max(0, numOrU(args.offset) ?? 0);
+      const page = r.matches.slice(offset, offset + limit);
       return {
         mode,
-        context: r.context,
-        tokensEstimate: r.tokensEstimate,
-        matches: r.matches.map((m) => ({ name: m.node.qualifiedName, kind: m.node.kind, file: m.node.file, line: m.node.span.start, score: m.score }))
+        summary: `${r.matches.length} match${r.matches.length === 1 ? "" : "es"}; top: ${r.matches[0].node.qualifiedName}`,
+        // The fact-annotated context block is detail (plan P2): ranked matches
+        // first, fetch nodes on demand.
+        ...isDetailed(args) ? { context: r.context, tokensEstimate: r.tokensEstimate } : {},
+        matches: page.map((m) => ({ name: m.node.qualifiedName, kind: m.node.kind, file: m.node.file, line: m.node.span.start, score: m.score })),
+        // Neutral pagination fact (nextOffset if the model genuinely needs more),
+        // not a "narrow the question" nudge that invites another discovery round.
+        ...offset + page.length < r.matches.length ? { moreAvailable: true, nextOffset: offset + page.length } : {}
       };
     }
   },
   {
     name: "get_node",
-    description: "Explain a node: kind, signature, callers, callees, area, importance. Resolves by qualified/short name, file:line, glob, or id.",
+    description: "Inspect one symbol: signature, callers, callees, area. Accepts name, file:line, glob or id.",
     inputSchema: obj(
-      { name: { type: "string" }, pick: { type: "number", description: "choose nth candidate when ambiguous" } },
+      {
+        name: { type: "string" },
+        pick: { type: "number", description: "nth candidate if ambiguous" },
+        response_format: RESPONSE_FORMAT
+      },
       ["name"]
     ),
     handler: (graph, args, ctx) => {
@@ -5287,8 +5660,9 @@ var TOOLS = [
       if (ctx?.dedup && ctx.seen?.has(node.id)) {
         return { ...base, repeat: true, callsTotal: uniqueNames(index.callees(node.id).map((x) => x.node.qualifiedName)).length, calledByTotal: uniqueNames(index.callers(node.id).map((x) => x.node.qualifiedName)).length };
       }
-      const calls = boundList(uniqueNames(index.callees(node.id).map((x) => x.node.qualifiedName)), NODE_EDGE_CAP);
-      const calledBy = boundList(uniqueNames(index.callers(node.id).map((x) => x.node.qualifiedName)), NODE_EDGE_CAP);
+      const edgeCap = isDetailed(args) ? NODE_EDGE_CAP : CONCISE_MATCHES;
+      const calls = boundList(uniqueNames(index.callees(node.id).map((x) => x.node.qualifiedName)), edgeCap);
+      const calledBy = boundList(uniqueNames(index.callers(node.id).map((x) => x.node.qualifiedName)), edgeCap);
       ctx?.seen?.add(node.id);
       return {
         ...base,
@@ -5301,13 +5675,13 @@ var TOOLS = [
   },
   {
     name: "find_path",
-    description: "Shortest connection between two nodes (how A reaches B).",
+    description: "Shortest connection from a to b.",
     inputSchema: obj(
       {
         a: { type: "string" },
         b: { type: "string" },
-        pick_a: { type: "number", description: "choose nth candidate for a when ambiguous" },
-        pick_b: { type: "number", description: "choose nth candidate for b when ambiguous" }
+        pick_a: { type: "number" },
+        pick_b: { type: "number" }
       },
       ["a", "b"]
     ),
@@ -5324,25 +5698,76 @@ var TOOLS = [
   },
   {
     name: "impact_of",
-    description: "What breaks if a node changes: the reverse-reachability blast radius with per-result depth and confidence.",
+    description: "Blast radius of a change: what breaks if this symbol changes \u2014 dependents, files, covering tests, risk.",
     inputSchema: obj(
       {
         name: { type: "string" },
-        depth: { type: "number", description: "max depth (default 4)" },
-        pick: { type: "number", description: "choose nth candidate when ambiguous" }
+        change_type: { type: "string", enum: ["modify", "delete", "rename", "add_dependency"] },
+        depth: { type: "number", description: "default 4" },
+        pick: { type: "number", description: "nth candidate if ambiguous" },
+        response_format: RESPONSE_FORMAT
       },
       ["name"]
     ),
     handler: (graph, args) => {
       const { node, candidates } = resolveOne(graph, String(args.name ?? ""), numOrU(args.pick));
       if (!node) return unresolved(candidates);
+      const changeType = ["modify", "delete", "rename", "add_dependency"].includes(String(args.change_type)) ? String(args.change_type) : "modify";
       const r = impactOf(graph, node.id, { depth: numOr(args.depth, 4) });
-      return { root: r.root.name, direct: r.direct, transitive: r.transitive, affected: r.affected.slice(0, 100).map(stripId) };
+      const tests = coveringTests(graph, node);
+      const filesAffected = [...new Set(r.affected.map((a) => a.file))];
+      const heavyChange = changeType === "delete" || changeType === "rename";
+      const riskLevel = node.isHub || r.direct >= 10 || r.transitive >= 50 || heavyChange && r.direct >= 3 ? "high" : r.direct >= 3 || r.transitive >= 10 ? "medium" : "low";
+      const summary = `${changeType} ${r.root.name}: ${r.direct} direct dependent${r.direct === 1 ? "" : "s"}, ${r.transitive} transitive across ${filesAffected.length} file${filesAffected.length === 1 ? "" : "s"}; ${tests.length} covering test${tests.length === 1 ? "" : "s"} \u2014 ${riskLevel} risk.`;
+      return {
+        root: r.root.name,
+        changeType,
+        directCallers: r.direct,
+        transitiveCount: r.transitive,
+        filesAffected: filesAffected.slice(0, 20),
+        testsAffected: tests.length,
+        riskLevel,
+        summary,
+        // The full row set is detail; concise callers act on the contract above.
+        ...isDetailed(args) ? { affected: r.affected.slice(0, 100).map(stripId) } : r.affected.length > 0 ? { hint: 'response_format:"detailed" lists the affected nodes' } : {}
+      };
     }
   },
+  {
+    name: "tests_for",
+    description: "Which tests cover this symbol \u2014 is a change here tested?",
+    inputSchema: obj(
+      {
+        name: { type: "string" },
+        pick: { type: "number", description: "nth candidate if ambiguous" },
+        response_format: RESPONSE_FORMAT
+      },
+      ["name"]
+    ),
+    handler: (graph, args) => {
+      const { node, candidates } = resolveOne(graph, String(args.name ?? ""), numOrU(args.pick));
+      if (!node) return unresolved(candidates);
+      const covers = coveringTests(graph, node);
+      return {
+        node: node.qualifiedName,
+        tested: node.tested,
+        coverage: node.coverage ?? null,
+        testCount: covers.length,
+        covers: isDetailed(args) ? covers : covers.slice(0, 10),
+        ...covers.length > 10 && !isDetailed(args) ? { moreAvailable: true } : {},
+        ...covers.length === 0 ? { hint: "no covering tests found \u2014 a change here lands untested" } : {}
+      };
+    }
+  },
+  {
+    name: "get_graph_summary",
+    description: "Code map overview: counts, languages, top areas and hubs.",
+    inputSchema: obj({}),
+    handler: (graph) => summarize(graph)
+  },
   {
     name: "list_areas",
-    description: "The natural code groupings (communities), each labelled, sized, with cohesion.",
+    description: "Code areas (communities) by size.",
     inputSchema: obj({ limit: { type: "number" } }),
     // Strip `members` (raw content-hash id arrays): a model cannot use them and
     // on a large repo they ballooned this result past 20k tokens.
@@ -5350,23 +5775,13 @@ var TOOLS = [
   },
   {
     name: "list_hubs",
-    description: "The most-depended-on code (centrality outliers).",
+    description: "Most-depended-on symbols.",
     inputSchema: obj({ limit: { type: "number" } }),
     handler: (graph, args) => graph.nodes.filter((n) => n.kind !== "file" && n.kind !== "external").sort((a, b) => b.importance - a.importance).slice(0, numOr(args.limit, 20)).map((n) => ({ name: n.qualifiedName, kind: n.kind, file: n.file, line: n.span.start, importance: n.importance, isHub: n.isHub }))
   },
-  {
-    name: "tests_for",
-    description: "Which tests cover a node (static call linkage + runtime coverage), with the linkage basis.",
-    inputSchema: obj({ name: { type: "string" }, pick: { type: "number", description: "choose nth candidate when ambiguous" } }, ["name"]),
-    handler: (graph, args) => {
-      const { node, candidates } = resolveOne(graph, String(args.name ?? ""), numOrU(args.pick));
-      if (!node) return unresolved(candidates);
-      return { node: node.qualifiedName, tested: node.tested, coverage: node.coverage ?? null, covers: coveringTests(graph, node) };
-    }
-  },
   {
     name: "get_facts",
-    description: "The deterministic open facts for a node (contract/invariant/characterization). Requires a --deep build.",
+    description: "Deterministic facts for a node (contract/invariant); needs a --deep build.",
     inputSchema: obj({ name: { type: "string" } }, ["name"]),
     handler: (graph, args) => {
       const { node, candidates } = resolveOne(graph, String(args.name ?? ""));
@@ -5377,7 +5792,7 @@ var TOOLS = [
   },
   {
     name: "guide_node",
-    description: "Cited relevant standards/practices for a node (OWASP/CWE), honest about recommended vs conjectured.",
+    description: "Cited standards/practices for a node (OWASP/CWE).",
     inputSchema: obj({ name: { type: "string" } }, ["name"]),
     handler: (graph, args) => {
       const { node, candidates } = resolveOne(graph, String(args.name ?? ""));
@@ -5391,17 +5806,17 @@ var TOOLS = [
   },
   {
     name: "check_drift",
-    description: 'Offline dependency inventory across npm/pypi/go (currency enrichment is the CLI\u2019s --online opt-in). Pass attribute:true to add git "who added this / who set the version" attribution for npm deps.',
+    description: "Offline dependency inventory (npm/pypi/go); attribute:true adds git who-added attribution.",
     inputSchema: obj(
-      { attribute: { type: "boolean", description: "enrich npm deps with git introduction attribution (requires git; slower)" } },
+      { attribute: { type: "boolean" } },
       []
     ),
     handler: (_graph, args, ctx) => attributedInventory(ctx.root, { attribute: args.attribute === true })
   },
   {
     name: "vuln_attribution",
-    description: "Who introduced each open vulnerability and how long you have been exposed, plus CRA remediation metrics: open exposure windows, SLA breaches, and real remediation time (MTTR) reconstructed from vulnerable versions that were later bumped out or removed in git history. Offline read of the last `vg scan --vulns`.",
-    inputSchema: obj({ package: { type: "string", description: "optional: restrict to one package" } }, []),
+    description: "Who introduced each open vulnerability, exposure windows, and CRA remediation metrics (MTTR, SLA breaches). Reads the last `vg scan --vulns`.",
+    inputSchema: obj({ package: { type: "string", description: "restrict to one package" } }, []),
     handler: (_graph, args, ctx) => {
       const data = loadVulnerabilities(ctx.root);
       if (!data) {
@@ -5430,9 +5845,9 @@ var TOOLS = [
   },
   {
     name: "list_vulnerabilities",
-    description: "Known vulnerabilities for installed dependencies, from the last `vg scan --vulns`. Offline read of the local scan artifact (no network); reports advisory id/CVE, severity, CVSS, and the fixed version.",
+    description: "Known vulnerabilities from the last `vg scan --vulns`: id/CVE, severity, CVSS, fixed version.",
     inputSchema: obj(
-      { severity: { type: "string", enum: ["low", "moderate", "high", "critical"], description: "optional minimum severity to include" } },
+      { severity: { type: "string", enum: ["low", "moderate", "high", "critical"], description: "minimum severity" } },
       []
     ),
     handler: (_graph, args, ctx) => {
@@ -5468,11 +5883,11 @@ var TOOLS = [
   },
   {
     name: "upgrade_impact",
-    description: 'A local "what breaks if I upgrade this" brief for a package: major-version distance + interim majors to step through, source blast radius (how many files import it), open vulnerabilities the upgrade would fix, and a recommended posture. Offline; richest after `vg scan`. Pass changelog:true to also fetch breaking-change signals from the package\'s GitHub releases (online; ignored under --local).',
+    description: "What breaks if you upgrade a package: major distance, import blast radius, vulns fixed, recommended posture. changelog:true adds GitHub breaking-change signals (online).",
     inputSchema: obj(
       {
-        package: { type: "string", description: "package name to assess" },
-        changelog: { type: "boolean", description: "also fetch breaking-change signals from GitHub releases between your version and latest (online; ignored under --local)" }
+        package: { type: "string" },
+        changelog: { type: "boolean" }
       },
       ["package"]
     ),
@@ -5488,19 +5903,19 @@ var TOOLS = [
   },
   {
     name: "list_models",
-    description: "The local model fleet discovered on disk (Ollama / LM Studio / gguf). Offline, no launch.",
+    description: "Local models on disk (Ollama / LM Studio / gguf).",
     inputSchema: obj({}),
     handler: () => ({ models: discoverModels() })
   },
   {
     name: "resolve_library",
-    description: "Resolve a library name/query to its canonical id + the version for YOUR project (version-correct + drift-annotated).",
+    description: "Resolve a library to its canonical id and the version YOUR project uses (drift-annotated).",
     // Canonical §4: `query` (+ optional `context_project`). `name` kept as a back-compat alias.
     inputSchema: obj(
       {
-        query: { type: "string", description: "library name or natural-language query" },
-        name: { type: "string", description: "alias for query (back-compat)" },
-        context_project: { type: "string", description: "optional lockfile/manifest context (informational; the local server uses the project root)" }
+        query: { type: "string", description: "library name or query" },
+        name: { type: "string" },
+        context_project: { type: "string" }
       },
       []
     ),
@@ -5543,19 +5958,19 @@ var TOOLS = [
   },
   {
     name: "library_docs",
-    description: "Version-correct, drift-annotated usage docs for a library \u2014 from the committed catalog or the installed package on disk.",
+    description: "Version-correct usage docs for a library, sliced to a token budget.",
     // Canonical §4: `targetId`/`query`, `verbosity`, `max_tokens`. `name`/`tokens` kept as aliases.
     inputSchema: obj(
       {
-        targetId: { type: "string", description: "canonical id from resolve_library" },
+        targetId: { type: "string", description: "id from resolve_library" },
         query: { type: "string", description: "library name or query" },
-        name: { type: "string", description: "alias for query (back-compat)" },
-        context_project: { type: "string", description: "optional project context (informational)" },
-        verbosity: { type: "string", enum: ["concise", "balanced", "exhaustive"], description: "detail level (sets the default token budget)" },
-        max_tokens: { type: "number", description: "explicit token budget (overrides verbosity)" },
-        tokens: { type: "number", description: "alias for max_tokens (back-compat)" },
-        enterprise_strict: { type: "boolean", description: "reserved (enterprise policy enforcement \u2014 hosted surface)" },
-        follow_up: { type: "boolean", description: "reserved (next slice \u2014 hosted surface)" }
+        name: { type: "string" },
+        context_project: { type: "string" },
+        verbosity: { type: "string", enum: ["concise", "balanced", "exhaustive"] },
+        max_tokens: { type: "number", description: "token budget" },
+        tokens: { type: "number" },
+        enterprise_strict: { type: "boolean" },
+        follow_up: { type: "boolean" }
       },
       []
     ),
@@ -5650,15 +6065,15 @@ var TOOLS = [
   }
 ];
 var VERBOSITY_BUDGET = { concise: 1500, balanced: 4e3, exhaustive: 12e3 };
-function summarize(graph) {
+function summarize(graph, top = 10) {
   return {
     counts: graph.meta.counts,
     languages: graph.meta.languages,
     cluster: graph.meta.cluster,
     resolver: graph.provenance.resolver,
     generatedAt: graph.generatedAt,
-    topAreas: [...graph.areas].sort((a, b) => b.size - a.size).slice(0, 10).map((a) => ({ id: a.id, label: a.label, size: a.size })),
-    topHubs: graph.nodes.filter((n) => n.isHub).sort((a, b) => b.importance - a.importance).slice(0, 10).map((n) => ({ name: n.qualifiedName, file: n.file, importance: n.importance }))
+    topAreas: [...graph.areas].sort((a, b) => b.size - a.size).slice(0, top).map((a) => ({ id: a.id, label: a.label, size: a.size })),
+    topHubs: graph.nodes.filter((n) => n.isHub).sort((a, b) => b.importance - a.importance).slice(0, top).map((n) => ({ name: n.qualifiedName, file: n.file, importance: n.importance }))
   };
 }
 function stripId(item) {
@@ -5689,6 +6104,19 @@ function numOrU(v) {
 function uniqueNames(xs) {
   return [...new Set(xs)];
 }
+var HOT_TOOLS = ["orient", "search_symbols", "query_graph", "get_node"];
+function deferredToolNames() {
+  const hot = new Set(HOT_TOOLS);
+  return TOOLS.map((t) => t.name).filter((n) => !hot.has(n));
+}
+function navigationToolsetConfig(serverName = "vibgrate") {
+  return {
+    type: "mcp_toolset",
+    mcp_server_name: serverName,
+    default_config: { defer_loading: true },
+    configs: Object.fromEntries(HOT_TOOLS.map((n) => [n, { defer_loading: false }]))
+  };
+}
 var LEDGER = "savings.jsonl";
 var PER_FILE_TOKENS = 400;
 function ledgerPath(root) {
@@ -5811,7 +6239,13 @@ function createServer(source, opts = {}) {
   const seen = /* @__PURE__ */ new Set();
   const server = new Server(
     { name: "vg", version: VERSION },
-    { capabilities: { tools: {} } }
+    {
+      capabilities: { tools: {} },
+      // Routing guidance once at the server level (hosts that surface
+      // `instructions` get it at zero per-step schema cost): the flashlight
+      // vs the map.
+      instructions: 'vg is a code map. Use search_symbols to find a known name or literal string fast. Use orient/query_graph for meaning: symptoms, relationships, and what-breaks-if. Responses are concise by default; pass response_format:"detailed" only when a node proves load-bearing. Navigate as little as possible: one good search/query usually locates the code. As soon as you have the file and line, read that file and make the edit \u2014 do not call further graph tools unless the edit fails or the match was wrong.'
+    }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map((t) => ({
@@ -5850,6 +6284,7 @@ function createServer(source, opts = {}) {
 async function serveStdio(graphPath, opts = {}) {
   const source = new GraphSource(graphPath, opts.refresh !== false);
   const server = createServer(source, opts);
+  warmEmbedderInBackground(opts.local);
   await server.connect(new StdioServerTransport());
 }
 function sleep(ms) {
@@ -6007,9 +6442,9 @@ function assistantById(id) {
 }
 function detectServeLaunch(which = whichOnPath) {
   const vg = which("vg");
-  if (vg && isOwnBinary(vg)) return { command: "vg", args: ["serve"] };
+  if (vg && isInstalledOwnBinary(vg)) return { command: "vg", args: ["serve"] };
   const vibgrate = which("vibgrate");
-  if (vibgrate && isOwnBinary(vibgrate)) {
+  if (vibgrate && isInstalledOwnBinary(vibgrate)) {
     return {
       command: "vibgrate",
       args: ["serve"],
@@ -6074,6 +6509,18 @@ function writeFileEnsured(file, content) {
   fs18.mkdirSync(path18.dirname(file), { recursive: true });
   fs18.writeFileSync(file, content);
 }
+function writeNavigationConfig(root) {
+  const rel2 = path18.join(".vibgrate", "mcp-navigation.json");
+  const doc = {
+    _readme: "Deferred-loading config for agents embedding `vg serve` via the Claude API (defer_loading + tool-search). The hot navigation core stays in context; the rest load on demand \u2014 ~350-450 schema tokens/step vs ~1,881 for the full set. Hosts without defer_loading ignore this and serve the whole (already optimized) tool set. See docs/graph/VG-NAVIGATION-PROFILE.md.",
+    hot_core: [...HOT_TOOLS],
+    deferred: deferredToolNames(),
+    toolset: navigationToolsetConfig()
+  };
+  writeFileEnsured(path18.join(root, rel2), `${JSON.stringify(doc, null, 2)}
+`);
+  return rel2;
+}
 function upsertMcp(file, target, launch) {
   const config = readJson(file);
   const entry = mcpServerEntry(launch);
@@ -6288,6 +6735,6 @@ function spdx(ctx) {
   return JSON.stringify(doc, null, 2) + "\n";
 }
 
-export { ASSISTANTS, CliError, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, SCHEMA_VERSION, SKIP_DIRS, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, exportGraph, fetchHostedDocs, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot, writeStoredCredentials };
-//# sourceMappingURL=chunk-WGXDYBAN.js.map
-//# sourceMappingURL=chunk-WGXDYBAN.js.map
+export { ASSISTANTS, CliError, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, exportGraph, fetchHostedDocs, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveLimits, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeNavigationConfig, writeSnapshot, writeStoredCredentials };
+//# sourceMappingURL=chunk-JL7FIC6W.js.map
+//# sourceMappingURL=chunk-JL7FIC6W.js.map