@vohongtho.infotech/code-intel 0.1.4 → 0.1.5

package/dist/cli/main.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 import { Database, Connection } from '@ladybugdb/core';
-import path, { dirname, join } from 'path';
-import fs8, { readFileSync } from 'fs';
-import os from 'os';
+import path16, { dirname, join } from 'path';
+import fs14, { readFileSync } from 'fs';
+import os2 from 'os';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
+import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
 import express from 'express';
 import cors from 'cors';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { execSync } from 'child_process';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -31,7 +34,7 @@ var init_db_manager = __esm({
         this.dbPath = dbPath;
       }
       async init() {
-        fs8.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+        fs14.mkdirSync(path16.dirname(this.dbPath), { recursive: true });
         this.db = new Database(this.dbPath);
         await this.db.init();
         this.conn = new Connection(this.db);
@@ -129,15 +132,15 @@ var init_schema = __esm({
   }
 });
 function writeNodeCSVs(graph, outputDir) {
-  fs8.mkdirSync(outputDir, { recursive: true });
+  fs14.mkdirSync(outputDir, { recursive: true });
   const tableFiles = /* @__PURE__ */ new Map();
   const tableFilePaths = /* @__PURE__ */ new Map();
   const header = "id,name,file_path,start_line,end_line,exported,content,metadata\n";
   for (const node of graph.allNodes()) {
     const table = NODE_TABLE_MAP[node.kind];
     if (!tableFiles.has(table)) {
-      const filePath = path.join(outputDir, `${table}.csv`);
-      const stream2 = fs8.createWriteStream(filePath);
+      const filePath = path16.join(outputDir, `${table}.csv`);
+      const stream2 = fs14.createWriteStream(filePath);
       stream2.write(header);
       tableFiles.set(table, stream2);
       tableFilePaths.set(table, filePath);
@@ -160,7 +163,7 @@ function writeNodeCSVs(graph, outputDir) {
   return tableFilePaths;
 }
 function writeEdgeCSV(graph, outputDir) {
-  fs8.mkdirSync(outputDir, { recursive: true });
+  fs14.mkdirSync(outputDir, { recursive: true });
   const groups = /* @__PURE__ */ new Map();
   const header = "from_id,to_id,kind,weight,label\n";
   for (const edge of graph.allEdges()) {
@@ -171,8 +174,8 @@ function writeEdgeCSV(graph, outputDir) {
     const toTable = NODE_TABLE_MAP[targetNode.kind];
     const key = `${fromTable}->${toTable}`;
     if (!groups.has(key)) {
-      const filePath = path.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
-      const stream = fs8.createWriteStream(filePath);
+      const filePath = path16.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
+      const stream = fs14.createWriteStream(filePath);
       stream.write(header);
       groups.set(key, { stream, filePath, from: fromTable, to: toTable });
     }
@@ -268,15 +271,15 @@ var init_graph_loader = __esm({
 });
 function loadRegistry() {
   try {
-    const data = fs8.readFileSync(REPOS_FILE, "utf-8");
+    const data = fs14.readFileSync(REPOS_FILE, "utf-8");
     return JSON.parse(data);
   } catch {
     return [];
   }
 }
 function saveRegistry(entries) {
-  fs8.mkdirSync(GLOBAL_DIR, { recursive: true });
-  fs8.writeFileSync(REPOS_FILE, JSON.stringify(entries, null, 2));
+  fs14.mkdirSync(GLOBAL_DIR, { recursive: true });
+  fs14.writeFileSync(REPOS_FILE, JSON.stringify(entries, null, 2));
 }
 function upsertRepo(entry) {
   const entries = loadRegistry();
@@ -295,28 +298,28 @@ function removeRepo(repoPath) {
 var GLOBAL_DIR, REPOS_FILE;
 var init_repo_registry = __esm({
   "src/storage/repo-registry.ts"() {
-    GLOBAL_DIR = path.join(os.homedir(), ".code-intel");
-    REPOS_FILE = path.join(GLOBAL_DIR, "repos.json");
+    GLOBAL_DIR = path16.join(os2.homedir(), ".code-intel");
+    REPOS_FILE = path16.join(GLOBAL_DIR, "repos.json");
   }
 });
 function saveMetadata(repoDir, metadata) {
-  const metaDir = path.join(repoDir, ".code-intel");
-  fs8.mkdirSync(metaDir, { recursive: true });
-  fs8.writeFileSync(path.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
+  const metaDir = path16.join(repoDir, ".code-intel");
+  fs14.mkdirSync(metaDir, { recursive: true });
+  fs14.writeFileSync(path16.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
 }
 function loadMetadata(repoDir) {
   try {
-    const data = fs8.readFileSync(path.join(repoDir, ".code-intel", "meta.json"), "utf-8");
+    const data = fs14.readFileSync(path16.join(repoDir, ".code-intel", "meta.json"), "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 function getDbPath(repoDir) {
-  return path.join(repoDir, ".code-intel", "graph.db");
+  return path16.join(repoDir, ".code-intel", "graph.db");
 }
 function getVectorDbPath(repoDir) {
-  return path.join(repoDir, ".code-intel", "vector.db");
+  return path16.join(repoDir, ".code-intel", "vector.db");
 }
 var init_metadata = __esm({
   "src/storage/metadata.ts"() {
@@ -448,27 +451,27 @@ __export(group_registry_exports, {
   saveSyncResult: () => saveSyncResult
 });
 function groupFile(name) {
-  return path.join(GROUPS_DIR, `${name}.json`);
+  return path16.join(GROUPS_DIR, `${name}.json`);
 }
 function loadGroup(name) {
   try {
-    return JSON.parse(fs8.readFileSync(groupFile(name), "utf-8"));
+    return JSON.parse(fs14.readFileSync(groupFile(name), "utf-8"));
   } catch {
     return null;
   }
 }
 function saveGroup(group) {
-  fs8.mkdirSync(GROUPS_DIR, { recursive: true });
-  fs8.writeFileSync(groupFile(group.name), JSON.stringify(group, null, 2) + "\n");
+  fs14.mkdirSync(GROUPS_DIR, { recursive: true });
+  fs14.writeFileSync(groupFile(group.name), JSON.stringify(group, null, 2) + "\n");
 }
 function listGroups() {
   const groups = [];
   try {
-    for (const file of fs8.readdirSync(GROUPS_DIR)) {
+    for (const file of fs14.readdirSync(GROUPS_DIR)) {
       if (!file.endsWith(".json") || file.endsWith(".sync.json")) continue;
       try {
         const g = JSON.parse(
-          fs8.readFileSync(path.join(GROUPS_DIR, file), "utf-8")
+          fs14.readFileSync(path16.join(GROUPS_DIR, file), "utf-8")
         );
         groups.push(g);
       } catch {
@@ -480,16 +483,16 @@ function listGroups() {
 }
 function deleteGroup(name) {
   try {
-    fs8.unlinkSync(groupFile(name));
+    fs14.unlinkSync(groupFile(name));
   } catch {
   }
   try {
-    fs8.unlinkSync(path.join(GROUPS_DIR, `${name}.sync.json`));
+    fs14.unlinkSync(path16.join(GROUPS_DIR, `${name}.sync.json`));
   } catch {
   }
 }
 function groupExists(name) {
-  return fs8.existsSync(groupFile(name));
+  return fs14.existsSync(groupFile(name));
 }
 function addMember(groupName, member) {
   const group = loadGroup(groupName);
@@ -515,16 +518,16 @@ function removeMember(groupName, groupPath) {
   return group;
 }
 function saveSyncResult(result) {
-  fs8.mkdirSync(GROUPS_DIR, { recursive: true });
-  fs8.writeFileSync(
-    path.join(GROUPS_DIR, `${result.groupName}.sync.json`),
+  fs14.mkdirSync(GROUPS_DIR, { recursive: true });
+  fs14.writeFileSync(
+    path16.join(GROUPS_DIR, `${result.groupName}.sync.json`),
     JSON.stringify(result, null, 2) + "\n"
   );
 }
 function loadSyncResult(groupName) {
   try {
     return JSON.parse(
-      fs8.readFileSync(path.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
+      fs14.readFileSync(path16.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
     );
   } catch {
     return null;
@@ -533,7 +536,7 @@ function loadSyncResult(groupName) {
 var GROUPS_DIR;
 var init_group_registry = __esm({
   "src/multi-repo/group-registry.ts"() {
-    GROUPS_DIR = path.join(os.homedir(), ".code-intel", "groups");
+    GROUPS_DIR = path16.join(os2.homedir(), ".code-intel", "groups");
   }
 });
 
@@ -584,6 +587,227 @@ var init_embedder = __esm({
     pipelineInstance = null;
   }
 });
+var SENSITIVE_KEYS = [
+  "password",
+  "passwd",
+  "pass",
+  "pwd",
+  "secret",
+  "secretkey",
+  "secret_key",
+  "secretaccesskey",
+  "accesskeyid",
+  "credentials",
+  "auth",
+  "authentication",
+  "login",
+  "api_key",
+  "apikey",
+  "api",
+  "access_key",
+  "access_token",
+  "accesskey",
+  "auth_key",
+  "auth_token",
+  "authkey",
+  "token",
+  "jwt",
+  "bearer_token",
+  "refresh_token",
+  "session_token",
+  "session_key",
+  "oauth_token",
+  "connection_string",
+  "conn_string",
+  "db_uri",
+  "db_url",
+  "database_url",
+  "mongodb_uri",
+  "mysql_uri",
+  "postgres_uri",
+  "sql_uri",
+  "db_username",
+  "db_password",
+  "db_host",
+  "db_port",
+  "db_name",
+  "encryption_key",
+  "crypto_key",
+  "private_key",
+  "public_key",
+  "ssl_key",
+  "ssh_key",
+  "pgp_key",
+  "rsa_key",
+  "aes_key",
+  "email",
+  "phone",
+  "telephone",
+  "mobile",
+  "ssn",
+  "social_security",
+  "credit_card",
+  "cc_number",
+  "card_number",
+  "cvv",
+  "expiry_date",
+  "birth_date",
+  "dob",
+  "address",
+  "zip_code",
+  "postal_code",
+  "bank_account",
+  "iban",
+  "swift_code",
+  "routing_number",
+  "tax_id",
+  "vat_number",
+  "financial_id",
+  "certificate",
+  "client_cert",
+  "server_cert",
+  "ca_cert",
+  "aws_key",
+  "aws_secret",
+  "azure_key",
+  "gcp_key",
+  "s3_key",
+  "cloudinary_key",
+  "stripe_key",
+  "paypal_key",
+  "twilio_key",
+  "app_secret",
+  "client_secret",
+  "consumer_secret",
+  "encryption_secret",
+  "master_key",
+  "root_password",
+  "admin_password",
+  "config_secret",
+  "env_secret",
+  "deploy_key",
+  "ci_key",
+  "session_id",
+  "cookie_secret",
+  "csrf_token",
+  "xsrf_token",
+  "license_key",
+  "product_key",
+  "serial_number",
+  "activation_code"
+];
+var SENSITIVE_PATTERNS = [
+  /(?:password|passwd|secret|api_key|access_token|auth_token|token)\s*[:=]\s*([^\s,]+)/gi,
+  /\b\d{16}\b/gi,
+  /\b\d{3}-\d{2}-\d{4}\b/gi,
+  /\b[A-Za-z0-9]{32}\b/gi,
+  /\b[A-Za-z0-9_-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}\b/gi,
+  /\b\d{10}\b/gi,
+  /\b[A-Za-z0-9]{64}\b/gi,
+  /(?:connection_string|db_uri|db_url|mongodb_uri)\s*[:=]\s*([^\s,]+)/gi,
+  /(?:apikey|api_key|auth_key)\s*[:=]\s*([^\s,]+)/gi,
+  /(?:bearer\s+)[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+/gi
+];
+var SENSITIVE_KEYS_REGEX = new RegExp(`^(${SENSITIVE_KEYS.join("|")})$`, "i");
+var Logger = class _Logger {
+  static instance = null;
+  static maskSensitiveData(value) {
+    if (typeof value === "string" && value.length > 5) {
+      const firstChar = value.at(0);
+      const lastChar = value.at(-1);
+      return firstChar + "*".repeat(value.length - 2) + lastChar;
+    }
+    return value;
+  }
+  static maskSensitive(message, args = []) {
+    const maskString = (input) => {
+      if (typeof input !== "string") return input;
+      return SENSITIVE_PATTERNS.reduce((str, pattern) => {
+        return str.replace(
+          pattern,
+          (match, value) => value ? match.replace(value, _Logger.maskSensitiveData(value)) : match
+        );
+      }, input);
+    };
+    const deepMask = (obj) => {
+      if (typeof obj === "string") return maskString(obj);
+      if (Array.isArray(obj)) return obj.map((item) => deepMask(item));
+      if (typeof obj === "object" && obj !== null) {
+        return Object.entries(obj).reduce(
+          (acc, [key, value]) => {
+            if (value === void 0) return acc;
+            const isSensitiveKey = SENSITIVE_KEYS_REGEX.test(key);
+            acc[key] = isSensitiveKey && typeof value === "string" ? _Logger.maskSensitiveData(value) : deepMask(value);
+            return acc;
+          },
+          {}
+        );
+      }
+      return obj;
+    };
+    return {
+      maskedMessage: maskString(message),
+      maskedArgs: args.map((arg) => deepMask(arg))
+    };
+  }
+  /** Global log directory: ~/.code-intel/logs */
+  static LOG_DIR = path16.join(os2.homedir(), ".code-intel", "logs");
+  static getLogger() {
+    if (!_Logger.instance) {
+      const isProduction = process.env.NODE_ENV === "production";
+      const logLevel = process.env.LOG_LEVEL ?? "info";
+      const transports = [];
+      transports.push(new winston.transports.Console());
+      if (!isProduction) {
+        try {
+          if (!fs14.existsSync(_Logger.LOG_DIR)) {
+            fs14.mkdirSync(_Logger.LOG_DIR, { recursive: true });
+          }
+          transports.push(
+            new DailyRotateFile({
+              filename: path16.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
+              datePattern: "YYYY-MM-DD",
+              maxSize: "20m",
+              maxFiles: "14d"
+            })
+          );
+        } catch {
+        }
+      }
+      _Logger.instance = winston.createLogger({
+        level: logLevel,
+        format: winston.format.combine(
+          winston.format.timestamp(),
+          winston.format.printf(({ timestamp, level, message, ...meta }) => {
+            const args = meta[/* @__PURE__ */ Symbol.for("splat")] || [];
+            const { maskedMessage, maskedArgs } = _Logger.maskSensitive(message, args);
+            const formattedArgs = maskedArgs.map(
+              (arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg)
+            );
+            const suffix = formattedArgs.length ? " " + formattedArgs.join(" ") : "";
+            return `${timestamp} [${level.toUpperCase()}]: ${maskedMessage}${suffix}`;
+          })
+        ),
+        transports
+      });
+    }
+    return _Logger.instance;
+  }
+  static info(message, ...args) {
+    _Logger.getLogger().info(message, ...args);
+  }
+  static warn(message, ...args) {
+    _Logger.getLogger().warn(message, ...args);
+  }
+  static error(message, ...args) {
+    _Logger.getLogger().error(message, ...args);
+  }
+  static debug(message, ...args) {
+    _Logger.getLogger().debug(message, ...args);
+  }
+};
+var logger_default = Logger;
+Logger.getLogger();
 
 // src/graph/knowledge-graph.ts
 function createKnowledgeGraph() {
@@ -729,25 +953,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, path15) {
+  function dfs(name, path17) {
     if (visiting.has(name)) {
-      const cycleStart = path15.indexOf(name);
-      const cycle = path15.slice(cycleStart).concat(name);
+      const cycleStart = path17.indexOf(name);
+      const cycle = path17.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);
-    path15.push(name);
+    path17.push(name);
     const phase = phaseMap.get(name);
     if (phase) {
       for (const dep of phase.dependencies) {
-        if (dfs(dep, path15)) return true;
+        if (dfs(dep, path17)) return true;
       }
     }
     visiting.delete(name);
     visited.add(name);
-    path15.pop();
+    path17.pop();
     return false;
   }
   for (const phase of phases) {
@@ -903,11 +1127,18 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".cache",
   "tmp",
   "temp",
-  ".parcel-cache"
+  ".parcel-cache",
+  ".venv",
+  "venv",
+  ".env",
+  "env",
+  "__snapshots__",
+  ".nyc_output",
+  "storybook-static"
 ]);
 function loadIgnorePatterns(workspaceRoot) {
   try {
-    const raw = fs8.readFileSync(path.join(workspaceRoot, ".codeintelignore"), "utf-8");
+    const raw = fs14.readFileSync(path16.join(workspaceRoot, ".codeintelignore"), "utf-8");
     const extras = /* @__PURE__ */ new Set();
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();
@@ -918,6 +1149,8 @@ function loadIgnorePatterns(workspaceRoot) {
     return /* @__PURE__ */ new Set();
   }
 }
+var IGNORED_FILE_SUFFIXES = [".d.ts", ".js.map", ".d.ts.map", ".min.js", ".min.css"];
+var MAX_FILE_SIZE_BYTES = 512 * 1024;
 var scanPhase = {
   name: "scan",
   dependencies: [],
@@ -929,29 +1162,35 @@ var scanPhase = {
     function walk(dir) {
       let entries;
       try {
-        entries = fs8.readdirSync(dir, { withFileTypes: true });
+        entries = fs14.readdirSync(dir, { withFileTypes: true });
       } catch {
         return;
       }
       for (const entry of entries) {
-        if (entry.name.startsWith(".") && entry.isDirectory()) continue;
-        if (IGNORED_DIRS.has(entry.name) && entry.isDirectory()) continue;
-        if (extraIgnore.has(entry.name) && entry.isDirectory()) continue;
-        const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-          walk(fullPath);
+          if (entry.name.startsWith(".")) continue;
+          if (IGNORED_DIRS.has(entry.name)) continue;
+          if (extraIgnore.has(entry.name)) continue;
+          walk(path16.join(dir, entry.name));
         } else if (entry.isFile()) {
-          const ext = path.extname(entry.name);
-          const fullName = entry.name;
-          if (fullName.endsWith(".d.ts") || fullName.endsWith(".js.map") || fullName.endsWith(".d.ts.map")) continue;
-          if (extensions.has(ext)) {
-            filePaths.push(fullPath);
+          const name = entry.name;
+          if (IGNORED_FILE_SUFFIXES.some((s) => name.endsWith(s))) continue;
+          const ext = path16.extname(name);
+          if (!extensions.has(ext)) continue;
+          const fullPath = path16.join(dir, name);
+          try {
+            const stat = fs14.statSync(fullPath);
+            if (stat.size > MAX_FILE_SIZE_BYTES) continue;
+          } catch {
+            continue;
           }
+          filePaths.push(fullPath);
         }
       }
     }
     walk(context.workspaceRoot);
     context.filePaths.push(...filePaths);
+    context.onPhaseProgress?.("scan", filePaths.length, filePaths.length);
     return {
       status: "completed",
       duration: Date.now() - start,
@@ -965,28 +1204,31 @@ var structurePhase = {
   async execute(context) {
     const start = Date.now();
     const dirs = /* @__PURE__ */ new Set();
+    let structDone = 0;
     for (const filePath of context.filePaths) {
-      const relativePath = path.relative(context.workspaceRoot, filePath);
+      const relativePath = path16.relative(context.workspaceRoot, filePath);
       const lang = detectLanguage(filePath);
       context.graph.addNode({
         id: generateNodeId("file", relativePath, relativePath),
         kind: "file",
-        name: path.basename(filePath),
+        name: path16.basename(filePath),
         filePath: relativePath,
         metadata: lang ? { language: lang } : void 0
       });
-      let dir = path.dirname(relativePath);
+      let dir = path16.dirname(relativePath);
       while (dir && dir !== "." && dir !== "") {
         if (dirs.has(dir)) break;
         dirs.add(dir);
-        dir = path.dirname(dir);
+        dir = path16.dirname(dir);
       }
+      structDone++;
+      context.onPhaseProgress?.("structure", structDone, context.filePaths.length);
     }
     for (const dir of dirs) {
       context.graph.addNode({
         id: generateNodeId("directory", dir, dir),
         kind: "directory",
-        name: path.basename(dir),
+        name: path16.basename(dir),
         filePath: dir
       });
     }
@@ -1003,23 +1245,37 @@ var parsePhase = {
   async execute(context) {
     const start = Date.now();
     let symbolCount = 0;
-    for (const filePath of context.filePaths) {
+    if (!context.fileCache) context.fileCache = /* @__PURE__ */ new Map();
+    if (!context.fileFunctionIndex) context.fileFunctionIndex = /* @__PURE__ */ new Map();
+    const CONCURRENCY = 64;
+    const filePaths = context.filePaths;
+    let readDone = 0;
+    for (let i = 0; i < filePaths.length; i += CONCURRENCY) {
+      const batch = filePaths.slice(i, i + CONCURRENCY);
+      await Promise.all(batch.map(async (filePath) => {
+        try {
+          const source = await fs14.promises.readFile(filePath, "utf-8");
+          context.fileCache.set(filePath, source);
+        } catch {
+        }
+      }));
+      readDone += batch.length;
+      context.onPhaseProgress?.("parse:read", readDone, filePaths.length);
+    }
+    let parseDone = 0;
+    for (const filePath of filePaths) {
       const lang = detectLanguage(filePath);
       if (!lang) {
         if (context.verbose) {
-          const relativePath2 = path.relative(context.workspaceRoot, filePath);
-          console.log(`  [parse] skipped (no parser): ${relativePath2}`);
+          const relativePath2 = path16.relative(context.workspaceRoot, filePath);
+          logger_default.info(`  [parse] skipped (no parser): ${relativePath2}`);
         }
         continue;
       }
-      const relativePath = path.relative(context.workspaceRoot, filePath);
+      const source = context.fileCache.get(filePath);
+      if (!source) continue;
+      const relativePath = path16.relative(context.workspaceRoot, filePath);
       const fileNodeId = generateNodeId("file", relativePath, relativePath);
-      let source;
-      try {
-        source = fs8.readFileSync(filePath, "utf-8");
-      } catch {
-        continue;
-      }
       const fileNode = context.graph.getNode(fileNodeId);
       if (fileNode) {
         fileNode.content = source.slice(0, 2e3);
@@ -1034,15 +1290,18 @@ var parsePhase = {
         if (trimmed.startsWith("//") || trimmed.startsWith("#") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
         const extracted = extractSymbol(trimmed, lang);
         if (!extracted) continue;
-        if (seen.has(extracted.name + ":" + extracted.kind)) continue;
-        seen.add(extracted.name + ":" + extracted.kind);
+        const dedupeKey = extracted.name + ":" + extracted.kind;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
         const nodeId = generateNodeId(extracted.kind, relativePath, extracted.name);
+        const endLine = estimateEndLine(lines, i, lang);
         nodes.push({
           id: nodeId,
           kind: extracted.kind,
           name: extracted.name,
           filePath: relativePath,
           startLine: i + 1,
+          endLine,
           exported: extracted.exported,
           content: extractBlock(lines, i, 20)
         });
@@ -1069,11 +1328,17 @@ var parsePhase = {
       }
       for (const n of nodes) context.graph.addNode(n);
       for (const e of edges) context.graph.addEdge(e);
+      const funcs = nodes.filter((n) => n.kind === "function" || n.kind === "method").map((n) => ({ id: n.id, startLine: n.startLine ?? 0, endLine: n.endLine })).sort((a, b) => a.startLine - b.startLine);
+      if (funcs.length > 0) {
+        context.fileFunctionIndex.set(relativePath, funcs);
+      }
+      parseDone++;
+      context.onPhaseProgress?.("parse", parseDone, filePaths.length);
     }
     return {
       status: "completed",
       duration: Date.now() - start,
-      message: `Extracted ${symbolCount} symbols`
+      message: `Extracted ${symbolCount} symbols from ${filePaths.length} files`
     };
   }
 };
@@ -1097,12 +1362,6 @@ function extractSymbol(line, lang, _lineNum, _filePath) {
     if (constVar && /^[A-Z_]+$/.test(constVar[1])) {
       return { kind: "constant", name: constVar[1], exported: line.includes("export") };
     }
-    const method = line.match(/^(?:(?:public|private|protected|static|async|readonly)\s+)*(\w+)\s*\(/);
-    if (method && !["if", "for", "while", "switch", "catch", "return", "constructor"].includes(method[1])) {
-      if (method[1] === "constructor") {
-        return { kind: "constructor", name: "constructor", exported: false };
-      }
-    }
   }
   if (lang === "python" /* Python */) {
     const func = line.match(/^(?:async\s+)?def\s+(\w+)/);
@@ -1214,32 +1473,100 @@ function extractSymbol(line, lang, _lineNum, _filePath) {
   }
   return null;
 }
+function estimateEndLine(lines, startIdx, lang) {
+  const MAX_SCAN = 200;
+  const end = Math.min(startIdx + MAX_SCAN, lines.length);
+  if (lang !== "python" /* Python */ && lang !== "ruby" /* Ruby */) {
+    let depth = 0;
+    let foundOpen = false;
+    for (let i = startIdx; i < end; i++) {
+      for (const ch of lines[i]) {
+        if (ch === "{") {
+          depth++;
+          foundOpen = true;
+        } else if (ch === "}") {
+          depth--;
+          if (foundOpen && depth === 0) return i + 1;
+        }
+      }
+    }
+    return void 0;
+  }
+  const startIndent = (lines[startIdx].match(/^(\s*)/) ?? ["", ""])[1].length;
+  for (let i = startIdx + 1; i < end; i++) {
+    const l = lines[i];
+    if (l.trim() === "") continue;
+    const indent = (l.match(/^(\s*)/) ?? ["", ""])[1].length;
+    if (indent <= startIndent && l.trim() !== "") return i;
+  }
+  return void 0;
+}
 function extractBlock(lines, startIdx, maxLines) {
   const end = Math.min(startIdx + maxLines, lines.length);
   return lines.slice(startIdx, end).join("\n");
 }
+var CALL_KEYWORDS = /* @__PURE__ */ new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "return",
+  "throw",
+  "typeof",
+  "instanceof",
+  "delete",
+  "void",
+  "new",
+  "import",
+  "export",
+  "from",
+  "const",
+  "let",
+  "var",
+  "function",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "extends",
+  "implements"
+]);
 var resolvePhase = {
   name: "resolve",
   dependencies: ["parse"],
   async execute(context) {
     const start = Date.now();
     const { graph, workspaceRoot, filePaths } = context;
+    const fileCache = context.fileCache ?? /* @__PURE__ */ new Map();
+    const fileFunctionIndex = context.fileFunctionIndex ?? /* @__PURE__ */ new Map();
     let importEdges = 0;
     let callEdges = 0;
     let heritageEdges = 0;
     const fileIndex = /* @__PURE__ */ new Map();
     for (const fp of filePaths) {
-      const rel = path.relative(workspaceRoot, fp);
+      const rel = path16.relative(workspaceRoot, fp);
       fileIndex.set(rel, fp);
       const noExt = rel.replace(/\.\w+$/, "");
       if (!fileIndex.has(noExt)) fileIndex.set(noExt, fp);
-      const base = path.basename(rel, path.extname(rel));
+      const base = path16.basename(rel, path16.extname(rel));
       if (!fileIndex.has(base)) fileIndex.set(base, fp);
     }
     const symbolIndex = /* @__PURE__ */ new Map();
     const fileSymbolIndex = /* @__PURE__ */ new Map();
     for (const node of graph.allNodes()) {
-      if (["function", "class", "interface", "method", "enum", "type_alias", "variable", "constant", "struct", "trait"].includes(node.kind)) {
+      if ([
+        "function",
+        "class",
+        "interface",
+        "method",
+        "enum",
+        "type_alias",
+        "variable",
+        "constant",
+        "struct",
+        "trait"
+      ].includes(node.kind)) {
         symbolIndex.set(node.name, node.id);
         let fileMap = fileSymbolIndex.get(node.filePath);
         if (!fileMap) {
@@ -1249,17 +1576,14 @@ var resolvePhase = {
         fileMap.set(node.name, node.id);
       }
     }
+    let fileDone = 0;
     for (const filePath of filePaths) {
       const lang = detectLanguage(filePath);
       if (!lang) continue;
-      const relativePath = path.relative(workspaceRoot, filePath);
+      const relativePath = path16.relative(workspaceRoot, filePath);
       const fileNodeId = generateNodeId("file", relativePath, relativePath);
-      let source;
-      try {
-        source = fs8.readFileSync(filePath, "utf-8");
-      } catch {
-        continue;
-      }
+      const source = fileCache.get(filePath);
+      if (!source) continue;
       const lines = source.split("\n");
       const imports = extractImports(lines, lang === "python");
       const calls = extractCalls(lines);
@@ -1269,13 +1593,13 @@ var resolvePhase = {
         let resolvedRelPath = null;
         if (cleaned.startsWith(".")) {
           const cleanedNoJs = cleaned.replace(/\.(js|jsx)$/, "");
-          const fromDir = path.dirname(relativePath);
+          const fromDir = path16.dirname(relativePath);
           for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", "/index.ts", "/index.js"]) {
-            const candidate = path.join(fromDir, cleanedNoJs + ext);
-            const normalized = path.normalize(candidate);
+            const candidate = path16.join(fromDir, cleanedNoJs + ext);
+            const normalized = path16.normalize(candidate);
             if (fileIndex.has(normalized)) {
               const absPath = fileIndex.get(normalized);
-              resolvedRelPath = path.relative(workspaceRoot, absPath);
+              resolvedRelPath = path16.relative(workspaceRoot, absPath);
               break;
             }
           }
@@ -1286,11 +1610,13 @@ var resolvePhase = {
               break;
             }
           }
-          const asPath = cleaned.replace(/\./g, "/");
-          for (const ext of ["", ".ts", ".js", ".py", ".java", ".go", "/index.ts", "/__init__.py"]) {
-            if (fileIndex.has(asPath + ext)) {
-              resolvedRelPath = asPath + ext;
-              break;
+          if (!resolvedRelPath) {
+            const asPath = cleaned.replace(/\./g, "/");
+            for (const ext of ["", ".ts", ".js", ".py", ".java", ".go", "/index.ts", "/__init__.py"]) {
+              if (fileIndex.has(asPath + ext)) {
+                resolvedRelPath = asPath + ext;
+                break;
+              }
             }
           }
         }
@@ -1313,6 +1639,7 @@ var resolvePhase = {
         }
       }
       const localSymbols = fileSymbolIndex.get(relativePath);
+      const funcList = fileFunctionIndex.get(relativePath);
       for (const call of calls) {
         let targetId = localSymbols?.get(call.name);
         let confidence = 0.95;
@@ -1321,7 +1648,7 @@ var resolvePhase = {
           confidence = 0.5;
         }
         if (targetId) {
-          const callerNodeId = findEnclosingFunction(graph, relativePath, call.line);
+          const callerNodeId = funcList ? findEnclosingFunctionFast(funcList, call.line) : null;
           const sourceId = callerNodeId ?? fileNodeId;
           if (sourceId !== targetId) {
             const edgeId = generateEdgeId(sourceId, targetId, "calls");
@@ -1377,6 +1704,8 @@ var resolvePhase = {
           }
         }
       }
+      fileDone++;
+      context.onPhaseProgress?.("resolve", fileDone, filePaths.length);
     }
     return {
       status: "completed",
@@ -1394,18 +1723,13 @@ function extractImports(lines, isPython) {
       const names = [];
       const namedMatch = line.match(/\{([^}]+)\}/);
       if (namedMatch) {
-        names.push(...namedMatch[1].split(",").map((n) => n.trim().split(/\s+as\s+/).pop().trim()).filter(Boolean));
+        names.push(
+          ...namedMatch[1].split(",").map((n) => n.trim().split(/\s+as\s+/).pop().trim()).filter(Boolean)
+        );
       }
       const defaultMatch = line.match(/import\s+(\w+)/);
-      if (defaultMatch && defaultMatch[1] !== "type") {
-        names.push(defaultMatch[1]);
-      }
-      imports.push({
-        rawPath: tsImport[1],
-        localNames: names,
-        isDefault: !namedMatch,
-        line: i + 1
-      });
+      if (defaultMatch && defaultMatch[1] !== "type") names.push(defaultMatch[1]);
+      imports.push({ rawPath: tsImport[1], localNames: names, isDefault: !namedMatch, line: i + 1 });
       continue;
     }
     if (isPython) {
@@ -1429,64 +1753,34 @@ function extractImports(lines, isPython) {
     const javaImport = line.match(/^import\s+(?:static\s+)?([\w.]+)/);
     if (javaImport && !line.includes("from")) {
       const parts = javaImport[1].split(".");
-      imports.push({
-        rawPath: javaImport[1],
-        localNames: [parts[parts.length - 1]],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: javaImport[1], localNames: [parts[parts.length - 1]], isDefault: false, line: i + 1 });
       continue;
     }
     const goImport = line.match(/^\s*"([^"]+)"/);
     if (goImport && (i > 0 && lines[i - 1]?.includes("import") || line.match(/^import\s+"/))) {
       const parts = goImport[1].split("/");
-      imports.push({
-        rawPath: goImport[1],
-        localNames: [parts[parts.length - 1]],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: goImport[1], localNames: [parts[parts.length - 1]], isDefault: false, line: i + 1 });
       continue;
     }
     const includeMatch = line.match(/#include\s+[<"]([^>"]+)[>"]/);
     if (includeMatch) {
-      imports.push({
-        rawPath: includeMatch[1],
-        localNames: [],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: includeMatch[1], localNames: [], isDefault: false, line: i + 1 });
       continue;
     }
     const rustUse = line.match(/^use\s+([\w:]+)/);
     if (rustUse) {
       const parts = rustUse[1].split("::");
-      imports.push({
-        rawPath: rustUse[1],
-        localNames: [parts[parts.length - 1]],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: rustUse[1], localNames: [parts[parts.length - 1]], isDefault: false, line: i + 1 });
       continue;
     }
     const usingMatch = line.match(/^using\s+([\w.]+)/);
     if (usingMatch) {
       const parts = usingMatch[1].split(".");
-      imports.push({
-        rawPath: usingMatch[1],
-        localNames: [parts[parts.length - 1]],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: usingMatch[1], localNames: [parts[parts.length - 1]], isDefault: false, line: i + 1 });
     }
     const requireMatch = line.match(/require\s+['"]([^'"]+)['"]/);
     if (requireMatch) {
-      imports.push({
-        rawPath: requireMatch[1],
-        localNames: [],
-        isDefault: false,
-        line: i + 1
-      });
+      imports.push({ rawPath: requireMatch[1], localNames: [], isDefault: false, line: i + 1 });
     }
   }
   return imports;
@@ -1507,19 +1801,14 @@ function extractCalls(lines) {
     callRegex.lastIndex = 0;
     while ((match = callRegex.exec(line)) !== null) {
       const name = match[1];
-      if (["if", "for", "while", "switch", "catch", "return", "throw", "typeof", "instanceof", "delete", "void", "new", "import", "export", "from", "const", "let", "var", "function", "class", "interface", "type", "enum", "extends", "implements"].includes(name)) continue;
+      if (CALL_KEYWORDS.has(name)) continue;
       const isNew = line.substring(Math.max(0, match.index - 4), match.index).includes("new");
       calls.push({ name, isNew, line: i + 1 });
     }
     const memberCallRegex = /(\w+)\.(\w+)\s*\(/g;
     memberCallRegex.lastIndex = 0;
     while ((match = memberCallRegex.exec(line)) !== null) {
-      calls.push({
-        name: match[2],
-        receiverText: match[1],
-        isNew: false,
-        line: i + 1
-      });
+      calls.push({ name: match[2], receiverText: match[1], isNew: false, line: i + 1 });
     }
   }
   return calls;
@@ -1542,19 +1831,23 @@ function extractHeritage(lines) {
   }
   return heritages;
 }
-function findEnclosingFunction(graph, filePath, line) {
+function findEnclosingFunctionFast(funcs, line) {
+  let lo = 0;
+  let hi = funcs.length - 1;
   let best = null;
-  for (const node of graph.allNodes()) {
-    if (node.filePath !== filePath) continue;
-    if (!["function", "method"].includes(node.kind)) continue;
-    if (!node.startLine) continue;
-    if (node.startLine <= line) {
-      if (!best || node.startLine > best.startLine) {
-        best = { id: node.id, startLine: node.startLine };
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    const fn = funcs[mid];
+    if (fn.startLine <= line) {
+      if (fn.endLine === void 0 || line <= fn.endLine) {
+        best = fn.id;
       }
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
     }
   }
-  return best?.id ?? null;
+  return best;
 }
 
 // src/pipeline/phases/cluster-phase.ts
@@ -1577,7 +1870,11 @@ var clusterPhase = {
       group.push({ id: node.id, name: node.name });
     }
     let clusterCount = 0;
-    for (const [dir, members] of nodesByDir) {
+    const dirEntries = [...nodesByDir.entries()];
+    let clusterDone = 0;
+    for (const [dir, members] of dirEntries) {
+      clusterDone++;
+      context.onPhaseProgress?.("cluster", clusterDone, dirEntries.length);
       if (members.length < 2) continue;
       const clusterId = generateNodeId("cluster", dir, `cluster-${clusterCount}`);
       const label = dir.split("/").filter(Boolean).pop() ?? `cluster-${clusterCount}`;
@@ -1638,27 +1935,30 @@ var flowPhase = {
     const maxDepth = 10;
     const maxBranching = 4;
     let flowCount = 0;
-    for (const ep of entryPoints.slice(0, 20)) {
+    const epSlice = entryPoints.slice(0, 20);
+    for (let epIdx = 0; epIdx < epSlice.length; epIdx++) {
+      const ep = epSlice[epIdx];
+      context.onPhaseProgress?.("flow", epIdx + 1, epSlice.length);
       if (flowCount >= maxFlows) break;
       const queue = [{ nodeId: ep.id, path: [ep.id] }];
       const visited = /* @__PURE__ */ new Set();
       while (queue.length > 0 && flowCount < maxFlows) {
-        const { nodeId, path: path15 } = queue.shift();
-        if (path15.length > maxDepth) continue;
+        const { nodeId, path: path17 } = queue.shift();
+        if (path17.length > maxDepth) continue;
         const callEdges = [...graph.findEdgesFrom(nodeId)].filter((e) => e.kind === "calls").slice(0, maxBranching);
-        if (callEdges.length === 0 && path15.length >= 3) {
+        if (callEdges.length === 0 && path17.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: path15, entryPoint: ep.name }
+            metadata: { steps: path17, entryPoint: ep.name }
           });
-          for (let i = 0; i < path15.length; i++) {
+          for (let i = 0; i < path17.length; i++) {
             graph.addEdge({
-              id: generateEdgeId(path15[i], flowId, `step_of_${i}`),
-              source: path15[i],
+              id: generateEdgeId(path17[i], flowId, `step_of_${i}`),
+              source: path17[i],
               target: flowId,
               kind: "step_of",
               weight: 1,
@@ -1671,7 +1971,7 @@ var flowPhase = {
         for (const edge of callEdges) {
           if (visited.has(edge.target)) continue;
           visited.add(edge.target);
-          queue.push({ nodeId: edge.target, path: [...path15, edge.target] });
+          queue.push({ nodeId: edge.target, path: [...path17, edge.target] });
         }
       }
     }
@@ -1940,12 +2240,12 @@ async function syncGroup(group) {
   for (const member of group.members) {
     const regEntry = registry.find((r) => r.name === member.registryName);
     if (!regEntry) {
-      console.warn(`  \u26A0 Registry entry "${member.registryName}" not found \u2014 skipping ${member.groupPath}`);
+      logger_default.warn(`  \u26A0 Registry entry "${member.registryName}" not found \u2014 skipping ${member.groupPath}`);
       continue;
     }
-    const dbPath = path.join(regEntry.path, ".code-intel", "graph.db");
-    if (!fs8.existsSync(dbPath)) {
-      console.warn(`  \u26A0 No index at ${dbPath} \u2014 run \`code-intel analyze ${regEntry.path}\` first`);
+    const dbPath = path16.join(regEntry.path, ".code-intel", "graph.db");
+    if (!fs14.existsSync(dbPath)) {
+      logger_default.warn(`  \u26A0 No index at ${dbPath} \u2014 run \`code-intel analyze ${regEntry.path}\` first`);
       continue;
     }
     const graph = createKnowledgeGraph();
@@ -1956,11 +2256,11 @@ async function syncGroup(group) {
       db.close();
     } catch (err) {
       db.close();
-      console.warn(`  \u26A0 Could not load graph for "${member.registryName}": ${err instanceof Error ? err.message : err}`);
+      logger_default.warn(`  \u26A0 Could not load graph for "${member.registryName}": ${err instanceof Error ? err.message : err}`);
       continue;
     }
     const contracts = extractContracts(graph, member.registryName, regEntry.path);
-    console.log(`  \u2713 ${member.registryName} (${member.groupPath}): ${contracts.length} contracts`);
+    logger_default.info(`  \u2713 ${member.registryName} (${member.groupPath}): ${contracts.length} contracts`);
     allContracts.push(...contracts);
   }
   const links = matchContracts(allContracts);
@@ -1981,8 +2281,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 = path.join(regEntry.path, ".code-intel", "graph.db");
-    if (!fs8.existsSync(dbPath)) continue;
+    const dbPath = path16.join(regEntry.path, ".code-intel", "graph.db");
+    if (!fs14.existsSync(dbPath)) continue;
     const graph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
     try {
@@ -2012,8 +2312,8 @@ async function queryGroup(group, query, limit = 20) {
 
 // src/http/app.ts
 init_repo_registry();
-var __dirname$1 = path.dirname(fileURLToPath(import.meta.url));
-var WEB_DIST = path.resolve(__dirname$1, "..", "..", "..", "web", "dist");
+var __dirname$1 = path16.dirname(fileURLToPath(import.meta.url));
+var WEB_DIST = path16.resolve(__dirname$1, "..", "..", "..", "web", "dist");
 function createApp(graph, repoName, workspaceRoot) {
   const app = express();
   app.use(cors({ origin: true }));
@@ -2034,23 +2334,23 @@ function createApp(graph, repoName, workspaceRoot) {
       await idx.init();
       const alreadyBuilt = await idx.isBuilt();
       if (!alreadyBuilt) {
-        console.log("  [vector] Building embeddings\u2026");
+        logger_default.info("  [vector] Building embeddings\u2026");
         const nodes = await embedNodes2(graph, {
           onProgress: (done, total) => {
             if (done % 50 === 0 || done === total) process.stdout.write(`\r  [vector] ${done}/${total}`);
           }
         });
-        console.log("");
+        logger_default.info("");
         await idx.buildIndex(nodes);
-        console.log(`  [vector] Index built: ${nodes.length} embeddings`);
+        logger_default.info(`  [vector] Index built: ${nodes.length} embeddings`);
       } else {
-        console.log("  [vector] Index already exists, skipping rebuild.");
+        logger_default.info("  [vector] Index already exists, skipping rebuild.");
       }
       vectorIndex = idx;
       vectorIndexReady = true;
       return idx;
     } catch (err) {
-      console.warn("  [vector] Index build failed:", err instanceof Error ? err.message : err);
+      logger_default.warn("  [vector] Index build failed:", err instanceof Error ? err.message : err);
       return null;
     } finally {
       vectorIndexBuilding = false;
@@ -2064,16 +2364,59 @@ function createApp(graph, repoName, workspaceRoot) {
     res.json({ status: "ok", nodes: graph.size.nodes, edges: graph.size.edges });
   });
   app.get("/api/repos", (_req, res) => {
-    res.json([{ name: repoName, nodes: graph.size.nodes, edges: graph.size.edges }]);
+    const registry = loadRegistry();
+    if (registry.length === 0) {
+      res.json([{ name: repoName, path: workspaceRoot ?? "", nodes: graph.size.nodes, edges: graph.size.edges, indexedAt: null }]);
+      return;
+    }
+    res.json(registry.map((r) => ({
+      name: r.name,
+      path: r.path,
+      nodes: r.stats.nodes,
+      edges: r.stats.edges,
+      indexedAt: r.indexedAt,
+      active: r.path === workspaceRoot
+    })));
   });
-  app.get("/api/graph/:repo", (_req, res) => {
-    const nodes = [...graph.allNodes()];
-    const edges = [...graph.allEdges()];
+  async function loadRepoGraph(requestedRepo) {
+    if (requestedRepo === repoName) return graph;
+    const registry = loadRegistry();
+    const entry = registry.find((r) => r.name === requestedRepo || r.path === requestedRepo);
+    if (!entry) return null;
+    const dbPath = path16.join(entry.path, ".code-intel", "graph.db");
+    if (!fs14.existsSync(dbPath)) return null;
+    const repoGraph = createKnowledgeGraph();
+    const db = new DbManager(dbPath);
+    try {
+      await db.init();
+      await loadGraphFromDB(repoGraph, db);
+      db.close();
+      return repoGraph;
+    } catch {
+      db.close();
+      return null;
+    }
+  }
+  app.get("/api/graph/:repo", async (req, res) => {
+    const requestedRepo = decodeURIComponent(req.params.repo);
+    const g = await loadRepoGraph(requestedRepo);
+    if (!g) {
+      res.status(404).json({ error: `Repo "${requestedRepo}" not found or not indexed. Run: code-intel analyze <path>` });
+      return;
+    }
+    const nodes = [...g.allNodes()];
+    const edges = [...g.allEdges()];
     res.json({ nodes, edges });
   });
-  app.post("/api/search", (req, res) => {
-    const { query, limit } = req.body;
-    const results = textSearch(graph, query, limit ?? 20);
+  async function getGraphForRepo(requestedRepo) {
+    if (!requestedRepo || requestedRepo === repoName) return graph;
+    const g = await loadRepoGraph(requestedRepo);
+    return g ?? graph;
+  }
+  app.post("/api/search", async (req, res) => {
+    const { query, limit, repo } = req.body;
+    const g = await getGraphForRepo(repo);
+    const results = textSearch(g, query, limit ?? 20);
     res.json({ results });
   });
   app.post("/api/vector-search", async (req, res) => {
@@ -2113,7 +2456,7 @@ function createApp(graph, repoName, workspaceRoot) {
   app.post("/api/files/read", (req, res) => {
     const { file_path } = req.body;
     try {
-      const content = fs8.readFileSync(file_path, "utf-8");
+      const content = fs14.readFileSync(file_path, "utf-8");
       res.json({ content });
     } catch {
       res.status(404).json({ error: "File not found" });
@@ -2192,55 +2535,57 @@ function createApp(graph, repoName, workspaceRoot) {
       res.status(400).json({ error: "Invalid query" });
     }
   });
-  app.get("/api/nodes/:id", (req, res) => {
+  app.get("/api/nodes/:id", async (req, res) => {
     const nodeId = decodeURIComponent(req.params.id);
-    const node = graph.getNode(nodeId);
+    const g = await getGraphForRepo(req.query.repo);
+    const node = g.getNode(nodeId);
     if (!node) {
       res.status(404).json({ error: "Node not found" });
       return;
     }
-    const incoming = [...graph.findEdgesTo(nodeId)];
-    const outgoing = [...graph.findEdgesFrom(nodeId)];
+    const incoming = [...g.findEdgesTo(nodeId)];
+    const outgoing = [...g.findEdgesFrom(nodeId)];
     res.json({
       node,
       callers: incoming.filter((e) => e.kind === "calls").map((e) => ({
         id: e.source,
-        name: graph.getNode(e.source)?.name,
+        name: g.getNode(e.source)?.name,
         weight: e.weight
       })),
       callees: outgoing.filter((e) => e.kind === "calls").map((e) => ({
         id: e.target,
-        name: graph.getNode(e.target)?.name,
+        name: g.getNode(e.target)?.name,
         weight: e.weight
       })),
       imports: outgoing.filter((e) => e.kind === "imports").map((e) => ({
         id: e.target,
-        name: graph.getNode(e.target)?.name
+        name: g.getNode(e.target)?.name
       })),
       importedBy: incoming.filter((e) => e.kind === "imports").map((e) => ({
         id: e.source,
-        name: graph.getNode(e.source)?.name
+        name: g.getNode(e.source)?.name
       })),
       extends: outgoing.filter((e) => e.kind === "extends").map((e) => ({
         id: e.target,
-        name: graph.getNode(e.target)?.name
+        name: g.getNode(e.target)?.name
       })),
       implementsEdges: outgoing.filter((e) => e.kind === "implements").map((e) => ({
         id: e.target,
-        name: graph.getNode(e.target)?.name
+        name: g.getNode(e.target)?.name
       })),
       members: outgoing.filter((e) => e.kind === "has_member").map((e) => ({
         id: e.target,
-        name: graph.getNode(e.target)?.name,
-        kind: graph.getNode(e.target)?.kind
+        name: g.getNode(e.target)?.name,
+        kind: g.getNode(e.target)?.kind
       })),
-      cluster: incoming.filter((e) => e.kind === "belongs_to").map((e) => graph.getNode(e.target)?.name)[0]
+      cluster: incoming.filter((e) => e.kind === "belongs_to").map((e) => g.getNode(e.target)?.name)[0]
     });
   });
-  app.post("/api/blast-radius", (req, res) => {
-    const { target, direction = "both", max_hops = 5 } = req.body;
+  app.post("/api/blast-radius", async (req, res) => {
+    const { target, direction = "both", max_hops = 5, repo } = req.body;
+    const g = await getGraphForRepo(repo);
     let targetNode = null;
-    for (const node of graph.allNodes()) {
+    for (const node of g.allNodes()) {
       if (node.name === target || node.id === target) {
         targetNode = node;
         break;
@@ -2257,22 +2602,16 @@ function createApp(graph, repoName, workspaceRoot) {
       const { id, depth } = queue.shift();
       if (visited.has(id) || depth > max_hops) continue;
       visited.add(id);
-      const node = graph.getNode(id);
-      if (node) {
-        affected.set(id, { name: node.name, kind: node.kind, depth });
-      }
+      const node = g.getNode(id);
+      if (node) affected.set(id, { name: node.name, kind: node.kind, depth });
       if (direction === "callers" || direction === "both") {
-        for (const edge of graph.findEdgesTo(id)) {
-          if (edge.kind === "calls" || edge.kind === "imports") {
-            queue.push({ id: edge.source, depth: depth + 1 });
-          }
+        for (const edge of g.findEdgesTo(id)) {
+          if (edge.kind === "calls" || edge.kind === "imports") queue.push({ id: edge.source, depth: depth + 1 });
         }
       }
       if (direction === "callees" || direction === "both") {
-        for (const edge of graph.findEdgesFrom(id)) {
-          if (edge.kind === "calls" || edge.kind === "imports") {
-            queue.push({ id: edge.target, depth: depth + 1 });
-          }
+        for (const edge of g.findEdgesFrom(id)) {
+          if (edge.kind === "calls" || edge.kind === "imports") queue.push({ id: edge.target, depth: depth + 1 });
         }
       }
     }
@@ -2282,28 +2621,20 @@ function createApp(graph, repoName, workspaceRoot) {
       affected: [...affected.entries()].map(([id, info]) => ({ id, ...info })).filter((a) => a.depth > 0)
     });
   });
-  app.get("/api/flows", (_req, res) => {
+  app.get("/api/flows", async (req, res) => {
+    const g = await getGraphForRepo(req.query.repo);
     const flows = [];
-    for (const node of graph.allNodes()) {
-      if (node.kind === "flow") {
-        flows.push({
-          id: node.id,
-          name: node.name,
-          steps: node.metadata?.steps
-        });
-      }
+    for (const node of g.allNodes()) {
+      if (node.kind === "flow") flows.push({ id: node.id, name: node.name, steps: node.metadata?.steps });
     }
     res.json({ flows });
   });
-  app.get("/api/clusters", (_req, res) => {
+  app.get("/api/clusters", async (req, res) => {
+    const g = await getGraphForRepo(req.query.repo);
     const clusters = [];
-    for (const node of graph.allNodes()) {
+    for (const node of g.allNodes()) {
       if (node.kind === "cluster") {
-        clusters.push({
-          id: node.id,
-          name: node.name,
-          memberCount: node.metadata?.memberCount ?? 0
-        });
+        clusters.push({ id: node.id, name: node.name, memberCount: node.metadata?.memberCount ?? 0 });
       }
     }
     res.json({ clusters });
@@ -2379,8 +2710,8 @@ function createApp(graph, repoName, workspaceRoot) {
     for (const member of group.members) {
       const regEntry = registry.find((r) => r.name === member.registryName);
       if (!regEntry) continue;
-      const dbPath = path.join(regEntry.path, ".code-intel", "graph.db");
-      if (!fs8.existsSync(dbPath)) continue;
+      const dbPath = path16.join(regEntry.path, ".code-intel", "graph.db");
+      if (!fs14.existsSync(dbPath)) continue;
       const db = new DbManager(dbPath);
       try {
         await db.init();
@@ -2392,10 +2723,10 @@ function createApp(graph, repoName, workspaceRoot) {
     }
     res.json({ nodes: [...mergedGraph.allNodes()], edges: [...mergedGraph.allEdges()] });
   });
-  if (fs8.existsSync(WEB_DIST)) {
+  if (fs14.existsSync(WEB_DIST)) {
     app.use(express.static(WEB_DIST));
     app.get("/{*path}", (_req, res) => {
-      res.sendFile(path.join(WEB_DIST, "index.html"));
+      res.sendFile(path16.join(WEB_DIST, "index.html"));
     });
   }
   return app;
@@ -2403,73 +2734,229 @@ function createApp(graph, repoName, workspaceRoot) {
 function startHttpServer(graph, repoName, port = 4747, workspaceRoot) {
   const app = createApp(graph, repoName, workspaceRoot);
   app.listen(port, () => {
-    console.log(`Code Intelligence server running at http://localhost:${port}`);
-    console.log(`  Graph: ${graph.size.nodes} nodes, ${graph.size.edges} edges`);
+    logger_default.info(`Code Intelligence server running at http://localhost:${port}`);
+    logger_default.info(`  Graph: ${graph.size.nodes} nodes, ${graph.size.edges} edges`);
   });
 }
-function createMcpServer(graph, repoName) {
+init_repo_registry();
+init_metadata();
+init_group_registry();
+function createMcpServer(graph, repoName, workspaceRoot) {
   const server = new Server(
     { name: "code-intel", version: "0.1.0" },
     { capabilities: { tools: {}, resources: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
+      // ── Core repo tools ──────────────────────────────────────────────────
       {
         name: "repos",
-        description: "List indexed repositories",
+        description: "List all indexed repositories with node and edge counts",
         inputSchema: { type: "object", properties: {} }
       },
+      {
+        name: "overview",
+        description: "Repository summary: total nodes/edges and a full breakdown of node and edge counts by kind. Use this first to understand the shape of the codebase.",
+        inputSchema: { type: "object", properties: {} }
+      },
+      // ── Search & inspect ─────────────────────────────────────────────────
       {
         name: "search",
-        description: "Hybrid search across the codebase knowledge graph",
+        description: "BM25 keyword search across all indexed symbols \u2014 functions, classes, files, routes, etc.",
         inputSchema: {
           type: "object",
           properties: {
-            query: { type: "string", description: "Search query" },
-            limit: { type: "number", description: "Max results (default 20)" }
+            query: { type: "string", description: "Search query (symbol name, keyword, or partial match)" },
+            limit: { type: "number", description: "Max results to return (default: 20)" }
           },
           required: ["query"]
         }
       },
       {
         name: "inspect",
-        description: "360\xB0 view of a symbol: definition, callers, callees, heritage, references",
+        description: "360\xB0 view of a symbol: definition location, callers, callees, heritage (extends/implements), members, cluster, and source preview (first 500 chars)",
         inputSchema: {
           type: "object",
           properties: {
-            symbol_name: { type: "string", description: "Symbol name to inspect" }
+            symbol_name: { type: "string", description: "Exact symbol name to inspect" }
           },
           required: ["symbol_name"]
         }
       },
       {
         name: "blast_radius",
-        description: "Impact analysis: what depends on / is affected by this symbol",
+        description: "Impact analysis: traverse the call/import graph to find all symbols that depend on or are affected by a given symbol. Returns risk level (LOW / MEDIUM / HIGH).",
         inputSchema: {
           type: "object",
           properties: {
             target: { type: "string", description: "Target symbol name" },
-            direction: { type: "string", enum: ["callers", "callees", "both"], description: "Direction to trace" },
-            max_hops: { type: "number", description: "Max hops (default 5)" }
+            direction: {
+              type: "string",
+              enum: ["callers", "callees", "both"],
+              description: "Which direction to trace \u2014 callers (who depends on it), callees (what it depends on), or both (default: both)"
+            },
+            max_hops: { type: "number", description: "Maximum traversal depth (default: 5)" }
           },
           required: ["target"]
         }
       },
+      {
+        name: "file_symbols",
+        description: "List all symbols defined in a specific file \u2014 useful to understand what a file exports or contains without reading raw source.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            file_path: { type: "string", description: 'File path (partial match is supported, e.g. "auth/login.ts")' }
+          },
+          required: ["file_path"]
+        }
+      },
+      {
+        name: "find_path",
+        description: "Find the shortest call/import path between two symbols. Useful for tracing how one module reaches another.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            from: { type: "string", description: "Source symbol name" },
+            to: { type: "string", description: "Target symbol name" },
+            max_hops: { type: "number", description: "Maximum path length to search (default: 8)" }
+          },
+          required: ["from", "to"]
+        }
+      },
+      {
+        name: "list_exports",
+        description: "List all exported symbols in the repository. Helps AI understand the public API surface of the codebase.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            kind: {
+              type: "string",
+              description: "Filter by node kind: function | class | interface | method | type_alias | constant | enum (optional)"
+            },
+            limit: { type: "number", description: "Max results (default: 100)" }
+          }
+        }
+      },
+      // ── Routes, clusters, flows ──────────────────────────────────────────
       {
         name: "routes",
-        description: "List route handler mappings in the codebase",
+        description: "List all HTTP route handler mappings detected in the codebase (kind=route or route/handler/controller files)",
         inputSchema: { type: "object", properties: {} }
       },
+      {
+        name: "clusters",
+        description: "List detected code clusters (directory-based communities) with member counts and top 10 symbols each. Useful for understanding code organisation.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: { type: "number", description: "Max clusters to return (default: 50)" }
+          }
+        }
+      },
+      {
+        name: "flows",
+        description: "List all detected execution flows \u2014 entry points traced through the call graph. Each flow has a name, entry point, and ordered steps.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: { type: "number", description: "Max flows to return (default: 50)" }
+          }
+        }
+      },
+      // ── Git change impact ─────────────────────────────────────────────────
+      {
+        name: "detect_changes",
+        description: "Git-diff impact analysis: detects which source files and line ranges changed (HEAD vs working tree or a custom diff), maps them to graph symbols, and computes the combined blast radius. Ideal for PR review or pre-commit analysis.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            base_ref: {
+              type: "string",
+              description: 'Git ref to diff against (default: HEAD). Examples: "HEAD~1", "main", a commit SHA.'
+            },
+            diff_text: {
+              type: "string",
+              description: "Raw unified diff text. If provided, base_ref is ignored and this diff is parsed directly."
+            }
+          }
+        }
+      },
+      // ── Raw query ─────────────────────────────────────────────────────────
       {
         name: "raw_query",
-        description: "Execute a graph query (simplified Cypher-like)",
+        description: "Execute a simplified Cypher-like graph query. Supports: name='X' (exact name match) or :kind (list nodes of a kind, max 50)",
         inputSchema: {
           type: "object",
           properties: {
-            cypher: { type: "string", description: "Query string (name='X' or :kind patterns)" }
+            cypher: { type: "string", description: "Query string \u2014 e.g. name='runPipeline' or :function" }
           },
           required: ["cypher"]
         }
+      },
+      // ── Group / multi-repo tools ──────────────────────────────────────────
+      {
+        name: "group_list",
+        description: "List all configured repository groups, or show the full membership of one group. Repository groups track multiple repos as a logical system.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Group name to inspect (optional \u2014 omit to list all groups)" }
+          }
+        }
+      },
+      {
+        name: "group_sync",
+        description: "Extract cross-repo contracts (exports, routes, schemas, events) from every member repo in a group and detect provider\u2192consumer links via name matching and RRF scoring.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Group name to sync" }
+          },
+          required: ["name"]
+        }
+      },
+      {
+        name: "group_contracts",
+        description: "Inspect extracted contracts and confidence-ranked cross-repo links from the last group sync. Supports filtering by kind, repo, and minimum confidence.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Group name" },
+            kind: {
+              type: "string",
+              enum: ["export", "route", "schema", "event"],
+              description: "Filter by contract kind (optional)"
+            },
+            repo: { type: "string", description: "Filter by registry name (optional)" },
+            min_confidence: { type: "number", description: "Minimum link confidence 0\u20131 (default: 0)" }
+          },
+          required: ["name"]
+        }
+      },
+      {
+        name: "group_query",
+        description: "BM25 search across all repos in a group, merged via Reciprocal Rank Fusion (RRF). Returns a unified ranked list plus per-repo breakdown.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Group name" },
+            query: { type: "string", description: "Search query" },
+            limit: { type: "number", description: "Max results per repo (default: 10)" }
+          },
+          required: ["name", "query"]
+        }
+      },
+      {
+        name: "group_status",
+        description: "Check index freshness and sync staleness for all repos in a group. Flags repos that have not been indexed or are stale (>24h).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Group name" }
+          },
+          required: ["name"]
+        }
       }
     ]
   }));
@@ -2477,43 +2964,100 @@ function createMcpServer(graph, repoName) {
     const { name, arguments: args } = request.params;
     const a = args ?? {};
     switch (name) {
+      // ── repos ──────────────────────────────────────────────────────────────
       case "repos": {
-        return { content: [{ type: "text", text: JSON.stringify([{ name: repoName, nodes: graph.size.nodes, edges: graph.size.edges }], null, 2) }] };
+        const registry = loadRegistry();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              registry.map((r) => ({ name: r.name, path: r.path, indexedAt: r.indexedAt, stats: r.stats })),
+              null,
+              2
+            )
+          }]
+        };
+      }
+      // ── overview ───────────────────────────────────────────────────────────
+      case "overview": {
+        const kindCounts = {};
+        for (const node of graph.allNodes()) {
+          kindCounts[node.kind] = (kindCounts[node.kind] ?? 0) + 1;
+        }
+        const edgeCounts = {};
+        for (const edge of graph.allEdges()) {
+          edgeCounts[edge.kind] = (edgeCounts[edge.kind] ?? 0) + 1;
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              repo: repoName,
+              stats: graph.size,
+              nodeCounts: kindCounts,
+              edgeCounts
+            }, null, 2)
+          }]
+        };
       }
+      // ── search ─────────────────────────────────────────────────────────────
       case "search": {
         const query = a.query;
         const limit = a.limit ?? 20;
         const results = textSearch(graph, query, limit);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
       }
+      // ── inspect ────────────────────────────────────────────────────────────
       case "inspect": {
         const symbolName = a.symbol_name;
         const node = findNodeByName(graph, symbolName);
-        if (!node) return { content: [{ type: "text", text: `Symbol "${symbolName}" not found` }] };
+        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)];
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
-              node: { id: node.id, kind: node.kind, name: node.name, filePath: node.filePath, startLine: node.startLine, endLine: node.endLine, exported: node.exported },
-              callers: incoming.filter((e) => e.kind === "calls").map((e) => ({ id: e.source, name: graph.getNode(e.source)?.name })),
-              callees: outgoing.filter((e) => e.kind === "calls").map((e) => ({ id: e.target, name: graph.getNode(e.target)?.name })),
+              node: {
+                id: node.id,
+                kind: node.kind,
+                name: node.name,
+                filePath: node.filePath,
+                startLine: node.startLine,
+                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
+              })),
+              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),
               implements: outgoing.filter((e) => e.kind === "implements").map((e) => graph.getNode(e.target)?.name),
-              members: outgoing.filter((e) => e.kind === "has_member").map((e) => ({ name: graph.getNode(e.target)?.name, kind: graph.getNode(e.target)?.kind })),
+              members: outgoing.filter((e) => e.kind === "has_member").map((e) => ({
+                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)
             }, null, 2)
           }]
         };
       }
+      // ── blast_radius ───────────────────────────────────────────────────────
       case "blast_radius": {
         const target = a.target;
         const direction = a.direction ?? "both";
         const maxHops = a.max_hops ?? 5;
         const node = findNodeByName(graph, target);
-        if (!node) return { content: [{ type: "text", text: `Symbol "${target}" not found` }] };
+        if (!node) return { content: [{ type: "text", text: `Symbol "${target}" not found.` }] };
         const affected = /* @__PURE__ */ new Set();
         const queue = [{ id: node.id, depth: 0 }];
         const visited = /* @__PURE__ */ new Set();
@@ -2537,17 +3081,219 @@ function createMcpServer(graph, repoName) {
           const n = graph.getNode(id);
           return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
         });
-        return { content: [{ type: "text", text: JSON.stringify({ target: node.name, affectedCount: affected.size, affected: affectedDetails }, null, 2) }] };
+        const risk = affected.size > 10 ? "HIGH" : affected.size > 5 ? "MEDIUM" : "LOW";
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              target: node.name,
+              affectedCount: affected.size,
+              riskLevel: risk,
+              affected: affectedDetails
+            }, null, 2)
+          }]
+        };
       }
+      // ── file_symbols ───────────────────────────────────────────────────────
+      case "file_symbols": {
+        const filePath = a.file_path;
+        const matches = [];
+        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 });
+          }
+        }
+        if (matches.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) }] };
+      }
+      // ── find_path ──────────────────────────────────────────────────────────
+      case "find_path": {
+        const fromName = a.from;
+        const toName = a.to;
+        const maxHops = a.max_hops ?? 8;
+        const fromNode = findNodeByName(graph, fromName);
+        const toNode = findNodeByName(graph, toName);
+        if (!fromNode) return { content: [{ type: "text", text: `Source symbol "${fromName}" not found.` }] };
+        if (!toNode) return { content: [{ type: "text", text: `Target symbol "${toName}" not found.` }] };
+        const queue = [{ id: fromNode.id, path: [fromNode.id] }];
+        const visited = /* @__PURE__ */ new Set();
+        let foundPath = null;
+        while (queue.length > 0) {
+          const { id, path: currentPath } = queue.shift();
+          if (visited.has(id)) continue;
+          visited.add(id);
+          if (id === toNode.id) {
+            foundPath = currentPath;
+            break;
+          }
+          if (currentPath.length > maxHops) continue;
+          for (const edge of graph.findEdgesFrom(id)) {
+            if ((edge.kind === "calls" || edge.kind === "imports") && !visited.has(edge.target)) {
+              queue.push({ id: edge.target, path: [...currentPath, edge.target] });
+            }
+          }
+        }
+        if (!foundPath) {
+          return { content: [{ type: "text", text: `No path found from "${fromName}" to "${toName}" within ${maxHops} hops.` }] };
+        }
+        const pathDetails = foundPath.map((id) => {
+          const n = graph.getNode(id);
+          return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ from: fromName, to: toName, hops: foundPath.length - 1, path: pathDetails }, null, 2)
+          }]
+        };
+      }
+      // ── list_exports ───────────────────────────────────────────────────────
+      case "list_exports": {
+        const kindFilter = a.kind;
+        const limit = a.limit ?? 100;
+        const exports$1 = [];
+        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;
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ total: exports$1.length, exports: exports$1 }, null, 2) }] };
+      }
+      // ── routes ─────────────────────────────────────────────────────────────
       case "routes": {
         const routes = [];
         for (const node of graph.allNodes()) {
           if (node.kind === "route" || node.kind === "function" && /route|handler|controller/i.test(node.filePath)) {
-            routes.push({ name: node.name, filePath: node.filePath });
+            routes.push({ name: node.name, filePath: node.filePath, startLine: node.startLine });
           }
         }
         return { content: [{ type: "text", text: JSON.stringify(routes, null, 2) }] };
       }
+      // ── clusters ───────────────────────────────────────────────────────────
+      case "clusters": {
+        const limit = a.limit ?? 50;
+        const clusters = [];
+        for (const node of graph.allNodes()) {
+          if (node.kind === "cluster") {
+            const members = [];
+            for (const edge of graph.findEdgesTo(node.id)) {
+              if (edge.kind === "belongs_to") {
+                const member = graph.getNode(edge.source);
+                if (member && member.kind !== "cluster") {
+                  members.push({ name: member.name, kind: member.kind });
+                }
+              }
+            }
+            clusters.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) }] };
+      }
+      // ── flows ──────────────────────────────────────────────────────────────
+      case "flows": {
+        const limit = a.limit ?? 50;
+        const flows = [];
+        for (const node of graph.allNodes()) {
+          if (node.kind === "flow") {
+            const steps = node.metadata?.steps;
+            flows.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) }] };
+      }
+      // ── detect_changes ─────────────────────────────────────────────────────
+      case "detect_changes": {
+        const baseRef = a.base_ref ?? "HEAD";
+        const diffTextInput = a.diff_text;
+        let diffText;
+        const repoRoot = workspaceRoot ?? process.cwd();
+        if (diffTextInput) {
+          diffText = diffTextInput;
+        } else {
+          try {
+            diffText = execSync(`git diff ${baseRef}`, { cwd: repoRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+            if (!diffText.trim()) {
+              diffText = execSync(`git diff HEAD`, { cwd: repoRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+            }
+          } catch {
+            return { content: [{ type: "text", text: `Could not run git diff in ${repoRoot}. Ensure the path is a Git repository.` }] };
+          }
+        }
+        if (!diffText.trim()) {
+          return { content: [{ type: "text", text: "No changes detected in git diff." }] };
+        }
+        const changedFiles = parseDiff(diffText);
+        const hitNodes = /* @__PURE__ */ new Set();
+        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 + path16.sep, "");
+            const normChanged = changedFile.replace(/^a\/|^b\//, "");
+            if (!normNode.endsWith(normChanged) && !normChanged.endsWith(normNode)) continue;
+            if (node.startLine !== void 0 && node.endLine !== void 0) {
+              const overlaps = changedLines.some((l) => l >= node.startLine && l <= node.endLine);
+              if (overlaps) hitNodes.add(node.id);
+            } else if (node.startLine !== void 0) {
+              const overlaps = changedLines.some((l) => Math.abs(l - node.startLine) <= 3);
+              if (overlaps) hitNodes.add(node.id);
+            }
+          }
+        }
+        const allAffected = /* @__PURE__ */ new Set();
+        for (const startId of hitNodes) {
+          const queue = [{ id: startId, depth: 0 }];
+          const visited = /* @__PURE__ */ new Set();
+          while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (visited.has(id) || depth > 5) continue;
+            visited.add(id);
+            allAffected.add(id);
+            for (const edge of graph.findEdgesTo(id)) {
+              if (edge.kind === "calls" || edge.kind === "imports") queue.push({ id: edge.source, depth: depth + 1 });
+            }
+          }
+        }
+        const changedSymbols = [...hitNodes].map((id) => {
+          const n = graph.getNode(id);
+          return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
+        });
+        const affectedSymbols = [...allAffected].filter((id) => !hitNodes.has(id)).map((id) => {
+          const n = graph.getNode(id);
+          return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
+        });
+        const risk = allAffected.size > 10 ? "HIGH" : allAffected.size > 4 ? "MEDIUM" : "LOW";
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              baseRef,
+              changedFiles: changedFiles.map((f) => f.filePath),
+              directlyChangedSymbols: changedSymbols,
+              transitivelyAffectedSymbols: affectedSymbols,
+              totalAffected: allAffected.size,
+              riskLevel: risk
+            }, null, 2)
+          }]
+        };
+      }
+      // ── raw_query ──────────────────────────────────────────────────────────
       case "raw_query": {
         const q = a.cypher;
         const nameMatch = q?.match(/name\s*=\s*['"]([^'"]+)['"]/i);
@@ -2567,7 +3313,123 @@ function createMcpServer(graph, repoName) {
           }
           return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
         }
-        return { content: [{ type: "text", text: "Query not recognized" }] };
+        return { content: [{ type: "text", text: "Query not recognized. Use name='X' or :kind syntax." }] };
+      }
+      // ── group_list ─────────────────────────────────────────────────────────
+      case "group_list": {
+        const groupName = a.name;
+        if (groupName) {
+          const group = loadGroup(groupName);
+          if (!group) return { content: [{ type: "text", text: `Group "${groupName}" not found.` }] };
+          return { content: [{ type: "text", text: JSON.stringify(group, null, 2) }] };
+        }
+        const groups = listGroups();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              groups.map((g) => ({ name: g.name, createdAt: g.createdAt, lastSync: g.lastSync, memberCount: g.members.length, members: g.members })),
+              null,
+              2
+            )
+          }]
+        };
+      }
+      // ── group_sync ─────────────────────────────────────────────────────────
+      case "group_sync": {
+        const groupName = a.name;
+        const group = loadGroup(groupName);
+        if (!group) return { content: [{ type: "text", text: `Group "${groupName}" not found.` }] };
+        if (group.members.length === 0) return { content: [{ type: "text", text: `Group "${groupName}" has no members.` }] };
+        const result = await syncGroup(group);
+        saveSyncResult(result);
+        group.lastSync = result.syncedAt;
+        saveGroup(group);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              groupName: result.groupName,
+              syncedAt: result.syncedAt,
+              memberCount: result.memberCount,
+              contractCount: result.contracts.length,
+              linkCount: result.links.length,
+              topLinks: result.links.slice(0, 20)
+            }, null, 2)
+          }]
+        };
+      }
+      // ── group_contracts ────────────────────────────────────────────────────
+      case "group_contracts": {
+        const groupName = a.name;
+        const kindFilter = a.kind;
+        const repoFilter = a.repo;
+        const minConf = a.min_confidence ?? 0;
+        const result = loadSyncResult(groupName);
+        if (!result) return { content: [{ type: "text", text: `No sync data for group "${groupName}". Run group_sync first.` }] };
+        let contracts = result.contracts;
+        if (kindFilter) contracts = contracts.filter((c) => c.kind === kindFilter);
+        if (repoFilter) contracts = contracts.filter((c) => c.repoName === repoFilter);
+        let links = result.links.filter((l) => l.confidence >= minConf);
+        if (repoFilter) links = links.filter((l) => l.providerRepo === repoFilter || l.consumerRepo === repoFilter);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ syncedAt: result.syncedAt, contracts, links }, null, 2)
+          }]
+        };
+      }
+      // ── group_query ────────────────────────────────────────────────────────
+      case "group_query": {
+        const groupName = a.name;
+        const query = a.query;
+        const limit = a.limit ?? 10;
+        const group = loadGroup(groupName);
+        if (!group) return { content: [{ type: "text", text: `Group "${groupName}" not found.` }] };
+        const { perRepo, merged } = await queryGroup(group, query, limit);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ query, merged, perRepo }, null, 2)
+          }]
+        };
+      }
+      // ── group_status ───────────────────────────────────────────────────────
+      case "group_status": {
+        const groupName = a.name;
+        const group = loadGroup(groupName);
+        if (!group) return { content: [{ type: "text", text: `Group "${groupName}" not found.` }] };
+        const registry = loadRegistry();
+        const now = Date.now();
+        const memberStatus = group.members.map((m) => {
+          const regEntry = registry.find((r) => r.name === m.registryName);
+          if (!regEntry) return { groupPath: m.groupPath, registryName: m.registryName, status: "NOT_IN_REGISTRY" };
+          const meta = loadMetadata(regEntry.path);
+          if (!meta) return { groupPath: m.groupPath, registryName: m.registryName, repoPath: regEntry.path, status: "NOT_INDEXED" };
+          const ageMin = Math.round((now - new Date(meta.indexedAt).getTime()) / 6e4);
+          const stale = ageMin > 1440;
+          return {
+            groupPath: m.groupPath,
+            registryName: m.registryName,
+            repoPath: regEntry.path,
+            indexedAt: meta.indexedAt,
+            ageMinutes: ageMin,
+            status: stale ? "STALE" : "OK",
+            stats: meta.stats
+          };
+        });
+        const syncAge = group.lastSync ? Math.round((now - new Date(group.lastSync).getTime()) / 6e4) : null;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              group: groupName,
+              lastSync: group.lastSync ?? null,
+              syncAgeMinutes: syncAge,
+              members: memberStatus
+            }, null, 2)
+          }]
+        };
       }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
@@ -2607,8 +3469,8 @@ function createMcpServer(graph, repoName) {
   });
   return server;
 }
-async function startMcpStdio(graph, repoName) {
-  const server = createMcpServer(graph, repoName);
+async function startMcpStdio(graph, repoName, workspaceRoot) {
+  const server = createMcpServer(graph, repoName, workspaceRoot);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -2618,24 +3480,54 @@ function findNodeByName(graph, name) {
   }
   return void 0;
 }
+function parseDiff(diffText) {
+  const result = [];
+  let currentFile = null;
+  let currentNewLine = 0;
+  const changedLinesMap = /* @__PURE__ */ new Map();
+  for (const raw of diffText.split("\n")) {
+    const fileMatch = raw.match(/^\+\+\+ b\/(.+)/);
+    if (fileMatch) {
+      currentFile = fileMatch[1];
+      if (!changedLinesMap.has(currentFile)) changedLinesMap.set(currentFile, []);
+      continue;
+    }
+    const hunkMatch = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunkMatch) {
+      currentNewLine = parseInt(hunkMatch[1], 10);
+      continue;
+    }
+    if (!currentFile) continue;
+    if (raw.startsWith("+") && !raw.startsWith("+++")) {
+      changedLinesMap.get(currentFile).push(currentNewLine);
+      currentNewLine++;
+    } else if (raw.startsWith("-") && !raw.startsWith("---")) ; else if (!raw.startsWith("\\")) {
+      currentNewLine++;
+    }
+  }
+  for (const [filePath, changedLines] of changedLinesMap) {
+    result.push({ filePath, changedLines });
+  }
+  return result;
+}
 
 // src/cli/main.ts
 init_metadata();
 async function writeSkillFiles(graph, workspaceRoot, projectName) {
-  const outputDir = path.join(workspaceRoot, ".claude", "skills", "code-intel");
+  const outputDir = path16.join(workspaceRoot, ".claude", "skills", "code-intel");
   const areas = buildAreaMap(graph, workspaceRoot);
   if (areas.length === 0) return { skills: [], outputDir };
-  fs8.rmSync(outputDir, { recursive: true, force: true });
-  fs8.mkdirSync(outputDir, { recursive: true });
+  fs14.rmSync(outputDir, { recursive: true, force: true });
+  fs14.mkdirSync(outputDir, { recursive: true });
   const skills = [];
   const usedNames = /* @__PURE__ */ new Set();
   for (const area of areas) {
     const kebab = uniqueKebab(area.label, usedNames);
     usedNames.add(kebab);
     const content = renderSkill(area, projectName, kebab);
-    const dir = path.join(outputDir, kebab);
-    fs8.mkdirSync(dir, { recursive: true });
-    fs8.writeFileSync(path.join(dir, "SKILL.md"), content, "utf-8");
+    const dir = path16.join(outputDir, kebab);
+    fs14.mkdirSync(dir, { recursive: true });
+    fs14.writeFileSync(path16.join(dir, "SKILL.md"), content, "utf-8");
     skills.push({ name: kebab, label: area.label, symbolCount: area.nodes.length, fileCount: area.files.size });
   }
   return { skills, outputDir };
@@ -2815,11 +3707,13 @@ var BLOCK_START = "<!-- code-intel:start -->";
 var BLOCK_END = "<!-- code-intel:end -->";
 function writeContextFiles(workspaceRoot, projectName, stats, skills) {
   const block = buildBlock(projectName, stats, skills);
-  upsertFile(path.join(workspaceRoot, "AGENTS.md"), block);
-  upsertFile(path.join(workspaceRoot, "CLAUDE.md"), block);
+  upsertFile(path16.join(workspaceRoot, "AGENTS.md"), block, "AGENTS.md");
+  upsertFile(path16.join(workspaceRoot, "CLAUDE.md"), block, "CLAUDE.md");
 }
 function buildBlock(projectName, stats, skills) {
-  const skillRows = skills.map((s) => `| Work in \`${s.label}\` (${s.symbolCount} symbols) | \`.claude/skills/code-intel/${s.name}/SKILL.md\` |`).join("\n");
+  const skillRows = skills.map(
+    (s) => `| Work in \`${s.label}\` (${s.symbolCount} symbols) | \`.claude/skills/code-intel/${s.name}/SKILL.md\` |`
+  ).join("\n");
   const skillTable = `| Task | Skill file |
 |------|------------|
 | Understand architecture / "How does X work?" | Load \`code-intel-exploring\` skill |
@@ -2829,16 +3723,19 @@ ${skillRows ? skillRows + "\n" : ""}`;
   return `${BLOCK_START}
 # Code Intelligence \u2014 ${projectName}
 
+> \u26A0 This section is auto-managed by \`code-intel analyze\`. Do **not** edit between the markers \u2014 your changes will be overwritten.
+> Add your own notes below the \`${BLOCK_END}\` marker.
+
 Indexed: **${stats.nodes.toLocaleString()} nodes** | **${stats.edges.toLocaleString()} edges** | **${stats.files} files** | analyzed in ${(stats.duration / 1e3).toFixed(1)}s
 
-> If the index is stale, re-run: \`code-intel analyze\`
+> Index stale? Re-run: \`code-intel analyze\`
 
 ## Always Do
 
-- **Before editing any symbol**, run \`code-intel impact <symbol>\` and review blast radius.
+- **Before editing any symbol**, run \`code-intel impact <symbol>\` to review its blast radius.
 - **Before committing**, verify scope with \`code-intel inspect <symbol>\`.
 - Use \`code-intel search "<concept>"\` to find related symbols instead of grepping.
-- Warn the user if impact shows \u2265 5 direct callers (HIGH risk).
+- Warn the user if impact shows \u2265 5 direct callers (**HIGH risk**).
 
 ## Never Do
 
@@ -2862,29 +3759,50 @@ code-intel clean [path]            # Remove index data
 ${skillTable}
 ${BLOCK_END}`;
 }
-function upsertFile(filePath, block) {
-  if (!fs8.existsSync(filePath)) {
-    fs8.writeFileSync(filePath, block + "\n", "utf-8");
+function upsertFile(filePath, block, fileName) {
+  if (!fs14.existsSync(filePath)) {
+    const newContent = [
+      `# ${fileName}`,
+      "",
+      block,
+      "",
+      "---",
+      "",
+      "<!-- Add your own custom notes below this line. They will never be overwritten by code-intel. -->",
+      ""
+    ].join("\n");
+    fs14.writeFileSync(filePath, newContent, "utf-8");
     return;
   }
-  const existing = fs8.readFileSync(filePath, "utf-8");
+  const existing = fs14.readFileSync(filePath, "utf-8");
   const startIdx = findLineMarker(existing, BLOCK_START);
   const endIdx = findLineMarker(existing, BLOCK_END, startIdx === -1 ? 0 : startIdx);
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
     const before = existing.slice(0, startIdx);
     const after = existing.slice(endIdx + BLOCK_END.length);
-    fs8.writeFileSync(filePath, (before + block + after).trimEnd() + "\n", "utf-8");
+    const updated = (before + block + after).trimEnd() + "\n";
+    fs14.writeFileSync(filePath, updated, "utf-8");
     return;
   }
-  fs8.writeFileSync(filePath, existing.trimEnd() + "\n\n" + block + "\n", "utf-8");
+  const appended = [
+    existing.trimEnd(),
+    "",
+    "---",
+    "",
+    "<!-- The following section is auto-managed by code-intel. Do not edit between the markers. -->",
+    "",
+    block,
+    ""
+  ].join("\n");
+  fs14.writeFileSync(filePath, appended, "utf-8");
 }
 function findLineMarker(content, marker, startFrom = 0) {
   let idx = content.indexOf(marker, startFrom);
   while (idx !== -1) {
-    const atStart = idx === 0 || content[idx - 1] === "\n";
+    const atLineStart = idx === 0 || content[idx - 1] === "\n";
     const end = idx + marker.length;
-    const atEnd = end === content.length || content[end] === "\n" || content[end] === "\r";
-    if (atStart && atEnd) return idx;
+    const atLineEnd = end === content.length || content[end] === "\n" || content[end] === "\r";
+    if (atLineStart && atLineEnd) return idx;
     idx = content.indexOf(marker, idx + 1);
   }
   return -1;
@@ -2898,27 +3816,160 @@ var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname(__filename$1);
 var _pkg = JSON.parse(readFileSync(join(__dirname2, "../../package.json"), "utf-8"));
 var program = new Command();
-program.name("code-intel").description("Code Intelligence Platform \u2014 Static Analysis + Knowledge Graph").version(_pkg.version);
+var BANNER = `
+  \u25C8  Code Intelligence Platform  v${_pkg.version}
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  Build a Knowledge Graph from source code and explore it via Web UI, HTTP API,
+  CLI, and MCP server. Supports 14+ languages. Zero config.
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`;
+program.name("code-intel").description("Code Intelligence Platform \u2014 Static Analysis + Knowledge Graph").version(_pkg.version).addHelpText("beforeAll", BANNER).addHelpText("after", `
+  \u250C\u2500 Quick Start \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502                                                                          \u2502
+  \u2502  code-intel setup                  Configure MCP for your editors        \u2502
+  \u2502  code-intel analyze                Index current directory               \u2502
+  \u2502  code-intel serve                  Start web UI at http://localhost:4747  \u2502
+  \u2502  code-intel search "query"         Search the knowledge graph            \u2502
+  \u2502  code-intel inspect <symbol>       Inspect a symbol's connections        \u2502
+  \u2502  code-intel impact <symbol>        Show blast radius for a symbol        \u2502
+  \u2502                                                                          \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+  \u250C\u2500 All Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502                                                                                                                    \u2502
+  \u2502  setup                                                                                                             \u2502
+  \u2502    code-intel setup                         Register the MCP server in your editor config (one-time)              \u2502
+  \u2502                                                                                                                    \u2502
+  \u2502  analyze                                                                                                           \u2502
+  \u2502    code-intel analyze [path]                Parse source code and build the knowledge graph                        \u2502
+  \u2502    code-intel analyze --force               Discard the existing index and perform a full re-analysis             \u2502
+  \u2502    code-intel analyze --skills              Emit per-cluster SKILL.md files under .claude/skills/code-intel/      \u2502
+  \u2502    code-intel analyze --embeddings          Build a vector index for semantic (natural-language) search           \u2502
+  \u2502    code-intel analyze --skip-embeddings     Omit embedding generation for a significantly faster run             \u2502
+  \u2502    code-intel analyze --skip-agents-md      Preserve any hand-edited content in AGENTS.md / CLAUDE.md            \u2502
+  \u2502    code-intel analyze --skip-git            Allow analysis of directories that are not Git repositories           \u2502
+  \u2502    code-intel analyze --verbose             Print every file skipped due to an unsupported parser                 \u2502
+  \u2502                                                                                                                    \u2502
+  \u2502  server                                                                                                            \u2502
+  \u2502    code-intel mcp [path]                    Launch the MCP stdio server consumed by AI-enabled editors            \u2502
+  \u2502    code-intel serve [path] --port <n>       Start the HTTP API and serve the interactive web UI (default :4747)   \u2502
+  \u2502                                                                                                                    \u2502
+  \u2502  registry                                                                                                          \u2502
+  \u2502    code-intel list                          Display all repositories that have been indexed                       \u2502
+  \u2502    code-intel status [path]                 Report index freshness, symbol counts, and last-run duration          \u2502
+  \u2502    code-intel clean [path]                  Remove the .code-intel/ index for the specified repository            \u2502
+  \u2502    code-intel clean --all --force           Permanently remove all indexed repositories (requires --force)        \u2502
+  \u2502                                                                                                                    \u2502
+  \u2502  exploration                                                                                                       \u2502
+  \u2502    code-intel search <query>                Execute a BM25 keyword search across all indexed symbols              \u2502
+  \u2502    code-intel inspect <symbol>              Show callers, callees, import edges, and source location              \u2502
+  \u2502    code-intel impact <symbol>               Compute the transitive blast radius of a change to a symbol           \u2502
+  \u2502                                                                                                                    \u2502
+  \u2502  groups  (multi-repo / monorepo service tracking)                                                                  \u2502
+  \u2502    code-intel group create <name>           Create a named group to track multiple repositories together          \u2502
+  \u2502    code-intel group add <g> <path> <repo>   Enroll an indexed repo in a group under the given hierarchy path     \u2502
+  \u2502    code-intel group remove <g> <path>       Remove a repository from a group by its hierarchy path               \u2502
+  \u2502    code-intel group list [name]             List all groups, or print the full membership of one group            \u2502
+  \u2502    code-intel group sync <name>             Extract cross-repo contracts and resolve provider/consumer links      \u2502
+  \u2502    code-intel group contracts <name>        Inspect extracted contracts and confidence-ranked cross-links         \u2502
+  \u2502    code-intel group query <name> <q>        Run a merged RRF search across every repository in a group           \u2502
+  \u2502    code-intel group status <name>           Audit index freshness and sync staleness for all group members        \u2502
+  \u2502                                                                                                                    \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+  Multi-language: TypeScript \xB7 JavaScript \xB7 Python \xB7 Java \xB7 Go \xB7 Rust \xB7 C/C++
+                  C# \xB7 PHP \xB7 Kotlin \xB7 Ruby \xB7 Swift \xB7 Dart
+
+  Docs: https://github.com/vohongtho/code-intel-platform
+`);
 async function analyzeWorkspace(targetPath, options) {
-  const workspaceRoot = path.resolve(targetPath);
+  const workspaceRoot = path16.resolve(targetPath);
   if (!options?.silent) console.log(`Analyzing: ${workspaceRoot}`);
+  logger_default.info(`analyze started: ${workspaceRoot}`);
+  if (options?.force) {
+    const dbPath = getDbPath(workspaceRoot);
+    const { getVectorDbPath: getVectorDbPath2 } = await Promise.resolve().then(() => (init_storage(), storage_exports));
+    const vdbPath = getVectorDbPath2(workspaceRoot);
+    const wipeFiles = [
+      dbPath,
+      `${dbPath}-shm`,
+      `${dbPath}-wal`,
+      `${dbPath}.shm`,
+      `${dbPath}.wal`,
+      vdbPath,
+      `${vdbPath}-shm`,
+      `${vdbPath}-wal`,
+      `${vdbPath}.shm`,
+      `${vdbPath}.wal`
+    ];
+    for (const f of wipeFiles) {
+      try {
+        if (fs14.existsSync(f)) fs14.unlinkSync(f);
+      } catch {
+      }
+    }
+  }
   if (!options?.skipGit) {
-    const gitDir = path.join(workspaceRoot, ".git");
-    if (!fs8.existsSync(gitDir)) {
-      console.warn(`  Warning: ${workspaceRoot} is not a Git repository. Use --skip-git to suppress this warning.`);
+    const gitDir = path16.join(workspaceRoot, ".git");
+    if (!fs14.existsSync(gitDir)) {
+      logger_default.warn(`${workspaceRoot} is not a Git repository`);
     }
   }
   const graph = createKnowledgeGraph();
+  const BAR_WIDTH = 30;
+  let currentPhase = "";
+  function renderBar(phase, done, total) {
+    const pct = total > 0 ? done / total : 1;
+    const filled = Math.round(pct * BAR_WIDTH);
+    const bar = "\u2588".repeat(filled) + "\u2591".repeat(BAR_WIDTH - filled);
+    const pctStr = (pct * 100).toFixed(0).padStart(3);
+    process.stdout.write(`\r  [${phase.padEnd(9)}] ${bar} ${pctStr}% (${done}/${total})`);
+  }
+  function clearBar() {
+    process.stdout.write("\r" + " ".repeat(70) + "\r");
+  }
+  const SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+  let spinnerIdx = 0;
+  let spinnerTimer = null;
+  function startSpinner(label) {
+    if (options?.silent) return;
+    spinnerIdx = 0;
+    spinnerTimer = setInterval(() => {
+      process.stdout.write(`\r  ${SPINNER_FRAMES[spinnerIdx % SPINNER_FRAMES.length]} ${label}\u2026`);
+      spinnerIdx++;
+    }, 80);
+  }
+  function stopSpinner() {
+    if (spinnerTimer) {
+      clearInterval(spinnerTimer);
+      spinnerTimer = null;
+    }
+    process.stdout.write("\r" + " ".repeat(60) + "\r");
+  }
   const context = {
     workspaceRoot,
     graph,
     filePaths: [],
     verbose: options?.verbose,
-    onProgress: options?.silent ? void 0 : (phase, msg) => console.log(`  [${phase}] ${msg}`)
+    onProgress: options?.silent ? void 0 : (phase, msg) => {
+      if (!options?.silent) {
+        if (currentPhase) clearBar();
+        console.log(`  [${phase}] ${msg}`);
+        currentPhase = "";
+      }
+    },
+    onPhaseProgress: options?.silent ? void 0 : (phase, done, total) => {
+      currentPhase = phase;
+      renderBar(phase, done, total);
+      if (done >= total) {
+        clearBar();
+        currentPhase = "";
+      }
+    }
   };
   const phases = [scanPhase, structurePhase, parsePhase, resolvePhase, clusterPhase, flowPhase];
   const result = await runPipeline(phases, context);
-  const repoName = path.basename(workspaceRoot);
+  const repoName = path16.basename(workspaceRoot);
   saveMetadata(workspaceRoot, {
     indexedAt: (/* @__PURE__ */ new Date()).toISOString(),
     stats: {
@@ -2938,45 +3989,71 @@ async function analyzeWorkspace(targetPath, options) {
       files: context.filePaths.length
     }
   });
+  startSpinner("Persisting graph to DB");
   try {
     const dbPath = getDbPath(workspaceRoot);
+    const staleFiles = [
+      dbPath,
+      `${dbPath}-shm`,
+      `${dbPath}-wal`,
+      `${dbPath}.shm`,
+      `${dbPath}.wal`
+    ];
+    for (const f of staleFiles) {
+      try {
+        if (fs14.existsSync(f)) fs14.unlinkSync(f);
+      } catch {
+      }
+    }
     const db = new DbManager(dbPath);
     await db.init();
     const { nodeCount, edgeCount } = await loadGraphToDB(graph, db);
     db.close();
+    stopSpinner();
+    logger_default.info(`DB persisted: ${nodeCount} nodes, ${edgeCount} edges`);
     if (!options?.silent) {
-      console.log(`  DB: ${nodeCount} nodes, ${edgeCount} edges persisted`);
+      console.log(`  \u2713 DB: ${nodeCount} nodes, ${edgeCount} edges persisted`);
     }
   } catch (err) {
-    if (!options?.silent) {
-      console.warn(`  DB persist warning: ${err instanceof Error ? err.message : err}`);
-    }
+    stopSpinner();
+    logger_default.warn(`DB persist failed: ${err instanceof Error ? err.message : err}`);
   }
   const doEmbeddings = options?.embeddings && !options?.skipEmbeddings;
   if (doEmbeddings) {
-    if (!options?.silent) console.log("  Embeddings: building vector index\u2026");
+    startSpinner("Building vector embeddings");
     try {
       const { embedNodes: embedNodes2 } = await Promise.resolve().then(() => (init_embedder(), embedder_exports));
       const { getVectorDbPath: getVectorDbPath2 } = await Promise.resolve().then(() => (init_storage(), storage_exports));
       const { VectorIndex: VectorIndex2 } = await Promise.resolve().then(() => (init_vector_index(), vector_index_exports));
       const vdbPath = getVectorDbPath2(workspaceRoot);
+      const staleVdb = [vdbPath, `${vdbPath}-shm`, `${vdbPath}-wal`, `${vdbPath}.shm`, `${vdbPath}.wal`];
+      for (const f of staleVdb) {
+        try {
+          if (fs14.existsSync(f)) fs14.unlinkSync(f);
+        } catch {
+        }
+      }
       const vdb = new DbManager(vdbPath);
       await vdb.init();
       const idx = new VectorIndex2(vdb);
       await idx.init();
       const nodes = await embedNodes2(graph, {
         onProgress: (done, total) => {
-          if (!options?.silent) process.stdout.write(`\r  [vector] ${done}/${total}`);
+          if (!options?.silent) {
+            stopSpinner();
+            renderBar("vector", done, total);
+            if (done >= total) clearBar();
+          }
         }
       });
-      if (!options?.silent) console.log("");
+      stopSpinner();
+      logger_default.info(`Embeddings built: ${nodes.length} vectors`);
       await idx.buildIndex(nodes);
-      if (!options?.silent) console.log(`  Embeddings: ${nodes.length} vectors built`);
+      if (!options?.silent) console.log(`  \u2713 Embeddings: ${nodes.length} vectors built`);
       vdb.close();
     } catch (err) {
-      if (!options?.silent) {
-        console.warn(`  Embeddings warning: ${err instanceof Error ? err.message : err}`);
-      }
+      stopSpinner();
+      logger_default.warn(`Embeddings failed: ${err instanceof Error ? err.message : err}`);
     }
   } else if (!options?.skipEmbeddings && !options?.silent) {
     console.log("  Embeddings: skipped (use --embeddings to enable)");
@@ -2984,19 +4061,22 @@ async function analyzeWorkspace(targetPath, options) {
   const doSkills = options?.skills !== false;
   let skillSummaries = [];
   if (doSkills) {
+    startSpinner("Generating skill files");
     try {
       const { skills } = await writeSkillFiles(graph, workspaceRoot, repoName);
       skillSummaries = skills;
+      stopSpinner();
+      logger_default.info(`Skills generated: ${skills.length}`);
       if (!options?.silent && skills.length > 0) {
-        console.log(`  Skills: ${skills.length} generated \u2192 .claude/skills/code-intel/`);
+        console.log(`  \u2713 Skills: ${skills.length} generated \u2192 .claude/skills/code-intel/`);
       }
     } catch (err) {
-      if (!options?.silent) {
-        console.warn(`  Skills warning: ${err instanceof Error ? err.message : err}`);
-      }
+      stopSpinner();
+      logger_default.warn(`Skills generation failed: ${err instanceof Error ? err.message : err}`);
     }
   }
   if (!options?.skipAgentsMd) {
+    startSpinner("Writing context files");
     try {
       writeContextFiles(workspaceRoot, repoName, {
         nodes: graph.size.nodes,
@@ -3004,29 +4084,37 @@ async function analyzeWorkspace(targetPath, options) {
         files: context.filePaths.length,
         duration: result.totalDuration
       }, skillSummaries);
+      stopSpinner();
+      logger_default.info("Context files written: AGENTS.md + CLAUDE.md");
       if (!options?.silent) {
-        console.log(`  Context: AGENTS.md + CLAUDE.md updated`);
+        console.log(`  \u2713 Context: AGENTS.md + CLAUDE.md updated`);
       }
     } catch (err) {
-      if (!options?.silent) {
-        console.warn(`  Context warning: ${err instanceof Error ? err.message : err}`);
-      }
+      stopSpinner();
+      logger_default.warn(`Context file write failed: ${err instanceof Error ? err.message : err}`);
     }
   }
   if (!options?.silent) {
+    const dur = result.totalDuration;
+    const durStr = dur >= 1e3 ? `${(dur / 1e3).toFixed(1)}s` : `${dur}ms`;
     console.log(`
-Done in ${result.totalDuration}ms`);
-    console.log(`  Nodes: ${graph.size.nodes}`);
-    console.log(`  Edges: ${graph.size.edges}`);
-    console.log(`  Files: ${context.filePaths.length}`);
-    console.log(`  Success: ${result.success}`);
+  \u2705  Done in ${durStr}  \u2014  ${graph.size.nodes} nodes \xB7 ${graph.size.edges} edges \xB7 ${context.filePaths.length} files`);
   }
+  logger_default.info(`analyze complete: ${graph.size.nodes} nodes, ${graph.size.edges} edges, ${context.filePaths.length} files, ${result.totalDuration}ms`);
   return { graph, result, repoName, workspaceRoot };
 }
-program.command("setup").description("Configure MCP server for your editors (one-time setup)").action(() => {
+program.command("setup").description("Configure MCP server for your editors (one-time setup)").addHelpText("after", `
+  Configure the code-intel MCP server for Claude Desktop, VS Code, or any
+  editor that supports the Model Context Protocol.
+
+  Auto-writes to ~/.config/claude/claude_desktop_config.json when available.
+
+  Examples:
+    $ code-intel setup
+`).action(() => {
   const configDir = process.env.HOME ? `${process.env.HOME}/.config/claude` : null;
-  console.log("\n\u{1F4E1} Code Intelligence MCP Setup\n");
-  console.log("Add the following to your editor MCP configuration:\n");
+  console.log("\n  \u25C8  Code Intelligence \u2014 MCP Setup\n");
+  console.log("  Add the following to your editor MCP configuration:\n");
   const mcpConfig = {
     mcpServers: {
       "code-intel": {
@@ -3035,14 +4123,14 @@ program.command("setup").description("Configure MCP server for your editors (one
       }
     }
   };
-  console.log("For Claude Desktop / Claude Code (~/.config/claude/claude_desktop_config.json):");
-  console.log(JSON.stringify(mcpConfig, null, 2));
+  console.log("  Claude Desktop / Claude Code  (~/.config/claude/claude_desktop_config.json)");
+  console.log("  " + JSON.stringify(mcpConfig, null, 2).split("\n").join("\n  "));
   if (configDir) {
     const configFile = `${configDir}/claude_desktop_config.json`;
     try {
       let existing = {};
-      if (fs8.existsSync(configFile)) {
-        existing = JSON.parse(fs8.readFileSync(configFile, "utf-8"));
+      if (fs14.existsSync(configFile)) {
+        existing = JSON.parse(fs14.readFileSync(configFile, "utf-8"));
       }
       const merged = {
         ...existing,
@@ -3051,30 +4139,35 @@ program.command("setup").description("Configure MCP server for your editors (one
           ...mcpConfig.mcpServers
         }
       };
-      fs8.mkdirSync(configDir, { recursive: true });
-      fs8.writeFileSync(configFile, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+      fs14.mkdirSync(configDir, { recursive: true });
+      fs14.writeFileSync(configFile, JSON.stringify(merged, null, 2) + "\n", "utf-8");
       console.log(`
-\u2705 Written to ${configFile}`);
+  \u2705  Written to ${configFile}`);
     } catch (err) {
-      console.warn(`
-\u26A0 Could not auto-write config: ${err instanceof Error ? err.message : err}`);
-      console.log("Please add the config above manually.");
+      logger_default.warn(`
+  \u26A0   Could not auto-write config: ${err instanceof Error ? err.message : err}`);
+      console.log("  Please add the config above manually.");
     }
   }
-  console.log("\nFor VS Code (settings.json or .vscode/mcp.json), use the same mcpServers block.");
-  console.log("\nThen run `code-intel analyze` in your project to index it.\n");
+  console.log("\n  VS Code / Cursor \u2014 add the same mcpServers block to settings.json or .vscode/mcp.json");
+  console.log("\n  Next: run `code-intel analyze` inside your project to build the knowledge graph.\n");
 });
-program.command("analyze").description("Index a repository (or update stale index)").argument("[path]", "Path to analyze", ".").option("--force", "Force full re-index even if already indexed").option("--skills", "Generate repo-specific skill files from detected communities").option("--skip-embeddings", "Skip embedding generation (faster)").option("--skip-agents-md", "Preserve custom AGENTS.md/CLAUDE.md code-intel section edits").option("--skip-git", "Index folders that are not Git repositories").option("--embeddings", "Enable embedding generation (slower, better search)").option("--verbose", "Log skipped files when parsers are unavailable").addHelpText("after", `
-Examples:
-  code-intel analyze                       Index current directory
-  code-intel analyze ./my-project          Index a specific path
-  code-intel analyze --force               Force full re-index
-  code-intel analyze --skills              Also generate .claude/skills/ files
-  code-intel analyze --skip-embeddings     Skip vector embeddings (faster)
-  code-intel analyze --skip-agents-md      Preserve custom AGENTS.md edits
-  code-intel analyze --skip-git            Allow non-Git folders
-  code-intel analyze --embeddings          Enable vector embeddings
-  code-intel analyze --verbose             Show skipped files`).action(async (targetPath, opts) => {
+program.command("analyze").description("Index a repository and build the knowledge graph").argument("[path]", "Path to the repository (default: current directory)", ".").option("--force", "Force full re-index, ignoring cached data").option("--skills", "Generate .claude/skills/ SKILL.md files from detected clusters").option("--embeddings", "Build vector embeddings for semantic search (slower, recommended)").option("--skip-embeddings", "Skip embedding generation (faster, text-search only)").option("--skip-agents-md", "Preserve any custom edits inside AGENTS.md / CLAUDE.md").option("--skip-git", "Allow indexing directories that are not Git repositories").option("--verbose", "Log every file skipped due to missing parser support").addHelpText("after", `
+  Parses your source code with tree-sitter, builds a Knowledge Graph of
+  symbols and their relationships, persists it to .code-intel/graph.db,
+  and auto-generates AGENTS.md + CLAUDE.md context blocks.
+
+  Examples:
+    $ code-intel analyze                        Index current directory
+    $ code-intel analyze ./my-project           Index a specific path
+    $ code-intel analyze --force                Force full re-index
+    $ code-intel analyze --embeddings           Enable semantic (vector) search
+    $ code-intel analyze --skills               Generate .claude/skills/ files
+    $ code-intel analyze --skip-embeddings      Skip vectors for a faster run
+    $ code-intel analyze --skip-agents-md       Preserve your custom AGENTS.md edits
+    $ code-intel analyze --skip-git             Index a non-Git folder
+    $ code-intel analyze --verbose              Show files skipped by the parser
+`).action(async (targetPath, opts) => {
   await analyzeWorkspace(targetPath, {
     force: opts.force,
     skills: opts.skills,
@@ -3085,123 +4178,252 @@ Examples:
     verbose: opts.verbose
   });
 });
-program.command("mcp").description("Start MCP server (stdio) \u2014 serves all indexed repos").argument("[path]", "Path to analyze", ".").action(async (targetPath) => {
-  const { graph, repoName } = await analyzeWorkspace(targetPath, { silent: true });
-  await startMcpStdio(graph, repoName);
+program.command("mcp").description("Start MCP server over stdio \u2014 exposes all tools to your AI editor").argument("[path]", "Path to analyze (default: current directory)", ".").addHelpText("after", `
+  Starts the Model Context Protocol server over stdio transport.
+  Your editor (Claude Desktop, VS Code, Cursor, etc.) connects to it
+  and gains access to search, inspect, blast-radius, and flow tools.
+
+  Typically invoked automatically by your editor via the config from \`code-intel setup\`.
+
+  Examples:
+    $ code-intel mcp
+    $ code-intel mcp ./my-project
+`).action(async (targetPath) => {
+  const workspaceRoot = path16.resolve(targetPath);
+  const repoName = path16.basename(workspaceRoot);
+  const dbPath = getDbPath(workspaceRoot);
+  const existingIndex = fs14.existsSync(dbPath) && loadMetadata(workspaceRoot) !== null;
+  if (existingIndex) {
+    const graph = createKnowledgeGraph();
+    const db = new DbManager(dbPath);
+    await db.init();
+    await loadGraphFromDB(graph, db);
+    db.close();
+    await startMcpStdio(graph, repoName, workspaceRoot);
+  } else {
+    const { graph, repoName: name, workspaceRoot: root } = await analyzeWorkspace(targetPath, { silent: true });
+    await startMcpStdio(graph, name, root);
+  }
 });
-program.command("serve").description("Start local HTTP server + web UI (http://localhost:4747)").argument("[path]", "Path to analyze", ".").option("-p, --port <port>", "Port number", "4747").action(async (targetPath, options) => {
-  const { graph, repoName, workspaceRoot } = await analyzeWorkspace(targetPath);
-  startHttpServer(graph, repoName, parseInt(options.port, 10), workspaceRoot);
+program.command("serve").description("Start the local HTTP server + web UI for graph exploration").argument("[path]", "Path to analyze (default: current directory)", ".").option("-p, --port <port>", "Port to listen on", "4747").option("--force", "Force re-analysis even if an index already exists").addHelpText("after", `
+  If a .code-intel/graph.db index already exists for the path, the server
+  loads the persisted graph directly and starts immediately \u2014 no re-analysis.
+  Use --force to discard the existing index and re-analyze from scratch.
+
+  The web UI offers:
+    \xB7 Force-directed Knowledge Graph with color-coded node types
+    \xB7 BM25 text search + optional semantic (vector) search
+    \xB7 Node detail panel: callers, callees, blast radius, source preview
+    \xB7 AI Code Chat grounded on your codebase
+    \xB7 Multi-repo group view (if groups are configured)
+
+  Examples:
+    $ code-intel serve
+    $ code-intel serve ./my-project
+    $ code-intel serve --port 8080
+    $ code-intel serve --force
+`).action(async (targetPath, options) => {
+  const workspaceRoot = path16.resolve(targetPath);
+  const repoName = path16.basename(workspaceRoot);
+  const dbPath = getDbPath(workspaceRoot);
+  const existingIndex = !options.force && fs14.existsSync(dbPath) && loadMetadata(workspaceRoot) !== null;
+  if (existingIndex) {
+    console.log(`Loading index: ${workspaceRoot}`);
+    const meta = loadMetadata(workspaceRoot);
+    console.log(`  \u25C8  ${meta.stats.nodes} nodes \xB7 ${meta.stats.edges} edges \xB7 ${meta.stats.files} files  (indexed ${meta.indexedAt})`);
+    const graph = createKnowledgeGraph();
+    const db = new DbManager(dbPath);
+    await db.init();
+    await loadGraphFromDB(graph, db);
+    db.close();
+    startHttpServer(graph, repoName, parseInt(options.port, 10), workspaceRoot);
+  } else {
+    const { graph, workspaceRoot: root, repoName: name } = await analyzeWorkspace(targetPath, { force: options.force });
+    startHttpServer(graph, name, parseInt(options.port, 10), root);
+  }
 });
-program.command("list").description("List all indexed repositories").action(() => {
+program.command("list").description("List all indexed repositories in the registry").addHelpText("after", `
+  Shows every repository that has been indexed with \`code-intel analyze\`.
+  Useful for checking what is available before using \`code-intel group add\`.
+
+  Examples:
+    $ code-intel list
+`).action(() => {
   const repos = loadRegistry();
   if (repos.length === 0) {
-    console.log("No indexed repositories. Run `code-intel analyze <path>` first.");
+    console.log("\n  No indexed repositories found.");
+    console.log("  Run `code-intel analyze <path>` to index a project.\n");
     return;
   }
   console.log(`
-Indexed repositories (${repos.length}):
+  Indexed repositories (${repos.length}):
 `);
   for (const r of repos) {
-    console.log(`  ${r.name.padEnd(25)} ${r.stats.nodes} nodes, ${r.stats.edges} edges, ${r.stats.files} files`);
-    console.log(`    Path:    ${r.path}`);
-    console.log(`    Indexed: ${r.indexedAt}`);
+    console.log(`  \u25C6  ${r.name}`);
+    console.log(`     Nodes:   ${r.stats.nodes}  \xB7  Edges: ${r.stats.edges}  \xB7  Files: ${r.stats.files}`);
+    console.log(`     Path:    ${r.path}`);
+    console.log(`     Indexed: ${r.indexedAt}
+`);
   }
 });
-program.command("status").description("Show index status for current repo").argument("[path]", "Path to check", ".").action((targetPath) => {
-  const workspaceRoot = path.resolve(targetPath);
+program.command("status").description("Show index freshness and statistics for a repository").argument("[path]", "Path to check (default: current directory)", ".").addHelpText("after", `
+  Reads the metadata from .code-intel/meta.json and reports when the index
+  was last built and how many symbols were found.
+
+  Examples:
+    $ code-intel status
+    $ code-intel status ./my-project
+`).action((targetPath) => {
+  const workspaceRoot = path16.resolve(targetPath);
   const meta = loadMetadata(workspaceRoot);
   if (!meta) {
-    console.log("Not indexed. Run `code-intel analyze` first.");
+    console.log(`
+  \u2717  ${workspaceRoot} is not indexed.`);
+    console.log("     Run `code-intel analyze` to build the index.\n");
     return;
   }
   console.log(`
-Index status for ${workspaceRoot}:`);
-  console.log(`  Indexed at: ${meta.indexedAt}`);
-  console.log(`  Nodes:      ${meta.stats.nodes}`);
-  console.log(`  Edges:      ${meta.stats.edges}`);
-  console.log(`  Files:      ${meta.stats.files}`);
-  console.log(`  Duration:   ${meta.stats.duration}ms`);
+  \u25C8  Index status \u2014 ${workspaceRoot}
+`);
+  console.log(`     Indexed at : ${meta.indexedAt}`);
+  console.log(`     Nodes      : ${meta.stats.nodes}`);
+  console.log(`     Edges      : ${meta.stats.edges}`);
+  console.log(`     Files      : ${meta.stats.files}`);
+  console.log(`     Duration   : ${meta.stats.duration}ms
+`);
 });
-program.command("clean").description("Delete index for current repo (or all repos with --all --force)").argument("[path]", "Path to clean", ".").option("--all", "Clean all indexed repositories").option("--force", "Required with --all to confirm destructive operation").action((targetPath, opts) => {
+program.command("clean").description("Remove the knowledge graph index for a repository").argument("[path]", "Path to clean (default: current directory)", ".").option("--all", "Remove indexes for ALL indexed repositories").option("--force", "Required with --all to confirm the destructive operation").addHelpText("after", `
+  Deletes the .code-intel/ directory and removes the entry from the registry.
+
+  \u26A0  --all --force is irreversible \u2014 it deletes every indexed repo's data.
+
+  Examples:
+    $ code-intel clean                   Remove index for current directory
+    $ code-intel clean ./my-project      Remove index for a specific path
+    $ code-intel clean --all --force     Remove ALL indexes (requires --force)
+`).action((targetPath, opts) => {
   if (opts.all) {
     if (!opts.force) {
-      console.error("Error: --all requires --force to confirm. Run: code-intel clean --all --force");
+      console.error("\n  \u2717  --all requires --force to confirm the destructive operation.");
+      console.error("     Run: code-intel clean --all --force\n");
       process.exit(1);
     }
     const repos = loadRegistry();
     if (repos.length === 0) {
-      console.log("No indexed repositories to clean.");
+      console.log("\n  No indexed repositories to clean.\n");
       return;
     }
     for (const r of repos) {
-      const codeIntelDir2 = path.join(r.path, ".code-intel");
-      if (fs8.existsSync(codeIntelDir2)) {
-        fs8.rmSync(codeIntelDir2, { recursive: true, force: true });
-        console.log(`  Removed ${codeIntelDir2}`);
+      const codeIntelDir2 = path16.join(r.path, ".code-intel");
+      if (fs14.existsSync(codeIntelDir2)) {
+        fs14.rmSync(codeIntelDir2, { recursive: true, force: true });
+        console.log(`  \u2713  Removed ${codeIntelDir2}`);
       }
       removeRepo(r.path);
     }
     console.log(`
-Cleaned ${repos.length} repositor${repos.length === 1 ? "y" : "ies"}.`);
+  Cleaned ${repos.length} repositor${repos.length === 1 ? "y" : "ies"}.
+`);
     return;
   }
-  const workspaceRoot = path.resolve(targetPath);
-  const codeIntelDir = path.join(workspaceRoot, ".code-intel");
-  if (fs8.existsSync(codeIntelDir)) {
-    fs8.rmSync(codeIntelDir, { recursive: true, force: true });
-    console.log(`Removed ${codeIntelDir}`);
+  const workspaceRoot = path16.resolve(targetPath);
+  const codeIntelDir = path16.join(workspaceRoot, ".code-intel");
+  if (fs14.existsSync(codeIntelDir)) {
+    fs14.rmSync(codeIntelDir, { recursive: true, force: true });
+    console.log(`
+  \u2713  Removed ${codeIntelDir}`);
   }
   removeRepo(workspaceRoot);
-  console.log("Index cleaned.");
+  console.log("  Index cleaned.\n");
 });
-program.command("search").description("Search the knowledge graph").argument("<query>", "Search query").option("-l, --limit <limit>", "Max results", "20").option("-p, --path <path>", "Path to analyze", ".").action(async (query, options) => {
+program.command("search").description("Search the knowledge graph for symbols matching a query").argument("<query>", "Search query (name, kind, or partial match)").option("-l, --limit <n>", "Maximum number of results", "20").option("-p, --path <path>", "Path to the repository (default: current directory)", ".").addHelpText("after", `
+  Runs BM25 text search across all indexed symbols \u2014 functions, classes,
+  files, routes, interfaces, and more.
+
+  Examples:
+    $ code-intel search "handleRequest"
+    $ code-intel search "auth" --limit 10
+    $ code-intel search "UserService" --path ./backend
+`).action(async (query, options) => {
   const { graph } = await analyzeWorkspace(options.path, { silent: true });
   const results = textSearch(graph, query, parseInt(options.limit, 10));
   if (results.length === 0) {
-    console.log("No results found.");
+    console.log(`
+  No results found for "${query}".
+`);
     return;
   }
-  console.log(`Found ${results.length} results for "${query}":
+  console.log(`
+  ${results.length} result(s) for "${query}":
 `);
   for (const r of results) {
-    console.log(`  ${r.kind.padEnd(12)} ${r.name.padEnd(30)} ${r.filePath}`);
+    console.log(`  ${r.kind.padEnd(14)} ${r.name.padEnd(32)} ${r.filePath}`);
   }
+  console.log("");
 });
-program.command("inspect").description("Inspect a symbol: callers, callees, location").argument("<symbol>", "Symbol name").option("-p, --path <path>", "Path to analyze", ".").action(async (symbol, options) => {
+program.command("inspect").description("Inspect a symbol \u2014 show callers, callees, file location, and export status").argument("<symbol>", "Exact symbol name to inspect").option("-p, --path <path>", "Path to the repository (default: current directory)", ".").addHelpText("after", `
+  Finds the symbol in the knowledge graph and prints its full connection
+  profile: where it lives, who calls it, and what it calls.
+
+  Use this before renaming a symbol to understand its blast radius.
+
+  Examples:
+    $ code-intel inspect runPipeline
+    $ code-intel inspect ApiClient --path ./frontend
+`).action(async (symbol, options) => {
   const { graph } = await analyzeWorkspace(options.path, { silent: true });
   let found = false;
   for (const node of graph.allNodes()) {
     if (node.name === symbol) {
       found = true;
       console.log(`
-${node.kind}: ${node.name}`);
-      console.log(`  File:     ${node.filePath}:${node.startLine ?? "?"}`);
-      console.log(`  Exported: ${node.exported ?? "unknown"}`);
+  \u25C6  ${node.kind}: ${node.name}`);
+      console.log(`     File     : ${node.filePath}:${node.startLine ?? "?"}`);
+      console.log(`     Exported : ${node.exported ?? "unknown"}`);
       const incoming = [...graph.findEdgesTo(node.id)];
       const outgoing = [...graph.findEdgesFrom(node.id)];
       const callers = incoming.filter((e) => e.kind === "calls");
       const callees = outgoing.filter((e) => e.kind === "calls");
       if (callers.length > 0) {
-        console.log(`  Callers (${callers.length}):`);
+        console.log(`
+     Callers (${callers.length}):`);
         for (const c of callers.slice(0, 10)) {
           const n = graph.getNode(c.source);
-          console.log(`    \u2190 ${n?.name ?? c.source} (${n?.filePath})`);
+          console.log(`       \u2190  ${n?.name ?? c.source}  (${n?.filePath})`);
         }
+        if (callers.length > 10) console.log(`       \u2026 and ${callers.length - 10} more`);
       }
       if (callees.length > 0) {
-        console.log(`  Callees (${callees.length}):`);
+        console.log(`
+     Callees (${callees.length}):`);
         for (const c of callees.slice(0, 10)) {
           const n = graph.getNode(c.target);
-          console.log(`    \u2192 ${n?.name ?? c.target} (${n?.filePath})`);
+          console.log(`       \u2192  ${n?.name ?? c.target}  (${n?.filePath})`);
         }
+        if (callees.length > 10) console.log(`       \u2026 and ${callees.length - 10} more`);
       }
+      console.log("");
       break;
     }
   }
-  if (!found) console.log(`Symbol "${symbol}" not found.`);
+  if (!found) {
+    console.log(`
+  Symbol "${symbol}" not found.`);
+    console.log(`  Try: code-intel search "${symbol}"
+`);
+  }
 });
-program.command("impact").description("Show blast radius for a symbol").argument("<symbol>", "Symbol name").option("-p, --path <path>", "Path to analyze", ".").option("-d, --depth <depth>", "Max hops", "5").action(async (symbol, options) => {
+program.command("impact").description("Show the blast radius \u2014 all symbols that break if this one changes").argument("<symbol>", "Symbol name to analyse").option("-p, --path <path>", "Path to the repository (default: current directory)", ".").option("-d, --depth <n>", "Maximum traversal depth (hops)", "5").addHelpText("after", `
+  Traverses the call graph upward from the target symbol, collecting every
+  symbol that transitively depends on it via calls or imports.
+
+  \u26A0  If impact shows \u2265 5 direct callers, treat the change as HIGH risk.
+
+  Examples:
+    $ code-intel impact runPipeline
+    $ code-intel impact ApiClient --depth 3
+    $ code-intel impact UserService --path ./backend
+`).action(async (symbol, options) => {
   const { graph } = await analyzeWorkspace(options.path, { silent: true });
   const maxHops = parseInt(options.depth, 10);
   let targetNode = null;
@@ -3212,7 +4434,10 @@ program.command("impact").description("Show blast radius for a symbol").argument
     }
   }
   if (!targetNode) {
-    console.log(`Symbol "${symbol}" not found.`);
+    console.log(`
+  Symbol "${symbol}" not found.`);
+    console.log(`  Try: code-intel search "${symbol}"
+`);
     return;
   }
   const affected = /* @__PURE__ */ new Set();
@@ -3229,123 +4454,213 @@ program.command("impact").description("Show blast radius for a symbol").argument
       }
     }
   }
+  const risk = affected.size > 10 ? "\u26A0  HIGH" : affected.size > 5 ? "\u26A1 MEDIUM" : "\u2713  LOW";
   console.log(`
-Blast radius for "${symbol}": ${affected.size} affected symbols
+  \u25C8  Blast radius for "${symbol}"
+`);
+  console.log(`     Affected symbols : ${affected.size}`);
+  console.log(`     Risk level       : ${risk}
 `);
   for (const id of affected) {
     const n = graph.getNode(id);
-    if (n) console.log(`  ${n.kind.padEnd(12)} ${n.name.padEnd(30)} ${n.filePath}`);
+    if (n) console.log(`  ${n.kind.padEnd(14)} ${n.name.padEnd(32)} ${n.filePath}`);
   }
+  console.log("");
 });
-var groupCmd = program.command("group").description("Manage repository groups (multi-repo / monorepo service tracking)");
-groupCmd.command("create <name>").description("Create a repository group").action((name) => {
+var groupCmd = program.command("group").description("Manage repository groups for multi-repo / monorepo service tracking").addHelpText("after", `
+  Repository groups let you track contracts (exports, routes, schemas, events)
+  across multiple indexed repos and detect cross-repo dependencies automatically.
+
+  Subcommands:
+    create <name>                        Create a new group
+    add <group> <groupPath> <registry>   Add a repo to the group
+    remove <group> <groupPath>           Remove a repo from the group
+    list [name]                          List all groups or inspect one
+    sync <name>                          Extract contracts + detect cross-links
+    contracts <name>                     View extracted contracts and links
+    query <name> <q>                     Search across all repos in the group
+    status <name>                        Check index freshness of group members
+
+  Examples:
+    $ code-intel group create my-platform
+    $ code-intel group add my-platform services/auth auth-service
+    $ code-intel group sync my-platform
+    $ code-intel group contracts my-platform --kind route
+`);
+groupCmd.command("create <name>").description("Create a new repository group").addHelpText("after", `
+  Examples:
+    $ code-intel group create my-platform
+    $ code-intel group create hr-services
+`).action((name) => {
   if (groupExists(name)) {
-    console.error(`Error: Group "${name}" already exists.`);
+    console.error(`
+  \u2717  Group "${name}" already exists.
+`);
     process.exit(1);
   }
   saveGroup({ name, createdAt: (/* @__PURE__ */ new Date()).toISOString(), members: [] });
-  console.log(`\u2705 Group "${name}" created.`);
+  console.log(`
+  \u2705  Group "${name}" created.`);
+  console.log(`      Add repos with: code-intel group add ${name} <groupPath> <registryName>
+`);
 });
-groupCmd.command("add <group> <groupPath> <registryName>").description("Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is from `code-intel list`").action((group, groupPath, registryName) => {
+groupCmd.command("add <group> <groupPath> <registryName>").description("Add an indexed repository to a group at the given hierarchy path").addHelpText("after", `
+  <groupPath>     Dot-separated or slash-separated hierarchy path, e.g. hr/hiring/backend
+  <registryName>  The repo's name as shown by \`code-intel list\`
+
+  Examples:
+    $ code-intel group add my-platform services/auth      auth-service
+    $ code-intel group add my-platform services/payments  payments-api
+    $ code-intel group add my-platform frontend           web-app
+`).action((group, groupPath, registryName) => {
   const registry = loadRegistry();
   const regEntry = registry.find((r) => r.name === registryName);
   if (!regEntry) {
-    console.error(`Error: Registry entry "${registryName}" not found. Run \`code-intel list\` to see available repos.`);
+    console.error(`
+  \u2717  Registry entry "${registryName}" not found.`);
+    console.error(`     Run \`code-intel list\` to see available repos.
+`);
     process.exit(1);
   }
   if (!groupExists(group)) {
-    console.error(`Error: Group "${group}" does not exist. Create it first with \`code-intel group create ${group}\`.`);
+    console.error(`
+  \u2717  Group "${group}" does not exist.`);
+    console.error(`     Create it first: code-intel group create ${group}
+`);
     process.exit(1);
   }
   addMember(group, { groupPath, registryName });
-  console.log(`\u2705 Added "${registryName}" to group "${group}" at path "${groupPath}".`);
+  console.log(`
+  \u2705  Added "${registryName}" \u2192 group "${group}" at path "${groupPath}"
+`);
 });
-groupCmd.command("remove <group> <groupPath>").description("Remove a repo from a group by its hierarchy path").action((group, groupPath) => {
+groupCmd.command("remove <group> <groupPath>").description("Remove a repository from a group by its hierarchy path").addHelpText("after", `
+  Examples:
+    $ code-intel group remove my-platform services/auth
+`).action((group, groupPath) => {
   if (!groupExists(group)) {
-    console.error(`Error: Group "${group}" does not exist.`);
+    console.error(`
+  \u2717  Group "${group}" does not exist.
+`);
     process.exit(1);
   }
   try {
     removeMember(group, groupPath);
-    console.log(`\u2705 Removed member at path "${groupPath}" from group "${group}".`);
+    console.log(`
+  \u2705  Removed "${groupPath}" from group "${group}"
+`);
   } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : err}`);
+    console.error(`
+  \u2717  ${err instanceof Error ? err.message : err}
+`);
     process.exit(1);
   }
 });
-groupCmd.command("list [name]").description("List all groups, or show one group's config").action((name) => {
+groupCmd.command("list [name]").description("List all groups, or show the full config of one group").addHelpText("after", `
+  Examples:
+    $ code-intel group list
+    $ code-intel group list my-platform
+`).action((name) => {
   if (name) {
     const group = loadGroup(name);
     if (!group) {
-      console.error(`Error: Group "${name}" not found.`);
+      console.error(`
+  \u2717  Group "${name}" not found.
+`);
       process.exit(1);
     }
     console.log(`
-Group: ${group.name}`);
-    console.log(`Created: ${group.createdAt}`);
-    if (group.lastSync) console.log(`Last sync: ${group.lastSync}`);
+  \u25C8  Group: ${group.name}`);
+    console.log(`     Created  : ${group.createdAt}`);
+    if (group.lastSync) console.log(`     Last sync: ${group.lastSync}`);
     console.log(`
-Members (${group.members.length}):`);
+     Members (${group.members.length}):`);
     if (group.members.length === 0) {
-      console.log("  (none \u2014 use `code-intel group add` to add repos)");
+      console.log("       (none \u2014 use `code-intel group add` to add repos)");
     } else {
       for (const m of group.members) {
-        console.log(`  ${m.groupPath.padEnd(35)} \u2192 ${m.registryName}`);
+        console.log(`       ${m.groupPath.padEnd(35)} \u2192  ${m.registryName}`);
       }
     }
+    console.log("");
   } else {
     const groups = listGroups();
     if (groups.length === 0) {
-      console.log("No groups found. Create one with `code-intel group create <name>`.");
+      console.log("\n  No groups found.");
+      console.log("  Create one with: code-intel group create <name>\n");
       return;
     }
     console.log(`
-Repository groups (${groups.length}):
+  Repository groups (${groups.length}):
 `);
     for (const g of groups) {
-      const sync = g.lastSync ? `synced ${g.lastSync}` : "not synced";
-      console.log(`  ${g.name.padEnd(25)} ${g.members.length} member(s)  [${sync}]`);
+      const sync = g.lastSync ? `synced ${g.lastSync}` : "never synced";
+      console.log(`  \u25C6  ${g.name.padEnd(25)} ${g.members.length} member(s)  [${sync}]`);
     }
+    console.log("");
   }
 });
-groupCmd.command("sync <name>").description("Extract contracts and match across repos/services in a group").action(async (name) => {
+groupCmd.command("sync <name>").description("Extract contracts and detect cross-repo dependencies in a group").addHelpText("after", `
+  Scans every member repo's knowledge graph for exported symbols, routes,
+  schemas, and events, then cross-matches names across repos to find
+  likely provider \u2192 consumer relationships.
+
+  Examples:
+    $ code-intel group sync my-platform
+`).action(async (name) => {
   const group = loadGroup(name);
   if (!group) {
-    console.error(`Error: Group "${name}" not found.`);
+    console.error(`
+  \u2717  Group "${name}" not found.
+`);
     process.exit(1);
   }
   if (group.members.length === 0) {
-    console.error(`Error: Group "${name}" has no members. Add repos with \`code-intel group add\`.`);
+    console.error(`
+  \u2717  Group "${name}" has no members.`);
+    console.error(`     Add repos with \`code-intel group add\`.
+`);
     process.exit(1);
   }
   console.log(`
-\u{1F504} Syncing group "${name}" (${group.members.length} member(s))\u2026
+  \u27F3  Syncing group "${name}" (${group.members.length} member(s))\u2026
 `);
   const result = await syncGroup(group);
   saveSyncResult(result);
   group.lastSync = result.syncedAt;
   saveGroup(group);
-  console.log(`
-\u2705 Sync complete:`);
-  console.log(`   Repos synced:  ${result.memberCount}`);
-  console.log(`   Contracts:     ${result.contracts.length}`);
-  console.log(`   Cross-links:   ${result.links.length}`);
+  console.log(`  \u2705  Sync complete
+`);
+  console.log(`     Repos synced  : ${result.memberCount}`);
+  console.log(`     Contracts     : ${result.contracts.length}`);
+  console.log(`     Cross-links   : ${result.links.length}`);
   if (result.links.length > 0) {
     console.log(`
-Top cross-repo links:`);
+  Top cross-repo links:
+`);
     for (const link of result.links.slice(0, 10)) {
       const conf = (link.confidence * 100).toFixed(0).padStart(3);
       console.log(`  ${conf}%  ${link.providerRepo} \u2237 ${link.providerContract.padEnd(30)} \u2194  ${link.consumerRepo} \u2237 ${link.consumerContract}`);
     }
     if (result.links.length > 10) {
-      console.log(`  \u2026 and ${result.links.length - 10} more. Run \`code-intel group contracts ${name}\` for full details.`);
+      console.log(`
+  \u2026 and ${result.links.length - 10} more. Run \`code-intel group contracts ${name}\` for full details.`);
     }
   }
+  console.log("");
 });
-groupCmd.command("contracts <name>").description("Inspect extracted contracts and cross-links from the last sync").option("--kind <kind>", "Filter by contract kind: export | route | schema | event").option("--repo <repo>", "Filter by registry name").option("--min-confidence <pct>", "Minimum link confidence 0-100 (default: 0)", "0").action((name, opts) => {
+groupCmd.command("contracts <name>").description("Inspect extracted contracts and cross-links from the last sync").option("--kind <kind>", "Filter by contract kind: export | route | schema | event").option("--repo <repo>", "Filter by registry name").option("--min-confidence <pct>", "Minimum link confidence 0\u2013100 (default: 0)", "0").addHelpText("after", `
+  Examples:
+    $ code-intel group contracts my-platform
+    $ code-intel group contracts my-platform --kind route
+    $ code-intel group contracts my-platform --repo auth-service --min-confidence 70
+`).action((name, opts) => {
   const result = loadSyncResult(name);
   if (!result) {
-    console.error(`No sync data for group "${name}". Run \`code-intel group sync ${name}\` first.`);
+    console.error(`
+  \u2717  No sync data for group "${name}".`);
+    console.error(`     Run: code-intel group sync ${name}
+`);
     process.exit(1);
   }
   const minConf = parseInt(opts.minConfidence, 10) / 100;
@@ -3355,15 +4670,17 @@ groupCmd.command("contracts <name>").description("Inspect extracted contracts an
   let links = result.links.filter((l) => l.confidence >= minConf);
   if (opts.repo) links = links.filter((l) => l.providerRepo === opts.repo || l.consumerRepo === opts.repo);
   console.log(`
-\u{1F4E6} Group "${name}" \u2014 synced ${result.syncedAt}
+  \u25C8  Group "${name}"  \u2014  synced ${result.syncedAt}
+`);
+  console.log(`  Contracts (${contracts.length}):
 `);
-  console.log(`Contracts (${contracts.length}):`);
   for (const c of contracts) {
-    const sig = c.signature ? `  ${c.signature.slice(0, 60)}` : "";
-    console.log(`  [${c.kind.padEnd(6)}] ${c.repoName.padEnd(20)} ${c.name.padEnd(35)}${sig}`);
+    const sig = c.signature ? `  ${c.signature.slice(0, 55)}` : "";
+    console.log(`  [${c.kind.padEnd(6)}]  ${c.repoName.padEnd(22)} ${c.name.padEnd(35)}${sig}`);
   }
   console.log(`
-Cross-repo links (${links.length}):`);
+  Cross-repo links (${links.length}):
+`);
   if (links.length === 0) {
     console.log("  (none)");
   } else {
@@ -3372,72 +4689,92 @@ Cross-repo links (${links.length}):`);
       console.log(`  ${conf}%  [${link.matchKind}]  ${link.providerRepo} \u2237 ${link.providerContract.padEnd(30)} \u2194  ${link.consumerRepo} \u2237 ${link.consumerContract}`);
     }
   }
+  console.log("");
 });
-groupCmd.command("query <name> <q>").description("Search execution flows across all repos in a group").option("-l, --limit <limit>", "Max results per repo", "10").action(async (name, q, opts) => {
+groupCmd.command("query <name> <q>").description("Search execution flows across all repos in a group").option("-l, --limit <n>", "Max results per repo", "10").addHelpText("after", `
+  Uses BM25 search within each member repo's graph, then merges the results
+  using Reciprocal Rank Fusion (RRF) for a unified ranked list.
+
+  Examples:
+    $ code-intel group query my-platform "handlePayment"
+    $ code-intel group query my-platform "UserAuth" --limit 5
+`).action(async (name, q, opts) => {
   const group = loadGroup(name);
   if (!group) {
-    console.error(`Error: Group "${name}" not found.`);
+    console.error(`
+  \u2717  Group "${name}" not found.
+`);
     process.exit(1);
   }
   console.log(`
-\u{1F50D} Querying group "${name}" for: "${q}"
+  \u25C8  Querying group "${name}" for: "${q}"
 `);
   const limit = parseInt(opts.limit, 10);
   const { perRepo, merged } = await queryGroup(group, q, limit);
   if (merged.length === 0) {
-    console.log("No results found across any repo in this group.");
+    console.log("  No results found across any repo in this group.\n");
     return;
   }
-  console.log(`Merged results (${merged.length} total, ranked by Reciprocal Rank Fusion):
+  console.log(`  Merged results (${merged.length}, ranked by RRF):
 `);
   for (const r of merged) {
-    console.log(`  ${r.kind.padEnd(12)} ${r.name.padEnd(30)} ${r.filePath}`);
-    if (r.snippet) console.log(`             ${r.snippet.slice(0, 100)}`);
+    console.log(`  ${r.kind.padEnd(14)} ${r.name.padEnd(32)} ${r.filePath}`);
+    if (r.snippet) console.log(`                 ${r.snippet.slice(0, 95)}`);
   }
   console.log(`
-Per-repo breakdown:`);
+  Per-repo breakdown:
+`);
   for (const rr of perRepo) {
-    console.log(`  ${rr.repoName} (${rr.groupPath}): ${rr.results.length} result(s)`);
+    console.log(`    ${rr.repoName.padEnd(25)} (${rr.groupPath})  \u2192  ${rr.results.length} result(s)`);
   }
+  console.log("");
 });
-groupCmd.command("status <name>").description("Check staleness of repos in a group").action((name) => {
+groupCmd.command("status <name>").description("Check index freshness and sync status of all repos in a group").addHelpText("after", `
+  Examples:
+    $ code-intel group status my-platform
+`).action((name) => {
   const group = loadGroup(name);
   if (!group) {
-    console.error(`Error: Group "${name}" not found.`);
+    console.error(`
+  \u2717  Group "${name}" not found.
+`);
     process.exit(1);
   }
   const registry = loadRegistry();
   const now = Date.now();
   console.log(`
-\u{1F4CA} Group "${name}" status
+  \u25C8  Group "${name}" \u2014 status
 `);
   if (group.lastSync) {
     const age = Math.round((now - new Date(group.lastSync).getTime()) / 6e4);
-    console.log(`Last sync: ${group.lastSync} (${age} min ago)`);
+    console.log(`     Last sync : ${group.lastSync} (${age} min ago)`);
   } else {
-    console.log("Last sync: never  (run `code-intel group sync " + name + "`)");
+    console.log(`     Last sync : never  \u2192  run \`code-intel group sync ${name}\``);
   }
   console.log(`
-Members (${group.members.length}):
+     Members (${group.members.length}):
 `);
   for (const m of group.members) {
     const regEntry = registry.find((r) => r.name === m.registryName);
     if (!regEntry) {
-      console.log(`  \u2717 ${m.groupPath.padEnd(35)} [${m.registryName}]  \u2014 NOT IN REGISTRY`);
+      console.log(`  \u2717  ${m.groupPath.padEnd(35)} [${m.registryName}]  \u2014 NOT IN REGISTRY`);
       continue;
     }
-    const metaPath = path.join(regEntry.path, ".code-intel", "meta.json");
-    let indexedAt = regEntry.indexedAt;
+    const metaPath = path16.join(regEntry.path, ".code-intel", "meta.json");
     try {
-      const meta = JSON.parse(fs8.readFileSync(metaPath, "utf-8"));
-      indexedAt = meta.indexedAt;
+      const meta = JSON.parse(fs14.readFileSync(metaPath, "utf-8"));
+      const indexedAt = meta.indexedAt;
       const ageMin = Math.round((now - new Date(indexedAt).getTime()) / 6e4);
-      const stale = ageMin > 1440 ? " \u26A0 STALE (>24h)" : "";
-      console.log(`  \u2713 ${m.groupPath.padEnd(35)} [${m.registryName}]  indexed ${indexedAt} (${ageMin} min ago)${stale}`);
-      console.log(`    ${regEntry.path}`);
-      console.log(`    ${meta.stats.nodes} nodes, ${meta.stats.edges} edges, ${meta.stats.files} files`);
+      const stale = ageMin > 1440 ? "  \u26A0  STALE (>24h)" : "";
+      console.log(`  \u2713  ${m.groupPath.padEnd(35)} [${m.registryName}]${stale}`);
+      console.log(`       indexed ${indexedAt} (${ageMin} min ago)`);
+      console.log(`       ${meta.stats.nodes} nodes \xB7 ${meta.stats.edges} edges \xB7 ${meta.stats.files} files`);
+      console.log(`       ${regEntry.path}
+`);
     } catch {
-      console.log(`  \u2717 ${m.groupPath.padEnd(35)} [${m.registryName}]  \u2014 NOT INDEXED  (run: code-intel analyze ${regEntry.path})`);
+      console.log(`  \u2717  ${m.groupPath.padEnd(35)} [${m.registryName}]  \u2014 NOT INDEXED`);
+      console.log(`       run: code-intel analyze ${regEntry.path}
+`);
     }
   }
 });