@vohongtho.infotech/code-intel 0.5.0 → 0.7.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
-import path27 from 'path';
-import fs19, { existsSync } from 'fs';
+import path29 from 'path';
+import fs23, { existsSync } from 'fs';
 import { Parser, Language, Query } from 'web-tree-sitter';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
@@ -126,11 +126,11 @@ var init_shared = __esm({
   }
 });
 function findBundledWasmDir() {
-  const fileDir = path27.dirname(fileURLToPath(import.meta.url));
+  const fileDir = path29.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path27.join(fileDir, "wasm"),
+    path29.join(fileDir, "wasm"),
     // dist/index.js → dist/wasm/
-    path27.join(fileDir, "../wasm")
+    path29.join(fileDir, "../wasm")
     // dist/cli/main.js → dist/wasm/
   ];
   for (const candidate of candidates) {
@@ -171,7 +171,7 @@ function wasmPath(lang) {
   }
   const bundled = BUNDLED_WASM_MAP[lang];
   if (bundled) {
-    const bundledPath = path27.join(_bundledWasmDir, bundled);
+    const bundledPath = path29.join(_bundledWasmDir, bundled);
     if (existsSync(bundledPath)) return bundledPath;
   }
   return null;
@@ -184,14 +184,14 @@ async function initParser() {
 }
 async function getLanguage(lang) {
   if (languageCache.has(lang)) return languageCache.get(lang);
-  const path28 = wasmPath(lang);
-  if (!path28) {
+  const path30 = wasmPath(lang);
+  if (!path30) {
     languageCache.set(lang, null);
     return null;
   }
   try {
     await initParser();
-    const language = await Language.load(path28);
+    const language = await Language.load(path30);
     languageCache.set(lang, language);
     return language;
   } catch {
@@ -1162,7 +1162,7 @@ var init_logger = __esm({
         };
       }
       /** Global log directory: ~/.code-intel/logs */
-      static LOG_DIR = path27.join(os12.homedir(), ".code-intel", "logs");
+      static LOG_DIR = path29.join(os12.homedir(), ".code-intel", "logs");
       static getLogger() {
         if (!_Logger.instance) {
           const isProduction = process.env.NODE_ENV === "production";
@@ -1171,12 +1171,12 @@ var init_logger = __esm({
           transports.push(new winston.transports.Console());
           if (!isProduction) {
             try {
-              if (!fs19.existsSync(_Logger.LOG_DIR)) {
-                fs19.mkdirSync(_Logger.LOG_DIR, { recursive: true });
+              if (!fs23.existsSync(_Logger.LOG_DIR)) {
+                fs23.mkdirSync(_Logger.LOG_DIR, { recursive: true });
               }
               transports.push(
                 new DailyRotateFile({
-                  filename: path27.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
+                  filename: path29.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
                   datePattern: "YYYY-MM-DD",
                   maxSize: "20m",
                   maxFiles: "14d"
@@ -1961,7 +1961,7 @@ var init_parse_phase = __esm({
           const batch = filePaths.slice(i, i + CONCURRENCY);
           await Promise.all(batch.map(async (filePath) => {
             try {
-              const source = await fs19.promises.readFile(filePath, "utf-8");
+              const source = await fs23.promises.readFile(filePath, "utf-8");
               context2.fileCache.set(filePath, source);
             } catch {
             }
@@ -1974,14 +1974,14 @@ var init_parse_phase = __esm({
           const lang = detectLanguage(filePath);
           if (!lang) {
             if (context2.verbose) {
-              const relativePath2 = path27.relative(context2.workspaceRoot, filePath);
+              const relativePath2 = path29.relative(context2.workspaceRoot, filePath);
               logger_default.info(`  [parse] skipped (no parser): ${relativePath2}`);
             }
             continue;
           }
           const source = context2.fileCache.get(filePath);
           if (!source) continue;
-          const relativePath = path27.relative(context2.workspaceRoot, filePath);
+          const relativePath = path29.relative(context2.workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const fileNode = context2.graph.getNode(fileNodeId);
           if (fileNode) {
@@ -2221,11 +2221,11 @@ var init_resolve_phase = __esm({
         let heritageEdges = 0;
         const fileIndex = /* @__PURE__ */ new Map();
         for (const fp of filePaths) {
-          const rel = path27.relative(workspaceRoot, fp);
+          const rel = path29.relative(workspaceRoot, fp);
           fileIndex.set(rel, fp);
           const noExt = rel.replace(/\.\w+$/, "");
           if (!fileIndex.has(noExt)) fileIndex.set(noExt, fp);
-          const base = path27.basename(rel, path27.extname(rel));
+          const base = path29.basename(rel, path29.extname(rel));
           if (!fileIndex.has(base)) fileIndex.set(base, fp);
         }
         const symbolIndex = /* @__PURE__ */ new Map();
@@ -2256,7 +2256,7 @@ var init_resolve_phase = __esm({
         for (const filePath of filePaths) {
           const lang = detectLanguage(filePath);
           if (!lang) continue;
-          const relativePath = path27.relative(workspaceRoot, filePath);
+          const relativePath = path29.relative(workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const source = fileCache.get(filePath);
           if (!source) continue;
@@ -2269,13 +2269,13 @@ var init_resolve_phase = __esm({
             let resolvedRelPath = null;
             if (cleaned.startsWith(".")) {
               const cleanedNoJs = cleaned.replace(/\.(js|jsx)$/, "");
-              const fromDir = path27.dirname(relativePath);
+              const fromDir = path29.dirname(relativePath);
               for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", "/index.ts", "/index.js"]) {
-                const candidate = path27.join(fromDir, cleanedNoJs + ext);
-                const normalized = path27.normalize(candidate);
+                const candidate = path29.join(fromDir, cleanedNoJs + ext);
+                const normalized = path29.normalize(candidate);
                 if (fileIndex.has(normalized)) {
                   const absPath = fileIndex.get(normalized);
-                  resolvedRelPath = path27.relative(workspaceRoot, absPath);
+                  resolvedRelPath = path29.relative(workspaceRoot, absPath);
                   break;
                 }
               }
@@ -2589,27 +2589,27 @@ __export(group_registry_exports, {
   saveSyncResult: () => saveSyncResult
 });
 function groupFile(name) {
-  return path27.join(GROUPS_DIR, `${name}.json`);
+  return path29.join(GROUPS_DIR, `${name}.json`);
 }
 function loadGroup(name) {
   try {
-    return JSON.parse(fs19.readFileSync(groupFile(name), "utf-8"));
+    return JSON.parse(fs23.readFileSync(groupFile(name), "utf-8"));
   } catch {
     return null;
   }
 }
 function saveGroup(group) {
-  fs19.mkdirSync(GROUPS_DIR, { recursive: true });
-  fs19.writeFileSync(groupFile(group.name), JSON.stringify(group, null, 2) + "\n");
+  fs23.mkdirSync(GROUPS_DIR, { recursive: true });
+  fs23.writeFileSync(groupFile(group.name), JSON.stringify(group, null, 2) + "\n");
 }
 function listGroups() {
   const groups = [];
   try {
-    for (const file of fs19.readdirSync(GROUPS_DIR)) {
+    for (const file of fs23.readdirSync(GROUPS_DIR)) {
       if (!file.endsWith(".json") || file.endsWith(".sync.json")) continue;
       try {
         const g = JSON.parse(
-          fs19.readFileSync(path27.join(GROUPS_DIR, file), "utf-8")
+          fs23.readFileSync(path29.join(GROUPS_DIR, file), "utf-8")
         );
         groups.push(g);
       } catch {
@@ -2621,16 +2621,16 @@ function listGroups() {
 }
 function deleteGroup(name) {
   try {
-    fs19.unlinkSync(groupFile(name));
+    fs23.unlinkSync(groupFile(name));
   } catch {
   }
   try {
-    fs19.unlinkSync(path27.join(GROUPS_DIR, `${name}.sync.json`));
+    fs23.unlinkSync(path29.join(GROUPS_DIR, `${name}.sync.json`));
   } catch {
   }
 }
 function groupExists(name) {
-  return fs19.existsSync(groupFile(name));
+  return fs23.existsSync(groupFile(name));
 }
 function addMember(groupName, member) {
   const group = loadGroup(groupName);
@@ -2656,16 +2656,16 @@ function removeMember(groupName, groupPath) {
   return group;
 }
 function saveSyncResult(result) {
-  fs19.mkdirSync(GROUPS_DIR, { recursive: true });
-  fs19.writeFileSync(
-    path27.join(GROUPS_DIR, `${result.groupName}.sync.json`),
+  fs23.mkdirSync(GROUPS_DIR, { recursive: true });
+  fs23.writeFileSync(
+    path29.join(GROUPS_DIR, `${result.groupName}.sync.json`),
     JSON.stringify(result, null, 2) + "\n"
   );
 }
 function loadSyncResult(groupName) {
   try {
     return JSON.parse(
-      fs19.readFileSync(path27.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
+      fs23.readFileSync(path29.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
     );
   } catch {
     return null;
@@ -2674,7 +2674,7 @@ function loadSyncResult(groupName) {
 var GROUPS_DIR;
 var init_group_registry = __esm({
   "src/multi-repo/group-registry.ts"() {
-    GROUPS_DIR = path27.join(os12.homedir(), ".code-intel", "groups");
+    GROUPS_DIR = path29.join(os12.homedir(), ".code-intel", "groups");
   }
 });
 
@@ -2927,9 +2927,9 @@ var init_orphan_files = __esm({
 // src/health/health-score.ts
 var health_score_exports = {};
 __export(health_score_exports, {
-  computeHealthReport: () => computeHealthReport
+  computeHealthReport: () => computeHealthReport2
 });
-function computeHealthReport(graph, godNodeConfig) {
+function computeHealthReport2(graph, godNodeConfig) {
   const deadCode = detectDeadCode(graph);
   const cycles = detectCircularDeps(graph);
   const godNodes = detectGodNodes(graph, godNodeConfig);
@@ -3735,10 +3735,10 @@ var init_codes = __esm({
   }
 });
 function secureMkdir(dir) {
-  fs19.mkdirSync(dir, { recursive: true, mode: SECURE_DIR_MODE });
+  fs23.mkdirSync(dir, { recursive: true, mode: SECURE_DIR_MODE });
   if (process.platform !== "win32") {
     try {
-      fs19.chmodSync(dir, SECURE_DIR_MODE);
+      fs23.chmodSync(dir, SECURE_DIR_MODE);
     } catch {
     }
   }
@@ -3746,17 +3746,17 @@ function secureMkdir(dir) {
 function secureChmodFile(file) {
   if (process.platform === "win32") return;
   try {
-    fs19.chmodSync(file, SECURE_FILE_MODE);
+    fs23.chmodSync(file, SECURE_FILE_MODE);
   } catch {
   }
 }
 function tightenDbFiles(dir) {
   if (process.platform === "win32") return;
-  if (!fs19.existsSync(dir)) return;
-  for (const name of fs19.readdirSync(dir)) {
+  if (!fs23.existsSync(dir)) return;
+  for (const name of fs23.readdirSync(dir)) {
     if (name.endsWith(".db") || name.endsWith(".db-wal") || name.endsWith(".db-shm")) {
       try {
-        fs19.chmodSync(path27.join(dir, name), SECURE_FILE_MODE);
+        fs23.chmodSync(path29.join(dir, name), SECURE_FILE_MODE);
       } catch {
       }
     }
@@ -3770,7 +3770,7 @@ var init_fs_secure = __esm({
   }
 });
 function getUsersDBPath() {
-  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "users.db");
+  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path29.join(os12.homedir(), ".code-intel", "users.db");
 }
 function getOrCreateUsersDB() {
   if (!_usersDB) {
@@ -3786,7 +3786,7 @@ var init_users_db = __esm({
     UsersDB = class {
       db;
       constructor(dbPath) {
-        const dir = path27.dirname(dbPath);
+        const dir = path29.dirname(dbPath);
         secureMkdir(dir);
         this.db = new Database3(dbPath);
         this.db.pragma("journal_mode = WAL");
@@ -4063,7 +4063,7 @@ function getScryptN() {
   return Number.isInteger(v) && v >= 1024 ? v : 1 << 14;
 }
 function getSecretsPath() {
-  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path27.join(os12.homedir(), ".code-intel", ".secrets");
+  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path29.join(os12.homedir(), ".code-intel", ".secrets");
 }
 function getMasterPassword() {
   const fromEnv = process.env["CODE_INTEL_SECRET_KEY"];
@@ -4094,8 +4094,8 @@ function decryptSecrets(encrypted) {
   return JSON.parse(plaintext.toString("utf8"));
 }
 function loadSecrets(secretsPath = getSecretsPath()) {
-  if (!fs19.existsSync(secretsPath)) return {};
-  const blob = fs19.readFileSync(secretsPath);
+  if (!fs23.existsSync(secretsPath)) return {};
+  const blob = fs23.readFileSync(secretsPath);
   return decryptSecrets(blob);
 }
 function getSecret(key, secretsPath = getSecretsPath()) {
@@ -4214,6 +4214,9 @@ function requireAuth(req, res, next) {
   }
   next();
 }
+function meetsRole(userRole, required) {
+  return (ROLE_RANK[userRole] ?? 0) >= (ROLE_RANK[required] ?? 0);
+}
 function requireRole(...roles) {
   return (req, res, next) => {
     if (!req.user) {
@@ -4228,7 +4231,8 @@ function requireRole(...roles) {
       });
       return;
     }
-    if (!roles.includes(req.user.role)) {
+    const allowed = roles.some((r) => meetsRole(req.user.role, r));
+    if (!allowed) {
       res.status(403).json({
         error: {
           code: ErrorCodes.FORBIDDEN,
@@ -4337,7 +4341,7 @@ function clearSessionCookie() {
 async function verifyPassword(plain, hash) {
   return bcrypt.compare(plain, hash);
 }
-var sessionStore, SESSION_COOKIE_NAME;
+var sessionStore, SESSION_COOKIE_NAME, ROLE_RANK;
 var init_middleware = __esm({
   "src/auth/middleware.ts"() {
     init_users_db();
@@ -4345,6 +4349,12 @@ var init_middleware = __esm({
     init_secret_store();
     sessionStore = /* @__PURE__ */ new Map();
     SESSION_COOKIE_NAME = "code_intel_session";
+    ROLE_RANK = {
+      viewer: 1,
+      "repo-owner": 2,
+      analyst: 3,
+      admin: 4
+    };
   }
 });
 function verifyWebSocketHandshake(req) {
@@ -4652,7 +4662,7 @@ init_shared();
 init_shared();
 init_typescript();
 function resolveRelative(rawPath, fromFile, workspace) {
-  const fromDir = path27.dirname(fromFile);
+  const fromDir = path29.dirname(fromFile);
   const cleaned = rawPath.replace(/['"]/g, "");
   const extensions = [".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.js"];
   const resolved = workspace.resolve(fromDir, cleaned);
@@ -4704,7 +4714,7 @@ var pythonModule = {
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/['"]/g, "");
     const parts = cleaned.split(".");
-    const fromDir = path27.dirname(fromFile);
+    const fromDir = path29.dirname(fromFile);
     const relPath = parts.join("/");
     for (const suffix of ["/__init__.py", ".py"]) {
       const r = workspace.resolve(fromDir, relPath + suffix);
@@ -4783,7 +4793,7 @@ var cModule = {
   inheritanceStrategy: "none",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path27.dirname(fromFile);
+    const fromDir = path29.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4806,7 +4816,7 @@ var cppModule = {
   inheritanceStrategy: "depth-first",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path27.dirname(fromFile);
+    const fromDir = path29.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4968,7 +4978,7 @@ var dartModule = {
       const pkg = cleaned.replace("package:", "");
       return workspace.findByPackage(pkg);
     }
-    const fromDir = path27.dirname(fromFile);
+    const fromDir = path29.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(node) {
@@ -5323,25 +5333,25 @@ function validateDAG(phases) {
   const visiting = /* @__PURE__ */ new Set();
   const visited = /* @__PURE__ */ new Set();
   const phaseMap = new Map(phases.map((p) => [p.name, p]));
-  function dfs(name, path28) {
+  function dfs(name, path30) {
     if (visiting.has(name)) {
-      const cycleStart = path28.indexOf(name);
-      const cycle = path28.slice(cycleStart).concat(name);
+      const cycleStart = path30.indexOf(name);
+      const cycle = path30.slice(cycleStart).concat(name);
       errors.push({ type: "cycle", message: `Cycle detected: ${cycle.join(" \u2192 ")}` });
       return true;
     }
     if (visited.has(name)) return false;
     visiting.add(name);
-    path28.push(name);
+    path30.push(name);
     const phase = phaseMap.get(name);
     if (phase) {
       for (const dep of phase.dependencies) {
-        if (dfs(dep, path28)) return true;
+        if (dfs(dep, path30)) return true;
       }
     }
     visiting.delete(name);
     visited.add(name);
-    path28.pop();
+    path30.pop();
     return false;
   }
   for (const phase of phases) {
@@ -5554,7 +5564,7 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
 ]);
 function loadIgnorePatterns(workspaceRoot) {
   try {
-    const raw = fs19.readFileSync(path27.join(workspaceRoot, ".codeintelignore"), "utf-8");
+    const raw = fs23.readFileSync(path29.join(workspaceRoot, ".codeintelignore"), "utf-8");
     const extras = /* @__PURE__ */ new Set();
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();
@@ -5578,7 +5588,7 @@ var scanPhase = {
     function walk(dir) {
       let entries;
       try {
-        entries = fs19.readdirSync(dir, { withFileTypes: true });
+        entries = fs23.readdirSync(dir, { withFileTypes: true });
       } catch {
         return;
       }
@@ -5587,15 +5597,15 @@ var scanPhase = {
           if (entry.name.startsWith(".")) continue;
           if (IGNORED_DIRS.has(entry.name)) continue;
           if (extraIgnore.has(entry.name)) continue;
-          walk(path27.join(dir, entry.name));
+          walk(path29.join(dir, entry.name));
         } else if (entry.isFile()) {
           const name = entry.name;
           if (IGNORED_FILE_SUFFIXES.some((s) => name.endsWith(s))) continue;
-          const ext = path27.extname(name);
+          const ext = path29.extname(name);
           if (!extensions.has(ext)) continue;
-          const fullPath = path27.join(dir, name);
+          const fullPath = path29.join(dir, name);
           try {
-            const stat = fs19.statSync(fullPath);
+            const stat = fs23.statSync(fullPath);
             if (stat.size > MAX_FILE_SIZE_BYTES) continue;
           } catch {
             continue;
@@ -5622,20 +5632,20 @@ var structurePhase = {
     const dirs = /* @__PURE__ */ new Set();
     let structDone = 0;
     for (const filePath of context2.filePaths) {
-      const relativePath = path27.relative(context2.workspaceRoot, filePath);
+      const relativePath = path29.relative(context2.workspaceRoot, filePath);
       const lang = detectLanguage(filePath);
       context2.graph.addNode({
         id: generateNodeId("file", relativePath, relativePath),
         kind: "file",
-        name: path27.basename(filePath),
+        name: path29.basename(filePath),
         filePath: relativePath,
         metadata: lang ? { language: lang } : void 0
       });
-      let dir = path27.dirname(relativePath);
+      let dir = path29.dirname(relativePath);
       while (dir && dir !== "." && dir !== "") {
         if (dirs.has(dir)) break;
         dirs.add(dir);
-        dir = path27.dirname(dir);
+        dir = path29.dirname(dir);
       }
       structDone++;
       context2.onPhaseProgress?.("structure", structDone, context2.filePaths.length);
@@ -5644,7 +5654,7 @@ var structurePhase = {
       context2.graph.addNode({
         id: generateNodeId("directory", dir, dir),
         kind: "directory",
-        name: path27.basename(dir),
+        name: path29.basename(dir),
         filePath: dir
       });
     }
@@ -5755,22 +5765,22 @@ var flowPhase = {
       const queue = [{ nodeId: ep.id, path: [ep.id] }];
       const visited = /* @__PURE__ */ new Set();
       while (queue.length > 0 && flowCount < maxFlows) {
-        const { nodeId, path: path28 } = queue.shift();
-        if (path28.length > maxDepth) continue;
+        const { nodeId, path: path30 } = queue.shift();
+        if (path30.length > maxDepth) continue;
         const callEdges = [...graph.findEdgesFrom(nodeId)].filter((e) => e.kind === "calls").slice(0, maxBranching);
-        if (callEdges.length === 0 && path28.length >= 3) {
+        if (callEdges.length === 0 && path30.length >= 3) {
           const flowId = generateNodeId("flow", ep.filePath, `flow-${flowCount}`);
           graph.addNode({
             id: flowId,
             kind: "flow",
             name: `${ep.name} flow ${flowCount}`,
             filePath: ep.filePath,
-            metadata: { steps: path28, entryPoint: ep.name }
+            metadata: { steps: path30, entryPoint: ep.name }
           });
-          for (let i = 0; i < path28.length; i++) {
+          for (let i = 0; i < path30.length; i++) {
             graph.addEdge({
-              id: generateEdgeId(path28[i], flowId, `step_of_${i}`),
-              source: path28[i],
+              id: generateEdgeId(path30[i], flowId, `step_of_${i}`),
+              source: path30[i],
               target: flowId,
               kind: "step_of",
               weight: 1,
@@ -5783,7 +5793,7 @@ var flowPhase = {
         for (const edge of callEdges) {
           if (visited.has(edge.target)) continue;
           visited.add(edge.target);
-          queue.push({ nodeId: edge.target, path: [...path28, edge.target] });
+          queue.push({ nodeId: edge.target, path: [...path30, edge.target] });
         }
       }
     }
@@ -5801,7 +5811,7 @@ var LLMGovernanceLogger = class {
   }
   /** Path to the JSONL log file. */
   getLogPath() {
-    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
+    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path29.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
   }
   /**
    * Append an entry to the governance log.
@@ -5817,8 +5827,8 @@ var LLMGovernanceLogger = class {
         ...entry
       };
       const logPath = this.getLogPath();
-      fs19.mkdirSync(path27.dirname(logPath), { recursive: true });
-      fs19.appendFileSync(logPath, JSON.stringify(full) + "\n", "utf-8");
+      fs23.mkdirSync(path29.dirname(logPath), { recursive: true });
+      fs23.appendFileSync(logPath, JSON.stringify(full) + "\n", "utf-8");
     } catch {
     }
   }
@@ -5828,7 +5838,7 @@ var LLMGovernanceLogger = class {
    */
   readLog(limit = 100) {
     try {
-      const raw = fs19.readFileSync(this.getLogPath(), "utf-8");
+      const raw = fs23.readFileSync(this.getLogPath(), "utf-8");
       const lines = raw.split("\n").filter((l) => l.trim().length > 0).slice(-limit);
       return lines.map((l) => JSON.parse(l));
     } catch {
@@ -5972,17 +5982,17 @@ function traceFlow(entryId, graph, maxDepth = 10, maxBranching = 4) {
     const queue = [{ nodeId: entryId, path: [entryId] }];
     const visited = /* @__PURE__ */ new Set();
     while (queue.length > 0 && flows.length < maxFlows) {
-      const { nodeId, path: path28 } = queue.shift();
-      if (path28.length > maxDepth) continue;
+      const { nodeId, path: path30 } = queue.shift();
+      if (path30.length > maxDepth) continue;
       const callEdges = [...graph.findEdgesFrom(nodeId)].filter((e) => e.kind === "calls").slice(0, maxBranching);
-      if (callEdges.length === 0 && path28.length >= 3) {
-        flows.push({ entryPointId: entryId, steps: [...path28] });
+      if (callEdges.length === 0 && path30.length >= 3) {
+        flows.push({ entryPointId: entryId, steps: [...path30] });
         continue;
       }
       for (const edge of callEdges) {
         if (visited.has(edge.target)) continue;
         visited.add(edge.target);
-        queue.push({ nodeId: edge.target, path: [...path28, edge.target] });
+        queue.push({ nodeId: edge.target, path: [...path30, edge.target] });
       }
     }
   }
@@ -6216,7 +6226,7 @@ init_embedder();
 async function hybridSearch(graph, query, limit, options = {}) {
   const { vectorDbPath, bm25Limit = 50, vectorLimit = 50 } = options;
   const bm25Promise = Promise.resolve(textSearch(graph, query, bm25Limit));
-  const hasVectorDb = Boolean(vectorDbPath && fs19.existsSync(vectorDbPath));
+  const hasVectorDb = Boolean(vectorDbPath && fs23.existsSync(vectorDbPath));
   if (!hasVectorDb) {
     const bm25Results2 = await bm25Promise;
     return {
@@ -6273,7 +6283,7 @@ var DbManager = class {
     this.dbPath = dbPath;
   }
   async init() {
-    fs19.mkdirSync(path27.dirname(this.dbPath), { recursive: true });
+    fs23.mkdirSync(path29.dirname(this.dbPath), { recursive: true });
     this.db = new Database(this.dbPath);
     await this.db.init();
     this.conn = new Connection(this.db);
@@ -6330,7 +6340,8 @@ var NODE_TABLE_MAP = {
   constant: "const_nodes",
   route: "route_nodes",
   cluster: "cluster_nodes",
-  flow: "flow_nodes"
+  flow: "flow_nodes",
+  vulnerability: "vuln_nodes"
 };
 var ALL_NODE_TABLES = [...new Set(Object.values(NODE_TABLE_MAP))];
 function getCreateNodeTableDDL(tableName) {
@@ -6362,7 +6373,7 @@ function getCreateEdgeTableDDL() {
 )`];
 }
 function writeNodeCSVs(graph, outputDir) {
-  fs19.mkdirSync(outputDir, { recursive: true });
+  fs23.mkdirSync(outputDir, { recursive: true });
   const header = "id,name,file_path,start_line,end_line,exported,content,metadata\n";
   const tableBuffers = /* @__PURE__ */ new Map();
   const tableFilePaths = /* @__PURE__ */ new Map();
@@ -6370,7 +6381,7 @@ function writeNodeCSVs(graph, outputDir) {
     const table = NODE_TABLE_MAP[node.kind];
     if (!tableBuffers.has(table)) {
       tableBuffers.set(table, [header]);
-      tableFilePaths.set(table, path27.join(outputDir, `${table}.csv`));
+      tableFilePaths.set(table, path29.join(outputDir, `${table}.csv`));
     }
     tableBuffers.get(table).push(
       csvRow([
@@ -6390,12 +6401,12 @@ function writeNodeCSVs(graph, outputDir) {
     );
   }
   for (const [table, lines] of tableBuffers) {
-    fs19.writeFileSync(tableFilePaths.get(table), lines.join(""), "utf-8");
+    fs23.writeFileSync(tableFilePaths.get(table), lines.join(""), "utf-8");
   }
   return tableFilePaths;
 }
 function writeEdgeCSV(graph, outputDir) {
-  fs19.mkdirSync(outputDir, { recursive: true });
+  fs23.mkdirSync(outputDir, { recursive: true });
   const header = "from_id,to_id,kind,weight,label\n";
   const groups = /* @__PURE__ */ new Map();
   for (const edge of graph.allEdges()) {
@@ -6406,7 +6417,7 @@ function writeEdgeCSV(graph, outputDir) {
     const toTable = NODE_TABLE_MAP[targetNode.kind];
     const key = `${fromTable}->${toTable}`;
     if (!groups.has(key)) {
-      const filePath = path27.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
+      const filePath = path29.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
       groups.set(key, { lines: [header], from: fromTable, to: toTable, filePath });
     }
     groups.get(key).lines.push(
@@ -6421,7 +6432,7 @@ function writeEdgeCSV(graph, outputDir) {
   }
   const result = [];
   for (const group of groups.values()) {
-    fs19.writeFileSync(group.filePath, group.lines.join(""), "utf-8");
+    fs23.writeFileSync(group.filePath, group.lines.join(""), "utf-8");
     result.push({ fromTable: group.from, toTable: group.to, filePath: group.filePath });
   }
   return result;
@@ -6449,7 +6460,7 @@ async function loadGraphToDB(graph, dbManager) {
     } catch {
     }
   }
-  const tmpDir = fs19.mkdtempSync(path27.join(os12.tmpdir(), "code-intel-csv-"));
+  const tmpDir = fs23.mkdtempSync(path29.join(os12.tmpdir(), "code-intel-csv-"));
   try {
     const nodeTableFiles = writeNodeCSVs(graph, tmpDir);
     const edgeGroups = writeEdgeCSV(graph, tmpDir);
@@ -6468,8 +6479,8 @@ async function loadGraphToDB(graph, dbManager) {
     }
     let nodeCount = 0;
     for (const [table, csvPath] of nodeTableFiles) {
-      if (!fs19.existsSync(csvPath)) continue;
-      const stat = fs19.statSync(csvPath);
+      if (!fs23.existsSync(csvPath)) continue;
+      const stat = fs23.statSync(csvPath);
       if (stat.size < 50) continue;
       try {
         await dbManager.execute(
@@ -6482,8 +6493,8 @@ async function loadGraphToDB(graph, dbManager) {
     }
     let edgeCount = 0;
     for (const group of edgeGroups) {
-      if (!fs19.existsSync(group.filePath)) continue;
-      const stat = fs19.statSync(group.filePath);
+      if (!fs23.existsSync(group.filePath)) continue;
+      const stat = fs23.statSync(group.filePath);
       if (stat.size < 50) continue;
       try {
         await dbManager.execute(
@@ -6497,7 +6508,7 @@ async function loadGraphToDB(graph, dbManager) {
     return { nodeCount, edgeCount };
   } finally {
     try {
-      fs19.rmSync(tmpDir, { recursive: true, force: true });
+      fs23.rmSync(tmpDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -6549,19 +6560,19 @@ function buildNodeProps(node) {
 function escCypher(s) {
   return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "");
 }
-var GLOBAL_DIR = path27.join(os12.homedir(), ".code-intel");
-var REPOS_FILE = path27.join(GLOBAL_DIR, "repos.json");
+var GLOBAL_DIR = path29.join(os12.homedir(), ".code-intel");
+var REPOS_FILE = path29.join(GLOBAL_DIR, "repos.json");
 function loadRegistry() {
   try {
-    const data = fs19.readFileSync(REPOS_FILE, "utf-8");
+    const data = fs23.readFileSync(REPOS_FILE, "utf-8");
     return JSON.parse(data);
   } catch {
     return [];
   }
 }
 function saveRegistry(entries) {
-  fs19.mkdirSync(GLOBAL_DIR, { recursive: true });
-  fs19.writeFileSync(REPOS_FILE, JSON.stringify(entries, null, 2));
+  fs23.mkdirSync(GLOBAL_DIR, { recursive: true });
+  fs23.writeFileSync(REPOS_FILE, JSON.stringify(entries, null, 2));
 }
 function upsertRepo(entry) {
   const entries = loadRegistry();
@@ -6578,23 +6589,23 @@ function removeRepo(repoPath) {
   saveRegistry(entries);
 }
 function saveMetadata(repoDir, metadata) {
-  const metaDir = path27.join(repoDir, ".code-intel");
-  fs19.mkdirSync(metaDir, { recursive: true });
-  fs19.writeFileSync(path27.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
+  const metaDir = path29.join(repoDir, ".code-intel");
+  fs23.mkdirSync(metaDir, { recursive: true });
+  fs23.writeFileSync(path29.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
 }
 function loadMetadata(repoDir) {
   try {
-    const data = fs19.readFileSync(path27.join(repoDir, ".code-intel", "meta.json"), "utf-8");
+    const data = fs23.readFileSync(path29.join(repoDir, ".code-intel", "meta.json"), "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 function getDbPath(repoDir) {
-  return path27.join(repoDir, ".code-intel", "graph.db");
+  return path29.join(repoDir, ".code-intel", "graph.db");
 }
 function getVectorDbPath(repoDir) {
-  return path27.join(repoDir, ".code-intel", "vector.db");
+  return path29.join(repoDir, ".code-intel", "vector.db");
 }
 
 // src/mcp-server/server.ts
@@ -6672,6 +6683,205 @@ async function loadGraphFromDB(graph, db) {
 
 // src/multi-repo/group-sync.ts
 init_logger();
+function scanForFiles(root, matcher, maxDepth = 2) {
+  const results = [];
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs23.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path29.join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        walk(full, depth + 1);
+      } else if (entry.isFile() && matcher(entry.name)) {
+        results.push(full);
+      }
+    }
+  }
+  walk(root, 0);
+  return results;
+}
+
+// src/multi-repo/schema-parsers/openapi-parser.ts
+var OPENAPI_FILENAMES = /* @__PURE__ */ new Set([
+  "openapi.yaml",
+  "openapi.json",
+  "openapi.yml",
+  "swagger.yaml",
+  "swagger.json",
+  "swagger.yml"
+]);
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+function tryParseFile(filePath) {
+  const ext = path29.extname(filePath).toLowerCase();
+  const content = fs23.readFileSync(filePath, "utf-8");
+  if (ext === ".json") {
+    try {
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+async function parseOpenAPIContracts(repoRoot) {
+  const files = scanForFiles(repoRoot, (name) => OPENAPI_FILENAMES.has(name));
+  const contracts = [];
+  for (const filePath of files) {
+    const spec = tryParseFile(filePath);
+    if (!spec) continue;
+    const paths = spec["paths"];
+    if (!paths || typeof paths !== "object") continue;
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== "object") continue;
+      const ops = pathItem;
+      for (const method of HTTP_METHODS) {
+        if (!(method in ops)) continue;
+        const operation = ops[method];
+        if (!operation) continue;
+        const requestBody = operation["requestBody"];
+        const requestSchema = requestBody?.["content"] ? requestBody["content"]["application/json"]?.["schema"] : void 0;
+        const responses = operation["responses"];
+        const ok200 = responses?.["200"];
+        const responseSchema = ok200?.["content"] ? ok200["content"]["application/json"]?.["schema"] : void 0;
+        contracts.push({
+          name: `${method.toUpperCase()} ${pathStr}`,
+          kind: "route",
+          method: method.toUpperCase(),
+          path: pathStr,
+          ...requestSchema ? { requestSchema } : {},
+          ...responseSchema ? { responseSchema } : {},
+          filePath
+        });
+      }
+    }
+  }
+  return contracts;
+}
+function extractFieldNames(block) {
+  return block.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).map((line) => {
+    const m = line.match(/^(\w+)\s*[(:]/);
+    return m ? m[1] : null;
+  }).filter((f) => f !== null);
+}
+async function parseGraphQLContracts(repoRoot) {
+  const files = scanForFiles(repoRoot, (name) => name.endsWith(".graphql") || name.endsWith(".gql"));
+  const contracts = [];
+  for (const filePath of files) {
+    const content = fs23.readFileSync(filePath, "utf-8");
+    const typeRegex = /type\s+(\w+)\s*\{([^}]+)\}/g;
+    let match;
+    while ((match = typeRegex.exec(content)) !== null) {
+      const typeName = match[1];
+      const body = match[2];
+      const fields = extractFieldNames(body);
+      const lcName = typeName.toLowerCase();
+      if (lcName === "query") {
+        for (const field of fields) {
+          contracts.push({ name: `query.${field}`, kind: "graphql", operation: "query", fields, filePath });
+        }
+      } else if (lcName === "mutation") {
+        for (const field of fields) {
+          contracts.push({ name: `mutation.${field}`, kind: "graphql", operation: "mutation", fields, filePath });
+        }
+      } else if (lcName === "subscription") {
+        for (const field of fields) {
+          contracts.push({ name: `subscription.${field}`, kind: "graphql", operation: "subscription", fields, filePath });
+        }
+      } else {
+        contracts.push({ name: `type.${typeName}`, kind: "graphql", operation: "type", fields, filePath });
+      }
+    }
+  }
+  return contracts;
+}
+async function parseProtoContracts(repoRoot) {
+  const files = scanForFiles(repoRoot, (name) => name.endsWith(".proto"));
+  const contracts = [];
+  for (const filePath of files) {
+    const content = fs23.readFileSync(filePath, "utf-8");
+    const serviceRegex = /service\s+(\w+)\s*\{([^}]+)\}/g;
+    let serviceMatch;
+    while ((serviceMatch = serviceRegex.exec(content)) !== null) {
+      const serviceName = serviceMatch[1];
+      const body = serviceMatch[2];
+      const rpcRegex = /rpc\s+(\w+)\s*\((\w+)\)\s*returns\s*\((\w+)\)/g;
+      let rpcMatch;
+      while ((rpcMatch = rpcRegex.exec(body)) !== null) {
+        const rpcName = rpcMatch[1];
+        const inputType = rpcMatch[2];
+        const outputType = rpcMatch[3];
+        contracts.push({
+          name: `${serviceName}.${rpcName}`,
+          kind: "grpc",
+          serviceName,
+          rpcName,
+          inputType,
+          outputType,
+          filePath
+        });
+      }
+    }
+  }
+  return contracts;
+}
+
+// src/multi-repo/type-similarity.ts
+function normalizeType(t) {
+  return t.toLowerCase().replace(/[\[\]?<>\s]/g, "").trim();
+}
+function paramTypeSimilarity(paramsA, paramsB) {
+  if (paramsA.length === 0 && paramsB.length === 0) return 1;
+  if (paramsA.length === 0 || paramsB.length === 0) return 0;
+  const setA = new Set(paramsA.map((p) => normalizeType(p.type ?? "")).filter(Boolean));
+  const setB = new Set(paramsB.map((p) => normalizeType(p.type ?? "")).filter(Boolean));
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+  const intersection = [...setA].filter((x) => setB.has(x)).length;
+  const union = (/* @__PURE__ */ new Set([...setA, ...setB])).size;
+  return intersection / union;
+}
+function returnTypeSimilarity(typeA, typeB) {
+  if (!typeA || !typeB) return 0.5;
+  const a = normalizeType(typeA);
+  const b = normalizeType(typeB);
+  if (a === b) return 1;
+  const compatible = [
+    ["string", "str"],
+    ["number", "int"],
+    ["number", "float"],
+    ["number", "double"],
+    ["boolean", "bool"],
+    ["void", "unit"],
+    ["void", "none"]
+  ];
+  for (const [x, y] of compatible) {
+    if (a === x && b === y || a === y && b === x) return 0.8;
+  }
+  return 0;
+}
+function paramCountSimilarity(countA, countB) {
+  const maxCount = Math.max(countA, countB, 1);
+  return 1 - Math.abs(countA - countB) / maxCount;
+}
+function computeContractSimilarity(a, b, nameSim) {
+  const paramsA = a.parameters ?? [];
+  const paramsB = b.parameters ?? [];
+  const ptSim = paramTypeSimilarity(paramsA, paramsB);
+  const rtSim = returnTypeSimilarity(a.returnType, b.returnType);
+  const pcSim = paramCountSimilarity(paramsA.length, paramsB.length);
+  let score = 0.4 * nameSim + 0.3 * ptSim + 0.2 * rtSim + 0.1 * pcSim;
+  if (ptSim > 0.8) {
+    score = Math.min(1, score * 1.2);
+  }
+  return score;
+}
+
+// src/multi-repo/group-sync.ts
 function extractContracts(graph, repoName, repoPath) {
   const contracts = [];
   for (const node of graph.allNodes()) {
@@ -6684,7 +6894,10 @@ function extractContracts(graph, repoName, repoPath) {
         nodeId: node.id,
         nodeKind: node.kind,
         filePath: node.filePath,
-        signature: node.content?.split("\n")[0]?.trim()
+        signature: node.content?.split("\n")[0]?.trim(),
+        parameters: node.metadata?.parameters ?? node.metadata?.params,
+        returnType: node.metadata?.returnType,
+        exported: node.exported
       });
     }
     if (node.kind === "route") {
@@ -6746,13 +6959,15 @@ function matchContracts(allContracts) {
         const consumer = consumerByName.get(provider.name);
         if (consumer) {
           const sameKind = provider.kind === consumer.kind;
+          const typedScore = computeContractSimilarity(provider, consumer, 1);
+          const confidence = sameKind ? Math.max(typedScore, 0.9) : Math.max(typedScore, 0.6);
           links.push({
             providerRepo: provider.repoName,
             providerContract: provider.name,
             consumerRepo: consumer.repoName,
             consumerContract: consumer.name,
             matchKind: provider.kind === "route" ? "route-match" : "name-match",
-            confidence: sameKind ? 0.9 : 0.6
+            confidence: Math.min(1, confidence)
           });
         } else {
           const providerLC = provider.name.toLowerCase();
@@ -6793,8 +7008,8 @@ async function syncGroup(group) {
       logger_default.warn(`  \u26A0 Registry entry "${member.registryName}" not found \u2014 skipping ${member.groupPath}`);
       continue;
     }
-    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
-    if (!fs19.existsSync(dbPath)) {
+    const dbPath = path29.join(regEntry.path, ".code-intel", "graph.db");
+    if (!fs23.existsSync(dbPath)) {
       logger_default.warn(`  \u26A0 No index at ${dbPath} \u2014 run \`code-intel analyze ${regEntry.path}\` first`);
       continue;
     }
@@ -6810,6 +7025,44 @@ async function syncGroup(group) {
       continue;
     }
     const contracts = extractContracts(graph, member.registryName, regEntry.path);
+    const [openapiContracts, graphqlContracts, protoContracts] = await Promise.all([
+      parseOpenAPIContracts(regEntry.path).catch(() => []),
+      parseGraphQLContracts(regEntry.path).catch(() => []),
+      parseProtoContracts(regEntry.path).catch(() => [])
+    ]);
+    for (const c of openapiContracts) {
+      contracts.push({
+        repoName: member.registryName,
+        repoPath: regEntry.path,
+        kind: "route",
+        name: c.name,
+        nodeId: `openapi:${c.method}:${c.path}`,
+        nodeKind: "route",
+        filePath: c.filePath
+      });
+    }
+    for (const c of graphqlContracts) {
+      contracts.push({
+        repoName: member.registryName,
+        repoPath: regEntry.path,
+        kind: "graphql",
+        name: c.name,
+        nodeId: `graphql:${c.name}`,
+        nodeKind: "graphql",
+        filePath: c.filePath
+      });
+    }
+    for (const c of protoContracts) {
+      contracts.push({
+        repoName: member.registryName,
+        repoPath: regEntry.path,
+        kind: "grpc",
+        name: c.name,
+        nodeId: `grpc:${c.serviceName}:${c.rpcName}`,
+        nodeKind: "grpc",
+        filePath: c.filePath
+      });
+    }
     logger_default.info(`  \u2713 ${member.registryName} (${member.groupPath}): ${contracts.length} contracts`);
     allContracts.push(...contracts);
   }
@@ -6829,8 +7082,8 @@ async function queryGroup(group, query, limit = 20) {
   for (const member of group.members) {
     const regEntry = registry.find((r) => r.name === member.registryName);
     if (!regEntry) continue;
-    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
-    if (!fs19.existsSync(dbPath)) continue;
+    const dbPath = path29.join(regEntry.path, ".code-intel", "graph.db");
+    if (!fs23.existsSync(dbPath)) continue;
     const graph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
     try {
@@ -6860,6 +7113,624 @@ async function queryGroup(group, query, limit = 20) {
 
 // src/mcp-server/server.ts
 init_tracing();
+
+// src/query/explain-relationship.ts
+function explainRelationship(graph, from, to) {
+  const allNodes = [...graph.allNodes()];
+  const fromNode = allNodes.find((n) => n.name === from);
+  if (!fromNode) {
+    const firstChar = from[0]?.toLowerCase() ?? "";
+    const fromLower = from.toLowerCase();
+    const suggestions = allNodes.filter((n) => n.name.toLowerCase().startsWith(firstChar) || n.name.toLowerCase().includes(fromLower)).slice(0, 5).map((n) => n.name);
+    return { error: `Symbol not found: ${from}`, suggestions };
+  }
+  const toNode = allNodes.find((n) => n.name === to);
+  if (!toNode) {
+    const firstChar = to[0]?.toLowerCase() ?? "";
+    const toLower = to.toLowerCase();
+    const suggestions = allNodes.filter((n) => n.name.toLowerCase().startsWith(firstChar) || n.name.toLowerCase().includes(toLower)).slice(0, 5).map((n) => n.name);
+    return { error: `Symbol not found: ${to}`, suggestions };
+  }
+  const paths = [];
+  const queue = [{
+    id: fromNode.id,
+    nodeNames: [fromNode.name],
+    lastEdgeKind: "",
+    visited: /* @__PURE__ */ new Set([fromNode.id])
+  }];
+  while (queue.length > 0 && paths.length < 10) {
+    const entry = queue.shift();
+    const { id, nodeNames, visited } = entry;
+    if (nodeNames.length > 6) continue;
+    for (const edge of graph.findEdgesFrom(id)) {
+      const targetNode = graph.getNode(edge.target);
+      if (!targetNode) continue;
+      if (visited.has(edge.target)) continue;
+      const newNames = [...nodeNames, targetNode.name];
+      if (edge.target === toNode.id) {
+        paths.push({ hops: newNames.length - 1, nodes: newNames, edgeKind: edge.kind });
+        if (paths.length >= 10) break;
+        continue;
+      }
+      if (newNames.length < 6) {
+        const newVisited = new Set(visited);
+        newVisited.add(edge.target);
+        queue.push({ id: edge.target, nodeNames: newNames, lastEdgeKind: edge.kind, visited: newVisited });
+      }
+    }
+  }
+  const fromImports = /* @__PURE__ */ new Set();
+  for (const edge of graph.findEdgesFrom(fromNode.id)) {
+    if (edge.kind === "imports") fromImports.add(edge.target);
+  }
+  const sharedImportIds = [];
+  for (const edge of graph.findEdgesFrom(toNode.id)) {
+    if (edge.kind === "imports" && fromImports.has(edge.target)) {
+      sharedImportIds.push(edge.target);
+    }
+  }
+  const sharedImports = sharedImportIds.map((id) => graph.getNode(id)?.name ?? id);
+  let heritage = null;
+  for (const edge of graph.findEdgesFrom(fromNode.id)) {
+    if ((edge.kind === "extends" || edge.kind === "implements") && edge.target === toNode.id) {
+      heritage = `${from} ${edge.kind} ${to}`;
+      break;
+    }
+  }
+  if (!heritage) {
+    for (const edge of graph.findEdgesFrom(toNode.id)) {
+      if ((edge.kind === "extends" || edge.kind === "implements") && edge.target === fromNode.id) {
+        heritage = `${to} ${edge.kind} ${from}`;
+        break;
+      }
+    }
+  }
+  const sharedStr = sharedImports.length > 0 ? sharedImports.join(", ") : "none";
+  const heritageStr = heritage ?? "none";
+  const connectionStr = paths.length === 0 ? "No connection found." : `${from} \u2192 ${to} via ${paths.length} path(s).`;
+  const summary = `${connectionStr} Shared imports: [${sharedStr}]. Heritage: ${heritageStr}.`;
+  return { paths, sharedImports, heritage, summary };
+}
+
+// src/query/pr-impact.ts
+function parseDiffFiles(diff) {
+  const files = [];
+  for (const line of diff.split("\n")) {
+    const match = line.match(/^\+\+\+ b\/(.+)/);
+    if (match) {
+      files.push(match[1]);
+    }
+  }
+  return files;
+}
+function computePRImpact(graph, changedFiles, maxHops) {
+  const changedSymbolIds = /* @__PURE__ */ new Set();
+  for (const node of graph.allNodes()) {
+    if (!node.filePath) continue;
+    for (const changedFile of changedFiles) {
+      if (node.filePath === changedFile || node.filePath.endsWith(changedFile) || changedFile.endsWith(node.filePath)) {
+        changedSymbolIds.add(node.id);
+        break;
+      }
+    }
+  }
+  const allBlastRadiusNodes = /* @__PURE__ */ new Set();
+  const changedSymbols = [];
+  for (const symbolId of changedSymbolIds) {
+    const symbolNode = graph.getNode(symbolId);
+    if (!symbolNode) continue;
+    const blastRadius = /* @__PURE__ */ new Set();
+    const queue = [{ id: symbolId, depth: 0 }];
+    const visited = /* @__PURE__ */ new Set();
+    while (queue.length > 0) {
+      const { id, depth } = queue.shift();
+      if (visited.has(id) || depth > maxHops) continue;
+      visited.add(id);
+      if (id !== symbolId) blastRadius.add(id);
+      for (const edge of graph.findEdgesTo(id)) {
+        if (edge.kind === "calls" || edge.kind === "imports") {
+          queue.push({ id: edge.source, depth: depth + 1 });
+        }
+      }
+    }
+    for (const id of blastRadius) allBlastRadiusNodes.add(id);
+    const blastCount = blastRadius.size;
+    let risk;
+    if (blastCount > 50) {
+      risk = "HIGH";
+    } else if (blastCount >= 10) {
+      risk = "MEDIUM";
+    } else {
+      risk = "LOW";
+    }
+    let callerCount = 0;
+    for (const edge of graph.findEdgesTo(symbolId)) {
+      if (edge.kind === "calls") callerCount++;
+    }
+    let testCoverage = false;
+    for (const edge of graph.findEdgesTo(symbolId)) {
+      if (edge.kind === "imports") {
+        const callerNode = graph.getNode(edge.source);
+        if (callerNode?.filePath && (callerNode.filePath.includes(".test.") || callerNode.filePath.includes(".spec."))) {
+          testCoverage = true;
+          break;
+        }
+      }
+    }
+    changedSymbols.push({ name: symbolNode.name, risk, callerCount, testCoverage });
+  }
+  const impactedSymbols = [];
+  for (const id of allBlastRadiusNodes) {
+    if (changedSymbolIds.has(id)) continue;
+    const node = graph.getNode(id);
+    if (node) {
+      impactedSymbols.push({ name: node.name, filePath: node.filePath });
+    }
+  }
+  const riskSummary = { HIGH: 0, MEDIUM: 0, LOW: 0 };
+  for (const s of changedSymbols) {
+    riskSummary[s.risk]++;
+  }
+  const coverageGaps = [];
+  for (const s of changedSymbols) {
+    if ((s.risk === "HIGH" || s.risk === "MEDIUM") && !s.testCoverage) {
+      coverageGaps.push(`${s.name} has no test coverage`);
+    }
+  }
+  const fileImpactCount = /* @__PURE__ */ new Map();
+  for (const sym of impactedSymbols) {
+    if (sym.filePath) {
+      fileImpactCount.set(sym.filePath, (fileImpactCount.get(sym.filePath) ?? 0) + 1);
+    }
+  }
+  const filesToReview = [...fileImpactCount.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([fp]) => fp);
+  return {
+    changedSymbols,
+    impactedSymbols,
+    riskSummary,
+    coverageGaps,
+    filesToReview,
+    crossRepoImpact: null
+  };
+}
+
+// src/query/similar-symbols.ts
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    (_, i) => Array.from({ length: n + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
+  }
+  return dp[m][n];
+}
+function findSimilarSymbols(graph, symbolName, limit) {
+  const clampedLimit = Math.min(Math.max(1, limit), 50);
+  const allNodes = [...graph.allNodes()];
+  const targetNode = allNodes.find((n) => n.name === symbolName);
+  if (!targetNode) {
+    return { similar: [] };
+  }
+  let targetCluster = null;
+  for (const edge of graph.findEdgesFrom(targetNode.id)) {
+    if (edge.kind === "belongs_to") {
+      const clusterNode = graph.getNode(edge.target);
+      if (clusterNode) {
+        targetCluster = clusterNode.name;
+        break;
+      }
+    }
+  }
+  if (!targetCluster) {
+    for (const edge of graph.findEdgesTo(targetNode.id)) {
+      if (edge.kind === "belongs_to") {
+        const clusterNode = graph.getNode(edge.source);
+        if (clusterNode) {
+          targetCluster = clusterNode.name;
+          break;
+        }
+      }
+    }
+  }
+  const results = [];
+  for (const node of allNodes) {
+    if (node.id === targetNode.id) continue;
+    const maxLen = Math.max(symbolName.length, node.name.length);
+    const nameSim = maxLen === 0 ? 1 : 1 - levenshtein(symbolName, node.name) / maxLen;
+    const structuralSim = node.kind === targetNode.kind ? 0.5 : 0;
+    const combined = 0.5 * nameSim + 0.5 * structuralSim;
+    const reasons = [];
+    if (nameSim >= 0.6) reasons.push("similar name");
+    if (node.kind === targetNode.kind) reasons.push("same kind");
+    if (targetCluster !== null) {
+      let nodeCluster = null;
+      for (const edge of graph.findEdgesFrom(node.id)) {
+        if (edge.kind === "belongs_to") {
+          const clusterNode = graph.getNode(edge.target);
+          if (clusterNode) {
+            nodeCluster = clusterNode.name;
+            break;
+          }
+        }
+      }
+      if (!nodeCluster) {
+        for (const edge of graph.findEdgesTo(node.id)) {
+          if (edge.kind === "belongs_to") {
+            const clusterNode = graph.getNode(edge.source);
+            if (clusterNode) {
+              nodeCluster = clusterNode.name;
+              break;
+            }
+          }
+        }
+      }
+      if (nodeCluster !== null && nodeCluster === targetCluster) {
+        reasons.push("same module");
+      }
+    }
+    if (targetNode.metadata?.["cluster"] !== void 0 && node.metadata?.["cluster"] !== void 0 && node.metadata["cluster"] === targetNode.metadata["cluster"]) {
+      if (!reasons.includes("same module")) reasons.push("same module");
+    }
+    results.push({ name: node.name, similarity: combined, reasons });
+  }
+  results.sort((a, b) => b.similarity - a.similarity);
+  return { similar: results.slice(0, clampedLimit) };
+}
+
+// src/query/health-report.ts
+function computeHealthReport(graph, scope) {
+  const wholeRepo = scope === ".";
+  function inScope(filePath) {
+    if (wholeRepo) return true;
+    return filePath.startsWith(scope) || filePath.includes(scope);
+  }
+  const scopedNodes = [...graph.allNodes()].filter((n) => inScope(n.filePath));
+  const deadCodeKinds = /* @__PURE__ */ new Set(["function", "method", "class"]);
+  const deadCode = [];
+  for (const node of scopedNodes) {
+    if (!deadCodeKinds.has(node.kind)) continue;
+    if (node.exported === true) continue;
+    let hasIncoming = false;
+    for (const _edge of graph.findEdgesTo(node.id)) {
+      hasIncoming = true;
+      break;
+    }
+    if (!hasIncoming) {
+      deadCode.push({ name: node.name, filePath: node.filePath, kind: node.kind });
+      if (deadCode.length >= 20) break;
+    }
+  }
+  const cycles = [];
+  const scopedNodeIds = new Set(scopedNodes.map((n) => n.id));
+  const importAdj = /* @__PURE__ */ new Map();
+  for (const node of scopedNodes) {
+    importAdj.set(node.id, []);
+  }
+  for (const edge of graph.findEdgesByKind("imports")) {
+    if (scopedNodeIds.has(edge.source) && scopedNodeIds.has(edge.target)) {
+      importAdj.get(edge.source).push(edge.target);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  const stackPath = [];
+  function dfs(nodeId) {
+    if (cycles.length >= 5) return;
+    visited.add(nodeId);
+    inStack.add(nodeId);
+    stackPath.push(nodeId);
+    for (const neighborId of importAdj.get(nodeId) ?? []) {
+      if (cycles.length >= 5) break;
+      if (inStack.has(neighborId)) {
+        const cycleStart = stackPath.indexOf(neighborId);
+        const cyclePath = stackPath.slice(cycleStart).map((id) => {
+          const node = graph.getNode(id);
+          return node ? node.name : id;
+        });
+        cycles.push(cyclePath);
+      } else if (!visited.has(neighborId)) {
+        dfs(neighborId);
+      }
+    }
+    stackPath.pop();
+    inStack.delete(nodeId);
+  }
+  for (const node of scopedNodes) {
+    if (cycles.length >= 5) break;
+    if (!visited.has(node.id)) {
+      dfs(node.id);
+    }
+  }
+  const godNodes = [];
+  for (const node of scopedNodes) {
+    let edgeCount = 0;
+    for (const _edge of graph.findEdgesFrom(node.id)) {
+      edgeCount++;
+    }
+    if (edgeCount > 10) {
+      godNodes.push({ name: node.name, edgeCount, filePath: node.filePath });
+    }
+  }
+  godNodes.sort((a, b) => b.edgeCount - a.edgeCount);
+  godNodes.splice(10);
+  const filePathToNodes = /* @__PURE__ */ new Map();
+  for (const node of scopedNodes) {
+    if (!node.filePath) continue;
+    let arr = filePathToNodes.get(node.filePath);
+    if (!arr) {
+      arr = [];
+      filePathToNodes.set(node.filePath, arr);
+    }
+    arr.push(node.id);
+  }
+  const orphanFiles = [];
+  for (const [filePath, nodeIds] of filePathToNodes) {
+    if (orphanFiles.length >= 10) break;
+    let hasAnyEdge = false;
+    for (const nodeId of nodeIds) {
+      let hasOut = false;
+      for (const _edge of graph.findEdgesFrom(nodeId)) {
+        hasOut = true;
+        break;
+      }
+      let hasIn = false;
+      for (const _edge of graph.findEdgesTo(nodeId)) {
+        hasIn = true;
+        break;
+      }
+      if (hasOut || hasIn) {
+        hasAnyEdge = true;
+        break;
+      }
+    }
+    if (!hasAnyEdge) {
+      orphanFiles.push(filePath);
+    }
+  }
+  const hotspotCandidates = [];
+  for (const node of scopedNodes) {
+    const visitedBfs = /* @__PURE__ */ new Set();
+    const queue = [{ id: node.id, depth: 0 }];
+    while (queue.length > 0) {
+      const item = queue.shift();
+      if (item.depth > 5 || visitedBfs.has(item.id)) continue;
+      visitedBfs.add(item.id);
+      for (const edge of graph.findEdgesTo(item.id)) {
+        if (edge.kind === "calls" || edge.kind === "imports") {
+          if (!visitedBfs.has(edge.source)) {
+            queue.push({ id: edge.source, depth: item.depth + 1 });
+          }
+        }
+      }
+    }
+    const blastRadius = visitedBfs.size - 1;
+    hotspotCandidates.push({ name: node.name, blastRadius, filePath: node.filePath });
+  }
+  hotspotCandidates.sort((a, b) => b.blastRadius - a.blastRadius);
+  const complexityHotspots = hotspotCandidates.slice(0, 5);
+  const healthScore = Math.max(
+    0,
+    Math.min(100, 100 - deadCode.length * 2 - cycles.length * 5 - godNodes.length * 3)
+  );
+  return {
+    healthScore,
+    deadCode,
+    cycles,
+    godNodes,
+    orphanFiles,
+    complexityHotspots
+  };
+}
+
+// src/query/suggest-tests.ts
+function getSuggestedCases(symbolName) {
+  const lower = symbolName.toLowerCase();
+  if (/parse|validate|check|verify/.test(lower)) {
+    return [
+      "Valid input \u2192 success",
+      "Invalid input \u2192 throws error",
+      "Edge case: empty/null input \u2192 handled gracefully"
+    ];
+  }
+  if (/create|add|insert|save/.test(lower)) {
+    return [
+      "Success: valid data \u2192 created",
+      "Duplicate: existing item \u2192 error or no-op",
+      "Missing required fields \u2192 validation error"
+    ];
+  }
+  if (/delete|remove|destroy/.test(lower)) {
+    return [
+      "Existing item \u2192 deleted successfully",
+      "Non-existent item \u2192 no error or 404",
+      "Unauthorized access \u2192 rejected"
+    ];
+  }
+  if (/get|find|fetch|load/.test(lower)) {
+    return [
+      "Found: returns correct data",
+      "Not found: returns null or throws",
+      "Empty collection: returns []"
+    ];
+  }
+  return [
+    "Happy path: valid input \u2192 expected output",
+    "Error case: invalid input \u2192 error handled",
+    "Edge case: boundary values \u2192 correct behavior"
+  ];
+}
+function suggestTests(graph, symbolName) {
+  let targetNode = void 0;
+  for (const node of graph.allNodes()) {
+    if (node.name === symbolName) {
+      targetNode = node;
+      break;
+    }
+  }
+  if (!targetNode) {
+    return { error: `Symbol not found: ${symbolName}` };
+  }
+  const targetId = targetNode.id;
+  const callPaths = [];
+  const pathQueue = [{ id: targetId, path: [symbolName], depth: 0 }];
+  while (pathQueue.length > 0 && callPaths.length < 5) {
+    const { id, path: path30, depth } = pathQueue.shift();
+    let hasCallers = false;
+    for (const edge of graph.findEdgesTo(id)) {
+      if (edge.kind !== "calls") continue;
+      const callerNode = graph.getNode(edge.source);
+      if (!callerNode) continue;
+      hasCallers = true;
+      const newPath = [callerNode.name, ...path30];
+      if (depth + 1 >= 3 || callPaths.length >= 5) {
+        if (callPaths.length < 5) callPaths.push(newPath);
+        continue;
+      }
+      pathQueue.push({ id: edge.source, path: newPath, depth: depth + 1 });
+    }
+    if (!hasCallers && path30.length > 1) {
+      callPaths.push(path30);
+    }
+  }
+  if (callPaths.length === 0) {
+    for (const edge of graph.findEdgesTo(targetId)) {
+      if (edge.kind !== "calls") continue;
+      const callerNode = graph.getNode(edge.source);
+      if (!callerNode) continue;
+      callPaths.push([callerNode.name, symbolName]);
+      if (callPaths.length >= 5) break;
+    }
+  }
+  const existingTestFiles = /* @__PURE__ */ new Set();
+  for (const edge of graph.findEdgesTo(targetId)) {
+    if (edge.kind !== "imports") continue;
+    const importerNode = graph.getNode(edge.source);
+    if (!importerNode) continue;
+    if (importerNode.filePath.includes(".test.") || importerNode.filePath.includes(".spec.")) {
+      existingTestFiles.add(importerNode.filePath);
+    }
+  }
+  const existingTests = [...existingTestFiles];
+  const untestedCallers = [];
+  for (const edge of graph.findEdgesTo(targetId)) {
+    if (edge.kind !== "calls") continue;
+    const callerNode = graph.getNode(edge.source);
+    if (!callerNode) continue;
+    if (callerNode.filePath.includes(".test.") || callerNode.filePath.includes(".spec.")) {
+      continue;
+    }
+    let callerHasTest = false;
+    for (const callerImportEdge of graph.findEdgesTo(callerNode.id)) {
+      if (callerImportEdge.kind !== "imports") continue;
+      const importerOfCaller = graph.getNode(callerImportEdge.source);
+      if (!importerOfCaller) continue;
+      if (importerOfCaller.filePath.includes(".test.") || importerOfCaller.filePath.includes(".spec.")) {
+        callerHasTest = true;
+        break;
+      }
+    }
+    if (!callerHasTest) {
+      untestedCallers.push(callerNode.name);
+    }
+  }
+  const suggestedCases = getSuggestedCases(symbolName);
+  return {
+    callPaths,
+    suggestedCases,
+    existingTests,
+    untestedCallers
+  };
+}
+
+// src/query/cluster-summary.ts
+function getPathPrefix(filePath) {
+  const parts = filePath.replace(/\\/g, "/").split("/");
+  return parts.slice(0, 2).join("/");
+}
+function summarizeCluster(graph, cluster) {
+  const clusterNodes = [...graph.allNodes()].filter(
+    (n) => n.filePath.startsWith(cluster) || n.metadata?.["cluster"] === cluster
+  );
+  if (clusterNodes.length === 0) {
+    return { error: `Cluster not found: ${cluster}` };
+  }
+  const clusterNodeIds = new Set(clusterNodes.map((n) => n.id));
+  const callerCountMap = /* @__PURE__ */ new Map();
+  for (const node of clusterNodes) {
+    let count = 0;
+    for (const _edge of graph.findEdgesTo(node.id)) {
+      count++;
+    }
+    callerCountMap.set(node.id, count);
+  }
+  const sortedByCallers = [...clusterNodes].sort(
+    (a, b) => (callerCountMap.get(b.id) ?? 0) - (callerCountMap.get(a.id) ?? 0)
+  );
+  const keySymbols = sortedByCallers.slice(0, 5).map((n) => ({
+    name: n.name,
+    callerCount: callerCountMap.get(n.id) ?? 0
+  }));
+  const depsSet = /* @__PURE__ */ new Set();
+  for (const node of clusterNodes) {
+    for (const edge of graph.findEdgesFrom(node.id)) {
+      if (edge.kind !== "imports") continue;
+      const targetNode = graph.getNode(edge.target);
+      if (!targetNode) continue;
+      if (!clusterNodeIds.has(targetNode.id)) {
+        const prefix = getPathPrefix(targetNode.filePath);
+        depsSet.add(prefix);
+      }
+    }
+  }
+  const dependencies = [...depsSet];
+  const dependentsSet = /* @__PURE__ */ new Set();
+  for (const node of clusterNodes) {
+    for (const edge of graph.findEdgesTo(node.id)) {
+      if (edge.kind !== "imports") continue;
+      const sourceNode = graph.getNode(edge.source);
+      if (!sourceNode) continue;
+      if (!clusterNodeIds.has(sourceNode.id)) {
+        const prefix = getPathPrefix(sourceNode.filePath);
+        dependentsSet.add(prefix);
+      }
+    }
+  }
+  const dependents = [...dependentsSet];
+  const healthResult = computeHealthReport(graph, cluster);
+  const health = { score: healthResult.healthScore };
+  const symbolCount = {};
+  for (const node of clusterNodes) {
+    symbolCount[node.kind] = (symbolCount[node.kind] ?? 0) + 1;
+  }
+  let purpose;
+  const topNode = sortedByCallers[0];
+  if (topNode?.metadata?.["summary"] && typeof topNode.metadata["summary"] === "string") {
+    purpose = topNode.metadata["summary"];
+  } else {
+    const clusterName = cluster.split("/").pop() ?? cluster;
+    purpose = `Handles ${clusterName.replace(/[-_/]/g, " ")} functionality`;
+  }
+  return {
+    cluster,
+    purpose,
+    keySymbols,
+    dependencies,
+    dependents,
+    health,
+    symbolCount
+  };
+}
+
+// src/mcp-server/server.ts
 function createMcpServer(graph, repoName, workspaceRoot) {
   const server = new Server(
     { name: "code-intel", version: "0.1.0" },
@@ -6889,7 +7760,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           type: "object",
           properties: {
             query: { type: "string", description: "Search query (symbol name, keyword, or partial match)" },
-            limit: { type: "number", description: "Max results to return (default: 20)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           },
           required: ["query"]
@@ -6932,6 +7804,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           type: "object",
           properties: {
             file_path: { type: "string", description: 'File path (partial match is supported, e.g. "auth/login.ts")' },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           },
           required: ["file_path"]
@@ -6961,7 +7835,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
               type: "string",
               description: "Filter by node kind: function | class | interface | method | type_alias | constant | enum (optional)"
             },
-            limit: { type: "number", description: "Max results (default: 100)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -6978,7 +7853,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
         inputSchema: {
           type: "object",
           properties: {
-            limit: { type: "number", description: "Max clusters to return (default: 50)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max clusters per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -6989,7 +7865,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
         inputSchema: {
           type: "object",
           properties: {
-            limit: { type: "number", description: "Max flows to return (default: 50)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max flows per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -7111,6 +7988,91 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           },
           required: ["name"]
         }
+      },
+      // ── Reasoning / analysis tools ────────────────────────────────────────
+      {
+        name: "explain_relationship",
+        description: "Explain how two symbols are connected: directed paths, shared imports, and heritage (extends/implements). Returns up to 10 paths with at most 5 hops each.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            from: { type: "string", description: "Source symbol name" },
+            to: { type: "string", description: "Target symbol name" },
+            ..._tokenProp
+          },
+          required: ["from", "to"]
+        }
+      },
+      {
+        name: "pr_impact",
+        description: "Given changed files or a unified diff, compute full blast radius with risk scores (HIGH/MEDIUM/LOW), test coverage gaps, and top files to review.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            changedFiles: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of changed file paths (relative or absolute)"
+            },
+            diff: {
+              type: "string",
+              description: "Raw unified diff text. Changed files are extracted automatically."
+            },
+            maxHops: {
+              type: "number",
+              description: "Maximum BFS depth for blast radius (default: 5)"
+            },
+            ..._tokenProp
+          }
+        }
+      },
+      {
+        name: "similar_symbols",
+        description: "Find symbols with similar names or structure using Levenshtein distance and kind matching. Useful for finding related functions, classes, or interfaces.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            symbol: { type: "string", description: "Symbol name to find similar symbols for" },
+            limit: { type: "number", description: "Maximum number of results (default: 10, max: 50)" },
+            ..._tokenProp
+          },
+          required: ["symbol"]
+        }
+      },
+      {
+        name: "health_report",
+        description: "Code health signals for a scope: dead code, cycles, god nodes, orphan files, complexity hotspots",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scope: { type: "string", description: "Directory scope, e.g. 'src/api/' or '.' for whole repo" },
+            ..._tokenProp
+          }
+        }
+      },
+      {
+        name: "suggest_tests",
+        description: "Suggest test cases for a symbol: call paths, suggested cases, existing tests, untested callers",
+        inputSchema: {
+          type: "object",
+          properties: {
+            symbol: { type: "string", description: "Symbol name to generate test suggestions for" },
+            ..._tokenProp
+          },
+          required: ["symbol"]
+        }
+      },
+      {
+        name: "cluster_summary",
+        description: "Rich summary of a module/cluster: purpose, key symbols, dependencies, health",
+        inputSchema: {
+          type: "object",
+          properties: {
+            cluster: { type: "string", description: "Cluster path e.g. 'src/auth'" },
+            ..._tokenProp
+          },
+          required: ["cluster"]
+        }
       }
     ]
   }));
@@ -7181,8 +8143,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       for (const edge of graph.allEdges()) {
         edgeCounts[edge.kind] = (edgeCounts[edge.kind] ?? 0) + 1;
       }
-      const { computeHealthReport: computeHealthReport2 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
-      const healthReport = computeHealthReport2(graph);
+      const { computeHealthReport: computeHealthReport3 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
+      const healthReport = computeHealthReport3(graph);
       const health = {
         score: Math.round(healthReport.score),
         grade: healthReport.grade,
@@ -7207,10 +8169,37 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── search ─────────────────────────────────────────────────────────────
     case "search": {
       const query = a.query;
-      const limit = a.limit ?? 20;
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
       const vdbPath = workspaceRoot ? getVectorDbPath(workspaceRoot) : void 0;
-      const { results, searchMode } = await hybridSearch(graph, query, limit, { vectorDbPath: vdbPath });
-      return { content: [{ type: "text", text: JSON.stringify({ results, searchMode, suggested_next_tools: ["inspect", "query", "blast_radius"] }, null, 2) }] };
+      const fetchLimit = Math.min(offset + effectiveLimit, 500);
+      const { results: allResults, searchMode } = await hybridSearch(graph, query, fetchLimit, { vectorDbPath: vdbPath });
+      const total = allResults.length;
+      const results = allResults.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      const suggestNextTools = [];
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      if (suggestEnabled && results.length > 0) {
+        const topName = results[0].name;
+        suggestNextTools.push(
+          { tool: "inspect", reason: "Inspect the top result in detail", input: { symbol: topName } },
+          { tool: "similar_symbols", reason: "Find symbols similar to the top result", input: { symbol: topName } }
+        );
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            results,
+            searchMode,
+            total,
+            offset,
+            limit: effectiveLimit,
+            hasMore,
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
+          }, null, 2)
+        }]
+      };
     }
     // ── inspect ────────────────────────────────────────────────────────────
     case "inspect": {
@@ -7219,6 +8208,26 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       if (!node) return { content: [{ type: "text", text: `Symbol "${symbolName}" not found. Try search first.` }] };
       const incoming = [...graph.findEdgesTo(node.id)];
       const outgoing = [...graph.findEdgesFrom(node.id)];
+      const callers = incoming.filter((e) => e.kind === "calls").map((e) => ({
+        id: e.source,
+        name: graph.getNode(e.source)?.name,
+        file: graph.getNode(e.source)?.filePath
+      }));
+      const callees = outgoing.filter((e) => e.kind === "calls").map((e) => ({
+        id: e.target,
+        name: graph.getNode(e.target)?.name,
+        file: graph.getNode(e.target)?.filePath
+      }));
+      const cluster = incoming.filter((e) => e.kind === "belongs_to").map((e) => graph.getNode(e.target)?.name)[0];
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      const suggestNextTools = [];
+      if (suggestEnabled) {
+        const topCallerName = callers[0]?.name;
+        suggestNextTools.push(
+          ...topCallerName ? [{ tool: "explain_relationship", reason: "Explain connection to a related symbol", input: { from: node.name, to: topCallerName } }] : [],
+          ...cluster ? [{ tool: "cluster_summary", reason: "Summarize the module this symbol belongs to", input: { cluster } }] : [{ tool: "cluster_summary", reason: "Summarize the module this symbol belongs to", input: { cluster: node.filePath } }]
+        );
+      }
       return {
         content: [{
           type: "text",
@@ -7232,16 +8241,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               endLine: node.endLine,
               exported: node.exported
             },
-            callers: incoming.filter((e) => e.kind === "calls").map((e) => ({
-              id: e.source,
-              name: graph.getNode(e.source)?.name,
-              file: graph.getNode(e.source)?.filePath
-            })),
-            callees: outgoing.filter((e) => e.kind === "calls").map((e) => ({
-              id: e.target,
-              name: graph.getNode(e.target)?.name,
-              file: graph.getNode(e.target)?.filePath
-            })),
+            callers,
+            callees,
             imports: incoming.filter((e) => e.kind === "imports").map((e) => graph.getNode(e.source)?.name),
             importedBy: outgoing.filter((e) => e.kind === "imports").map((e) => graph.getNode(e.target)?.name),
             extends: outgoing.filter((e) => e.kind === "extends").map((e) => graph.getNode(e.target)?.name),
@@ -7250,8 +8251,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               name: graph.getNode(e.target)?.name,
               kind: graph.getNode(e.target)?.kind
             })),
-            cluster: incoming.filter((e) => e.kind === "belongs_to").map((e) => graph.getNode(e.target)?.name)[0],
-            content: node.content?.slice(0, 500)
+            cluster,
+            content: node.content?.slice(0, 500),
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
           }, null, 2)
         }]
       };
@@ -7287,6 +8289,16 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
       });
       const risk = affected.size > 10 ? "HIGH" : affected.size > 5 ? "MEDIUM" : "LOW";
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      const suggestNextTools = [];
+      if (suggestEnabled) {
+        const highestRiskSymbol = node.name;
+        const firstFilePath = affectedDetails[0]?.filePath ?? "";
+        suggestNextTools.push(
+          { tool: "suggest_tests", reason: "Generate tests for the highest-risk symbol", input: { symbol: highestRiskSymbol } },
+          { tool: "pr_impact", reason: "Compute full PR impact for changed files", input: { changedFiles: [firstFilePath] } }
+        );
+      }
       return {
         content: [{
           type: "text",
@@ -7294,7 +8306,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
             target: node.name,
             affectedCount: affected.size,
             riskLevel: risk,
-            affected: affectedDetails
+            affected: affectedDetails,
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
           }, null, 2)
         }]
       };
@@ -7302,17 +8315,27 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── file_symbols ───────────────────────────────────────────────────────
     case "file_symbols": {
       const filePath = a.file_path;
-      const matches = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allMatches = [];
       for (const node of graph.allNodes()) {
         if (node.filePath && node.filePath.includes(filePath)) {
-          matches.push({ kind: node.kind, name: node.name, startLine: node.startLine, exported: node.exported });
+          allMatches.push({ kind: node.kind, name: node.name, startLine: node.startLine, exported: node.exported });
         }
       }
-      if (matches.length === 0) {
+      if (allMatches.length === 0) {
         return { content: [{ type: "text", text: `No symbols found for file path matching "${filePath}".` }] };
       }
-      matches.sort((a2, b) => (a2.startLine ?? 0) - (b.startLine ?? 0));
-      return { content: [{ type: "text", text: JSON.stringify(matches, null, 2) }] };
+      allMatches.sort((a2, b) => (a2.startLine ?? 0) - (b.startLine ?? 0));
+      const total = allMatches.length;
+      const matches = allMatches.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ symbols: matches, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── find_path ──────────────────────────────────────────────────────────
     case "find_path": {
@@ -7358,15 +8381,23 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── list_exports ───────────────────────────────────────────────────────
     case "list_exports": {
       const kindFilter = a.kind;
-      const limit = a.limit ?? 100;
-      const exports$1 = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allExports = [];
       for (const node of graph.allNodes()) {
         if (!node.exported) continue;
         if (kindFilter && node.kind !== kindFilter) continue;
-        exports$1.push({ kind: node.kind, name: node.name, filePath: node.filePath, startLine: node.startLine });
-        if (exports$1.length >= limit) break;
+        allExports.push({ kind: node.kind, name: node.name, filePath: node.filePath, startLine: node.startLine });
       }
-      return { content: [{ type: "text", text: JSON.stringify({ total: exports$1.length, exports: exports$1 }, null, 2) }] };
+      const total = allExports.length;
+      const exports$1 = allExports.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ exports: exports$1, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── routes ─────────────────────────────────────────────────────────────
     case "routes": {
@@ -7380,8 +8411,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     }
     // ── clusters ───────────────────────────────────────────────────────────
     case "clusters": {
-      const limit = a.limit ?? 50;
-      const clusters = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allClusters = [];
       for (const node of graph.allNodes()) {
         if (node.kind === "cluster") {
           const members = [];
@@ -7393,35 +8425,50 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               }
             }
           }
-          clusters.push({
+          allClusters.push({
             id: node.id,
             name: node.name,
             memberCount: node.metadata?.memberCount ?? members.length,
             topSymbols: members.slice(0, 10)
           });
-          if (clusters.length >= limit) break;
         }
       }
-      return { content: [{ type: "text", text: JSON.stringify(clusters, null, 2) }] };
+      const total = allClusters.length;
+      const clusters = allClusters.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ clusters, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── flows ──────────────────────────────────────────────────────────────
     case "flows": {
-      const limit = a.limit ?? 50;
-      const flows = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allFlows = [];
       for (const node of graph.allNodes()) {
         if (node.kind === "flow") {
           const steps = node.metadata?.steps;
-          flows.push({
+          allFlows.push({
             id: node.id,
             name: node.name,
             entryPoint: node.metadata?.entryPoint,
             steps: steps ?? [],
             stepCount: Array.isArray(steps) ? steps.length : 0
           });
-          if (flows.length >= limit) break;
         }
       }
-      return { content: [{ type: "text", text: JSON.stringify(flows, null, 2) }] };
+      const total = allFlows.length;
+      const flows = allFlows.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ flows, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── detect_changes ─────────────────────────────────────────────────────
     case "detect_changes": {
@@ -7449,7 +8496,7 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       for (const { filePath: changedFile, changedLines } of changedFiles) {
         for (const node of graph.allNodes()) {
           if (!node.filePath) continue;
-          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path27.sep, "");
+          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path29.sep, "");
           const normChanged = changedFile.replace(/^a\/|^b\//, "");
           if (!normNode.endsWith(normChanged) && !normChanged.endsWith(normNode)) continue;
           if (node.startLine !== void 0 && node.endLine !== void 0) {
@@ -7671,6 +8718,57 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         }]
       };
     }
+    // ── explain_relationship ───────────────────────────────────────────────
+    case "explain_relationship": {
+      const fromName = a.from;
+      const toName = a.to;
+      const result = explainRelationship(graph, fromName, toName);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── pr_impact ──────────────────────────────────────────────────────────
+    case "pr_impact": {
+      const maxHops = a.maxHops ?? 5;
+      let changedFiles = a.changedFiles ?? [];
+      if (a.diff && typeof a.diff === "string") {
+        const diffFiles = parseDiffFiles(a.diff);
+        changedFiles = [.../* @__PURE__ */ new Set([...changedFiles, ...diffFiles])];
+      }
+      if (changedFiles.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ error: 'No changed files provided. Supply "changedFiles" or "diff".' })
+          }]
+        };
+      }
+      const result = computePRImpact(graph, changedFiles, maxHops);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── similar_symbols ────────────────────────────────────────────────────
+    case "similar_symbols": {
+      const symbolName = a.symbol;
+      const limit = a.limit ?? 10;
+      const result = findSimilarSymbols(graph, symbolName, limit);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── health_report ──────────────────────────────────────────────────────
+    case "health_report": {
+      const scope = a.scope ?? ".";
+      const result = computeHealthReport(graph, scope);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── suggest_tests ──────────────────────────────────────────────────────
+    case "suggest_tests": {
+      const sym = a.symbol;
+      const result = suggestTests(graph, sym);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── cluster_summary ────────────────────────────────────────────────────
+    case "cluster_summary": {
+      const cluster = a.cluster;
+      const result = summarizeCluster(graph, cluster);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
     default:
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
   }
@@ -7764,7 +8862,7 @@ var STUCK_THRESHOLD_MINUTES = 30;
 var JobsDB = class {
   db;
   constructor(dbPath) {
-    fs19.mkdirSync(path27.dirname(dbPath), { recursive: true });
+    fs23.mkdirSync(path29.dirname(dbPath), { recursive: true });
     this.db = new Database3(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("foreign_keys = ON");
@@ -7906,7 +9004,7 @@ var JobsDB = class {
   }
 };
 function getJobsDBPath() {
-  return path27.join(os12.homedir(), ".code-intel", "jobs.db");
+  return path29.join(os12.homedir(), ".code-intel", "jobs.db");
 }
 var _jobsDB = null;
 function getOrCreateJobsDB() {
@@ -7998,7 +9096,7 @@ var BACKUP_VERSION = "1.0";
 var ALGORITHM = "aes-256-gcm";
 var IV_LENGTH = 16;
 function getBackupDir() {
-  return path27.join(os12.homedir(), ".code-intel", "backups");
+  return path29.join(os12.homedir(), ".code-intel", "backups");
 }
 function getBackupKey() {
   const keyHex = process.env["CODE_INTEL_BACKUP_KEY"];
@@ -8029,30 +9127,30 @@ var BackupService = class {
   constructor(backupDir) {
     this.backupDir = backupDir ?? getBackupDir();
     this.key = getBackupKey();
-    fs19.mkdirSync(this.backupDir, { recursive: true });
+    fs23.mkdirSync(this.backupDir, { recursive: true });
   }
   /**
    * Create a backup for a repository.
    * Returns the backup entry.
    */
   createBackup(repoPath) {
-    const codeIntelDir = path27.join(repoPath, ".code-intel");
+    const codeIntelDir = path29.join(repoPath, ".code-intel");
     const id = v4();
     const createdAt = (/* @__PURE__ */ new Date()).toISOString();
     const filesToBackup = [];
     const candidates = ["graph.db", "vector.db", "meta.json"];
     for (const f of candidates) {
-      const fp = path27.join(codeIntelDir, f);
-      if (fs19.existsSync(fp)) {
+      const fp = path29.join(codeIntelDir, f);
+      if (fs23.existsSync(fp)) {
         filesToBackup.push({ name: f, localPath: fp });
       }
     }
-    const registryPath = path27.join(os12.homedir(), ".code-intel", "registry.json");
-    if (fs19.existsSync(registryPath)) {
+    const registryPath = path29.join(os12.homedir(), ".code-intel", "registry.json");
+    if (fs23.existsSync(registryPath)) {
       filesToBackup.push({ name: "registry.json", localPath: registryPath });
     }
-    const usersDbPath = path27.join(os12.homedir(), ".code-intel", "users.db");
-    if (fs19.existsSync(usersDbPath)) {
+    const usersDbPath = path29.join(os12.homedir(), ".code-intel", "users.db");
+    if (fs23.existsSync(usersDbPath)) {
       filesToBackup.push({ name: "users.db", localPath: usersDbPath });
     }
     if (filesToBackup.length === 0) {
@@ -8063,7 +9161,7 @@ var BackupService = class {
       createdAt,
       version: BACKUP_VERSION,
       files: filesToBackup.map((f) => {
-        const data = fs19.readFileSync(f.localPath);
+        const data = fs23.readFileSync(f.localPath);
         return {
           name: f.name,
           sha256: crypto5.createHash("sha256").update(data).digest("hex"),
@@ -8077,7 +9175,7 @@ var BackupService = class {
     manifestLenBuf.writeUInt32BE(manifestBuf.length, 0);
     parts.push(manifestLenBuf, manifestBuf);
     for (const f of filesToBackup) {
-      const data = fs19.readFileSync(f.localPath);
+      const data = fs23.readFileSync(f.localPath);
       const nameBuf = Buffer.from(f.name, "utf-8");
       const nameLenBuf = Buffer.alloc(2);
       nameLenBuf.writeUInt16BE(nameBuf.length, 0);
@@ -8088,8 +9186,8 @@ var BackupService = class {
     const plaintext = Buffer.concat(parts);
     const encrypted = encryptBuffer(plaintext, this.key);
     const backupFileName = `backup-${id}.cib`;
-    const backupPath = path27.join(this.backupDir, backupFileName);
-    fs19.writeFileSync(backupPath, encrypted);
+    const backupPath = path29.join(this.backupDir, backupFileName);
+    fs23.writeFileSync(backupPath, encrypted);
     const entry = {
       id,
       createdAt,
@@ -8116,9 +9214,9 @@ var BackupService = class {
   async uploadToS3(entry) {
     const cfg = getS3Config();
     if (!cfg) throw new Error("S3 not configured. Set CODE_INTEL_BACKUP_S3_BUCKET, CODE_INTEL_BACKUP_S3_ACCESS_KEY_ID, CODE_INTEL_BACKUP_S3_SECRET_ACCESS_KEY.");
-    const fileName = path27.basename(entry.path);
+    const fileName = path29.basename(entry.path);
     const s3Key = `${cfg.prefix}${fileName}`;
-    const body = fs19.readFileSync(entry.path);
+    const body = fs23.readFileSync(entry.path);
     const result = await s3Request({ method: "PUT", cfg, key: s3Key, body });
     if (result.statusCode < 200 || result.statusCode >= 300) {
       throw new Error(`S3 upload failed (HTTP ${result.statusCode}): ${result.body.slice(0, 200)}`);
@@ -8135,8 +9233,8 @@ var BackupService = class {
     if (result.statusCode < 200 || result.statusCode >= 300) {
       throw new Error(`S3 download failed (HTTP ${result.statusCode}): ${result.body.slice(0, 200)}`);
     }
-    fs19.mkdirSync(path27.dirname(destPath), { recursive: true });
-    fs19.writeFileSync(destPath, Buffer.from(result.body, "binary"));
+    fs23.mkdirSync(path29.dirname(destPath), { recursive: true });
+    fs23.writeFileSync(destPath, Buffer.from(result.body, "binary"));
   }
   /**
    * List backup objects in S3 with the configured prefix.
@@ -8182,10 +9280,10 @@ var BackupService = class {
     if (!entry) {
       throw new Error(`Backup "${backupId}" not found.`);
     }
-    if (!fs19.existsSync(entry.path)) {
+    if (!fs23.existsSync(entry.path)) {
       throw new Error(`Backup file not found at: ${entry.path}`);
     }
-    const encrypted = fs19.readFileSync(entry.path);
+    const encrypted = fs23.readFileSync(entry.path);
     let plaintext;
     try {
       plaintext = decryptBuffer(encrypted, this.key);
@@ -8199,8 +9297,8 @@ var BackupService = class {
     offset += manifestLen;
     const manifest = JSON.parse(manifestStr);
     const restoreBase = targetRepoPath ?? entry.repoPath;
-    const codeIntelDir = path27.join(restoreBase, ".code-intel");
-    fs19.mkdirSync(codeIntelDir, { recursive: true });
+    const codeIntelDir = path29.join(restoreBase, ".code-intel");
+    fs23.mkdirSync(codeIntelDir, { recursive: true });
     for (const fileEntry of manifest.files) {
       const nameLen = plaintext.readUInt16BE(offset);
       offset += 2;
@@ -8217,18 +9315,18 @@ var BackupService = class {
       }
       let destPath;
       if (name === "registry.json" || name === "users.db") {
-        destPath = path27.join(os12.homedir(), ".code-intel", name);
+        destPath = path29.join(os12.homedir(), ".code-intel", name);
       } else {
-        destPath = path27.join(codeIntelDir, name);
+        destPath = path29.join(codeIntelDir, name);
       }
-      fs19.writeFileSync(destPath, data);
+      fs23.writeFileSync(destPath, data);
     }
   }
   /**
    * Apply retention policy: keep N daily, M weekly, L monthly backups.
    */
   applyRetention(options = { daily: 7, weekly: 4, monthly: 12 }) {
-    const entries = this._loadIndex().filter((e) => fs19.existsSync(e.path)).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    const entries = this._loadIndex().filter((e) => fs23.existsSync(e.path)).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
     const keep = /* @__PURE__ */ new Set();
     const now = /* @__PURE__ */ new Date();
     const dailyCutoff = new Date(now);
@@ -8258,7 +9356,7 @@ var BackupService = class {
     for (const e of entries) {
       if (!keep.has(e.id)) {
         try {
-          fs19.unlinkSync(e.path);
+          fs23.unlinkSync(e.path);
           deleted++;
         } catch {
         }
@@ -8270,17 +9368,17 @@ var BackupService = class {
   }
   // ── Index helpers ──────────────────────────────────────────────────────────
   _indexPath() {
-    return path27.join(this.backupDir, "index.json");
+    return path29.join(this.backupDir, "index.json");
   }
   _loadIndex() {
     try {
-      return JSON.parse(fs19.readFileSync(this._indexPath(), "utf-8"));
+      return JSON.parse(fs23.readFileSync(this._indexPath(), "utf-8"));
     } catch {
       return [];
     }
   }
   _saveIndex(entries) {
-    fs19.writeFileSync(this._indexPath(), JSON.stringify(entries, null, 2));
+    fs23.writeFileSync(this._indexPath(), JSON.stringify(entries, null, 2));
   }
   _appendIndex(entry) {
     const entries = this._loadIndex();
@@ -8939,6 +10037,30 @@ var openApiSpec = {
         }
       }
     },
+    "/groups/{name}/topology": {
+      get: {
+        tags: ["Groups"],
+        summary: "Get the topology of repos and cross-repo contract edges for a group",
+        parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+        responses: {
+          "200": {
+            description: "Repos and cross-repo edges",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    repos: { type: "array", items: { type: "object", properties: { name: { type: "string" }, groupPath: { type: "string" }, nodeCount: { type: "integer" }, edgeCount: { type: "integer" } } } },
+                    edges: { type: "array", items: { type: "object", properties: { source: { type: "string" }, target: { type: "string" }, contractName: { type: "string" }, confidence: { type: "number" }, kind: { type: "string" } } } }
+                  }
+                }
+              }
+            }
+          },
+          "404": { description: "Group not found", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
     "/query": {
       post: {
         tags: ["GQL"],
@@ -9049,11 +10171,11 @@ var openApiSpec = {
 };
 
 // src/http/app.ts
-var __dirname$1 = path27.dirname(fileURLToPath(import.meta.url));
+var __dirname$1 = path29.dirname(fileURLToPath(import.meta.url));
 var WEB_DIST = (() => {
-  const bundled = path27.resolve(__dirname$1, "..", "web");
-  if (fs19.existsSync(bundled)) return bundled;
-  return path27.resolve(__dirname$1, "..", "..", "..", "web", "dist");
+  const bundled = path29.resolve(__dirname$1, "..", "web");
+  if (fs23.existsSync(bundled)) return bundled;
+  return path29.resolve(__dirname$1, "..", "..", "..", "web", "dist");
 })();
 function getAllowedOrigins() {
   const env = process.env["CODE_INTEL_CORS_ORIGINS"];
@@ -9584,8 +10706,8 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     const registry = loadRegistry();
     const entry = registry.find((r) => r.name === requestedRepo || r.path === requestedRepo);
     if (!entry) return null;
-    const dbPath = path27.join(entry.path, ".code-intel", "graph.db");
-    if (!fs19.existsSync(dbPath)) return null;
+    const dbPath = path29.join(entry.path, ".code-intel", "graph.db");
+    if (!fs23.existsSync(dbPath)) return null;
     const repoGraph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
     try {
@@ -9672,7 +10794,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
       return;
     }
     try {
-      const content = fs19.readFileSync(file_path, "utf-8");
+      const content = fs23.readFileSync(file_path, "utf-8");
       res.json({ content });
     } catch {
       res.status(404).json({ error: { code: ErrorCodes.NOT_FOUND, message: "File not found" } });
@@ -9930,8 +11052,8 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     for (const member of group.members) {
       const regEntry = registry.find((r) => r.name === member.registryName);
       if (!regEntry) continue;
-      const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
-      if (!fs19.existsSync(dbPath)) continue;
+      const dbPath = path29.join(regEntry.path, ".code-intel", "graph.db");
+      if (!fs23.existsSync(dbPath)) continue;
       const db = new DbManager(dbPath);
       try {
         await db.init();
@@ -9943,6 +11065,45 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     }
     res.json({ nodes: [...mergedGraph.allNodes()], edges: [...mergedGraph.allEdges()] });
   });
+  app.get("/api/v1/groups/:name/topology", requireAuth, requireRole("viewer"), async (req, res) => {
+    const groupName = req.params["name"];
+    const group = loadGroup(groupName);
+    if (!group) {
+      res.status(404).json({ error: { code: ErrorCodes.NOT_FOUND, message: "Group not found" } });
+      return;
+    }
+    const syncResult = loadSyncResult(groupName);
+    const registry = loadRegistry();
+    const repos = await Promise.all(group.members.map(async (member) => {
+      const regEntry = registry.find((r) => r.name === member.registryName);
+      let nodeCount = 0;
+      let edgeCount = 0;
+      if (regEntry) {
+        const dbPath = path29.join(regEntry.path, ".code-intel", "graph.db");
+        if (fs23.existsSync(dbPath)) {
+          try {
+            const db = new DbManager(dbPath);
+            await db.init();
+            const g = createKnowledgeGraph();
+            await loadGraphFromDB(g, db);
+            db.close();
+            nodeCount = g.size.nodes;
+            edgeCount = g.size.edges;
+          } catch {
+          }
+        }
+      }
+      return { name: member.registryName, groupPath: member.groupPath, nodeCount, edgeCount };
+    }));
+    const edges = syncResult ? syncResult.links.map((link) => ({
+      source: link.providerRepo,
+      target: link.consumerRepo,
+      contractName: link.providerContract,
+      confidence: link.confidence,
+      kind: "contract"
+    })) : [];
+    res.json({ repos, edges });
+  });
   app.get("/api/v1/source", requireAuth, requireRole("viewer"), (req, res) => {
     const { file, startLine: startLineStr, endLine: endLineStr } = req.query;
     if (!file) {
@@ -9968,14 +11129,14 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
       });
       return;
     }
-    let rawResolved = path27.normalize(file);
-    if (!path27.isAbsolute(rawResolved) && workspaceRoot) {
-      rawResolved = path27.join(workspaceRoot, rawResolved);
+    let rawResolved = path29.normalize(file);
+    if (!path29.isAbsolute(rawResolved) && workspaceRoot) {
+      rawResolved = path29.join(workspaceRoot, rawResolved);
     }
-    const resolvedFile = path27.resolve(rawResolved);
+    const resolvedFile = path29.resolve(rawResolved);
     function isInsideDir(fileAbs, dir) {
-      const rel = path27.relative(path27.resolve(dir), fileAbs);
-      return !rel.startsWith("..") && !path27.isAbsolute(rel);
+      const rel = path29.relative(path29.resolve(dir), fileAbs);
+      return !rel.startsWith("..") && !path29.isAbsolute(rel);
     }
     if (workspaceRoot) {
       if (!isInsideDir(resolvedFile, workspaceRoot)) {
@@ -10012,7 +11173,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     }
     let fileContent;
     try {
-      fileContent = fs19.readFileSync(resolvedFile, "utf-8");
+      fileContent = fs23.readFileSync(resolvedFile, "utf-8");
     } catch {
       res.status(404).json({
         error: {
@@ -10043,7 +11204,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     const contextStart = Math.max(1, startLine - 20);
     const contextEnd = Math.min(lines.length, endLine + 20);
     const content = lines.slice(contextStart - 1, contextEnd).join("\n");
-    const ext = path27.extname(resolvedFile).toLowerCase();
+    const ext = path29.extname(resolvedFile).toLowerCase();
     const languageMap = {
       ".ts": "typescript",
       ".tsx": "typescript",
@@ -10178,10 +11339,10 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
       res.status(500).json({ error: { code: ErrorCodes.INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err), requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
     }
   });
-  if (fs19.existsSync(WEB_DIST)) {
+  if (fs23.existsSync(WEB_DIST)) {
     app.use(express.static(WEB_DIST));
     app.get("/{*path}", (_req, res) => {
-      res.sendFile(path27.join(WEB_DIST, "index.html"));
+      res.sendFile(path29.join(WEB_DIST, "index.html"));
     });
   }
   app.use("/admin", requireRole("admin"));