@wrongstack/tools 1.0.1 → 1.0.3

package/dist/{chunk-YEISRT4S.js → chunk-PNLDTRC5.js}

@@ -3,9 +3,11 @@ import {
 } from "./chunk-XRNN44QY.js";
 import {
   spawnStream
-} from "./chunk-DRRY6SCM.js";
+} from "./chunk-EMA2XENR.js";
 import {
+  codebaseContext,
   codebaseIndexStats,
+  codebaseVectorSearch,
   enqueueReindex,
   getIndexState,
   incomingCallsService,
@@ -13,34 +15,31 @@ import {
   outgoingCallsService,
   runStartupIndex,
   searchCodebaseIndex
-} from "./chunk-ZTCJCYLN.js";
+} from "./chunk-CVNCSMVU.js";
 import {
   IndexTimeoutError,
   SCHEMA_VERSION,
   codebaseIndexDirOverride,
   indexCircuitBreaker,
   indexStorePool,
-  resolveIndexDir
-} from "./chunk-N3K2SFEI.js";
+  isConceptRelation,
+  posixIndexPath,
+  resolveIndexDir,
+  xxhash64String
+} from "./chunk-3JVSOBHU.js";
 import {
   EXT_TO_LANG,
   detectLang,
   isIndexablePath
 } from "./chunk-YOHO4DVT.js";
+import {
+  loadGitignoreMatcher
+} from "./chunk-2CTZW6JQ.js";
 import {
   normalizeCommandOutput,
   safeResolveProjectPath
 } from "./chunk-ZUFHAHTE.js";
 
-// src/codebase-index/codebase-ast-replace-tool.ts
-import * as path2 from "node:path";
-import { toErrorMessage } from "@wrongstack/core/utils";
-
-// src/codebase-index/ast-symbol-mutator.ts
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { atomicWrite } from "@wrongstack/core/utils";
-
 // src/codebase-index/ast-invariant-engine.ts
 var tsModule = null;
 async function loadTs() {
@@ -467,6 +466,9 @@ var PolyglotInvariantEngine = class {
 var polyglotInvariantEngine = new PolyglotInvariantEngine();
 
 // src/codebase-index/ast-symbol-mutator.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite } from "@wrongstack/core/utils";
 var tsModule2 = null;
 async function loadTs2() {
   if (!tsModule2) {
@@ -639,6 +641,8 @@ Pass allowBreakingChanges: true if this breaking change is intended.`
 }
 
 // src/codebase-index/codebase-ast-replace-tool.ts
+import * as path2 from "node:path";
+import { toErrorMessage } from "@wrongstack/core/utils";
 var codebaseAstReplaceTool = {
   name: "codebase-ast-replace",
   category: "Edit",
@@ -705,88 +709,9 @@ var codebaseAstReplaceTool = {
   }
 };
 
-// src/codebase-index/codebase-invariant-check-tool.ts
-import * as fs2 from "node:fs/promises";
-import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
-var codebaseInvariantCheckTool = {
-  name: "codebase-invariant-check",
-  category: "Inspect",
-  icon: "index",
-  permission: "auto",
-  subjectKey: "file",
-  mutating: false,
-  capabilities: ["fs.read"],
-  description: "Mathematically verify AST backward-compatibility invariants between original code and candidate mutations across TypeScript, Python, Go, Rust, Java, etc. Detects missing exports (INV-001), mandatory parameter additions (INV-002), interface breaking expansions (INV-003), and return type changes (INV-004) with zero hallucinations.",
-  usageHint: "PRE-FLIGHT AST INVARIANT AUDIT:\n\n- Provide `file` and `modifiedCode` (or both `originalCode` and `modifiedCode`).\n- Returns `valid: true` if changes are strictly backward compatible.\n- Returns structured `violations[]` with exact rule IDs, offending symbol names, and fix instructions.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      file: {
-        type: "string",
-        description: "Path to existing source file to compare against candidate modifications."
-      },
-      originalCode: {
-        type: "string",
-        description: "Original source code string (if not reading from an existing file)."
-      },
-      modifiedCode: {
-        type: "string",
-        description: "The candidate modified code string to validate."
-      },
-      lang: {
-        type: "string",
-        description: "Language hint (ts, py, go, rs, etc.). Inferred from file path if omitted."
-      }
-    },
-    required: ["modifiedCode"],
-    additionalProperties: false
-  },
-  async execute(input, ctx) {
-    try {
-      let originalCode = input.originalCode;
-      let lang = input.lang;
-      if (!originalCode && input.file) {
-        const resolved = await safeResolveProjectPath(input.file, ctx);
-        originalCode = await fs2.readFile(resolved, "utf8");
-        if (!lang) {
-          lang = detectLang(resolved) ?? "ts";
-        }
-      }
-      if (originalCode === void 0) {
-        return {
-          valid: false,
-          violations: [],
-          summary: "Neither originalCode nor file was provided for invariant comparison.",
-          error: "Missing originalCode or file path."
-        };
-      }
-      const res = await polyglotInvariantEngine.evaluate({
-        originalCode,
-        modifiedCode: input.modifiedCode,
-        lang,
-        filePath: input.file
-      });
-      const summary = res.valid ? "AST Invariants PASSED. Mutation is 100% backward compatible." : `AST Invariants FAILED with ${res.violations.length} violation(s):
-` + res.violations.map((v) => ` - [${v.ruleId}] ${v.symbolName}: ${v.message}`).join("\n");
-      return {
-        valid: res.valid,
-        violations: res.violations,
-        summary
-      };
-    } catch (err) {
-      return {
-        valid: false,
-        violations: [],
-        summary: `Error during invariant evaluation: ${toErrorMessage2(err)}`,
-        error: toErrorMessage2(err)
-      };
-    }
-  }
-};
-
 // src/codebase-index/codebase-impact-analysis-tool.ts
 import * as path3 from "node:path";
-import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils";
+import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
 var TEST_FILE_REGEX = /(?:test|spec|mock|fixture|bench)[s]?[/\\._]/i;
 var codebaseImpactAnalysisTool = {
   name: "codebase-impact-analysis",
@@ -840,7 +765,7 @@ var codebaseImpactAnalysisTool = {
       } catch (err) {
         symbolFound = false;
         indexUnavailable = true;
-        indexError = toErrorMessage3(err);
+        indexError = toErrorMessage2(err);
       }
       if (indexUnavailable) {
         const detail = indexError ? ` (${indexError})` : "";
@@ -943,14 +868,15 @@ var codebaseImpactAnalysisTool = {
         callSites: [],
         recommendedActionPlan: [],
         symbolFound: false,
-        error: toErrorMessage3(err)
+        error: toErrorMessage2(err)
       };
     }
   }
 };
 
 // src/codebase-index/codebase-incoming-calls-tool.ts
-import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
+import { ToolValidationError } from "@wrongstack/core/types";
+import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils";
 var codebaseIncomingCallsTool = {
   name: "codebase-incoming-calls",
   category: "Project",
@@ -987,6 +913,12 @@ var codebaseIncomingCallsTool = {
     required: ["symbol"]
   },
   async execute(input, ctx) {
+    if (!input?.symbol || typeof input.symbol !== "string" || !input.symbol.trim()) {
+      throw new ToolValidationError({
+        message: "codebase-incoming-calls: symbol is required and cannot be empty",
+        field: "symbol"
+      });
+    }
     const state = getIndexState();
     if (state.lastError) {
       const circuit = state.circuit;
@@ -1024,7 +956,7 @@ var codebaseIncomingCallsTool = {
         symbol: input.symbol,
         calls: [],
         total: 0,
-        indexStatus: `Index query failed: ${toErrorMessage4(err)}. Fall back to grep for this lookup.`
+        indexStatus: `Index query failed: ${toErrorMessage3(err)}. Fall back to grep for this lookup.`
       };
     }
     const { calls, symbolFound, ambiguous, totalMatches, stale } = serviced;
@@ -1082,11 +1014,11 @@ var codebaseIncomingCallsTool = {
 };
 
 // src/codebase-index/codebase-index-tool.ts
-import { ToolValidationError as ToolValidationError2 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError3 } from "@wrongstack/core/types";
 
 // src/codebase-index/codebase-search-tool.ts
-import { ToolValidationError } from "@wrongstack/core/types";
-import { toErrorMessage as toErrorMessage5 } from "@wrongstack/core/utils";
+import { ToolValidationError as ToolValidationError2 } from "@wrongstack/core/types";
+import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
 var INDEXABLE_LANG_IDS = [
   ...new Set(Object.values(EXT_TO_LANG))
 ].sort();
@@ -1163,13 +1095,13 @@ var codebaseSearchTool = {
   },
   async execute(input, ctx, execOpts) {
     if (!input?.query || typeof input.query !== "string" || !input.query.trim()) {
-      throw new ToolValidationError({
+      throw new ToolValidationError2({
         message: "codebase-search: query is required and cannot be empty",
         field: "query"
       });
     }
     if (input.lspKind !== void 0 && (!Number.isInteger(input.lspKind) || input.lspKind < 1 || input.lspKind > 26)) {
-      throw new ToolValidationError({
+      throw new ToolValidationError2({
         message: "codebase-search: lspKind must be an integer between 1 and 26",
         field: "lspKind"
       });
@@ -1219,7 +1151,7 @@ var codebaseSearchTool = {
         results: [],
         total: 0,
         query: input.query,
-        indexStatus: `Index query failed: ${toErrorMessage5(err)}. Fall back to grep/glob for this lookup.`
+        indexStatus: `Index query failed: ${toErrorMessage4(err)}. Fall back to grep/glob for this lookup.`
       };
     }
     const { results, total, stale, indexSummary } = searched;
@@ -1287,7 +1219,7 @@ var codebaseIndexTool = {
     signal?.throwIfAborted();
     if (input.langs) {
       if (!Array.isArray(input.langs) || input.langs.length === 0) {
-        throw new ToolValidationError2({
+        throw new ToolValidationError3({
           message: "codebase-index: langs cannot be an empty array. Pass at least one valid language or omit langs.",
           field: "langs"
         });
@@ -1296,7 +1228,7 @@ var codebaseIndexTool = {
         (lang) => !INDEXABLE_LANG_IDS.includes(lang)
       );
       if (unknown.length > 0) {
-        throw new ToolValidationError2({
+        throw new ToolValidationError3({
           message: `codebase-index: unknown lang(s) ${unknown.map((l) => `"${l}"`).join(", ")}. Valid ids: ${INDEXABLE_LANG_IDS.join(", ")}.`,
           field: "langs"
         });
@@ -1345,7 +1277,87 @@ var codebaseIndexTool = {
   }
 };
 
+// src/codebase-index/codebase-invariant-check-tool.ts
+import * as fs2 from "node:fs/promises";
+import { toErrorMessage as toErrorMessage5 } from "@wrongstack/core/utils";
+var codebaseInvariantCheckTool = {
+  name: "codebase-invariant-check",
+  category: "Inspect",
+  icon: "index",
+  permission: "auto",
+  subjectKey: "file",
+  mutating: false,
+  capabilities: ["fs.read"],
+  description: "Mathematically verify AST backward-compatibility invariants between original code and candidate mutations across TypeScript, Python, Go, Rust, Java, etc. Detects missing exports (INV-001), mandatory parameter additions (INV-002), interface breaking expansions (INV-003), and return type changes (INV-004) with zero hallucinations.",
+  usageHint: "PRE-FLIGHT AST INVARIANT AUDIT:\n\n- Provide `file` and `modifiedCode` (or both `originalCode` and `modifiedCode`).\n- Returns `valid: true` if changes are strictly backward compatible.\n- Returns structured `violations[]` with exact rule IDs, offending symbol names, and fix instructions.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file: {
+        type: "string",
+        description: "Path to existing source file to compare against candidate modifications."
+      },
+      originalCode: {
+        type: "string",
+        description: "Original source code string (if not reading from an existing file)."
+      },
+      modifiedCode: {
+        type: "string",
+        description: "The candidate modified code string to validate."
+      },
+      lang: {
+        type: "string",
+        description: "Language hint (ts, py, go, rs, etc.). Inferred from file path if omitted."
+      }
+    },
+    required: ["modifiedCode"],
+    additionalProperties: false
+  },
+  async execute(input, ctx) {
+    try {
+      let originalCode = input.originalCode;
+      let lang = input.lang;
+      if (!originalCode && input.file) {
+        const resolved = await safeResolveProjectPath(input.file, ctx);
+        originalCode = await fs2.readFile(resolved, "utf8");
+        if (!lang) {
+          lang = detectLang(resolved) ?? "ts";
+        }
+      }
+      if (originalCode === void 0) {
+        return {
+          valid: false,
+          violations: [],
+          summary: "Neither originalCode nor file was provided for invariant comparison.",
+          error: "Missing originalCode or file path."
+        };
+      }
+      const res = await polyglotInvariantEngine.evaluate({
+        originalCode,
+        modifiedCode: input.modifiedCode,
+        lang,
+        filePath: input.file
+      });
+      const summary = res.valid ? "AST Invariants PASSED. Mutation is 100% backward compatible." : `AST Invariants FAILED with ${res.violations.length} violation(s):
+` + res.violations.map((v) => ` - [${v.ruleId}] ${v.symbolName}: ${v.message}`).join("\n");
+      return {
+        valid: res.valid,
+        violations: res.violations,
+        summary
+      };
+    } catch (err) {
+      return {
+        valid: false,
+        violations: [],
+        summary: `Error during invariant evaluation: ${toErrorMessage5(err)}`,
+        error: toErrorMessage5(err)
+      };
+    }
+  }
+};
+
 // src/codebase-index/codebase-outgoing-calls-tool.ts
+import { ToolValidationError as ToolValidationError4 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage6 } from "@wrongstack/core/utils";
 var codebaseOutgoingCallsTool = {
   name: "codebase-outgoing-calls",
@@ -1383,6 +1395,12 @@ var codebaseOutgoingCallsTool = {
     required: ["symbol"]
   },
   async execute(input, ctx) {
+    if (!input?.symbol || typeof input.symbol !== "string" || !input.symbol.trim()) {
+      throw new ToolValidationError4({
+        message: "codebase-outgoing-calls: symbol is required and cannot be empty",
+        field: "symbol"
+      });
+    }
     const state = getIndexState();
     if (state.lastError) {
       const circuit = state.circuit;
@@ -1481,9 +1499,16 @@ var codebaseOutgoingCallsTool = {
 import { toErrorMessage as toErrorMessage7 } from "@wrongstack/core/utils";
 
 // src/codebase-index/repo-map.ts
-import * as fs4 from "node:fs/promises";
+import { existsSync } from "node:fs";
+import * as path6 from "node:path";
+
+// src/codebase-index/repo-map-fallback.ts
+import * as fs5 from "node:fs/promises";
 import * as path5 from "node:path";
 
+// src/codebase-index/repo-map-render.ts
+import * as fs4 from "node:fs/promises";
+
 // src/codebase-index/skeleton-extractor.ts
 import * as fs3 from "node:fs/promises";
 import * as path4 from "node:path";
@@ -1870,40 +1895,102 @@ ${res.skeleton}`
   };
 }
 
-// src/codebase-index/repo-map.ts
+// src/codebase-index/repo-map-render.ts
+var TRUNCATION_NOTE = "\n  // \u2026 signatures truncated to fit the token budget";
+function truncateAtLine(text, limit) {
+  if (text.length <= limit) return text;
+  const cut = text.slice(0, limit);
+  const lastNewline = cut.lastIndexOf("\n");
+  return lastNewline > 0 ? cut.slice(0, lastNewline) : cut;
+}
+var COMMENT_ONLY_LINE = /^\s*(?:\/\/|\/\*|\*\/|\*|#|--|<!--|-->)/;
+function stripCommentLines(body) {
+  const kept = body.split("\n").filter((line) => !COMMENT_ONLY_LINE.test(line));
+  const joined = kept.join("\n").trim();
+  return joined.length > 0 ? joined : body;
+}
+async function renderSkeletonSections(candidates, charBudget, options = {}) {
+  const sections = [];
+  const files = [];
+  const maxSectionChars = options.maxSectionChars ?? Number.POSITIVE_INFINITY;
+  let chars = 0;
+  for (const candidate of candidates) {
+    if (chars >= charBudget) break;
+    let content;
+    try {
+      content = await fs4.readFile(candidate.absolute, "utf8");
+    } catch {
+      continue;
+    }
+    if (content.length === 0) continue;
+    let skeleton;
+    try {
+      skeleton = await extractFileSkeleton({
+        file: candidate.absolute,
+        content,
+        options: {
+          exportsOnly: true,
+          collapseImports: true,
+          includeDocs: false,
+          includeLineNumbers: true,
+          ...options.skeleton ?? {}
+        }
+      });
+    } catch {
+      continue;
+    }
+    const body = skeleton.skeleton.trim();
+    if (!body) continue;
+    const indented = (options.signaturesOnly === true ? stripCommentLines(body) : body).split("\n").map((line) => line.trim() ? `  ${line}` : "").join("\n");
+    const header = `${candidate.relative} (${skeleton.lang}):
+`;
+    const room = Math.min(maxSectionChars, charBudget - chars) - header.length - TRUNCATION_NOTE.length - 2;
+    let section;
+    if (indented.length <= room) {
+      section = header + indented;
+    } else {
+      if (room <= 0) break;
+      section = `${header}${truncateAtLine(indented, room)}${TRUNCATION_NOTE}`;
+    }
+    const sectionChars = section.length + 2;
+    if (chars + sectionChars > charBudget && files.length > 0) break;
+    sections.push(section);
+    files.push(candidate.relative);
+    chars += sectionChars;
+  }
+  return { sections, files, chars };
+}
+
+// src/codebase-index/repo-map-fallback.ts
 var ENTRY_POINT_REGEX = /(?:^|[/\\])(?:index|main|app|server|cli|lib|api|types|routes|mod)\.[a-zA-Z0-9]+$/i;
 var TEST_OR_MOCK_REGEX = /(?:test|spec|mock|fixture|bench|example)[s]?[/\\._]/i;
+var ALWAYS_SKIP = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage"]);
 function getEntryPointBonus(relPath) {
-  if (TEST_OR_MOCK_REGEX.test(relPath)) {
-    return -20;
-  }
-  if (ENTRY_POINT_REGEX.test(relPath)) {
-    return 25;
-  }
+  if (TEST_OR_MOCK_REGEX.test(relPath)) return -20;
+  if (ENTRY_POINT_REGEX.test(relPath)) return 25;
   const depth = relPath.split(/[/\\]/).length;
   if (depth <= 2) return 10;
   if (depth <= 3) return 5;
   return 0;
 }
-async function generateRepoMap(opts) {
+async function generateFallbackRepoMap(opts) {
   const projectRoot = opts.projectRoot;
-  const maxTokens = opts.maxTokens ?? 1200;
-  const charBudget = maxTokens * 4;
+  const charBudget = (opts.maxTokens ?? 1200) * 4;
   const focusSet = new Set((opts.focusFiles ?? []).map((f) => path5.resolve(projectRoot, f)));
+  const isGitIgnored = await loadGitignoreMatcher(projectRoot);
   const allFiles = [];
   async function scan(dir) {
-    if (allFiles.length > 500) return;
     let entries;
     try {
-      entries = await fs4.readdir(dir, { withFileTypes: true });
+      entries = await fs5.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build" || entry.name === "coverage") {
-        continue;
-      }
+      if (entry.name.startsWith(".") || ALWAYS_SKIP.has(entry.name)) continue;
       const fullPath = path5.join(dir, entry.name);
+      const rel = path5.relative(projectRoot, fullPath).replace(/\\/g, "/");
+      if (isGitIgnored(rel, entry.isDirectory())) continue;
       if (entry.isDirectory()) {
         await scan(fullPath);
       } else if (entry.isFile() && isIndexablePath(fullPath)) {
@@ -1921,58 +2008,141 @@ async function generateRepoMap(opts) {
       rankedFiles: []
     };
   }
-  const scoredFiles = [];
-  for (const file of allFiles) {
+  const scored = allFiles.map((file) => {
     const relPath = path5.relative(projectRoot, file).replace(/\\/g, "/");
-    let score = 10;
-    if (focusSet.has(file)) {
-      score += 100;
-    }
-    score += getEntryPointBonus(relPath);
-    scoredFiles.push({ file, score, relPath });
-  }
-  scoredFiles.sort((a, b) => b.score - a.score);
-  const includedSections = [];
-  const includedFiles = [];
-  let currentChars = 0;
-  for (const candidate of scoredFiles) {
-    if (currentChars >= charBudget) break;
-    try {
-      const content = await fs4.readFile(candidate.file, "utf8");
-      if (content.length === 0) continue;
-      const skeletonResult = await extractFileSkeleton({
-        file: candidate.file,
-        content,
-        options: {
-          exportsOnly: true,
-          collapseImports: true,
-          includeDocs: false,
-          includeLineNumbers: true,
-          ...opts.options ?? {}
-        }
+    const score = 10 + (focusSet.has(file) ? 100 : 0) + getEntryPointBonus(relPath);
+    return { file, relPath, score };
+  });
+  scored.sort((a, b) => b.score - a.score || a.relPath.localeCompare(b.relPath));
+  const { sections, files } = await renderSkeletonSections(
+    scored.map((s) => ({ absolute: s.file, relative: s.relPath })),
+    charBudget,
+    { skeleton: opts.options }
+  );
+  const map = sections.join("\n\n");
+  return {
+    map,
+    filesCount: files.length,
+    totalFilesScanned: allFiles.length,
+    estimatedTokens: Math.ceil(map.length / 4),
+    rankedFiles: files
+  };
+}
+
+// src/codebase-index/repo-map.ts
+var RANKED_FETCH_LIMIT = 400;
+var INDEX_DB_FILE = "index.db";
+var MAX_CLUSTERS = 16;
+var MAX_HOTSPOTS = 12;
+var HEADER_BUDGET_SHARE = 0.4;
+var TARGET_BODY_FILES = 6;
+var MIN_SECTION_CHARS = 300;
+function buildClusters(rows, relativeOf, packageCounts) {
+  const byLabel = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const relative12 = relativeOf(row.file);
+    const label = row.package || relative12.split("/")[0] || "(root)";
+    const existing = byLabel.get(label);
+    if (existing === void 0) {
+      byLabel.set(label, {
+        label,
+        fileCount: packageCounts.get(row.package) ?? 0,
+        rankedCount: 1,
+        hub: relative12,
+        hubRank: row.rank
       });
-      const cleanSkeleton = skeletonResult.skeleton.trim();
-      if (!cleanSkeleton) continue;
-      const section = `${candidate.relPath} (${skeletonResult.lang}):
-${cleanSkeleton.split("\n").map((line) => line.trim() ? `  ${line}` : "").join("\n")}`;
-      const sectionChars = section.length + 2;
-      if (currentChars + sectionChars > charBudget && includedFiles.length > 0) {
-        break;
-      }
-      includedSections.push(section);
-      includedFiles.push(candidate.relPath);
-      currentChars += sectionChars;
-    } catch {
+      continue;
+    }
+    existing.rankedCount += 1;
+    if (row.rank > existing.hubRank) {
+      existing.hub = relative12;
+      existing.hubRank = row.rank;
+    }
+  }
+  return [...byLabel.values()].sort(
+    (a, b) => b.hubRank - a.hubRank || a.label.localeCompare(b.label)
+  );
+}
+function renderHeader(clusters, hotspots, relativeOf, budget) {
+  const lines = ["// Repo map \u2014 ranked by graph centrality (1.00 = most central)."];
+  if (clusters.length > 0) {
+    lines.push("", "// Clusters (hub = most central file):");
+    for (const cluster of clusters.slice(0, MAX_CLUSTERS)) {
+      const size = cluster.fileCount > 0 ? `${cluster.fileCount} files` : "unlabelled";
+      lines.push(`//   ${cluster.label}  (${size})  hub: ${cluster.hub}`);
+    }
+  }
+  if (hotspots.length > 0) {
+    lines.push("", "// Hotspots:");
+    for (const row of hotspots.slice(0, MAX_HOTSPOTS)) {
+      lines.push(
+        `//   ${row.rank.toFixed(2)}  in=${row.inDeg} out=${row.outDeg}  ${relativeOf(row.file)}`
+      );
+    }
+  }
+  while (lines.length > 1 && lines.join("\n").length + 2 > budget) lines.pop();
+  return lines.join("\n");
+}
+async function generateRepoMap(opts) {
+  const projectRoot = opts.projectRoot;
+  const charBudget = (opts.maxTokens ?? 1200) * 4;
+  let ranked = [];
+  let packageCounts = /* @__PURE__ */ new Map();
+  let totalRankedFiles = 0;
+  let store;
+  try {
+    if (!existsSync(path6.join(resolveIndexDir(projectRoot, opts.indexDir), INDEX_DB_FILE))) {
+      return generateFallbackRepoMap(opts);
     }
+    store = indexStorePool.acquire(projectRoot, { indexDir: opts.indexDir });
+    totalRankedFiles = store.getRankCounts().files;
+    if (totalRankedFiles > 0) {
+      ranked = store.getRankedFiles(RANKED_FETCH_LIMIT);
+      packageCounts = store.getPackageFileCounts();
+    }
+  } catch {
+    ranked = [];
+  } finally {
+    if (store !== void 0) indexStorePool.release(store);
   }
-  const map = includedSections.join("\n\n");
-  const estimatedTokens = Math.ceil(map.length / 4);
+  if (ranked.length === 0) return generateFallbackRepoMap(opts);
+  const relativeOf = (file) => {
+    const relative12 = path6.relative(projectRoot, file);
+    if (!relative12 || relative12.startsWith("..")) return posixIndexPath(file);
+    return posixIndexPath(relative12);
+  };
+  const clusters = buildClusters(ranked, relativeOf, packageCounts);
+  const header = renderHeader(clusters, ranked, relativeOf, charBudget * HEADER_BUDGET_SHARE);
+  const focus = (opts.focusFiles ?? []).map((f) => path6.resolve(projectRoot, f));
+  const focusIndex = new Map(focus.map((file, i) => [file, i]));
+  const candidates = ranked.map((row) => ({
+    row,
+    absolute: path6.resolve(projectRoot, row.file)
+  })).sort((a, b) => {
+    const fa = focusIndex.get(a.absolute) ?? Number.POSITIVE_INFINITY;
+    const fb = focusIndex.get(b.absolute) ?? Number.POSITIVE_INFINITY;
+    if (fa !== fb) return fa - fb;
+    return b.row.rank - a.row.rank;
+  }).map(({ row, absolute }) => ({ absolute, relative: relativeOf(row.file) }));
+  const known = new Set(candidates.map((c) => c.absolute));
+  const missingFocus = focus.filter((file) => !known.has(file)).map((file) => ({ absolute: file, relative: relativeOf(file) }));
+  const bodyBudget = Math.max(0, charBudget - header.length - 2);
+  const { sections, files } = await renderSkeletonSections(
+    [...missingFocus, ...candidates],
+    bodyBudget,
+    {
+      skeleton: opts.options,
+      maxSectionChars: Math.max(MIN_SECTION_CHARS, bodyBudget / TARGET_BODY_FILES),
+      signaturesOnly: true
+    }
+  );
+  const map = [header, ...sections].join("\n\n");
   return {
     map,
-    filesCount: includedFiles.length,
-    totalFilesScanned: allFiles.length,
-    estimatedTokens,
-    rankedFiles: includedFiles
+    filesCount: files.length,
+    totalFilesScanned: totalRankedFiles,
+    estimatedTokens: Math.ceil(map.length / 4),
+    rankedFiles: files
   };
 }
 
@@ -1984,8 +2154,8 @@ var codebaseRepoMapTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
-  description: "Generate a reference-weighted, token-budgeted Repository Map of the codebase (~1200 token default). Use it for orientation before a cross-file change. Extracts the most architecturally central types, interfaces, classes, and function signatures across the repository into a compact outline (~800-1500 tokens). Use this at the beginning of tasks or when navigating unfamiliar repositories to get a bird-eye view of the architecture.",
-  usageHint: 'USE AT THE START OF COMPLEX OR REPOSITORY-WIDE TASKS:\n\n- Call with default parameters to get a global architecture map within ~1200 tokens.\n- Pass `focusFiles: ["src/auth.ts"]` to ensure candidate files are guaranteed to be mapped alongside related entry-points.\n- Use the returned line numbers (e.g. `/* L32-L45 */`) to navigate or partially read only the functions you need.',
+  description: "Generate a centrality-ranked, token-budgeted Repository Map of the codebase (~1200 token default). Use it for orientation before a cross-file change. Ranking comes from the index's reference graph (PageRank over calls, imports, type references and inheritance), not from filenames, so the map opens with the package clusters and their hub files, then the repository-wide hotspots, then the signatures of the most central files. Use this at the beginning of tasks or when navigating unfamiliar repositories to get a bird-eye view of the architecture.",
+  usageHint: 'USE AT THE START OF COMPLEX OR REPOSITORY-WIDE TASKS:\n\n- Call with default parameters to get a global architecture map within ~1200 tokens.\n- The `1.00 = most central` scores are relative to this repository only; never compare them across projects.\n- Pass `focusFiles: ["src/auth.ts"]` to put specific files at the head of the map alongside the central ones.\n- Use the returned line numbers (e.g. `/* L32-L45 */`) to navigate or partially read only the functions you need.\n- Falls back to a filename heuristic when the index has not been built yet; run `/codebase-reindex` to get the ranked map.',
   inputSchema: {
     type: "object",
     properties: {
@@ -2007,7 +2177,10 @@ var codebaseRepoMapTool = {
       const result = await generateRepoMap({
         projectRoot,
         maxTokens: input.maxTokens,
-        focusFiles: input.focusFiles
+        focusFiles: input.focusFiles,
+        // Honour a caller-supplied index location so the map reads the same
+        // index the other codebase-* tools do.
+        indexDir: codebaseIndexDirOverride(ctx)
       });
       return {
         status: "ok",
@@ -2028,7 +2201,7 @@ var codebaseRepoMapTool = {
 };
 
 // src/codebase-index/codebase-skeleton-tool.ts
-import * as fs5 from "node:fs/promises";
+import * as fs6 from "node:fs/promises";
 import { toErrorMessage as toErrorMessage8 } from "@wrongstack/core/utils";
 var codebaseSkeletonTool = {
   name: "codebase-skeleton",
@@ -2073,7 +2246,7 @@ var codebaseSkeletonTool = {
     const targetPath = await safeResolveProjectPath(input.path, ctx);
     let stat3;
     try {
-      stat3 = await fs5.stat(targetPath);
+      stat3 = await fs6.stat(targetPath);
     } catch (err) {
       throw new Error(
         `codebase-skeleton: file or directory not found at "${input.path}": ${toErrorMessage8(err)}`
@@ -2109,7 +2282,7 @@ var codebaseSkeletonTool = {
         files: dirResult.files
       };
     }
-    const content = await fs5.readFile(targetPath, "utf8");
+    const content = await fs6.readFile(targetPath, "utf8");
     const fileResult = await extractFileSkeleton({
       file: targetPath,
       content,
@@ -2215,28 +2388,28 @@ var codebaseStatsTool = {
 };
 
 // src/codebase-index/codebase-targeted-test-tool.ts
-import * as fs6 from "node:fs/promises";
-import * as path6 from "node:path";
+import * as fs7 from "node:fs/promises";
+import * as path7 from "node:path";
 import { toErrorMessage as toErrorMessage10 } from "@wrongstack/core/utils";
 var TEST_FILE_REGEX2 = /(?:test|spec|mock|fixture|bench)[s]?[/\\._]/i;
 async function findConventionTestFiles(projectRoot, sourceRelPath) {
-  const parsed = path6.parse(sourceRelPath);
+  const parsed = path7.parse(sourceRelPath);
   const candidates = [
-    path6.join(parsed.dir, `${parsed.name}.test${parsed.ext}`),
-    path6.join(parsed.dir, `${parsed.name}.spec${parsed.ext}`),
-    path6.join(parsed.dir, `${parsed.name}_test${parsed.ext}`),
-    path6.join(parsed.dir, `test_${parsed.name}${parsed.ext}`),
-    path6.join("tests", `${parsed.name}.test${parsed.ext}`),
-    path6.join("tests", `${parsed.name}.spec${parsed.ext}`),
-    path6.join("test", `${parsed.name}.test${parsed.ext}`),
-    path6.join(parsed.dir, "__tests__", `${parsed.name}.test${parsed.ext}`),
-    path6.join(parsed.dir, "__tests__", `${parsed.name}${parsed.ext}`)
+    path7.join(parsed.dir, `${parsed.name}.test${parsed.ext}`),
+    path7.join(parsed.dir, `${parsed.name}.spec${parsed.ext}`),
+    path7.join(parsed.dir, `${parsed.name}_test${parsed.ext}`),
+    path7.join(parsed.dir, `test_${parsed.name}${parsed.ext}`),
+    path7.join("tests", `${parsed.name}.test${parsed.ext}`),
+    path7.join("tests", `${parsed.name}.spec${parsed.ext}`),
+    path7.join("test", `${parsed.name}.test${parsed.ext}`),
+    path7.join(parsed.dir, "__tests__", `${parsed.name}.test${parsed.ext}`),
+    path7.join(parsed.dir, "__tests__", `${parsed.name}${parsed.ext}`)
   ];
   const found = [];
   for (const cand of candidates) {
-    const absPath = path6.resolve(projectRoot, cand);
+    const absPath = path7.resolve(projectRoot, cand);
     try {
-      const st = await fs6.stat(absPath);
+      const st = await fs7.stat(absPath);
       if (st.isFile()) {
         found.push(cand.replace(/\\/g, "/"));
       }
@@ -2293,7 +2466,7 @@ var codebaseTargetedTestTool = {
             transitive: true
           });
           for (const site of serviced.calls) {
-            const relPath = path6.relative(projectRoot, site.symbol.file).replace(/\\/g, "/");
+            const relPath = path7.relative(projectRoot, site.symbol.file).replace(/\\/g, "/");
             if (TEST_FILE_REGEX2.test(relPath)) {
               suitesSet.add(relPath);
             }
@@ -2377,8 +2550,8 @@ ${streamRes.stderr}`.trim(),
 };
 
 // src/codebase-index/dead-code-scan.ts
-import * as fs7 from "node:fs";
-import * as path7 from "node:path";
+import * as fs8 from "node:fs";
+import * as path8 from "node:path";
 var deadCodeScanTool = {
   name: "dead-code-scan",
   category: "Project",
@@ -2423,25 +2596,25 @@ var deadCodeScanTool = {
 };
 function tryReadJson(filePath) {
   try {
-    const raw = fs7.readFileSync(filePath, "utf8");
+    const raw = fs8.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
   }
 }
-function resolveAgainst(base, relative7) {
-  if (path7.isAbsolute(relative7)) return relative7;
-  return path7.resolve(base, relative7);
+function resolveAgainst(base, relative12) {
+  if (path8.isAbsolute(relative12)) return relative12;
+  return path8.resolve(base, relative12);
 }
 function discoverEntryPoints(projectRoot, userEntryPoints) {
   const entries = /* @__PURE__ */ new Set();
   if (userEntryPoints) {
     for (const ep of userEntryPoints) {
       const resolved = resolveAgainst(projectRoot, ep);
-      if (fs7.existsSync(resolved)) entries.add(resolved);
+      if (fs8.existsSync(resolved)) entries.add(resolved);
     }
   }
-  const rootPkg = tryReadJson(path7.join(projectRoot, "package.json"));
+  const rootPkg = tryReadJson(path8.join(projectRoot, "package.json"));
   if (rootPkg) {
     addPkgJsonEntryPoints(projectRoot, rootPkg, entries);
   }
@@ -2455,45 +2628,45 @@ function discoverEntryPoints(projectRoot, userEntryPoints) {
     workspaces = [];
   }
   for (const wsDir of workspaces) {
-    const pkgJsonPath = path7.join(wsDir, "package.json");
+    const pkgJsonPath = path8.join(wsDir, "package.json");
     const pkg = tryReadJson(pkgJsonPath);
     if (pkg) {
       addPkgJsonEntryPoints(wsDir, pkg, entries);
-      const convention1 = path7.join(wsDir, "src", "index.ts");
-      if (fs7.existsSync(convention1)) entries.add(convention1);
-      const convention2 = path7.join(wsDir, "src", "main.ts");
-      if (fs7.existsSync(convention2)) entries.add(convention2);
-      const convention3 = path7.join(wsDir, "index.ts");
-      if (fs7.existsSync(convention3)) entries.add(convention3);
+      const convention1 = path8.join(wsDir, "src", "index.ts");
+      if (fs8.existsSync(convention1)) entries.add(convention1);
+      const convention2 = path8.join(wsDir, "src", "main.ts");
+      if (fs8.existsSync(convention2)) entries.add(convention2);
+      const convention3 = path8.join(wsDir, "index.ts");
+      if (fs8.existsSync(convention3)) entries.add(convention3);
     }
   }
   if (!rootPkg || !workspaces.length) {
     for (const name of ["src/index.ts", "src/main.ts", "index.ts"]) {
-      const convention = path7.join(projectRoot, name);
-      if (fs7.existsSync(convention)) entries.add(convention);
+      const convention = path8.join(projectRoot, name);
+      if (fs8.existsSync(convention)) entries.add(convention);
     }
   }
   return [...entries];
 }
 var BUILD_OUTPUT_DIRS = ["dist", "out", "build", "release"];
-var BUILD_OUTPUT_DIR_NAMES = BUILD_OUTPUT_DIRS.map((d) => `${path7.sep}${d}${path7.sep}`);
+var BUILD_OUTPUT_DIR_NAMES = BUILD_OUTPUT_DIRS.map((d) => `${path8.sep}${d}${path8.sep}`);
 function trySourceEquivalent(resolved) {
-  resolved = resolved.replace(/[/\\]/g, path7.sep);
+  resolved = resolved.replace(/[/\\]/g, path8.sep);
   for (const marker of BUILD_OUTPUT_DIR_NAMES) {
     const idx = resolved.indexOf(marker);
     if (idx === -1) continue;
-    const base = resolved.replace(marker, `${path7.sep}src${path7.sep}`);
+    const base = resolved.replace(marker, `${path8.sep}src${path8.sep}`);
     const candidate = base.replace(/\.(js|mjs|cjs)$/, ".ts");
-    if (candidate !== base && fs7.existsSync(candidate)) {
+    if (candidate !== base && fs8.existsSync(candidate)) {
       return candidate;
     }
     const dtsStripped = base.replace(/\.d\.ts$/, "");
     const candidateDts = dtsStripped + ".ts";
-    if (candidateDts !== base && candidateDts !== candidate && fs7.existsSync(candidateDts)) {
+    if (candidateDts !== base && candidateDts !== candidate && fs8.existsSync(candidateDts)) {
       return candidateDts;
     }
     const candidateNoExt = base + ".ts";
-    if (candidate !== candidateNoExt && candidateNoExt !== candidateDts && fs7.existsSync(candidateNoExt)) {
+    if (candidate !== candidateNoExt && candidateNoExt !== candidateDts && fs8.existsSync(candidateNoExt)) {
       return candidateNoExt;
     }
   }
@@ -2501,9 +2674,9 @@ function trySourceEquivalent(resolved) {
 }
 function tryAddEntryPath(pkgDir, rawPath, entries) {
   const resolved = resolveAgainst(pkgDir, rawPath);
-  if (fs7.existsSync(resolved)) entries.add(resolved);
+  if (fs8.existsSync(resolved)) entries.add(resolved);
   const tsResolved = resolved.replace(/\.(js|mjs|cjs)$/, ".ts");
-  if (tsResolved !== resolved && fs7.existsSync(tsResolved)) {
+  if (tsResolved !== resolved && fs8.existsSync(tsResolved)) {
     entries.add(tsResolved);
   }
   const srcAlt = trySourceEquivalent(resolved);
@@ -2547,18 +2720,18 @@ function expandGlobPattern(entry, projectRoot) {
   const dirs = [];
   if (entry.includes("*")) {
     const base = entry.replace(/\/\*+$/, "");
-    const baseDir = path7.resolve(projectRoot, base);
+    const baseDir = path8.resolve(projectRoot, base);
     try {
-      const children = fs7.readdirSync(baseDir, { withFileTypes: true });
+      const children = fs8.readdirSync(baseDir, { withFileTypes: true });
       for (const child of children) {
         if (child.isDirectory()) {
-          dirs.push(path7.join(baseDir, child.name));
+          dirs.push(path8.join(baseDir, child.name));
         }
       }
     } catch {
     }
   } else {
-    dirs.push(path7.resolve(projectRoot, entry));
+    dirs.push(path8.resolve(projectRoot, entry));
   }
   return dirs;
 }
@@ -2575,10 +2748,10 @@ function extractWorkspaceGlobs(pkg, projectRoot) {
   return dirs;
 }
 function extractPnpmWorkspaceDirs(projectRoot) {
-  const yamlPath = path7.join(projectRoot, "pnpm-workspace.yaml");
-  if (!fs7.existsSync(yamlPath)) return [];
+  const yamlPath = path8.join(projectRoot, "pnpm-workspace.yaml");
+  if (!fs8.existsSync(yamlPath)) return [];
   try {
-    const content = fs7.readFileSync(yamlPath, "utf8");
+    const content = fs8.readFileSync(yamlPath, "utf8");
     const dirs = [];
     let inPackages = false;
     const lines = content.split("\n");
@@ -2612,8 +2785,8 @@ function extractPnpmWorkspaceDirs(projectRoot) {
 }
 function resolveModulePath(importerPath, moduleSpecifier, indexedFiles) {
   if (!moduleSpecifier.startsWith(".")) return [];
-  const dir = path7.dirname(importerPath);
-  const base = path7.resolve(dir, moduleSpecifier);
+  const dir = path8.dirname(importerPath);
+  const base = path8.resolve(dir, moduleSpecifier);
   const results = [];
   const stripped = base.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, "");
   const skipBase = stripped !== base && /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(base);
@@ -2625,18 +2798,18 @@ function resolveModulePath(importerPath, moduleSpecifier, indexedFiles) {
     if (indexedFiles.has(candidate + ".jsx")) results.push(candidate + ".jsx");
     if (indexedFiles.has(candidate + ".mjs")) results.push(candidate + ".mjs");
     if (indexedFiles.has(candidate + ".cjs")) results.push(candidate + ".cjs");
-    if (indexedFiles.has(path7.join(candidate, "index.ts")))
-      results.push(path7.join(candidate, "index.ts"));
-    if (indexedFiles.has(path7.join(candidate, "index.tsx")))
-      results.push(path7.join(candidate, "index.tsx"));
-    if (indexedFiles.has(path7.join(candidate, "index.js")))
-      results.push(path7.join(candidate, "index.js"));
-    if (indexedFiles.has(path7.join(candidate, "index.jsx")))
-      results.push(path7.join(candidate, "index.jsx"));
-    if (indexedFiles.has(path7.join(candidate, "index.mjs")))
-      results.push(path7.join(candidate, "index.mjs"));
-    if (indexedFiles.has(path7.join(candidate, "index.cjs")))
-      results.push(path7.join(candidate, "index.cjs"));
+    if (indexedFiles.has(path8.join(candidate, "index.ts")))
+      results.push(path8.join(candidate, "index.ts"));
+    if (indexedFiles.has(path8.join(candidate, "index.tsx")))
+      results.push(path8.join(candidate, "index.tsx"));
+    if (indexedFiles.has(path8.join(candidate, "index.js")))
+      results.push(path8.join(candidate, "index.js"));
+    if (indexedFiles.has(path8.join(candidate, "index.jsx")))
+      results.push(path8.join(candidate, "index.jsx"));
+    if (indexedFiles.has(path8.join(candidate, "index.mjs")))
+      results.push(path8.join(candidate, "index.mjs"));
+    if (indexedFiles.has(path8.join(candidate, "index.cjs")))
+      results.push(path8.join(candidate, "index.cjs"));
   }
   return [...new Set(results)];
 }
@@ -2668,7 +2841,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
       symbolById.set(s.id, s);
     }
     const discoveredFiles = discoverEntryPoints(projectRoot, opts.userEntryPoints);
-    const entryFileSet = new Set(discoveredFiles.map((f) => path7.resolve(f)));
+    const entryFileSet = new Set(discoveredFiles.map((f) => path8.resolve(f)));
     const indexedFiles = /* @__PURE__ */ new Set();
     for (const s of allSymbols) indexedFiles.add(s.file);
     for (const fm of store.getAllFileMetas()) indexedFiles.add(fm.file);
@@ -2694,7 +2867,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
       if (scannedBarrels.has(epFile)) continue;
       scannedBarrels.add(epFile);
       try {
-        const content = fs7.readFileSync(epFile, "utf8");
+        const content = fs8.readFileSync(epFile, "utf8");
         const strippedContent = content.replace(/\/\*[\s\S]*?\*\//g, (m) => " ".repeat(m.length)).replace(/\/\/[^\n]*/g, (m) => " ".repeat(m.length));
         const reExportRe = /export\s+(?:(?:type\s+)?\{[\s\S]*?\}\s+from|\*\s+as\s+\w+\s+from|\*\s+from)\s+['"]([^'"]+)['"]/g;
         for (; ; ) {
@@ -2784,7 +2957,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
     const deadPackages = [];
     const pkgEntries = findPackageEntries(projectRoot);
     for (const [pkgName, pkgDir] of pkgEntries) {
-      const pkgFiles = allSymbols.filter((s) => s.file.startsWith(pkgDir + path7.sep));
+      const pkgFiles = allSymbols.filter((s) => s.file.startsWith(pkgDir + path8.sep));
       if (pkgFiles.length === 0) continue;
       const pkgUsed = pkgFiles.filter((s) => alive.has(s.id));
       if (pkgUsed.length === 0) {
@@ -2820,7 +2993,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
 }
 function findPackageEntries(projectRoot) {
   const pkgMap = /* @__PURE__ */ new Map();
-  const rootPkg = tryReadJson(path7.join(projectRoot, "package.json"));
+  const rootPkg = tryReadJson(path8.join(projectRoot, "package.json"));
   if (rootPkg && typeof rootPkg.name === "string") {
     pkgMap.set(rootPkg.name, projectRoot);
   }
@@ -2830,7 +3003,7 @@ function findPackageEntries(projectRoot) {
       wsDirs = extractPnpmWorkspaceDirs(projectRoot);
     }
     for (const wsDir of wsDirs) {
-      const wsPkg = tryReadJson(path7.join(wsDir, "package.json"));
+      const wsPkg = tryReadJson(path8.join(wsDir, "package.json"));
       if (wsPkg && typeof wsPkg.name === "string") {
         pkgMap.set(wsPkg.name, wsDir);
       }
@@ -2839,16 +3012,997 @@ function findPackageEntries(projectRoot) {
   return pkgMap;
 }
 
+// src/codebase-index/atlas-brief.ts
+import { existsSync as existsSync4 } from "node:fs";
+import * as path10 from "node:path";
+
+// src/codebase-index/atlas-projection.ts
+import { createHash } from "node:crypto";
+import { existsSync as existsSync3 } from "node:fs";
+import * as fs9 from "node:fs/promises";
+import * as path9 from "node:path";
+
+// src/codebase-index/atlas-export.ts
+var EXPORT_PACKAGE_LIMIT = 40;
+var EXPORT_FILE_LIMIT = 120;
+var CANVAS = { width: 1e3, height: 700 };
+var RADIUS = { min: 14, max: 46 };
+var ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => ESCAPES[character] ?? character);
+}
+function inlineJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function placePackages(packages) {
+  const shown = packages.slice(0, EXPORT_PACKAGE_LIMIT);
+  if (shown.length === 0) return [];
+  const maxRank = shown.reduce((max, pkg) => Math.max(max, pkg.rank), 0) || 1;
+  const centreX = CANVAS.width / 2;
+  const centreY = CANVAS.height / 2;
+  const placed = [];
+  let index = 0;
+  let ring = 0;
+  while (index < shown.length) {
+    const capacity = ring === 0 ? 1 : Math.min(ring * 6, shown.length - index);
+    const radius = ring === 0 ? 0 : ring * 115;
+    for (let slot = 0; slot < capacity && index < shown.length; slot++, index++) {
+      const pkg = shown[index];
+      const angle = slot / capacity * Math.PI * 2 - Math.PI / 2;
+      placed.push({
+        package: pkg,
+        x: centreX + Math.cos(angle) * radius,
+        y: centreY + Math.sin(angle) * radius * 0.68,
+        radius: RADIUS.min + pkg.rank / maxRank * (RADIUS.max - RADIUS.min)
+      });
+    }
+    ring++;
+  }
+  return placed;
+}
+var unit = (value) => value.toFixed(1);
+function renderSvg(document) {
+  const placed = placePackages(document.packages);
+  if (placed.length === 0) {
+    return '<p class="empty">No ranked packages to draw.</p>';
+  }
+  const at = new Map(placed.map((entry) => [entry.package.name, entry]));
+  const maxWeight = document.edges.reduce((max, edge) => Math.max(max, edge.weight), 0) || 1;
+  const lines = [
+    `<svg viewBox="0 0 ${CANVAS.width} ${CANVAS.height}" role="img" aria-label="Package dependency map">`
+  ];
+  for (const edge of document.edges) {
+    const from = at.get(edge.from);
+    const to = at.get(edge.to);
+    if (from === void 0 || to === void 0 || from === to) continue;
+    const strength = Math.min(1, edge.weight / maxWeight);
+    lines.push(
+      `<line x1="${unit(from.x)}" y1="${unit(from.y)}" x2="${unit(to.x)}" y2="${unit(to.y)}" stroke-width="${(0.5 + strength * 2.5).toFixed(2)}" stroke-opacity="${(0.12 + strength * 0.4).toFixed(2)}" />`
+    );
+  }
+  for (const entry of placed) {
+    const name = escapeHtml(entry.package.name);
+    const summary = entry.package.summary ?? "";
+    const title = escapeHtml(
+      `${entry.package.name} \u2014 ${entry.package.files} files, rank ${entry.package.rank.toFixed(4)}${summary === "" ? "" : `
+${summary}`}`
+    );
+    lines.push(
+      `<g class="pkg" data-package="${name}" tabindex="0">`,
+      `<title>${title}</title>`,
+      `<circle cx="${unit(entry.x)}" cy="${unit(entry.y)}" r="${unit(entry.radius)}" />`,
+      `<text x="${unit(entry.x)}" y="${unit(entry.y + entry.radius + 13)}">${name}</text>`,
+      "</g>"
+    );
+  }
+  lines.push("</svg>");
+  return lines.join("\n");
+}
+function renderFileRows(document) {
+  return document.files.slice(0, EXPORT_FILE_LIMIT).map((file) => {
+    const declarations = file.symbols.slice(0, 4).map((symbol) => escapeHtml(symbol.name)).join(", ");
+    const description = file.concept ?? declarations;
+    return `<tr data-package="${escapeHtml(file.package)}"><td class="num">${file.rank.toFixed(4)}</td><td class="path">${escapeHtml(file.path)}</td><td class="num">${file.inDeg}</td><td class="num">${file.outDeg}</td><td class="desc">${escapeHtml(description)}</td></tr>`;
+  }).join("\n");
+}
+function renderAtlasHtml(document, options = {}) {
+  const name = options.projectName ?? "Codebase";
+  const described = document.packages.filter((pkg) => pkg.summary !== void 0);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(name)} \u2014 Codebase Atlas</title>
+<style>
+:root {
+  color-scheme: light dark;
+  --bg: #ffffff; --fg: #16181d; --muted: #61656e; --line: #d9dce2;
+  --accent: #3b5bdb; --panel: #f6f7f9;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --bg: #101216; --fg: #e6e8ec; --muted: #9aa0ab; --line: #2a2e36;
+          --accent: #7c93f5; --panel: #171a20; }
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg);
+       font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
+header { padding: 24px 28px 12px; border-bottom: 1px solid var(--line); }
+h1 { margin: 0 0 4px; font-size: 20px; }
+h2 { margin: 28px 0 10px; font-size: 15px; text-transform: uppercase;
+     letter-spacing: .12em; color: var(--muted); }
+main { padding: 8px 28px 48px; max-width: 1180px; margin: 0 auto; }
+.counts { color: var(--muted); font-size: 12px; }
+figure { margin: 16px 0 0; border: 1px solid var(--line); background: var(--panel); }
+svg { display: block; width: 100%; height: auto; }
+svg line { stroke: var(--accent); }
+svg circle { fill: var(--accent); fill-opacity: .22; stroke: var(--accent); stroke-width: 1.5; }
+svg text { fill: var(--fg); font-size: 10px; text-anchor: middle; font-family: ui-monospace, monospace; }
+svg .pkg { cursor: pointer; }
+svg .pkg:hover circle, svg .pkg:focus circle { fill-opacity: .5; outline: none; }
+svg .pkg.muted { opacity: .25; }
+table { width: 100%; border-collapse: collapse; font-size: 12px; }
+th, td { padding: 5px 8px; border-bottom: 1px solid var(--line); text-align: left;
+         vertical-align: top; }
+th { color: var(--muted); font-weight: 600; font-size: 11px; text-transform: uppercase;
+     letter-spacing: .08em; }
+td.num { text-align: right; font-family: ui-monospace, monospace; white-space: nowrap; }
+td.path { font-family: ui-monospace, monospace; }
+td.desc { color: var(--muted); }
+tr[hidden] { display: none; }
+ul.subsystems { list-style: none; padding: 0; margin: 0; }
+ul.subsystems li { padding: 6px 0; border-bottom: 1px solid var(--line); }
+ul.subsystems b { font-family: ui-monospace, monospace; }
+.filter { margin: 10px 0 0; font-size: 12px; color: var(--muted); }
+.filter button { font: inherit; color: var(--accent); background: none; border: 0;
+                 cursor: pointer; padding: 0; text-decoration: underline; }
+.empty { color: var(--muted); }
+.wrap { overflow-x: auto; }
+footer { color: var(--muted); font-size: 11px; padding: 0 28px 32px; max-width: 1180px;
+         margin: 0 auto; }
+</style>
+</head>
+<body>
+<header>
+  <h1>${escapeHtml(name)} \u2014 Codebase Atlas</h1>
+  <p class="counts">${document.counts.files} files \xB7 ${document.counts.symbols} symbols \xB7 ${document.counts.packages} packages \xB7 ranking is PageRank over the reference graph, relative to this repository</p>
+</header>
+<main>
+  <h2>Package map</h2>
+  <figure>${renderSvg(document)}</figure>
+  <p class="filter" id="filter">Click a package to filter the table. <button type="button" id="clear" hidden>Clear filter</button></p>
+${described.length === 0 ? "" : `  <h2>Subsystems</h2>
+  <ul class="subsystems">
+${described.map((pkg) => `    <li><b>${escapeHtml(pkg.name)}</b> \u2014 ${escapeHtml(pkg.summary ?? "")}</li>`).join("\n")}
+  </ul>
+`}  <h2>Most central files</h2>
+  <div class="wrap">
+  <table>
+    <thead><tr><th>Rank</th><th>File</th><th>In</th><th>Out</th><th>What it is</th></tr></thead>
+    <tbody id="files">
+${renderFileRows(document)}
+    </tbody>
+  </table>
+  </div>
+</main>
+<footer>Generated from the codebase index by <code>/codebase-map --export</code>. Ranks are relative to this repository and mean nothing across repositories.</footer>
+<script id="atlas" type="application/json">${inlineJson({
+    counts: document.counts,
+    packages: document.packages,
+    edges: document.edges
+  })}</script>
+<script>
+(function () {
+  var rows = Array.prototype.slice.call(document.querySelectorAll('#files tr'));
+  var groups = Array.prototype.slice.call(document.querySelectorAll('svg .pkg'));
+  var clear = document.getElementById('clear');
+  var active = null;
+
+  function apply(name) {
+    active = name;
+    rows.forEach(function (row) {
+      row.hidden = name !== null && row.getAttribute('data-package') !== name;
+    });
+    groups.forEach(function (group) {
+      group.classList.toggle('muted', name !== null && group.getAttribute('data-package') !== name);
+    });
+    clear.hidden = name === null;
+  }
+
+  groups.forEach(function (group) {
+    var name = group.getAttribute('data-package');
+    function toggle() { apply(active === name ? null : name); }
+    group.addEventListener('click', toggle);
+    group.addEventListener('keydown', function (event) {
+      if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); toggle(); }
+    });
+  });
+  clear.addEventListener('click', function () { apply(null); });
+})();
+</script>
+</body>
+</html>
+`;
+}
+
+// src/codebase-index/atlas-projection.ts
+var ATLAS_DIR = path9.join(".wrongstack", "atlas");
+var ATLAS_JSON = "atlas.json";
+var ATLAS_MARKDOWN = "ATLAS.md";
+var ATLAS_MANIFEST = "manifest.json";
+var ATLAS_SCHEMA = 2;
+var ATLAS_FILE_LIMIT = 300;
+var SYMBOLS_PER_FILE = 6;
+var MARKDOWN_FILE_LIMIT = 60;
+var MARKDOWN_SYMBOLS_PER_FILE = 3;
+var RANK_PRECISION = 4;
+function round(value) {
+  return Number(value.toFixed(RANK_PRECISION));
+}
+function relativeFactory(projectRoot) {
+  return (file) => {
+    const relative12 = path9.relative(projectRoot, file);
+    if (!relative12 || relative12.startsWith("..")) return posixIndexPath(file);
+    return posixIndexPath(relative12);
+  };
+}
+function digestOf(entries) {
+  const hash = createHash("sha256");
+  for (const [file, contentHash] of [...entries].sort((a, b) => a[0] < b[0] ? -1 : 1)) {
+    hash.update(file);
+    hash.update("\0");
+    hash.update(contentHash);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+function renderMarkdown(document) {
+  const lines = [
+    "# Codebase Atlas",
+    "",
+    "Generated from the codebase index. Do not edit by hand \u2014 run `/codebase-map --write`.",
+    "",
+    `- Indexed files: ${document.counts.files}`,
+    `- Indexed symbols: ${document.counts.symbols}`,
+    `- Packages: ${document.counts.packages}`,
+    "",
+    "Ranking is PageRank over the reference graph (calls, imports, type references,",
+    "inheritance). `1.0000` is the most central file in this repository; the scores",
+    "are relative to this repository only.",
+    "",
+    "## Packages",
+    "",
+    "| Package | Files | Hub | Rank |",
+    "| --- | ---: | --- | ---: |"
+  ];
+  for (const pkg of document.packages) {
+    lines.push(`| ${pkg.name} | ${pkg.files} | \`${pkg.hub}\` | ${pkg.rank.toFixed(4)} |`);
+  }
+  const described = document.packages.filter((pkg) => pkg.summary !== void 0);
+  if (described.length > 0) {
+    lines.push("", "## Subsystems", "");
+    for (const pkg of described) {
+      lines.push(`- **${pkg.name}** \u2014 ${pkg.summary}`);
+    }
+  }
+  lines.push(
+    "",
+    `## Most central files (top ${Math.min(MARKDOWN_FILE_LIMIT, document.files.length)} of ${document.files.length})`,
+    "",
+    `The full ranking, with every declaration, is in \`${ATLAS_JSON}\`.`,
+    "",
+    "| Rank | File | In | Out | Declarations |",
+    "| ---: | --- | ---: | ---: | --- |"
+  );
+  for (const file of document.files.slice(0, MARKDOWN_FILE_LIMIT)) {
+    const declarations = file.symbols.slice(0, MARKDOWN_SYMBOLS_PER_FILE).map((symbol) => `\`${symbol.name}\``).join(", ");
+    lines.push(
+      `| ${file.rank.toFixed(4)} | \`${file.path}\` | ${file.inDeg} | ${file.outDeg} | ${declarations} |`
+    );
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function buildAtlas(store, projectRoot) {
+  const relativeOf = relativeFactory(projectRoot);
+  const stats = store.getStats();
+  const packageCounts = store.getPackageFileCounts();
+  const ranked = store.getRankedFiles(ATLAS_FILE_LIMIT);
+  const concepts = store.getReadyConceptSummaries();
+  const subsystemSummaries = new Map(
+    store.getSubsystems().map((subsystem) => [subsystem.id, subsystem.summary])
+  );
+  const packages = /* @__PURE__ */ new Map();
+  const packageNameOf = (row) => row.package || relativeOf(row.file).split("/")[0] || "(root)";
+  for (const row of ranked) {
+    const relative12 = relativeOf(row.file);
+    const name = packageNameOf(row);
+    const existing = packages.get(name);
+    if (existing === void 0) {
+      const summary = subsystemSummaries.get(name);
+      packages.set(name, {
+        name,
+        files: packageCounts.get(row.package) ?? 0,
+        hub: relative12,
+        rank: round(row.rank),
+        // Absent rather than empty: an un-enriched repository must project the
+        // same bytes it projected before the concept layer existed.
+        ...summary !== void 0 && summary !== "" ? { summary } : {}
+      });
+      continue;
+    }
+    if (row.rank > existing.rank) {
+      existing.hub = relative12;
+      existing.rank = round(row.rank);
+    }
+  }
+  const files = ranked.map((row) => {
+    const symbols = store.getFileSymbols(row.file, SYMBOLS_PER_FILE).map((symbol) => ({ name: symbol.name, kind: symbol.kind, line: symbol.line }));
+    const concept = concepts.get(row.file);
+    return {
+      path: relativeOf(row.file),
+      rank: round(row.rank),
+      inDeg: row.inDeg,
+      outDeg: row.outDeg,
+      package: packageNameOf(row),
+      symbols,
+      ...concept !== void 0 && concept !== "" ? { concept } : {}
+    };
+  });
+  const known = new Set(packages.keys());
+  const edges = store.getPackageGraph().edges.map((edge) => ({
+    from: edge.source.replace(/^pkg:/, ""),
+    to: edge.target.replace(/^pkg:/, ""),
+    weight: edge.weight,
+    refType: edge.refType
+  })).filter((edge) => known.has(edge.from) && known.has(edge.to)).sort(
+    (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.refType.localeCompare(b.refType)
+  );
+  const document = {
+    schema: ATLAS_SCHEMA,
+    counts: { files: stats.totalFiles, symbols: stats.totalSymbols, packages: packages.size },
+    packages: [...packages.values()].sort(
+      (a, b) => b.rank - a.rank || a.name.localeCompare(b.name)
+    ),
+    edges,
+    files
+  };
+  const allHashes = store.getAllFileMetas().map((meta) => [relativeOf(meta.file), meta.contentHash ?? ""]);
+  const atlasPaths = new Set(files.map((file) => file.path));
+  const manifestFiles = {};
+  for (const [file, hash] of [...allHashes].sort((a, b) => a[0] < b[0] ? -1 : 1)) {
+    if (atlasPaths.has(file)) manifestFiles[file] = hash;
+  }
+  const manifest = {
+    schema: ATLAS_SCHEMA,
+    counts: {
+      files: document.counts.files,
+      symbols: document.counts.symbols,
+      tracked: allHashes.length
+    },
+    digest: digestOf(allHashes),
+    files: manifestFiles
+  };
+  return { document, manifest, markdown: renderMarkdown(document) };
+}
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+async function writeAtlas(store, projectRoot) {
+  const projection = buildAtlas(store, projectRoot);
+  const dir = path9.join(projectRoot, ATLAS_DIR);
+  await fs9.mkdir(dir, { recursive: true });
+  const written = [
+    [ATLAS_JSON, stableJson(projection.document)],
+    [ATLAS_MANIFEST, stableJson(projection.manifest)],
+    [ATLAS_MARKDOWN, projection.markdown]
+  ];
+  for (const [name, body] of written) {
+    await fs9.writeFile(path9.join(dir, name), body, "utf8");
+  }
+  return {
+    dir: posixIndexPath(ATLAS_DIR),
+    files: written.map(([name]) => name),
+    fileCount: projection.document.files.length,
+    packageCount: projection.document.packages.length
+  };
+}
+var MAX_REPORTED_DRIFT = 20;
+async function checkAtlasFreshness(store, projectRoot) {
+  const stale = (reason) => ({
+    fresh: false,
+    reason,
+    changed: [],
+    removed: [],
+    added: 0,
+    digestMatches: false
+  });
+  let raw;
+  try {
+    raw = await fs9.readFile(path9.join(projectRoot, ATLAS_DIR, ATLAS_MANIFEST), "utf8");
+  } catch {
+    return stale("missing");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    return stale("unreadable");
+  }
+  if (manifest?.schema !== ATLAS_SCHEMA || typeof manifest.files !== "object") {
+    return stale("schema");
+  }
+  const relativeOf = relativeFactory(projectRoot);
+  const live = /* @__PURE__ */ new Map();
+  const allHashes = [];
+  for (const meta of store.getAllFileMetas()) {
+    const relative12 = relativeOf(meta.file);
+    const hash = meta.contentHash ?? "";
+    live.set(relative12, hash);
+    allHashes.push([relative12, hash]);
+  }
+  const changed = [];
+  const removed = [];
+  for (const [file, hash] of Object.entries(manifest.files)) {
+    const current = live.get(file);
+    if (current === void 0) {
+      removed.push(file);
+      continue;
+    }
+    if (hash !== "" && current !== "" && hash !== current) changed.push(file);
+  }
+  const digestMatches = digestOf(allHashes) === manifest.digest;
+  const tracked = typeof manifest.counts?.tracked === "number" ? manifest.counts.tracked : live.size;
+  const added = Math.max(0, live.size - tracked);
+  const fresh = digestMatches && changed.length === 0 && removed.length === 0;
+  return {
+    fresh,
+    ...fresh ? {} : { reason: "drift" },
+    changed: changed.sort().slice(0, MAX_REPORTED_DRIFT),
+    removed: removed.sort().slice(0, MAX_REPORTED_DRIFT),
+    added,
+    digestMatches
+  };
+}
+function hasIndex(projectRoot, indexDir) {
+  return existsSync3(path9.join(resolveIndexDir(projectRoot, indexDir), "index.db"));
+}
+async function withStore(projectRoot, indexDir, job) {
+  if (!hasIndex(projectRoot, indexDir)) return { indexed: false };
+  const store = indexStorePool.acquire(projectRoot, { indexDir });
+  try {
+    return await job(store);
+  } finally {
+    indexStorePool.release(store);
+  }
+}
+function writeProjectAtlas(projectRoot, opts = {}) {
+  return withStore(projectRoot, opts.indexDir, (store) => writeAtlas(store, projectRoot));
+}
+function checkProjectAtlasFreshness(projectRoot, opts = {}) {
+  return withStore(projectRoot, opts.indexDir, (store) => checkAtlasFreshness(store, projectRoot));
+}
+function exportProjectAtlasHtml(projectRoot, opts = {}) {
+  return withStore(
+    projectRoot,
+    opts.indexDir,
+    (store) => renderAtlasHtml(buildAtlas(store, projectRoot).document, {
+      projectName: opts.projectName ?? path9.basename(projectRoot)
+    })
+  );
+}
+
+// src/codebase-index/atlas-brief.ts
+var BRIEF_HUB_LIMIT = 20;
+var BRIEF_PACKAGE_LIMIT = 12;
+var BRIEF_SUBSYSTEM_LIMIT = 10;
+var BRIEF_SUMMARY_CHARS = 160;
+function trim(text) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  return clean.length > BRIEF_SUMMARY_CHARS ? `${clean.slice(0, BRIEF_SUMMARY_CHARS - 1).trimEnd()}\u2026` : clean;
+}
+async function buildAtlasBrief(store, projectRoot) {
+  const relativeOf = (file) => {
+    const relative12 = path10.relative(projectRoot, file);
+    return posixIndexPath(relative12 && !relative12.startsWith("..") ? relative12 : file);
+  };
+  const stats = store.getStats();
+  const concepts = store.getReadyConceptSummaries();
+  const ranked = store.getRankedFiles(BRIEF_HUB_LIMIT);
+  const hubs = ranked.map((row) => {
+    const concept = concepts.get(row.file);
+    return {
+      path: relativeOf(row.file),
+      rank: row.rank,
+      ...concept !== void 0 && concept !== "" ? { concept: trim(concept) } : {}
+    };
+  });
+  const counts = store.getPackageFileCounts();
+  const hubOf = /* @__PURE__ */ new Map();
+  for (const row of store.getRankedFiles(Math.max(counts.size * 4, BRIEF_HUB_LIMIT))) {
+    const name = row.package || relativeOf(row.file).split("/")[0] || "(root)";
+    const current = hubOf.get(name);
+    if (current === void 0 || row.rank > current.rank) {
+      hubOf.set(name, { file: relativeOf(row.file), rank: row.rank });
+    }
+  }
+  const packages = [...hubOf.entries()].sort((a, b) => b[1].rank - a[1].rank || a[0].localeCompare(b[0])).slice(0, BRIEF_PACKAGE_LIMIT).map(([name, hub]) => ({ name, files: counts.get(name) ?? 0, hub: hub.file }));
+  const subsystems = store.getSubsystems().filter((subsystem) => subsystem.summary !== "").slice(0, BRIEF_SUBSYSTEM_LIMIT).map((subsystem) => ({ name: subsystem.name, summary: trim(subsystem.summary) }));
+  const brief = {
+    ranked: hubs.length > 0,
+    counts: {
+      files: stats.totalFiles,
+      symbols: stats.totalSymbols,
+      packages: counts.size
+    },
+    hubs,
+    packages,
+    subsystems
+  };
+  try {
+    const freshness = await checkAtlasFreshness(store, projectRoot);
+    if (freshness.reason !== "missing") {
+      brief.staleFiles = freshness.changed.length + freshness.removed.length + freshness.added;
+    }
+  } catch {
+  }
+  return brief;
+}
+async function buildProjectAtlasBrief(projectRoot, opts = {}) {
+  if (!existsSync4(path10.join(resolveIndexDir(projectRoot, opts.indexDir), "index.db"))) {
+    return { indexed: false };
+  }
+  const store = indexStorePool.acquire(projectRoot, { indexDir: opts.indexDir });
+  try {
+    return await buildAtlasBrief(store, projectRoot);
+  } finally {
+    indexStorePool.release(store);
+  }
+}
+
+// src/codebase-index/codebase-context-tool.ts
+import { ToolValidationError as ToolValidationError5 } from "@wrongstack/core/types";
+import { toErrorMessage as toErrorMessage11 } from "@wrongstack/core/utils";
+var TOOL_TIMEOUT_MS = 35e3;
+var VECTOR_HIT_LIMIT = 12;
+var VECTOR_MIN_SCORE = 0.25;
+var queryEmbedder;
+function setContextQueryEmbedder(port) {
+  queryEmbedder = port;
+}
+async function semanticSeeds(projectRoot, indexDir, query) {
+  const port = queryEmbedder;
+  if (port === void 0) return [];
+  try {
+    const [vector] = await port.embed([query]);
+    if (vector === void 0 || vector.length !== port.dimensions) return [];
+    const result = await codebaseVectorSearch({
+      projectRoot,
+      indexDir,
+      vector: Array.from(vector),
+      limit: VECTOR_HIT_LIMIT,
+      minScore: VECTOR_MIN_SCORE
+    });
+    return result.hits;
+  } catch {
+    return [];
+  }
+}
+var codebaseContextTool = {
+  name: "codebase-context",
+  category: "Project",
+  icon: "index",
+  permission: "auto",
+  mutating: false,
+  capabilities: ["fs.read"],
+  timeoutMs: TOOL_TIMEOUT_MS,
+  description: "Find the files and declarations a task touches, from a plain-language description. Combines ranked symbol search with a personalised walk over the reference graph, so results include not just what matched by name but what those matches are structurally attached to \u2014 the interface behind a handler, the store behind a route, the module every match imports. Returns ranked files with the relevant declarations, their signatures and line numbers.",
+  usageHint: 'START HERE FOR ANY TASK THAT SPANS MORE THAN ONE FILE:\n\n- Describe the task, not a symbol name: `codebase-context({ query: "retry a provider request after a 429" })`.\n- Prefer this over `codebase-search` when you do not already know the symbol you want; prefer `codebase-search` when you do.\n- Use the returned `file` + `line` to `read` only the parts you need, instead of reading whole files.\n- `matched: true` means the file matched the query directly; the rest were reached through the graph.\n- `relevance` is relative to this answer only (top result is always 1.0) \u2014 never compare it across queries.\n- Narrow with `pathPrefix: "packages/core"` when you already know the area.\n- `indexStatus: "no-index"` means run `/codebase-reindex` first.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "What you are trying to do or understand, in plain words."
+      },
+      limit: {
+        type: "number",
+        description: "Number of files to return (default 12, max 50)."
+      },
+      symbolsPerFile: {
+        type: "number",
+        description: "Declarations shown per file (default 4, max 20)."
+      },
+      pathPrefix: {
+        type: "string",
+        description: "Restrict results to this project-relative path prefix."
+      }
+    },
+    required: ["query"],
+    additionalProperties: false
+  },
+  async execute(input, ctx, execOpts) {
+    const query = typeof input.query === "string" ? input.query.trim() : "";
+    if (query.length === 0) {
+      throw new ToolValidationError5({
+        message: "codebase-context requires a non-empty `query`.",
+        field: "query"
+      });
+    }
+    const signal = execOpts?.signal ?? ctx.signal;
+    const projectRoot = ctx.projectRoot ?? ctx.cwd ?? process.cwd();
+    try {
+      signal?.throwIfAborted();
+      const indexDir = codebaseIndexDirOverride(ctx);
+      const vectorFiles = await semanticSeeds(projectRoot, indexDir, query);
+      signal?.throwIfAborted();
+      const result = await codebaseContext({
+        projectRoot,
+        indexDir,
+        query,
+        ...vectorFiles.length > 0 ? { vectorFiles } : {},
+        limit: input.limit,
+        symbolsPerFile: input.symbolsPerFile,
+        pathPrefix: input.pathPrefix
+      });
+      return {
+        query: result.query,
+        entries: result.entries,
+        seedCount: result.seedCount,
+        semanticSeedCount: result.semanticSeedCount,
+        totalCandidates: result.totalCandidates,
+        indexStatus: result.indexStatus,
+        ..."stale" in result && result.stale === true ? { stale: true } : {}
+      };
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      const refreshing = err instanceof Error && err.name === "IndexRefreshInProgressError";
+      return {
+        query,
+        entries: [],
+        seedCount: 0,
+        semanticSeedCount: 0,
+        totalCandidates: 0,
+        indexStatus: "error",
+        error: refreshing ? "Codebase index is refreshing; retry once the current generation is published." : toErrorMessage11(err)
+      };
+    }
+  }
+};
+
+// src/codebase-index/concept-enrichment.ts
+import { existsSync as existsSync5 } from "node:fs";
+import * as fs10 from "node:fs/promises";
+import * as path11 from "node:path";
+var MAX_SOURCE_CHARS = 12e3;
+var MAX_CRUX_LINES = 12;
+var MAX_DECLARATIONS = 24;
+var DEFAULT_CONCURRENCY = 5;
+var MAX_SUMMARY_CHARS = 400;
+function normaliseCrux(result, lineCount) {
+  const rawStart = result.cruxStart;
+  const rawEnd = result.cruxEnd;
+  if (typeof rawStart !== "number" || !Number.isFinite(rawStart)) return { start: null, end: null };
+  const start = Math.max(1, Math.min(Math.trunc(rawStart), lineCount));
+  const proposedEnd = typeof rawEnd === "number" && Number.isFinite(rawEnd) ? Math.trunc(rawEnd) : start;
+  const end = Math.max(start, Math.min(proposedEnd, lineCount, start + MAX_CRUX_LINES - 1));
+  return { start, end };
+}
+async function enrichConcepts(store, port, relativeOf, options = {}) {
+  const startedAt = Date.now();
+  const errors = [];
+  const signal = options.signal;
+  const concurrency = Math.max(1, Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, 16));
+  const pruned = store.pruneOrphanConcepts();
+  const markedStale = store.markStaleConcepts();
+  const hashByFile = /* @__PURE__ */ new Map();
+  for (const meta of store.getAllFileMetas()) hashByFile.set(meta.file, meta.contentHash ?? "");
+  const existing = /* @__PURE__ */ new Map();
+  for (const concept of store.getAllFileConcepts()) existing.set(concept.file, concept);
+  const rankOf = /* @__PURE__ */ new Map();
+  for (const row of store.getRankedFiles(hashByFile.size || 1)) rankOf.set(row.file, row.rank);
+  const ordered = [...hashByFile.keys()].sort(
+    (a, b) => (rankOf.get(b) ?? 0) - (rankOf.get(a) ?? 0) || a.localeCompare(b)
+  );
+  const queue = [];
+  let cached = 0;
+  for (const file of ordered) {
+    const hash = hashByFile.get(file);
+    if (hash === void 0) continue;
+    const concept = existing.get(file);
+    const current = concept !== void 0 && concept.state === "ready" && concept.contentHash === hash;
+    if (current && options.force !== true) {
+      cached++;
+      continue;
+    }
+    queue.push(file);
+    if (options.maxFiles !== void 0 && queue.length >= options.maxFiles) break;
+  }
+  let summarised = 0;
+  let failed = 0;
+  let done = 0;
+  let cursor = 0;
+  const worker = async () => {
+    for (; ; ) {
+      if (signal?.aborted) return;
+      const index = cursor++;
+      const file = queue[index];
+      if (file === void 0) return;
+      try {
+        const result = await summariseOne(
+          store,
+          port,
+          relativeOf,
+          file,
+          hashByFile,
+          existing,
+          signal
+        );
+        if (result === "skipped") failed++;
+        else summarised++;
+      } catch (error) {
+        failed++;
+        if (errors.length < 50) {
+          errors.push(
+            `${relativeOf(file)}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      } finally {
+        done++;
+        options.onProgress?.(done, queue.length);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, () => worker()));
+  let subsystems = 0;
+  if (options.subsystems === true && port.describeSubsystem !== void 0 && signal?.aborted !== true) {
+    try {
+      subsystems = await deriveSubsystems(store, port, relativeOf, signal);
+    } catch (error) {
+      errors.push(`subsystems: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return {
+    summarised,
+    cached,
+    failed,
+    markedStale,
+    pruned,
+    subsystems,
+    durationMs: Date.now() - startedAt,
+    errors
+  };
+}
+async function summariseOne(store, port, relativeOf, file, hashByFile, existing, signal) {
+  let source;
+  try {
+    source = await fs10.readFile(file, "utf8");
+  } catch {
+    return "skipped";
+  }
+  if (source.trim().length === 0) return "skipped";
+  const truncated = source.length > MAX_SOURCE_CHARS;
+  const declarations = store.getFileSymbols(file, MAX_DECLARATIONS).map((symbol) => ({ name: symbol.name, kind: symbol.kind, line: symbol.line }));
+  const stale = existing.get(file);
+  const result = await port.describeFile({
+    file: relativeOf(file),
+    absolutePath: file,
+    language: "",
+    source: truncated ? source.slice(0, MAX_SOURCE_CHARS) : source,
+    truncated,
+    declarations,
+    ...stale !== void 0 && stale.summary !== "" ? { staleSummary: stale.summary } : {},
+    signal
+  });
+  const summary = result?.summary?.trim() ?? "";
+  if (summary.length === 0) return "skipped";
+  const lineCount = source.split("\n").length;
+  const crux = normaliseCrux(result, lineCount);
+  store.upsertFileConcept({
+    file,
+    contentHash: hashByFile.get(file) ?? "",
+    summary: summary.slice(0, MAX_SUMMARY_CHARS),
+    cruxStart: crux.start,
+    cruxEnd: crux.end,
+    state: "ready",
+    model: result?.model ?? "",
+    updatedAt: Date.now()
+  });
+  return "stored";
+}
+var SUBSYSTEM_FILE_SAMPLE = 12;
+async function deriveSubsystems(store, port, relativeOf, signal) {
+  const describe = port.describeSubsystem;
+  if (describe === void 0) return 0;
+  const summaries = store.getReadyConceptSummaries();
+  if (summaries.size === 0) return 0;
+  const byPackage = /* @__PURE__ */ new Map();
+  for (const row of store.getRankedFiles(summaries.size * 2)) {
+    const summary = summaries.get(row.file);
+    if (summary === void 0) continue;
+    const name = row.package || relativeOf(row.file).split("/")[0] || "(root)";
+    const bucket = byPackage.get(name);
+    const entry = { file: relativeOf(row.file), summary, rank: row.rank };
+    if (bucket === void 0) byPackage.set(name, [entry]);
+    else if (bucket.length < SUBSYSTEM_FILE_SAMPLE) bucket.push(entry);
+  }
+  const names = [...byPackage.keys()].sort();
+  const known = new Set(names);
+  const subsystems = [];
+  const edges = [];
+  for (const name of names) {
+    if (signal?.aborted) break;
+    const files = byPackage.get(name) ?? [];
+    const result = await describe({ name, files, signal });
+    const summary = result?.summary?.trim() ?? "";
+    if (summary.length === 0) continue;
+    subsystems.push({
+      id: name,
+      name,
+      summary: summary.slice(0, MAX_SUMMARY_CHARS),
+      memberFiles: files.map((f) => f.file),
+      model: result?.model ?? "",
+      updatedAt: Date.now()
+    });
+    for (const relation of result?.relations ?? []) {
+      if (!known.has(relation.to) || relation.to === name) continue;
+      if (!isConceptRelation(relation.relation)) continue;
+      edges.push({ fromId: name, toId: relation.to, relation: relation.relation });
+    }
+  }
+  store.replaceSubsystems(subsystems, edges);
+  return subsystems.length;
+}
+async function enrichProjectConcepts(projectRoot, port, options = {}) {
+  const { indexDir, ...rest } = options;
+  if (!existsSync5(path11.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
+    return { indexed: false };
+  }
+  const store = indexStorePool.acquire(projectRoot, { indexDir });
+  try {
+    return await enrichConcepts(
+      store,
+      port,
+      (file) => {
+        const relative12 = path11.relative(projectRoot, file);
+        const chosen = relative12 && !relative12.startsWith("..") ? relative12 : file;
+        return posixIndexPath(chosen);
+      },
+      rest
+    );
+  } finally {
+    indexStorePool.release(store);
+  }
+}
+
+// src/codebase-index/embedding-pass.ts
+import { existsSync as existsSync6 } from "node:fs";
+import * as path12 from "node:path";
+var DEFAULT_BATCH_SIZE = 16;
+var MAX_EMBED_CHARS = 2e3;
+var FALLBACK_DECLARATIONS = 12;
+function embedTextFor(relativePath, summary, declarations) {
+  const described = summary?.trim() ?? "";
+  if (described.length > 0) {
+    return {
+      text: `${relativePath}
+${described}`.slice(0, MAX_EMBED_CHARS),
+      fromDeclarations: false
+    };
+  }
+  const names = declarations.slice(0, FALLBACK_DECLARATIONS).join(", ");
+  return {
+    text: `${relativePath}${names.length > 0 ? `
+${names}` : ""}`.slice(0, MAX_EMBED_CHARS),
+    fromDeclarations: true
+  };
+}
+async function embedFiles(store, port, relativeOf, options = {}) {
+  const startedAt = Date.now();
+  const errors = [];
+  const signal = options.signal;
+  const batchSize = Math.max(1, Math.min(options.batchSize ?? DEFAULT_BATCH_SIZE, 128));
+  const providerChanged = store.reconcileVectorProvider(port.id);
+  const pruned = store.pruneOrphanFileVectors();
+  const stored = store.getFileVectorStates(port.id);
+  const summaries = store.getReadyConceptSummaries();
+  const rankOf = /* @__PURE__ */ new Map();
+  const metas = store.getAllFileMetas();
+  for (const row of store.getRankedFiles(metas.length || 1)) rankOf.set(row.file, row.rank);
+  const ordered = metas.map((meta) => meta.file).sort((a, b) => (rankOf.get(b) ?? 0) - (rankOf.get(a) ?? 0) || a.localeCompare(b));
+  const queue = [];
+  let cached = 0;
+  for (const file of ordered) {
+    const declarations = summaries.has(file) ? [] : store.getFileSymbols(file, FALLBACK_DECLARATIONS).map((symbol) => symbol.name);
+    const { text, fromDeclarations: fromDeclarations2 } = embedTextFor(
+      relativeOf(file),
+      summaries.get(file),
+      declarations
+    );
+    if (text.trim().length === 0) continue;
+    const hash = xxhash64String(text);
+    if (options.force !== true && stored.get(file) === hash) {
+      cached++;
+      continue;
+    }
+    queue.push({ file, text, hash, fromDeclarations: fromDeclarations2 });
+    if (options.maxFiles !== void 0 && queue.length >= options.maxFiles) break;
+  }
+  let embedded = 0;
+  let fromDeclarations = 0;
+  let done = 0;
+  for (let start = 0; start < queue.length; start += batchSize) {
+    if (signal?.aborted) break;
+    const batch = queue.slice(start, start + batchSize);
+    try {
+      const vectors = await port.embed(batch.map((entry) => entry.text));
+      const rows = [];
+      for (let i = 0; i < batch.length; i++) {
+        const entry = batch[i];
+        const vector = vectors[i];
+        if (vector === void 0 || vector.length !== port.dimensions) continue;
+        rows.push({ file: entry.file, vector, sourceHash: entry.hash, provider: port.id });
+        if (entry.fromDeclarations) fromDeclarations++;
+      }
+      store.upsertFileVectors(rows);
+      embedded += rows.length;
+    } catch (error) {
+      if (errors.length < 20) {
+        errors.push(`batch at ${start}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    } finally {
+      done += batch.length;
+      options.onProgress?.(done, queue.length);
+    }
+  }
+  return {
+    embedded,
+    cached,
+    pruned,
+    providerChanged,
+    fromDeclarations,
+    durationMs: Date.now() - startedAt,
+    errors
+  };
+}
+async function embedProjectFiles(projectRoot, port, options = {}) {
+  const { indexDir, ...rest } = options;
+  if (!existsSync6(path12.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
+    return { indexed: false };
+  }
+  const store = indexStorePool.acquire(projectRoot, { indexDir });
+  try {
+    return await embedFiles(
+      store,
+      port,
+      (file) => {
+        const relative12 = path12.relative(projectRoot, file);
+        return posixIndexPath(relative12 && !relative12.startsWith("..") ? relative12 : file);
+      },
+      rest
+    );
+  } finally {
+    indexStorePool.release(store);
+  }
+}
+
 export {
   PolyglotInvariantEngine,
   polyglotInvariantEngine,
   replaceSymbolInFile,
   codebaseAstReplaceTool,
-  codebaseInvariantCheckTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseSearchTool,
   codebaseIndexTool,
+  codebaseInvariantCheckTool,
   codebaseOutgoingCallsTool,
   extractFileSkeleton,
   extractDirectorySkeleton,
@@ -2858,6 +4012,39 @@ export {
   codebaseStatsTool,
   codebaseTargetedTestTool,
   deadCodeScanTool,
-  runDeadCodeScan
+  runDeadCodeScan,
+  EXPORT_PACKAGE_LIMIT,
+  EXPORT_FILE_LIMIT,
+  renderAtlasHtml,
+  ATLAS_DIR,
+  ATLAS_JSON,
+  ATLAS_MARKDOWN,
+  ATLAS_MANIFEST,
+  ATLAS_SCHEMA,
+  ATLAS_FILE_LIMIT,
+  buildAtlas,
+  writeAtlas,
+  MAX_REPORTED_DRIFT,
+  checkAtlasFreshness,
+  writeProjectAtlas,
+  checkProjectAtlasFreshness,
+  exportProjectAtlasHtml,
+  BRIEF_HUB_LIMIT,
+  BRIEF_PACKAGE_LIMIT,
+  BRIEF_SUBSYSTEM_LIMIT,
+  buildAtlasBrief,
+  buildProjectAtlasBrief,
+  setContextQueryEmbedder,
+  codebaseContextTool,
+  MAX_SOURCE_CHARS,
+  MAX_CRUX_LINES,
+  DEFAULT_CONCURRENCY,
+  MAX_SUMMARY_CHARS,
+  enrichConcepts,
+  enrichProjectConcepts,
+  DEFAULT_BATCH_SIZE,
+  MAX_EMBED_CHARS,
+  embedFiles,
+  embedProjectFiles
 };
-//# sourceMappingURL=chunk-YEISRT4S.js.map
+//# sourceMappingURL=chunk-PNLDTRC5.js.map