@liendev/lien 0.14.0 → 0.16.0

package/dist/index.js

@@ -161,7 +161,7 @@ function migrateConfig(oldConfig) {
       path: ".",
       enabled: true,
       config: {
-        include: oldConfig.indexing.include ?? ["**/*.{ts,tsx,js,jsx,py,go,rs,java,c,cpp,cs}"],
+        include: oldConfig.indexing.include ?? ["**/*.{ts,tsx,js,jsx,py,php,go,rs,java,c,cpp,cs}"],
         exclude: oldConfig.indexing.exclude ?? [
           "**/node_modules/**",
           "**/dist/**",
@@ -181,7 +181,7 @@ function migrateConfig(oldConfig) {
       path: ".",
       enabled: true,
       config: {
-        include: ["**/*.{ts,tsx,js,jsx,py,go,rs,java,c,cpp,cs}"],
+        include: ["**/*.{ts,tsx,js,jsx,py,php,go,rs,java,c,cpp,cs}"],
         exclude: [
           "**/node_modules/**",
           "**/dist/**",
@@ -1030,7 +1030,7 @@ async function scanCodebase(options) {
     ".lien/**",
     ...excludePatterns
   ]);
-  const patterns = includePatterns.length > 0 ? includePatterns : ["**/*.{ts,tsx,js,jsx,py,go,rs,java,cpp,c,h,md,mdx}"];
+  const patterns = includePatterns.length > 0 ? includePatterns : ["**/*.{ts,tsx,js,jsx,py,php,go,rs,java,cpp,c,cs,h,md,mdx}"];
   const allFiles = [];
   for (const pattern of patterns) {
     const files = await glob(pattern, {
@@ -1388,6 +1388,7 @@ import Parser from "tree-sitter";
 import TypeScript from "tree-sitter-typescript";
 import JavaScript from "tree-sitter-javascript";
 import PHPParser from "tree-sitter-php";
+import Python from "tree-sitter-python";
 import { extname } from "path";
 function getParser(language) {
   if (!parserCache.has(language)) {
@@ -1414,6 +1415,8 @@ function detectLanguage2(filePath) {
       return "javascript";
     case "php":
       return "php";
+    case "py":
+      return "python";
     default:
       return null;
   }
@@ -1447,8 +1450,9 @@ var init_parser = __esm({
     languageConfig = {
       typescript: TypeScript.typescript,
       javascript: JavaScript,
-      php: PHPParser.php
+      php: PHPParser.php,
       // Note: tree-sitter-php exports both 'php' (mixed HTML/PHP) and 'php_only'
+      python: Python
     };
   }
 });
@@ -1524,7 +1528,35 @@ function extractInterfaceInfo(node, _content, _parentClass) {
     signature: `interface ${nameNode.text}`
   };
 }
-function extractSymbolInfo(node, content, parentClass) {
+function extractPythonFunctionInfo(node, content, parentClass) {
+  const nameNode = node.childForFieldName("name");
+  if (!nameNode) return null;
+  return {
+    name: nameNode.text,
+    type: parentClass ? "method" : "function",
+    startLine: node.startPosition.row + 1,
+    endLine: node.endPosition.row + 1,
+    parentClass,
+    signature: extractSignature(node, content),
+    parameters: extractParameters(node, content),
+    complexity: calculateComplexity(node)
+  };
+}
+function extractPythonClassInfo(node, _content, _parentClass) {
+  const nameNode = node.childForFieldName("name");
+  if (!nameNode) return null;
+  return {
+    name: nameNode.text,
+    type: "class",
+    startLine: node.startPosition.row + 1,
+    endLine: node.endPosition.row + 1,
+    signature: `class ${nameNode.text}`
+  };
+}
+function extractSymbolInfo(node, content, parentClass, language) {
+  if (node.type === "function_definition" && language === "python") {
+    return extractPythonFunctionInfo(node, content, parentClass);
+  }
   const extractor = symbolExtractors[node.type];
   return extractor ? extractor(node, content, parentClass) : null;
 }
@@ -1563,23 +1595,39 @@ function extractReturnType(node, _content) {
 function calculateComplexity(node) {
   let complexity = 1;
   const decisionPoints = [
-    // TypeScript/JavaScript
+    // Common across languages (TypeScript/JavaScript/Python/PHP)
     "if_statement",
+    // if conditions
     "while_statement",
-    "do_statement",
-    // do...while loops
+    // while loops
     "for_statement",
-    "for_in_statement",
-    "for_of_statement",
-    // for...of loops
+    // for loops
     "switch_case",
+    // switch/case statements
     "catch_clause",
+    // try/catch error handling
     "ternary_expression",
+    // Ternary operator (a ? b : c)
     "binary_expression",
-    // For && and ||
-    // PHP
-    "foreach_statement"
+    // For && and || logical operators
+    // TypeScript/JavaScript specific
+    "do_statement",
+    // do...while loops
+    "for_in_statement",
+    // for...in loops
+    "for_of_statement",
+    // for...of loops
+    // PHP specific
+    "foreach_statement",
     // PHP foreach loops
+    // Python specific
+    "elif_clause",
+    // Python elif (adds decision point)
+    // Note: 'else_clause' is NOT a decision point (it's the default path)
+    "except_clause",
+    // Python except (try/except)
+    "conditional_expression"
+    // Python ternary (x if cond else y)
   ];
   function traverse(n) {
     if (decisionPoints.includes(n.type)) {
@@ -1608,7 +1656,13 @@ function extractImports(rootNode) {
       if (sourceNode) {
         const importPath = sourceNode.text.replace(/['"]/g, "");
         imports.push(importPath);
+      } else {
+        const importText = node.text.split("\n")[0];
+        imports.push(importText);
       }
+    } else if (node.type === "import_from_statement") {
+      const importText = node.text.split("\n")[0];
+      imports.push(importText);
     }
     if (node === rootNode) {
       for (let i = 0; i < node.namedChildCount; i++) {
@@ -1635,9 +1689,16 @@ var init_symbols = __esm({
       "interface_declaration": extractInterfaceInfo,
       // PHP
       "function_definition": extractFunctionInfo,
-      // PHP functions
-      "method_declaration": extractMethodInfo
+      // PHP functions (Python handled via language check in extractSymbolInfo)
+      "method_declaration": extractMethodInfo,
       // PHP methods
+      // Python
+      "async_function_definition": extractPythonFunctionInfo,
+      // Python async functions
+      "class_definition": extractPythonClassInfo
+      // Python classes
+      // Note: Python regular functions use 'function_definition' (same as PHP)
+      // They are dispatched to extractPythonFunctionInfo via language check in extractSymbolInfo()
     };
   }
 });
@@ -1795,6 +1856,69 @@ var init_php = __esm({
   }
 });
 
+// src/indexer/ast/traversers/python.ts
+var PythonTraverser;
+var init_python = __esm({
+  "src/indexer/ast/traversers/python.ts"() {
+    "use strict";
+    PythonTraverser = class {
+      targetNodeTypes = [
+        "function_definition",
+        "async_function_definition"
+      ];
+      containerTypes = [
+        "class_definition"
+        // We extract methods, not the class itself
+      ];
+      declarationTypes = [
+        // Python doesn't have const/let/var declarations like JS/TS
+        // Functions are always defined with 'def' or 'async def'
+      ];
+      functionTypes = [
+        "function_definition",
+        "async_function_definition"
+      ];
+      shouldExtractChildren(node) {
+        return this.containerTypes.includes(node.type);
+      }
+      isDeclarationWithFunction(_node) {
+        return false;
+      }
+      getContainerBody(node) {
+        if (node.type === "class_definition") {
+          return node.childForFieldName("body");
+        }
+        return null;
+      }
+      shouldTraverseChildren(node) {
+        return node.type === "module" || // Top-level Python file
+        node.type === "block";
+      }
+      findParentContainerName(node) {
+        let current = node.parent;
+        while (current) {
+          if (current.type === "class_definition") {
+            const nameNode = current.childForFieldName("name");
+            return nameNode?.text;
+          }
+          current = current.parent;
+        }
+        return void 0;
+      }
+      /**
+       * Python doesn't have this pattern (const x = () => {})
+       * Functions are always defined with 'def' or 'async def'
+       */
+      findFunctionInDeclaration(_node) {
+        return {
+          hasFunction: false,
+          functionNode: null
+        };
+      }
+    };
+  }
+});
+
 // src/indexer/ast/traversers/index.ts
 function getTraverser(language) {
   const traverser = traverserRegistry[language];
@@ -1809,10 +1933,12 @@ var init_traversers = __esm({
     "use strict";
     init_typescript();
     init_php();
+    init_python();
     traverserRegistry = {
       typescript: new TypeScriptTraverser(),
       javascript: new JavaScriptTraverser(),
-      php: new PHPTraverser()
+      php: new PHPTraverser(),
+      python: new PythonTraverser()
     };
   }
 });
@@ -1843,7 +1969,7 @@ function chunkByAST(filepath, content, options = {}) {
       }
     }
     const parentClassName = traverser.findParentContainerName(actualNode);
-    const symbolInfo = extractSymbolInfo(actualNode, content, parentClassName);
+    const symbolInfo = extractSymbolInfo(actualNode, content, parentClassName, language);
     const nodeContent = getNodeContent(node, lines);
     chunks.push(createChunk(filepath, node, nodeContent, symbolInfo, fileImports, language));
   }
@@ -2398,26 +2524,73 @@ var init_relevance = __esm({
 });
 
 // src/vectordb/intent-classifier.ts
+function getSortedRules() {
+  if (cachedSortedRules === null) {
+    cachedSortedRules = [...INTENT_RULES].sort((a, b) => b.priority - a.priority);
+  }
+  return cachedSortedRules;
+}
 function classifyQueryIntent(query) {
   const lower = query.toLowerCase().trim();
-  if (lower.match(/where\s+(is|are|does|can\s+i\s+find)/) || lower.match(/find\s+the\s+/) || lower.match(/locate\s+/)) {
-    return "location" /* LOCATION */;
-  }
-  if (lower.match(/how\s+does\s+.*\s+work/) || lower.match(/what\s+(is|are|does)/) || lower.match(/explain\s+/) || lower.match(/understand\s+/) || lower.match(/\b(process|workflow|architecture)\b/)) {
-    return "conceptual" /* CONCEPTUAL */;
-  }
-  if (lower.match(/how\s+(is|are)\s+.*\s+(implemented|built|coded)/) || lower.match(/implementation\s+of/) || lower.match(/source\s+code\s+for/)) {
-    return "implementation" /* IMPLEMENTATION */;
+  const sortedRules = getSortedRules();
+  for (const rule of sortedRules) {
+    if (rule.patterns.some((pattern) => pattern.test(lower))) {
+      return rule.intent;
+    }
   }
   return "implementation" /* IMPLEMENTATION */;
 }
+var INTENT_RULES, INITIAL_RULE_COUNT, cachedSortedRules;
 var init_intent_classifier = __esm({
   "src/vectordb/intent-classifier.ts"() {
     "use strict";
+    INTENT_RULES = [
+      // LOCATION intent (highest priority - most specific)
+      {
+        intent: "location" /* LOCATION */,
+        priority: 3,
+        patterns: [
+          /where\s+(is|are|does|can\s+i\s+find)/,
+          /find\s+the\s+/,
+          /locate\s+/
+        ]
+      },
+      // CONCEPTUAL intent (medium priority)
+      {
+        intent: "conceptual" /* CONCEPTUAL */,
+        priority: 2,
+        patterns: [
+          /how\s+does\s+.*\s+work/,
+          /what\s+(is|are|does)/,
+          /explain\s+/,
+          /understand\s+/,
+          /\b(process|workflow|architecture)\b/
+        ]
+      },
+      // IMPLEMENTATION intent (low priority - catches "how is X implemented")
+      {
+        intent: "implementation" /* IMPLEMENTATION */,
+        priority: 1,
+        patterns: [
+          /how\s+(is|are)\s+.*\s+(implemented|built|coded)/,
+          /implementation\s+of/,
+          /source\s+code\s+for/
+        ]
+      }
+    ];
+    INITIAL_RULE_COUNT = INTENT_RULES.length;
+    cachedSortedRules = null;
   }
 });
 
-// src/vectordb/query.ts
+// src/vectordb/boosting/types.ts
+var init_types2 = __esm({
+  "src/vectordb/boosting/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/vectordb/boosting/strategies.ts
 import path13 from "path";
 function isDocumentationFile(filepath) {
   const lower = filepath.toLowerCase();
@@ -2455,106 +2628,162 @@ function isUtilityFile(filepath) {
   }
   return false;
 }
-function boostPathRelevance(query, filepath, baseScore) {
-  const queryTokens = query.toLowerCase().split(/\s+/);
-  const pathSegments = filepath.toLowerCase().split("/");
-  let boostFactor = 1;
-  for (const token of queryTokens) {
-    if (token.length <= 2) continue;
-    if (pathSegments.some((seg) => seg.includes(token))) {
-      boostFactor *= 0.9;
-    }
-  }
-  return baseScore * boostFactor;
-}
-function boostFilenameRelevance(query, filepath, baseScore) {
-  const filename = path13.basename(filepath, path13.extname(filepath)).toLowerCase();
-  const queryTokens = query.toLowerCase().split(/\s+/);
-  let boostFactor = 1;
-  for (const token of queryTokens) {
-    if (token.length <= 2) continue;
-    if (filename === token) {
-      boostFactor *= 0.7;
-    } else if (filename.includes(token)) {
-      boostFactor *= 0.8;
-    }
-  }
-  return baseScore * boostFactor;
-}
-function boostForLocationIntent(query, filepath, baseScore) {
-  let score = baseScore;
-  const filename = path13.basename(filepath, path13.extname(filepath)).toLowerCase();
-  const queryTokens = query.toLowerCase().split(/\s+/);
-  for (const token of queryTokens) {
-    if (token.length <= 2) continue;
-    if (filename === token) {
-      score *= 0.6;
-    } else if (filename.includes(token)) {
-      score *= 0.7;
-    }
-  }
-  score = boostPathRelevance(query, filepath, score);
-  if (isTestFile(filepath)) {
-    score *= 1.1;
-  }
-  return score;
-}
-function boostForConceptualIntent(query, filepath, baseScore) {
-  let score = baseScore;
-  if (isDocumentationFile(filepath)) {
-    score *= 0.65;
-    const lower = filepath.toLowerCase();
-    if (lower.includes("architecture") || lower.includes("workflow") || lower.includes("flow")) {
-      score *= 0.9;
-    }
-  }
-  if (isUtilityFile(filepath)) {
-    score *= 1.05;
-  }
-  const filename = path13.basename(filepath, path13.extname(filepath)).toLowerCase();
-  const queryTokens = query.toLowerCase().split(/\s+/);
-  for (const token of queryTokens) {
-    if (token.length <= 2) continue;
-    if (filename.includes(token)) {
-      score *= 0.9;
-    }
+var PathBoostingStrategy, FilenameBoostingStrategy, FileTypeBoostingStrategy;
+var init_strategies = __esm({
+  "src/vectordb/boosting/strategies.ts"() {
+    "use strict";
+    init_intent_classifier();
+    PathBoostingStrategy = class {
+      name = "path-matching";
+      apply(query, filepath, baseScore) {
+        const queryTokens = query.toLowerCase().split(/\s+/);
+        const pathSegments = filepath.toLowerCase().split("/");
+        let boostFactor = 1;
+        for (const token of queryTokens) {
+          if (token.length <= 2) continue;
+          if (pathSegments.some((seg) => seg.includes(token))) {
+            boostFactor *= 0.9;
+          }
+        }
+        return baseScore * boostFactor;
+      }
+    };
+    FilenameBoostingStrategy = class {
+      name = "filename-matching";
+      apply(query, filepath, baseScore) {
+        const filename = path13.basename(filepath, path13.extname(filepath)).toLowerCase();
+        const queryTokens = query.toLowerCase().split(/\s+/);
+        let boostFactor = 1;
+        for (const token of queryTokens) {
+          if (token.length <= 2) continue;
+          if (filename === token) {
+            boostFactor *= 0.7;
+          } else if (filename.includes(token)) {
+            boostFactor *= 0.8;
+          }
+        }
+        return baseScore * boostFactor;
+      }
+    };
+    FileTypeBoostingStrategy = class {
+      constructor(intent) {
+        this.intent = intent;
+      }
+      name = "file-type";
+      apply(query, filepath, baseScore) {
+        switch (this.intent) {
+          case "location" /* LOCATION */:
+            return this.applyLocationBoosting(query, filepath, baseScore);
+          case "conceptual" /* CONCEPTUAL */:
+            return this.applyConceptualBoosting(query, filepath, baseScore);
+          case "implementation" /* IMPLEMENTATION */:
+            return this.applyImplementationBoosting(query, filepath, baseScore);
+          default:
+            return baseScore;
+        }
+      }
+      applyLocationBoosting(_query, filepath, score) {
+        if (isTestFile(filepath)) {
+          score *= 1.1;
+        }
+        return score;
+      }
+      applyConceptualBoosting(_query, filepath, score) {
+        if (isDocumentationFile(filepath)) {
+          score *= 0.65;
+          const lower = filepath.toLowerCase();
+          if (lower.includes("architecture") || lower.includes("workflow") || lower.includes("flow")) {
+            score *= 0.9;
+          }
+        }
+        if (isUtilityFile(filepath)) {
+          score *= 0.95;
+        }
+        return score;
+      }
+      applyImplementationBoosting(_query, filepath, score) {
+        if (isTestFile(filepath)) {
+          score *= 1.1;
+        }
+        return score;
+      }
+    };
   }
-  const pathSegments = filepath.toLowerCase().split(path13.sep);
-  for (const token of queryTokens) {
-    if (token.length <= 2) continue;
-    for (const segment of pathSegments) {
-      if (segment.includes(token)) {
-        score *= 0.95;
-        break;
+});
+
+// src/vectordb/boosting/composer.ts
+var BoostingComposer;
+var init_composer = __esm({
+  "src/vectordb/boosting/composer.ts"() {
+    "use strict";
+    BoostingComposer = class {
+      strategies = [];
+      /**
+       * Add a boosting strategy to the pipeline.
+       * Strategies are applied in the order they are added.
+       * 
+       * @param strategy - The strategy to add
+       * @returns This composer for chaining
+       */
+      addStrategy(strategy) {
+        this.strategies.push(strategy);
+        return this;
       }
-    }
+      /**
+       * Apply all strategies to a base score.
+       * 
+       * @param query - The search query
+       * @param filepath - The file path being scored
+       * @param baseScore - The initial score from vector similarity
+       * @returns The final boosted score after all strategies
+       */
+      apply(query, filepath, baseScore) {
+        let score = baseScore;
+        for (const strategy of this.strategies) {
+          score = strategy.apply(query, filepath, score);
+        }
+        return score;
+      }
+      /**
+       * Get the names of all strategies in this composer.
+       * Useful for debugging and logging.
+       */
+      getStrategyNames() {
+        return this.strategies.map((s) => s.name);
+      }
+      /**
+       * Get the number of strategies in this composer.
+       */
+      getStrategyCount() {
+        return this.strategies.length;
+      }
+      /**
+       * Clear all strategies from this composer.
+       */
+      clear() {
+        this.strategies = [];
+      }
+    };
   }
-  return score;
-}
-function boostForImplementationIntent(query, filepath, baseScore) {
-  let score = baseScore;
-  score = boostFilenameRelevance(query, filepath, score);
-  score = boostPathRelevance(query, filepath, score);
-  if (isTestFile(filepath)) {
-    score *= 0.9;
+});
+
+// src/vectordb/boosting/index.ts
+var init_boosting = __esm({
+  "src/vectordb/boosting/index.ts"() {
+    "use strict";
+    init_types2();
+    init_strategies();
+    init_composer();
   }
-  return score;
-}
+});
+
+// src/vectordb/query.ts
 function applyRelevanceBoosting(query, filepath, baseScore) {
   if (!query) {
     return baseScore;
   }
   const intent = classifyQueryIntent(query);
-  switch (intent) {
-    case "location" /* LOCATION */:
-      return boostForLocationIntent(query, filepath, baseScore);
-    case "conceptual" /* CONCEPTUAL */:
-      return boostForConceptualIntent(query, filepath, baseScore);
-    case "implementation" /* IMPLEMENTATION */:
-      return boostForImplementationIntent(query, filepath, baseScore);
-    default:
-      return boostForImplementationIntent(query, filepath, baseScore);
-  }
+  return BOOSTING_COMPOSERS[intent].apply(query, filepath, baseScore);
 }
 function dbRecordToSearchResult(r, query) {
   const baseScore = r._distance ?? 0;
@@ -2736,6 +2965,7 @@ async function querySymbols(table, options) {
     throw wrapError(error, "Failed to query symbols");
   }
 }
+var PATH_STRATEGY, FILENAME_STRATEGY, FILE_TYPE_STRATEGIES, BOOSTING_COMPOSERS;
 var init_query = __esm({
   "src/vectordb/query.ts"() {
     "use strict";
@@ -2743,6 +2973,19 @@ var init_query = __esm({
     init_errors();
     init_relevance();
     init_intent_classifier();
+    init_boosting();
+    PATH_STRATEGY = new PathBoostingStrategy();
+    FILENAME_STRATEGY = new FilenameBoostingStrategy();
+    FILE_TYPE_STRATEGIES = {
+      ["location" /* LOCATION */]: new FileTypeBoostingStrategy("location" /* LOCATION */),
+      ["conceptual" /* CONCEPTUAL */]: new FileTypeBoostingStrategy("conceptual" /* CONCEPTUAL */),
+      ["implementation" /* IMPLEMENTATION */]: new FileTypeBoostingStrategy("implementation" /* IMPLEMENTATION */)
+    };
+    BOOSTING_COMPOSERS = {
+      ["location" /* LOCATION */]: new BoostingComposer().addStrategy(PATH_STRATEGY).addStrategy(FILENAME_STRATEGY).addStrategy(FILE_TYPE_STRATEGIES["location" /* LOCATION */]),
+      ["conceptual" /* CONCEPTUAL */]: new BoostingComposer().addStrategy(PATH_STRATEGY).addStrategy(FILENAME_STRATEGY).addStrategy(FILE_TYPE_STRATEGIES["conceptual" /* CONCEPTUAL */]),
+      ["implementation" /* IMPLEMENTATION */]: new BoostingComposer().addStrategy(PATH_STRATEGY).addStrategy(FILENAME_STRATEGY).addStrategy(FILE_TYPE_STRATEGIES["implementation" /* IMPLEMENTATION */])
+    };
   }
 });
 
@@ -3667,6 +3910,22 @@ var init_change_detector = __esm({
   }
 });
 
+// src/utils/result.ts
+function Ok(value) {
+  return { ok: true, value };
+}
+function Err(error) {
+  return { ok: false, error };
+}
+function isOk(result) {
+  return result.ok;
+}
+var init_result = __esm({
+  "src/utils/result.ts"() {
+    "use strict";
+  }
+});
+
 // src/indexer/incremental.ts
 import fs16 from "fs/promises";
 async function processFileContent(filepath, content, embeddings, config, verbose) {
@@ -3748,36 +4007,29 @@ async function indexSingleFile(filepath, vectorDB, embeddings, config, options =
     console.error(`[Lien] \u26A0\uFE0F  Failed to index ${filepath}: ${error}`);
   }
 }
+async function processSingleFileForIndexing(filepath, embeddings, config, verbose) {
+  try {
+    const stats = await fs16.stat(filepath);
+    const content = await fs16.readFile(filepath, "utf-8");
+    const result = await processFileContent(filepath, content, embeddings, config, verbose);
+    return Ok({
+      filepath,
+      result,
+      mtime: stats.mtimeMs
+    });
+  } catch (error) {
+    return Err(`Failed to process ${filepath}: ${error}`);
+  }
+}
 async function indexMultipleFiles(filepaths, vectorDB, embeddings, config, options = {}) {
   const { verbose } = options;
   let processedCount = 0;
   const manifestEntries = [];
   for (const filepath of filepaths) {
-    let content;
-    let fileMtime;
-    try {
-      const stats = await fs16.stat(filepath);
-      fileMtime = stats.mtimeMs;
-      content = await fs16.readFile(filepath, "utf-8");
-    } catch (error) {
-      if (verbose) {
-        console.error(`[Lien] File not readable: ${filepath}`);
-      }
-      try {
-        await vectorDB.deleteByFile(filepath);
-        const manifest = new ManifestManager(vectorDB.dbPath);
-        await manifest.removeFile(filepath);
-      } catch (error2) {
-        if (verbose) {
-          console.error(`[Lien] Note: ${filepath} not in index`);
-        }
-      }
-      processedCount++;
-      continue;
-    }
-    try {
-      const result = await processFileContent(filepath, content, embeddings, config, verbose || false);
-      if (result === null) {
+    const result = await processSingleFileForIndexing(filepath, embeddings, config, verbose || false);
+    if (isOk(result)) {
+      const { result: processResult, mtime } = result.value;
+      if (processResult === null) {
         try {
           await vectorDB.deleteByFile(filepath);
         } catch (error) {
@@ -3785,7 +4037,7 @@ async function indexMultipleFiles(filepaths, vectorDB, embeddings, config, optio
         const manifest = new ManifestManager(vectorDB.dbPath);
         await manifest.updateFile(filepath, {
           filepath,
-          lastModified: fileMtime,
+          lastModified: mtime,
           chunkCount: 0
         });
         processedCount++;
@@ -3796,21 +4048,33 @@ async function indexMultipleFiles(filepaths, vectorDB, embeddings, config, optio
       } catch (error) {
       }
       await vectorDB.insertBatch(
-        result.vectors,
-        result.chunks.map((c) => c.metadata),
-        result.texts
+        processResult.vectors,
+        processResult.chunks.map((c) => c.metadata),
+        processResult.texts
       );
       manifestEntries.push({
         filepath,
-        chunkCount: result.chunkCount,
-        mtime: fileMtime
+        chunkCount: processResult.chunkCount,
+        mtime
       });
       if (verbose) {
-        console.error(`[Lien] \u2713 Updated ${filepath} (${result.chunkCount} chunks)`);
+        console.error(`[Lien] \u2713 Updated ${filepath} (${processResult.chunkCount} chunks)`);
+      }
+      processedCount++;
+    } else {
+      if (verbose) {
+        console.error(`[Lien] ${result.error}`);
+      }
+      try {
+        await vectorDB.deleteByFile(filepath);
+        const manifest = new ManifestManager(vectorDB.dbPath);
+        await manifest.removeFile(filepath);
+      } catch (error) {
+        if (verbose) {
+          console.error(`[Lien] Note: ${filepath} not in index`);
+        }
       }
       processedCount++;
-    } catch (error) {
-      console.error(`[Lien] \u26A0\uFE0F  Failed to index ${filepath}: ${error}`);
     }
   }
   if (manifestEntries.length > 0) {
@@ -3833,6 +4097,7 @@ var init_incremental = __esm({
     init_schema();
     init_manifest();
     init_constants();
+    init_result();
   }
 });
 
@@ -3918,6 +4183,99 @@ var init_loading_messages = __esm({
   }
 });
 
+// src/indexer/progress-tracker.ts
+var IndexingProgressTracker;
+var init_progress_tracker = __esm({
+  "src/indexer/progress-tracker.ts"() {
+    "use strict";
+    init_loading_messages();
+    IndexingProgressTracker = class _IndexingProgressTracker {
+      processedFiles = 0;
+      totalFiles;
+      wittyMessage;
+      spinner;
+      updateInterval;
+      // Configuration constants
+      static SPINNER_UPDATE_INTERVAL_MS = 200;
+      // How often to update spinner
+      static MESSAGE_ROTATION_INTERVAL_MS = 8e3;
+      // How often to rotate message
+      constructor(totalFiles, spinner) {
+        this.totalFiles = totalFiles;
+        this.spinner = spinner;
+        this.wittyMessage = getIndexingMessage();
+      }
+      /**
+       * Start the progress tracker.
+       * Sets up periodic updates for spinner and message rotation.
+       * 
+       * Safe to call multiple times - will not create duplicate intervals.
+       */
+      start() {
+        if (this.updateInterval) {
+          return;
+        }
+        const MESSAGE_ROTATION_TICKS = Math.floor(
+          _IndexingProgressTracker.MESSAGE_ROTATION_INTERVAL_MS / _IndexingProgressTracker.SPINNER_UPDATE_INTERVAL_MS
+        );
+        let spinnerTick = 0;
+        this.updateInterval = setInterval(() => {
+          spinnerTick++;
+          if (spinnerTick >= MESSAGE_ROTATION_TICKS) {
+            this.wittyMessage = getIndexingMessage();
+            spinnerTick = 0;
+          }
+          this.spinner.text = `${this.processedFiles}/${this.totalFiles} files | ${this.wittyMessage}`;
+        }, _IndexingProgressTracker.SPINNER_UPDATE_INTERVAL_MS);
+      }
+      /**
+       * Increment the count of processed files.
+       * 
+       * Safe for async operations in Node.js's single-threaded event loop.
+       * Note: Not thread-safe for true concurrent operations (e.g., worker threads).
+       */
+      incrementFiles() {
+        this.processedFiles++;
+      }
+      /**
+       * Set a custom message (e.g., for special operations like embedding generation).
+       * The message will be displayed until the next automatic rotation.
+       */
+      setMessage(message) {
+        this.wittyMessage = message;
+      }
+      /**
+       * Stop the progress tracker and clean up intervals.
+       * Must be called when indexing completes or fails.
+       */
+      stop() {
+        if (this.updateInterval) {
+          clearInterval(this.updateInterval);
+          this.updateInterval = void 0;
+        }
+      }
+      /**
+       * Get the current count of processed files.
+       */
+      getProcessedCount() {
+        return this.processedFiles;
+      }
+      /**
+       * Get the total number of files to process.
+       */
+      getTotalFiles() {
+        return this.totalFiles;
+      }
+      /**
+       * Get the current message being displayed.
+       */
+      getCurrentMessage() {
+        return this.wittyMessage;
+      }
+    };
+  }
+});
+
 // src/indexer/index.ts
 var indexer_exports = {};
 __export(indexer_exports, {
@@ -3927,162 +4285,171 @@ import fs17 from "fs/promises";
 import ora from "ora";
 import chalk5 from "chalk";
 import pLimit from "p-limit";
-async function indexCodebase(options = {}) {
-  const rootDir = options.rootDir ?? process.cwd();
-  const spinner = ora("Starting indexing process...").start();
-  let updateInterval;
+async function updateGitState(rootDir, vectorDB, manifest) {
+  const { isGitAvailable: isGitAvailable2, isGitRepo: isGitRepo2 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
+  const { GitStateTracker: GitStateTracker2 } = await Promise.resolve().then(() => (init_tracker(), tracker_exports));
+  const gitAvailable = await isGitAvailable2();
+  const isRepo = await isGitRepo2(rootDir);
+  if (!gitAvailable || !isRepo) {
+    return;
+  }
+  const gitTracker = new GitStateTracker2(rootDir, vectorDB.dbPath);
+  await gitTracker.initialize();
+  const gitState = gitTracker.getState();
+  if (gitState) {
+    await manifest.updateGitState(gitState);
+  }
+}
+async function handleDeletions(deletedFiles, vectorDB, manifest, spinner) {
+  if (deletedFiles.length === 0) {
+    return;
+  }
+  spinner.start(`Removing ${deletedFiles.length} deleted files...`);
+  let removedCount = 0;
+  for (const filepath of deletedFiles) {
+    try {
+      await vectorDB.deleteByFile(filepath);
+      await manifest.removeFile(filepath);
+      removedCount++;
+    } catch (err) {
+      spinner.warn(
+        `Failed to remove file "${filepath}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  spinner.succeed(`Removed ${removedCount}/${deletedFiles.length} deleted files`);
+}
+async function handleUpdates(addedFiles, modifiedFiles, vectorDB, embeddings, config, options, spinner) {
+  const filesToIndex = [...addedFiles, ...modifiedFiles];
+  if (filesToIndex.length === 0) {
+    return;
+  }
+  spinner.start(`Reindexing ${filesToIndex.length} changed files...`);
+  const count = await indexMultipleFiles(
+    filesToIndex,
+    vectorDB,
+    embeddings,
+    config,
+    { verbose: options.verbose }
+  );
+  await writeVersionFile(vectorDB.dbPath);
+  spinner.succeed(
+    `Incremental reindex complete: ${count}/${filesToIndex.length} files indexed successfully`
+  );
+}
+async function tryIncrementalIndex(rootDir, vectorDB, config, options, spinner) {
+  spinner.text = "Checking for changes...";
+  const manifest = new ManifestManager(vectorDB.dbPath);
+  const savedManifest = await manifest.load();
+  if (!savedManifest) {
+    return false;
+  }
+  const changes = await detectChanges(rootDir, vectorDB, config);
+  if (changes.reason === "full") {
+    spinner.text = "Full reindex required...";
+    return false;
+  }
+  const totalChanges = changes.added.length + changes.modified.length;
+  const totalDeleted = changes.deleted.length;
+  if (totalChanges === 0 && totalDeleted === 0) {
+    spinner.succeed("No changes detected - index is up to date!");
+    return true;
+  }
+  spinner.succeed(
+    `Detected changes: ${totalChanges} files to index, ${totalDeleted} to remove (${changes.reason} detection)`
+  );
+  spinner.start(getModelLoadingMessage());
+  const embeddings = new LocalEmbeddings();
+  await embeddings.initialize();
+  spinner.succeed("Embedding model loaded");
+  await handleDeletions(changes.deleted, vectorDB, manifest, spinner);
+  await handleUpdates(changes.added, changes.modified, vectorDB, embeddings, config, options, spinner);
+  await updateGitState(rootDir, vectorDB, manifest);
+  console.log(chalk5.dim("\nNext step: Run"), chalk5.bold("lien serve"), chalk5.dim("to start the MCP server"));
+  return true;
+}
+async function performFullIndex(rootDir, vectorDB, config, options, spinner) {
+  spinner.text = "Scanning codebase...";
+  let files;
+  if (isModernConfig(config) && config.frameworks.length > 0) {
+    files = await scanCodebaseWithFrameworks(rootDir, config);
+  } else if (isLegacyConfig(config)) {
+    files = await scanCodebase({
+      rootDir,
+      includePatterns: config.indexing.include,
+      excludePatterns: config.indexing.exclude
+    });
+  } else {
+    files = await scanCodebase({
+      rootDir,
+      includePatterns: [],
+      excludePatterns: []
+    });
+  }
+  if (files.length === 0) {
+    spinner.fail("No files found to index");
+    return;
+  }
+  spinner.text = `Found ${files.length} files`;
+  spinner.text = getModelLoadingMessage();
+  const embeddings = new LocalEmbeddings();
+  await embeddings.initialize();
+  spinner.succeed("Embedding model loaded");
+  const concurrency = isModernConfig(config) ? config.core.concurrency : 4;
+  const embeddingBatchSize = isModernConfig(config) ? config.core.embeddingBatchSize : 50;
+  const vectorDBBatchSize = 100;
+  spinner.start(`Processing files with ${concurrency}x concurrency...`);
+  const startTime = Date.now();
+  let processedChunks = 0;
+  const chunkAccumulator = [];
+  const limit = pLimit(concurrency);
+  const indexedFileEntries = [];
+  const progressTracker = new IndexingProgressTracker(files.length, spinner);
+  progressTracker.start();
   try {
-    spinner.text = "Loading configuration...";
-    const config = await configService.load(rootDir);
-    spinner.text = "Initializing vector database...";
-    const vectorDB = new VectorDB(rootDir);
-    await vectorDB.initialize();
-    if (!options.force) {
-      spinner.text = "Checking for changes...";
-      const manifest2 = new ManifestManager(vectorDB.dbPath);
-      const savedManifest = await manifest2.load();
-      if (savedManifest) {
-        const changes = await detectChanges(rootDir, vectorDB, config);
-        if (changes.reason !== "full") {
-          const totalChanges = changes.added.length + changes.modified.length;
-          const totalDeleted = changes.deleted.length;
-          if (totalChanges === 0 && totalDeleted === 0) {
-            spinner.succeed("No changes detected - index is up to date!");
-            return;
-          }
-          spinner.succeed(
-            `Detected changes: ${totalChanges} files to index, ${totalDeleted} to remove (${changes.reason} detection)`
-          );
-          spinner.start(getModelLoadingMessage());
-          const embeddings2 = new LocalEmbeddings();
-          await embeddings2.initialize();
-          spinner.succeed("Embedding model loaded");
-          if (totalDeleted > 0) {
-            spinner.start(`Removing ${totalDeleted} deleted files...`);
-            let removedCount = 0;
-            for (const filepath of changes.deleted) {
-              try {
-                await vectorDB.deleteByFile(filepath);
-                await manifest2.removeFile(filepath);
-                removedCount++;
-              } catch (err) {
-                spinner.warn(`Failed to remove file "${filepath}": ${err instanceof Error ? err.message : String(err)}`);
-              }
-            }
-            spinner.succeed(`Removed ${removedCount}/${totalDeleted} deleted files`);
-          }
-          if (totalChanges > 0) {
-            spinner.start(`Reindexing ${totalChanges} changed files...`);
-            const filesToIndex = [...changes.added, ...changes.modified];
-            const count = await indexMultipleFiles(
-              filesToIndex,
-              vectorDB,
-              embeddings2,
-              config,
-              { verbose: options.verbose }
-            );
-            await writeVersionFile(vectorDB.dbPath);
-            spinner.succeed(
-              `Incremental reindex complete: ${count}/${totalChanges} files indexed successfully`
-            );
-          }
-          const { isGitAvailable: isGitAvailable3, isGitRepo: isGitRepo3 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
-          const { GitStateTracker: GitStateTracker3 } = await Promise.resolve().then(() => (init_tracker(), tracker_exports));
-          const gitAvailable2 = await isGitAvailable3();
-          const isRepo2 = await isGitRepo3(rootDir);
-          if (gitAvailable2 && isRepo2) {
-            const gitTracker = new GitStateTracker3(rootDir, vectorDB.dbPath);
-            await gitTracker.initialize();
-            const gitState = gitTracker.getState();
-            if (gitState) {
-              await manifest2.updateGitState(gitState);
-            }
-          }
-          console.log(chalk5.dim("\nNext step: Run"), chalk5.bold("lien serve"), chalk5.dim("to start the MCP server"));
-          return;
-        }
-        spinner.text = "Full reindex required...";
+    let addChunksLock = null;
+    let processingQueue = null;
+    const processAccumulatedChunks = async () => {
+      if (processingQueue) {
+        processingQueue = processingQueue.then(() => doProcessChunks());
+      } else {
+        processingQueue = doProcessChunks();
       }
-    } else {
-      spinner.text = "Force flag enabled, performing full reindex...";
-    }
-    spinner.text = "Scanning codebase...";
-    let files;
-    if (isModernConfig(config) && config.frameworks.length > 0) {
-      files = await scanCodebaseWithFrameworks(rootDir, config);
-    } else if (isLegacyConfig(config)) {
-      files = await scanCodebase({
-        rootDir,
-        includePatterns: config.indexing.include,
-        excludePatterns: config.indexing.exclude
-      });
-    } else {
-      files = await scanCodebase({
-        rootDir,
-        includePatterns: [],
-        excludePatterns: []
-      });
-    }
-    if (files.length === 0) {
-      spinner.fail("No files found to index");
-      return;
-    }
-    spinner.text = `Found ${files.length} files`;
-    spinner.text = getModelLoadingMessage();
-    const embeddings = new LocalEmbeddings();
-    await embeddings.initialize();
-    spinner.succeed("Embedding model loaded");
-    const concurrency = isModernConfig(config) ? config.core.concurrency : 4;
-    const embeddingBatchSize = isModernConfig(config) ? config.core.embeddingBatchSize : 50;
-    const vectorDBBatchSize = 100;
-    spinner.start(`Processing files with ${concurrency}x concurrency...`);
-    const startTime = Date.now();
-    let processedFiles = 0;
-    let processedChunks = 0;
-    const chunkAccumulator = [];
-    const limit = pLimit(concurrency);
-    const indexedFileEntries = [];
-    const progressState = {
-      processedFiles: 0,
-      totalFiles: files.length,
-      wittyMessage: getIndexingMessage()
+      return processingQueue;
     };
-    const SPINNER_UPDATE_INTERVAL_MS = 200;
-    const MESSAGE_ROTATION_INTERVAL_MS = 8e3;
-    const MESSAGE_ROTATION_TICKS = Math.floor(MESSAGE_ROTATION_INTERVAL_MS / SPINNER_UPDATE_INTERVAL_MS);
-    let spinnerTick = 0;
-    updateInterval = setInterval(() => {
-      spinnerTick++;
-      if (spinnerTick >= MESSAGE_ROTATION_TICKS) {
-        progressState.wittyMessage = getIndexingMessage();
-        spinnerTick = 0;
-      }
-      spinner.text = `${progressState.processedFiles}/${progressState.totalFiles} files | ${progressState.wittyMessage}`;
-    }, SPINNER_UPDATE_INTERVAL_MS);
-    const processAccumulatedChunks = async () => {
-      if (chunkAccumulator.length === 0) return;
-      const toProcess = chunkAccumulator.splice(0, chunkAccumulator.length);
-      for (let i = 0; i < toProcess.length; i += embeddingBatchSize) {
-        const batch = toProcess.slice(i, Math.min(i + embeddingBatchSize, toProcess.length));
-        progressState.wittyMessage = getEmbeddingMessage();
-        const texts = batch.map((item) => item.content);
-        const embeddingVectors = [];
-        for (let j = 0; j < texts.length; j += EMBEDDING_MICRO_BATCH_SIZE) {
-          const microBatch = texts.slice(j, Math.min(j + EMBEDDING_MICRO_BATCH_SIZE, texts.length));
-          const microResults = await embeddings.embedBatch(microBatch);
-          embeddingVectors.push(...microResults);
+    const doProcessChunks = async () => {
+      if (chunkAccumulator.length === 0) {
+        return;
+      }
+      const currentPromise = processingQueue;
+      try {
+        const toProcess = chunkAccumulator.splice(0, chunkAccumulator.length);
+        for (let i = 0; i < toProcess.length; i += embeddingBatchSize) {
+          const batch = toProcess.slice(i, Math.min(i + embeddingBatchSize, toProcess.length));
+          progressTracker.setMessage(getEmbeddingMessage());
+          const texts = batch.map((item) => item.content);
+          const embeddingVectors = [];
+          for (let j = 0; j < texts.length; j += EMBEDDING_MICRO_BATCH_SIZE) {
+            const microBatch = texts.slice(j, Math.min(j + EMBEDDING_MICRO_BATCH_SIZE, texts.length));
+            const microResults = await embeddings.embedBatch(microBatch);
+            embeddingVectors.push(...microResults);
+            await new Promise((resolve) => setImmediate(resolve));
+          }
+          processedChunks += batch.length;
+          progressTracker.setMessage(`Inserting ${batch.length} chunks into vector space...`);
+          await vectorDB.insertBatch(
+            embeddingVectors,
+            batch.map((item) => item.chunk.metadata),
+            texts
+          );
           await new Promise((resolve) => setImmediate(resolve));
         }
-        processedChunks += batch.length;
-        progressState.wittyMessage = `Inserting ${batch.length} chunks into vector space...`;
-        await vectorDB.insertBatch(
-          embeddingVectors,
-          batch.map((item) => item.chunk.metadata),
-          texts
-        );
-        await new Promise((resolve) => setImmediate(resolve));
+        progressTracker.setMessage(getIndexingMessage());
+      } finally {
+        if (processingQueue === currentPromise) {
+          processingQueue = null;
+        }
       }
-      progressState.wittyMessage = getIndexingMessage();
     };
     const filePromises = files.map(
       (file) => limit(async () => {
@@ -4100,73 +4467,91 @@ async function indexCodebase(options = {}) {
             astFallback
           });
           if (chunks.length === 0) {
-            processedFiles++;
-            progressState.processedFiles = processedFiles;
+            progressTracker.incrementFiles();
             return;
           }
-          for (const chunk of chunks) {
-            chunkAccumulator.push({
-              chunk,
-              content: chunk.content
+          {
+            if (addChunksLock) {
+              await addChunksLock;
+            }
+            let releaseAddLock;
+            addChunksLock = new Promise((resolve) => {
+              releaseAddLock = resolve;
             });
-          }
-          indexedFileEntries.push({
-            filepath: file,
-            chunkCount: chunks.length,
-            mtime: stats.mtimeMs
-          });
-          processedFiles++;
-          progressState.processedFiles = processedFiles;
-          if (chunkAccumulator.length >= vectorDBBatchSize) {
-            await processAccumulatedChunks();
+            try {
+              for (const chunk of chunks) {
+                chunkAccumulator.push({
+                  chunk,
+                  content: chunk.content
+                });
+              }
+              indexedFileEntries.push({
+                filepath: file,
+                chunkCount: chunks.length,
+                mtime: stats.mtimeMs
+              });
+              progressTracker.incrementFiles();
+              if (chunkAccumulator.length >= vectorDBBatchSize) {
+                await processAccumulatedChunks();
+              }
+            } finally {
+              releaseAddLock();
+              addChunksLock = null;
+            }
           }
         } catch (error) {
           if (options.verbose) {
             console.error(chalk5.yellow(`
 \u26A0\uFE0F  Skipping ${file}: ${error}`));
           }
-          processedFiles++;
-          progressState.processedFiles = processedFiles;
+          progressTracker.incrementFiles();
         }
       })
     );
     await Promise.all(filePromises);
-    progressState.wittyMessage = "Processing final chunks...";
+    progressTracker.setMessage("Processing final chunks...");
     await processAccumulatedChunks();
-    clearInterval(updateInterval);
-    spinner.start("Saving index manifest...");
-    const manifest = new ManifestManager(vectorDB.dbPath);
-    await manifest.updateFiles(
-      indexedFileEntries.map((entry) => ({
-        filepath: entry.filepath,
-        lastModified: entry.mtime,
-        // Use actual file mtime for accurate change detection
-        chunkCount: entry.chunkCount
-      }))
-    );
-    const { isGitAvailable: isGitAvailable2, isGitRepo: isGitRepo2 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
-    const { GitStateTracker: GitStateTracker2 } = await Promise.resolve().then(() => (init_tracker(), tracker_exports));
-    const gitAvailable = await isGitAvailable2();
-    const isRepo = await isGitRepo2(rootDir);
-    if (gitAvailable && isRepo) {
-      const gitTracker = new GitStateTracker2(rootDir, vectorDB.dbPath);
-      await gitTracker.initialize();
-      const gitState = gitTracker.getState();
-      if (gitState) {
-        await manifest.updateGitState(gitState);
+  } finally {
+    progressTracker.stop();
+  }
+  spinner.start("Saving index manifest...");
+  const manifest = new ManifestManager(vectorDB.dbPath);
+  await manifest.updateFiles(
+    indexedFileEntries.map((entry) => ({
+      filepath: entry.filepath,
+      // Use actual file mtime for accurate change detection
+      lastModified: entry.mtime,
+      chunkCount: entry.chunkCount
+    }))
+  );
+  await updateGitState(rootDir, vectorDB, manifest);
+  spinner.succeed("Manifest saved");
+  await writeVersionFile(vectorDB.dbPath);
+  const totalTime = ((Date.now() - startTime) / 1e3).toFixed(1);
+  spinner.succeed(
+    `Indexed ${progressTracker.getProcessedCount()} files (${processedChunks} chunks) in ${totalTime}s using ${concurrency}x concurrency`
+  );
+  console.log(chalk5.dim("\nNext step: Run"), chalk5.bold("lien serve"), chalk5.dim("to start the MCP server"));
+}
+async function indexCodebase(options = {}) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const spinner = ora("Starting indexing process...").start();
+  try {
+    spinner.text = "Loading configuration...";
+    const config = await configService.load(rootDir);
+    spinner.text = "Initializing vector database...";
+    const vectorDB = new VectorDB(rootDir);
+    await vectorDB.initialize();
+    if (!options.force) {
+      const completed = await tryIncrementalIndex(rootDir, vectorDB, config, options, spinner);
+      if (completed) {
+        return;
       }
+    } else {
+      spinner.text = "Force flag enabled, performing full reindex...";
     }
-    spinner.succeed("Manifest saved");
-    await writeVersionFile(vectorDB.dbPath);
-    const totalTime = ((Date.now() - startTime) / 1e3).toFixed(1);
-    spinner.succeed(
-      `Indexed ${processedFiles} files (${processedChunks} chunks) in ${totalTime}s using ${concurrency}x concurrency`
-    );
-    console.log(chalk5.dim("\nNext step: Run"), chalk5.bold("lien serve"), chalk5.dim("to start the MCP server"));
+    await performFullIndex(rootDir, vectorDB, config, options, spinner);
   } catch (error) {
-    if (updateInterval) {
-      clearInterval(updateInterval);
-    }
     spinner.fail(`Indexing failed: ${error}`);
     throw error;
   }
@@ -4186,6 +4571,7 @@ var init_indexer = __esm({
     init_incremental();
     init_loading_messages();
     init_constants();
+    init_progress_tracker();
   }
 });
 
@@ -4926,7 +5312,7 @@ async function createNewConfig(rootDir, options) {
       path: ".",
       enabled: true,
       config: {
-        include: ["**/*.{ts,tsx,js,jsx,py,go,rs,java,c,cpp,cs}"],
+        include: ["**/*.{ts,tsx,js,jsx,py,php,go,rs,java,c,cpp,cs}"],
         exclude: [
           "**/node_modules/**",
           "**/dist/**",
@@ -5279,9 +5665,12 @@ var FindSimilarSchema = z2.object({
 
 // src/mcp/schemas/file.schema.ts
 import { z as z3 } from "zod";
-var GetFileContextSchema = z3.object({
-  filepath: z3.string().min(1, "Filepath cannot be empty").describe(
-    "Relative path to file from workspace root.\n\nExample: 'src/components/Button.tsx'"
+var GetFilesContextSchema = z3.object({
+  filepaths: z3.union([
+    z3.string().min(1, "Filepath cannot be empty"),
+    z3.array(z3.string().min(1, "Filepath cannot be empty")).min(1, "Array must contain at least one filepath").max(50, "Maximum 50 files per request")
+  ]).describe(
+    "Single filepath or array of filepaths (relative to workspace root).\n\nSingle file: 'src/components/Button.tsx'\nMultiple files: ['src/auth.ts', 'src/user.ts']\n\nMaximum 50 files per request for batch operations."
   ),
   includeRelated: z3.boolean().default(true).describe(
     "Include semantically related chunks from nearby code.\n\nDefault: true\n\nWhen enabled, also returns related code from other files that are semantically similar to the target file's contents."
@@ -5304,22 +5693,56 @@ var tools = [
   toMCPToolSchema(
     SemanticSearchSchema,
     "semantic_search",
-    "Search the codebase semantically for relevant code using natural language. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+    `Search codebase by MEANING, not text. USE THIS INSTEAD OF grep/ripgrep for finding implementations, features, or understanding how code works.
+
+Examples:
+- "Where is authentication handled?" \u2192 semantic_search({ query: "handles user authentication" })
+- "How does payment work?" \u2192 semantic_search({ query: "processes payment transactions" })
+
+Use natural language describing what the code DOES, not function names. For exact string matching, use grep instead.
+
+Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) for each match.`
   ),
   toMCPToolSchema(
     FindSimilarSchema,
     "find_similar",
-    "Find code similar to a given code snippet. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+    `Find code structurally similar to a given snippet. Use for:
+- Ensuring consistency when adding new code
+- Finding duplicate implementations
+- Refactoring similar patterns together
+
+Provide at least 10 characters of code to match against. Results include a relevance category for each match.`
   ),
   toMCPToolSchema(
-    GetFileContextSchema,
-    "get_file_context",
-    "Get all chunks and related context for a specific file. Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) based on semantic similarity."
+    GetFilesContextSchema,
+    "get_files_context",
+    `Get context for one or more files including dependencies and test coverage.
+
+MANDATORY: Call this BEFORE editing any file. Accepts single path or array of paths.
+
+Single file:
+  get_files_context({ filepaths: "src/auth.ts" })
+
+Multiple files (batch):
+  get_files_context({ filepaths: ["src/auth.ts", "src/user.ts"] })
+
+Returns for each file:
+- All chunks and related code
+- testAssociations (which tests cover this file)
+- Relevance scoring
+
+Batch calls are more efficient than multiple single-file calls.`
   ),
   toMCPToolSchema(
     ListFunctionsSchema,
     "list_functions",
-    "List functions, classes, and interfaces by name pattern and language"
+    `Fast symbol lookup by naming pattern. Use when searching by NAME, not behavior.
+
+Examples:
+- "Show all controllers" \u2192 list_functions({ pattern: ".*Controller.*" })
+- "Find service classes" \u2192 list_functions({ pattern: ".*Service$" })
+
+10x faster than semantic_search for structural/architectural queries. Use semantic_search instead when searching by what code DOES.`
   )
 ];
 
@@ -5618,32 +6041,69 @@ async function startMCPServer(options) {
               };
             }
           )(args);
-        case "get_file_context":
+        case "get_files_context":
           return await wrapToolHandler(
-            GetFileContextSchema,
+            GetFilesContextSchema,
             async (validatedArgs) => {
-              log(`Getting context for: ${validatedArgs.filepath}`);
+              const filepaths = Array.isArray(validatedArgs.filepaths) ? validatedArgs.filepaths : [validatedArgs.filepaths];
+              const isSingleFile = !Array.isArray(validatedArgs.filepaths);
+              log(`Getting context for: ${filepaths.join(", ")}`);
               await checkAndReconnect();
-              const fileEmbedding = await embeddings.embed(validatedArgs.filepath);
-              const allResults = await vectorDB.search(fileEmbedding, 50, validatedArgs.filepath);
-              const fileChunks = allResults.filter(
-                (r) => r.metadata.file.includes(validatedArgs.filepath) || validatedArgs.filepath.includes(r.metadata.file)
+              const fileEmbeddings = await Promise.all(filepaths.map((fp) => embeddings.embed(fp)));
+              const allFileSearches = await Promise.all(
+                fileEmbeddings.map(
+                  (embedding, i) => vectorDB.search(embedding, 50, filepaths[i])
+                )
               );
-              let results = fileChunks;
-              if (validatedArgs.includeRelated && fileChunks.length > 0) {
-                const relatedEmbedding = await embeddings.embed(fileChunks[0].content);
-                const related = await vectorDB.search(relatedEmbedding, 5, fileChunks[0].content);
-                const relatedOtherFiles = related.filter(
-                  (r) => !r.metadata.file.includes(validatedArgs.filepath) && !validatedArgs.filepath.includes(r.metadata.file)
+              const fileChunksMap = filepaths.map((filepath, i) => {
+                const allResults = allFileSearches[i];
+                return allResults.filter(
+                  (r) => r.metadata.file.includes(filepath) || filepath.includes(r.metadata.file)
                 );
-                results = [...fileChunks, ...relatedOtherFiles];
+              });
+              let relatedChunksMap = [];
+              if (validatedArgs.includeRelated) {
+                const filesWithChunks = fileChunksMap.map((chunks, i) => ({ chunks, filepath: filepaths[i], index: i })).filter(({ chunks }) => chunks.length > 0);
+                if (filesWithChunks.length > 0) {
+                  const relatedEmbeddings = await Promise.all(
+                    filesWithChunks.map(({ chunks }) => embeddings.embed(chunks[0].content))
+                  );
+                  const relatedSearches = await Promise.all(
+                    relatedEmbeddings.map(
+                      (embedding, i) => vectorDB.search(embedding, 5, filesWithChunks[i].chunks[0].content)
+                    )
+                  );
+                  relatedChunksMap = Array.from({ length: filepaths.length }, () => []);
+                  filesWithChunks.forEach(({ filepath, index }, i) => {
+                    const related = relatedSearches[i];
+                    relatedChunksMap[index] = related.filter(
+                      (r) => !r.metadata.file.includes(filepath) && !filepath.includes(r.metadata.file)
+                    );
+                  });
+                }
+              }
+              const filesData = {};
+              filepaths.forEach((filepath, i) => {
+                const fileChunks = fileChunksMap[i];
+                const relatedChunks = relatedChunksMap[i] || [];
+                filesData[filepath] = {
+                  chunks: [...fileChunks, ...relatedChunks]
+                };
+              });
+              log(`Found ${Object.values(filesData).reduce((sum, f) => sum + f.chunks.length, 0)} total chunks`);
+              if (isSingleFile) {
+                const filepath = filepaths[0];
+                return {
+                  indexInfo: getIndexMetadata(),
+                  file: filepath,
+                  chunks: filesData[filepath].chunks
+                };
+              } else {
+                return {
+                  indexInfo: getIndexMetadata(),
+                  files: filesData
+                };
               }
-              log(`Found ${results.length} chunks`);
-              return {
-                indexInfo: getIndexMetadata(),
-                file: validatedArgs.filepath,
-                chunks: results
-              };
             }
           )(args);
         case "list_functions":