@getmikk/mcp-server 1.8.1 → 1.9.1

package/dist/index.cjs

@@ -41845,7 +41845,7 @@ ${lanes.join("\n")}
           jsDocParsingMode
         } = typeof languageVersionOrOptions === "object" ? languageVersionOrOptions : { languageVersion: languageVersionOrOptions };
         if (languageVersion === 100) {
-          result = Parser.parseSourceFile(
+          result = Parser2.parseSourceFile(
             fileName,
             sourceText,
             languageVersion,
@@ -41861,7 +41861,7 @@ ${lanes.join("\n")}
             file.impliedNodeFormat = format;
             return (overrideSetExternalModuleIndicator || setExternalModuleIndicator)(file);
           };
-          result = Parser.parseSourceFile(
+          result = Parser2.parseSourceFile(
             fileName,
             sourceText,
             languageVersion,
@@ -41879,10 +41879,10 @@ ${lanes.join("\n")}
         return result;
       }
       function parseIsolatedEntityName(text, languageVersion) {
-        return Parser.parseIsolatedEntityName(text, languageVersion);
+        return Parser2.parseIsolatedEntityName(text, languageVersion);
       }
       function parseJsonText(fileName, sourceText) {
-        return Parser.parseJsonText(fileName, sourceText);
+        return Parser2.parseJsonText(fileName, sourceText);
       }
       function isExternalModule(file) {
         return file.externalModuleIndicator !== void 0;
@@ -41893,17 +41893,17 @@ ${lanes.join("\n")}
         return newSourceFile;
       }
       function parseIsolatedJSDocComment(content, start, length2) {
-        const result = Parser.JSDocParser.parseIsolatedJSDocComment(content, start, length2);
+        const result = Parser2.JSDocParser.parseIsolatedJSDocComment(content, start, length2);
         if (result && result.jsDoc) {
-          Parser.fixupParentReferences(result.jsDoc);
+          Parser2.fixupParentReferences(result.jsDoc);
         }
         return result;
       }
       function parseJSDocTypeExpressionForTests(content, start, length2) {
-        return Parser.JSDocParser.parseJSDocTypeExpressionForTests(content, start, length2);
+        return Parser2.JSDocParser.parseJSDocTypeExpressionForTests(content, start, length2);
       }
-      var Parser;
-      ((Parser2) => {
+      var Parser2;
+      ((Parser22) => {
         var scanner2 = createScanner(
           99,
           /*skipTrivia*/
@@ -42030,7 +42030,7 @@ ${lanes.join("\n")}
           clearState();
           return result;
         }
-        Parser2.parseSourceFile = parseSourceFile;
+        Parser22.parseSourceFile = parseSourceFile;
         function parseIsolatedEntityName2(content, languageVersion2) {
           initializeState(
             "",
@@ -42051,7 +42051,7 @@ ${lanes.join("\n")}
           clearState();
           return isValid2 ? entityName : void 0;
         }
-        Parser2.parseIsolatedEntityName = parseIsolatedEntityName2;
+        Parser22.parseIsolatedEntityName = parseIsolatedEntityName2;
         function parseJsonText2(fileName2, sourceText2, languageVersion2 = 2, syntaxCursor2, setParentNodes = false) {
           initializeState(
             fileName2,
@@ -42147,7 +42147,7 @@ ${lanes.join("\n")}
           clearState();
           return result;
         }
-        Parser2.parseJsonText = parseJsonText2;
+        Parser22.parseJsonText = parseJsonText2;
         function initializeState(_fileName, _sourceText, _languageVersion, _syntaxCursor, _scriptKind, _jsDocParsingMode) {
           NodeConstructor2 = objectAllocator.getNodeConstructor();
           TokenConstructor2 = objectAllocator.getTokenConstructor();
@@ -42219,7 +42219,7 @@ ${lanes.join("\n")}
           }
           sourceFlags = contextFlags;
           nextToken();
-          const statements = parseList(0, parseStatement);
+          const statements = parseList2(0, parseStatement);
           Debug.assert(
             token() === 1
             /* EndOfFileToken */
@@ -42353,7 +42353,7 @@ ${lanes.join("\n")}
             true
           );
         }
-        Parser2.fixupParentReferences = fixupParentReferences;
+        Parser22.fixupParentReferences = fixupParentReferences;
         function createSourceFile2(fileName2, languageVersion2, scriptKind2, isDeclarationFile, statements, endOfFileToken, flags, setExternalModuleIndicator2) {
           let sourceFile = factory2.createSourceFile(statements, endOfFileToken, flags);
           setTextRangePosWidth(sourceFile, 0, sourceText.length);
@@ -43261,7 +43261,7 @@ ${lanes.join("\n")}
           }
           return false;
         }
-        function parseList(kind, parseElement) {
+        function parseList2(kind, parseElement) {
           const saveParsingContext = parsingContext;
           parsingContext |= 1 << kind;
           const list = [];
@@ -44344,7 +44344,7 @@ ${lanes.join("\n")}
             19
             /* OpenBraceToken */
           )) {
-            members = parseList(4, parseTypeMember);
+            members = parseList2(4, parseTypeMember);
             parseExpected(
               20
               /* CloseBraceToken */
@@ -44422,7 +44422,7 @@ ${lanes.join("\n")}
           }
           const type = parseTypeAnnotation();
           parseSemicolon();
-          const members = parseList(4, parseTypeMember);
+          const members = parseList2(4, parseTypeMember);
           parseExpected(
             20
             /* CloseBraceToken */
@@ -45843,7 +45843,7 @@ ${lanes.join("\n")}
         }
         function parseJsxAttributes() {
           const pos = getNodePos();
-          return finishNode(factory2.createJsxAttributes(parseList(13, parseJsxAttribute)), pos);
+          return finishNode(factory2.createJsxAttributes(parseList2(13, parseJsxAttribute)), pos);
         }
         function parseJsxOpeningOrSelfClosingElementOrOpeningFragment(inExpressionContext) {
           const pos = getNodePos();
@@ -46585,7 +46585,7 @@ ${lanes.join("\n")}
           const openBraceParsed = parseExpected(19, diagnosticMessage);
           if (openBraceParsed || ignoreMissingOpenBrace) {
             const multiLine = scanner2.hasPrecedingLineBreak();
-            const statements = parseList(1, parseStatement);
+            const statements = parseList2(1, parseStatement);
             parseExpectedMatchingBrackets(19, 20, openBraceParsed, openBracePosition);
             const result = withJSDoc(finishNode(factoryCreateBlock(statements, multiLine), pos), hasJSDoc);
             if (token() === 64) {
@@ -46825,7 +46825,7 @@ ${lanes.join("\n")}
             59
             /* ColonToken */
           );
-          const statements = parseList(3, parseStatement);
+          const statements = parseList2(3, parseStatement);
           return withJSDoc(finishNode(factory2.createCaseClause(expression, statements), pos), hasJSDoc);
         }
         function parseDefaultClause() {
@@ -46838,7 +46838,7 @@ ${lanes.join("\n")}
             59
             /* ColonToken */
           );
-          const statements = parseList(3, parseStatement);
+          const statements = parseList2(3, parseStatement);
           return finishNode(factory2.createDefaultClause(statements), pos);
         }
         function parseCaseOrDefaultClause() {
@@ -46850,7 +46850,7 @@ ${lanes.join("\n")}
             19
             /* OpenBraceToken */
           );
-          const clauses = parseList(2, parseCaseOrDefaultClause);
+          const clauses = parseList2(2, parseCaseOrDefaultClause);
           parseExpected(
             20
             /* CloseBraceToken */
@@ -47974,7 +47974,7 @@ ${lanes.join("\n")}
         }
         function parseHeritageClauses() {
           if (isHeritageClause2()) {
-            return parseList(22, parseHeritageClause);
+            return parseList2(22, parseHeritageClause);
           }
           return void 0;
         }
@@ -48011,7 +48011,7 @@ ${lanes.join("\n")}
           return token() === 96 || token() === 119;
         }
         function parseClassMembers() {
-          return parseList(5, parseClassElement);
+          return parseList2(5, parseClassElement);
         }
         function parseInterfaceDeclaration(pos, hasJSDoc, modifiers) {
           parseExpected(
@@ -48080,7 +48080,7 @@ ${lanes.join("\n")}
             19
             /* OpenBraceToken */
           )) {
-            statements = parseList(1, parseStatement);
+            statements = parseList2(1, parseStatement);
             parseExpected(
               20
               /* CloseBraceToken */
@@ -49740,8 +49740,8 @@ ${lanes.join("\n")}
               return result2;
             }
           }
-        })(JSDocParser = Parser2.JSDocParser || (Parser2.JSDocParser = {}));
-      })(Parser || (Parser = {}));
+        })(JSDocParser = Parser22.JSDocParser || (Parser22.JSDocParser = {}));
+      })(Parser2 || (Parser2 = {}));
       var incrementallyParsedFiles = /* @__PURE__ */ new WeakSet();
       function markAsIncrementallyParsed(sourceFile) {
         if (incrementallyParsedFiles.has(sourceFile)) {
@@ -49768,7 +49768,7 @@ ${lanes.join("\n")}
             return sourceFile;
           }
           if (sourceFile.statements.length === 0) {
-            return Parser.parseSourceFile(
+            return Parser2.parseSourceFile(
               sourceFile.fileName,
               newText,
               sourceFile.languageVersion,
@@ -49782,7 +49782,7 @@ ${lanes.join("\n")}
             );
           }
           markAsIncrementallyParsed(sourceFile);
-          Parser.fixupParentReferences(sourceFile);
+          Parser2.fixupParentReferences(sourceFile);
           const oldText = sourceFile.text;
           const syntaxCursor = createSyntaxCursor(sourceFile);
           const changeRange = extendToAffectedRange(sourceFile, textChangeRange);
@@ -49792,7 +49792,7 @@ ${lanes.join("\n")}
           Debug.assert(textSpanEnd(textChangeRangeNewSpan(changeRange)) === textSpanEnd(textChangeRangeNewSpan(textChangeRange)));
           const delta = textChangeRangeNewSpan(changeRange).length - changeRange.span.length;
           updateTokenPositionsAndMarkElements(sourceFile, changeRange.span.start, textSpanEnd(changeRange.span), textSpanEnd(textChangeRangeNewSpan(changeRange)), delta, oldText, newText, aggressiveChecks);
-          const result = Parser.parseSourceFile(
+          const result = Parser2.parseSourceFile(
             sourceFile.fileName,
             newText,
             sourceFile.languageVersion,
@@ -236750,6 +236750,7 @@ var EMPTY_COMPLETION_RESULT = {
 // src/tools.ts
 var path4 = __toESM(require("node:path"), 1);
 var fs6 = __toESM(require("node:fs/promises"), 1);
+var import_node_child_process = require("node:child_process");
 var import_node_crypto = require("node:crypto");
 
 // ../core/dist/parser/typescript/ts-extractor.js
@@ -236780,22 +236781,34 @@ var LockNotFoundError = class extends MikkError {
 
 // ../core/dist/parser/boundary-checker.js
 var path = __toESM(require("node:path"), 1);
+function stripPrefix(s) {
+  return s.trim().replace(/^module:/, "");
+}
+function parseList(raw) {
+  return raw.split(/,\s*/).map(stripPrefix).filter(Boolean);
+}
 function parseConstraint(constraint) {
-  const c = constraint.trim().toLowerCase();
-  const denyMatch = c.match(/^module:(\S+)\s+cannot\s+import\s+(.+)$/);
-  if (denyMatch) {
-    const toModules = denyMatch[2].split(",").map((s) => s.trim().replace("module:", "")).filter(Boolean);
-    return { type: "deny", fromModuleId: denyMatch[1], toModuleIds: toModules, raw: constraint };
-  }
-  const allowOnlyMatch = c.match(/^module:(\S+)\s+can\s+only\s+import\s+(.+)$/);
-  if (allowOnlyMatch) {
-    const toModules = allowOnlyMatch[2].split(",").map((s) => s.trim().replace("module:", "")).filter(Boolean);
-    return { type: "allow_only", fromModuleId: allowOnlyMatch[1], toModuleIds: toModules, raw: constraint };
-  }
-  const isolatedMatch = c.match(/^module:(\S+)\s+(has\s+no\s+imports|is\s+isolated)$/);
-  if (isolatedMatch) {
-    return { type: "isolated", fromModuleId: isolatedMatch[1], toModuleIds: [], raw: constraint };
-  }
+  const c = constraint.trim();
+  const l = c.toLowerCase();
+  const natDeny = l.match(/^(\S+)\s+(?:must\s+not|cannot|should\s+not)\s+(?:import\s+from|import|call\s+into|call)\s+(.+)$/);
+  if (natDeny)
+    return { type: "deny", fromModuleId: stripPrefix(natDeny[1]), toModuleIds: parseList(natDeny[2]), raw: c };
+  const natAllow = l.match(/^(\S+)\s+can\s+only\s+(?:import\s+from|import)\s+(.+)$/);
+  if (natAllow)
+    return { type: "allow_only", fromModuleId: stripPrefix(natAllow[1]), toModuleIds: parseList(natAllow[2]), raw: c };
+  const natIso = l.match(/^(\S+)\s+(?:is\s+isolated|has\s+no\s+imports)$/);
+  if (natIso)
+    return { type: "isolated", fromModuleId: stripPrefix(natIso[1]), toModuleIds: [], raw: c };
+  const legDeny = l.match(/^module:(\S+)\s+cannot\s+import\s+(.+)$/);
+  if (legDeny)
+    return { type: "deny", fromModuleId: legDeny[1], toModuleIds: parseList(legDeny[2]), raw: c };
+  const legAllow = l.match(/^module:(\S+)\s+can\s+only\s+import\s+(.+)$/);
+  if (legAllow)
+    return { type: "allow_only", fromModuleId: legAllow[1], toModuleIds: parseList(legAllow[2]), raw: c };
+  const legIso = l.match(/^module:(\S+)\s+(?:has\s+no\s+imports|is\s+isolated)$/);
+  if (legIso)
+    return { type: "isolated", fromModuleId: legIso[1], toModuleIds: [], raw: c };
+  console.warn(`[mikk] Constraint skipped: "${c}" - use "auth must not import from payments"`);
   return null;
 }
 var BoundaryChecker = class {
@@ -236803,160 +236816,113 @@ var BoundaryChecker = class {
   lock;
   rules;
   moduleNames;
-  // id → name
   constructor(contract, lock) {
     this.contract = contract;
     this.lock = lock;
     this.rules = contract.declared.constraints.map(parseConstraint).filter((r) => r !== null);
     this.moduleNames = new Map(contract.declared.modules.map((m) => [m.id, m.name]));
   }
-  /** Run boundary check. Returns pass/fail + all violations. */
   check() {
     const violations = [];
     for (const fn of Object.values(this.lock.functions)) {
+      if (fn.moduleId === "unknown")
+        continue;
       for (const calleeId of fn.calls) {
         const callee = this.lock.functions[calleeId];
-        if (!callee)
+        if (!callee || callee.moduleId === "unknown" || fn.moduleId === callee.moduleId)
           continue;
-        if (fn.moduleId === callee.moduleId)
-          continue;
-        const violation = this.checkCall(fn, callee);
-        if (violation)
-          violations.push(violation);
+        const v = this.checkCall(fn, callee);
+        if (v)
+          violations.push(v);
       }
     }
     for (const file of Object.values(this.lock.files)) {
-      if (!file.imports || file.imports.length === 0)
+      if (file.moduleId === "unknown" || !file.imports?.length)
         continue;
       for (const importedPath of file.imports) {
         const importedFile = this.lock.files[importedPath];
-        if (!importedFile)
-          continue;
-        if (file.moduleId === importedFile.moduleId)
+        if (!importedFile || importedFile.moduleId === "unknown" || file.moduleId === importedFile.moduleId)
           continue;
-        const violation = this.checkFileImport(file, importedFile);
-        if (violation)
-          violations.push(violation);
+        const v = this.checkFileImport(file, importedFile);
+        if (v)
+          violations.push(v);
       }
     }
-    const errorCount = violations.filter((v) => v.severity === "error").length;
-    const warnCount = violations.filter((v) => v.severity === "warning").length;
-    const summary = violations.length === 0 ? `\u2713 All module boundaries respected (${Object.keys(this.lock.functions).length} functions, ${Object.keys(this.lock.files).length} files checked)` : `\u2717 ${errorCount} boundary error(s), ${warnCount} warning(s) found`;
-    return {
-      pass: errorCount === 0,
-      violations,
-      summary
-    };
+    const seen = /* @__PURE__ */ new Set();
+    const unique = violations.filter((v) => {
+      const key = `${v.from.functionId}|${v.to.functionId}|${v.rule}`;
+      if (seen.has(key))
+        return false;
+      seen.add(key);
+      return true;
+    });
+    const fnCount = Object.keys(this.lock.functions).length;
+    const fileCount = Object.keys(this.lock.files).length;
+    const errorCount = unique.filter((v) => v.severity === "error").length;
+    const warnCount = unique.filter((v) => v.severity === "warning").length;
+    const summary = unique.length === 0 ? `All module boundaries respected (${fnCount} functions, ${fileCount} files checked)` : `${errorCount} boundary error(s), ${warnCount} warning(s) found`;
+    return { pass: errorCount === 0, violations: unique, summary };
   }
-  /**
-   * Check a single cross-module call against parsed rules.
-   * Returns a violation if the call is forbidden, null if it's allowed.
-   */
   checkCall(caller, callee) {
     for (const rule of this.rules) {
       if (rule.fromModuleId !== caller.moduleId)
         continue;
-      let forbidden = false;
-      let ruleDesc = rule.raw;
-      if (rule.type === "isolated") {
-        forbidden = true;
-      } else if (rule.type === "deny") {
-        forbidden = rule.toModuleIds.includes(callee.moduleId);
-      } else if (rule.type === "allow_only") {
-        forbidden = !rule.toModuleIds.includes(callee.moduleId);
-      }
-      if (forbidden) {
+      const forbidden = rule.type === "isolated" ? true : rule.type === "deny" ? rule.toModuleIds.includes(callee.moduleId) : !rule.toModuleIds.includes(callee.moduleId);
+      if (forbidden)
         return {
-          from: {
-            functionId: caller.id,
-            functionName: caller.name,
-            file: caller.file,
-            moduleId: caller.moduleId,
-            moduleName: this.moduleNames.get(caller.moduleId) ?? caller.moduleId
-          },
-          to: {
-            functionId: callee.id,
-            functionName: callee.name,
-            file: callee.file,
-            moduleId: callee.moduleId,
-            moduleName: this.moduleNames.get(callee.moduleId) ?? callee.moduleId
-          },
-          rule: ruleDesc,
+          from: { functionId: caller.id, functionName: caller.name, file: caller.file, moduleId: caller.moduleId, moduleName: this.moduleNames.get(caller.moduleId) ?? caller.moduleId },
+          to: { functionId: callee.id, functionName: callee.name, file: callee.file, moduleId: callee.moduleId, moduleName: this.moduleNames.get(callee.moduleId) ?? callee.moduleId },
+          rule: rule.raw,
           severity: "error"
         };
-      }
     }
     return null;
   }
-  /**
-   * Check a single cross-module file import against parsed rules.
-   * Returns a violation if the import is forbidden, null if it's allowed.
-   */
   checkFileImport(sourceFile, targetFile) {
     for (const rule of this.rules) {
       if (rule.fromModuleId !== sourceFile.moduleId)
         continue;
-      let forbidden = false;
-      if (rule.type === "isolated") {
-        forbidden = true;
-      } else if (rule.type === "deny") {
-        forbidden = rule.toModuleIds.includes(targetFile.moduleId);
-      } else if (rule.type === "allow_only") {
-        forbidden = !rule.toModuleIds.includes(targetFile.moduleId);
-      }
-      if (forbidden) {
+      const forbidden = rule.type === "isolated" ? true : rule.type === "deny" ? rule.toModuleIds.includes(targetFile.moduleId) : !rule.toModuleIds.includes(targetFile.moduleId);
+      if (forbidden)
         return {
-          from: {
-            functionId: `file:${sourceFile.path}`,
-            functionName: path.basename(sourceFile.path),
-            file: sourceFile.path,
-            moduleId: sourceFile.moduleId,
-            moduleName: this.moduleNames.get(sourceFile.moduleId) ?? sourceFile.moduleId
-          },
-          to: {
-            functionId: `file:${targetFile.path}`,
-            functionName: path.basename(targetFile.path),
-            file: targetFile.path,
-            moduleId: targetFile.moduleId,
-            moduleName: this.moduleNames.get(targetFile.moduleId) ?? targetFile.moduleId
-          },
+          from: { functionId: `file:${sourceFile.path}`, functionName: path.basename(sourceFile.path), file: sourceFile.path, moduleId: sourceFile.moduleId, moduleName: this.moduleNames.get(sourceFile.moduleId) ?? sourceFile.moduleId },
+          to: { functionId: `file:${targetFile.path}`, functionName: path.basename(targetFile.path), file: targetFile.path, moduleId: targetFile.moduleId, moduleName: this.moduleNames.get(targetFile.moduleId) ?? targetFile.moduleId },
           rule: rule.raw,
           severity: "error"
         };
-      }
     }
     return null;
   }
-  /** Return all cross-module call pairs (useful for generating allow rules) */
   allCrossModuleCalls() {
     const counts = /* @__PURE__ */ new Map();
     for (const fn of Object.values(this.lock.functions)) {
       for (const calleeId of fn.calls) {
         const callee = this.lock.functions[calleeId];
-        if (!callee || fn.moduleId === callee.moduleId)
-          continue;
-        const key = `${fn.moduleId}\u2192${callee.moduleId}`;
-        counts.set(key, (counts.get(key) ?? 0) + 1);
-      }
-    }
-    for (const file of Object.values(this.lock.files)) {
-      if (!file.imports)
-        continue;
-      for (const importedPath of file.imports) {
-        const importedFile = this.lock.files[importedPath];
-        if (!importedFile || file.moduleId === importedFile.moduleId)
+        if (!callee || fn.moduleId === callee.moduleId || fn.moduleId === "unknown" || callee.moduleId === "unknown")
           continue;
-        const key = `${file.moduleId}\u2192${importedFile.moduleId}`;
+        const key = `${fn.moduleId}>${callee.moduleId}`;
         counts.set(key, (counts.get(key) ?? 0) + 1);
       }
     }
     return [...counts.entries()].map(([key, count]) => {
-      const [from, to] = key.split("\u2192");
+      const [from, to] = key.split(">");
       return { from, to, count };
     }).sort((a, b) => b.count - a.count);
   }
 };
 
+// ../core/dist/parser/tree-sitter/parser.js
+var import_node_module = require("node:module");
+var import_meta = {};
+var getRequire = () => {
+  if (typeof require !== "undefined")
+    return require;
+  return (0, import_node_module.createRequire)(import_meta.url);
+};
+var _require = getRequire();
+var ParserModule = _require("web-tree-sitter");
+var Parser = ParserModule.Parser || ParserModule;
+
 // ../core/dist/graph/impact-analyzer.js
 var ImpactAnalyzer = class {
   graph;
@@ -237190,7 +237156,7 @@ var MikkContractSchema = external_exports.object({
     description: external_exports.string(),
     language: external_exports.string(),
     framework: external_exports.string().optional(),
-    entryPoints: external_exports.array(external_exports.string())
+    entryPoints: external_exports.array(external_exports.string()).default([])
   }),
   declared: external_exports.object({
     modules: external_exports.array(MikkModuleSchema),
@@ -237317,7 +237283,7 @@ var ContractReader = class {
     } catch {
       throw new ContractNotFoundError(contractPath);
     }
-    const json = JSON.parse(content);
+    const json = JSON.parse(content.replace(/^\uFEFF/, ""));
     const result = MikkContractSchema.safeParse(json);
     if (!result.success) {
       const errors = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
@@ -237339,7 +237305,7 @@ var LockReader = class {
     } catch {
       throw new LockNotFoundError();
     }
-    const json = JSON.parse(content);
+    const json = JSON.parse(content.replace(/^\uFEFF/, ""));
     const hydrated = hydrateLock(json);
     const result = MikkLockSchema.safeParse(hydrated);
     if (!result.success) {
@@ -237663,6 +237629,106 @@ var AdrManager = class {
 // ../core/dist/hash/hash-store.js
 var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
 
+// ../core/dist/search/bm25.js
+var K1 = 1.2;
+var B = 0.75;
+var BM25Index = class {
+  documents = [];
+  documentFrequency = /* @__PURE__ */ new Map();
+  // term → how many docs contain it
+  avgDocLength = 0;
+  /** Clear the index */
+  clear() {
+    this.documents = [];
+    this.documentFrequency.clear();
+    this.avgDocLength = 0;
+  }
+  /** Add a document with pre-tokenized terms */
+  addDocument(id, tokens) {
+    const normalizedTokens = tokens.map((t) => t.toLowerCase());
+    this.documents.push({ id, tokens: normalizedTokens, length: normalizedTokens.length });
+    const uniqueTerms = new Set(normalizedTokens);
+    for (const term of uniqueTerms) {
+      this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+    }
+    this.avgDocLength = this.documents.reduce((sum, d) => sum + d.length, 0) / this.documents.length;
+  }
+  /** Search the index and return ranked results */
+  search(query, limit = 20) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0 || this.documents.length === 0)
+      return [];
+    const N = this.documents.length;
+    const results = [];
+    for (const doc of this.documents) {
+      let score = 0;
+      for (const term of queryTokens) {
+        const df = this.documentFrequency.get(term) ?? 0;
+        if (df === 0)
+          continue;
+        const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+        let tf = 0;
+        for (const t of doc.tokens) {
+          if (t === term)
+            tf++;
+        }
+        const tfNorm = tf * (K1 + 1) / (tf + K1 * (1 - B + B * (doc.length / this.avgDocLength)));
+        score += idf * tfNorm;
+      }
+      if (score > 0) {
+        results.push({ id: doc.id, score });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+  }
+};
+function reciprocalRankFusion(...rankedLists) {
+  const K = 60;
+  const scores = /* @__PURE__ */ new Map();
+  for (const list of rankedLists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const item = list[rank];
+      scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (K + rank + 1));
+    }
+  }
+  return [...scores.entries()].map(([id, score]) => ({ id, score })).sort((a, b) => b.score - a.score);
+}
+function tokenize(text) {
+  const tokens = [];
+  const words = text.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+  for (const word of words) {
+    const camelParts = word.replace(/([a-z])([A-Z])/g, "$1 $2").split(" ");
+    for (const part of camelParts) {
+      const lower = part.toLowerCase();
+      if (lower.length >= 2) {
+        tokens.push(lower);
+      }
+    }
+  }
+  return tokens;
+}
+function buildFunctionTokens(fn) {
+  const parts = [];
+  parts.push(...tokenize(fn.name));
+  parts.push(...tokenize(fn.name));
+  const filename = fn.file.split("/").pop() ?? fn.file;
+  parts.push(...tokenize(filename.replace(/\.[^.]+$/, "")));
+  if (fn.purpose) {
+    parts.push(...tokenize(fn.purpose));
+  }
+  if (fn.params) {
+    for (const p of fn.params) {
+      parts.push(...tokenize(p.name));
+      parts.push(...tokenize(p.type));
+    }
+  }
+  if (fn.returnType) {
+    parts.push(...tokenize(fn.returnType));
+  }
+  return parts;
+}
+
 // ../core/dist/utils/fs.js
 var import_fast_glob = __toESM(require_out4(), 1);
 
@@ -238486,7 +238552,7 @@ var SemanticSearcher = class _SemanticSearcher {
   }
   /**
    * Build (or load from cache) embeddings for every function in the lock.
-   * Safe to call on every MCP request — cache hit is O(1) disk read.
+   * Safe to call on every MCP request -- cache hit is O(1) disk read.
    */
   async index(lock) {
     const fingerprint = lockFingerprint(lock);
@@ -238593,6 +238659,38 @@ var IntentSchema = external_exports.object({
 // src/tools.ts
 var projectCache = /* @__PURE__ */ new Map();
 var CACHE_TTL_MS = 3e4;
+var _CPT = 4;
+var _ALC = 42;
+var _tallies = /* @__PURE__ */ new Map();
+function _tally(r) {
+  let t = _tallies.get(r);
+  if (!t) {
+    t = { calls: 0, used: 0, raw: 0, saved: 0, start: Date.now() };
+    _tallies.set(r, t);
+  }
+  return t;
+}
+function _tok(o) {
+  return Math.max(1, Math.round(JSON.stringify(o).length / _CPT));
+}
+function _fileTok(lock, fp) {
+  const fs22 = Object.values(lock.functions).filter((f) => f.file === fp);
+  const ln = fs22.length > 0 ? Math.max(...fs22.map((f) => f.endLine)) : 80;
+  return Math.round(ln * _ALC / _CPT);
+}
+function _filesTok(lock, fps) {
+  return fps.reduce((s, f) => s + _fileTok(lock, f), 0);
+}
+function _track(root, raw, resp) {
+  const used = _tok(resp);
+  const saved = Math.max(0, raw - used);
+  const t = _tally(root);
+  t.calls++;
+  t.used += used;
+  t.raw += raw;
+  t.saved += saved;
+  return { used, raw, saved, sessionSaved: t.saved, sessionCalls: t.calls };
+}
 var semanticSearchers = /* @__PURE__ */ new Map();
 function getSemanticSearcher(projectRoot) {
   let s = semanticSearchers.get(projectRoot);
@@ -238603,9 +238701,17 @@ function getSemanticSearcher(projectRoot) {
   return s;
 }
 function registerTools(server2, projectRoot) {
+  server2.tool(
+    "mikk_test_tool",
+    "A simple test tool that returns a static message.",
+    {},
+    async () => {
+      return { content: [{ type: "text", text: "Mikk test tool executed successfully." }] };
+    }
+  );
   server2.tool(
     "mikk_get_project_overview",
-    "Get a high-level overview of the project: modules, function counts, file counts, tech stack",
+    "Get a high-level overview: modules, function counts, file counts, constraints. WHEN TO USE: When you need raw project stats. For session start, prefer mikk_get_session_context instead. AFTER THIS: Use mikk_query_context with your task, or mikk_list_modules to drill into a module.",
     {},
     async () => {
       const { contract, lock, staleness } = await loadContractAndLock(projectRoot);
@@ -238632,12 +238738,14 @@ function registerTools(server2, projectRoot) {
         warning: staleness,
         hint: "Next: Use mikk_query_context with your task description, or mikk_list_modules to explore the architecture."
       };
+      const _rawOverview = Math.min(15, Object.keys(lock.files).length) * Math.round(80 * _ALC / _CPT);
+      overview.tokens = _track(projectRoot, _rawOverview, overview);
       return { content: [{ type: "text", text: JSON.stringify(overview, null, 2) }] };
     }
   );
   server2.tool(
     "mikk_query_context",
-    "Ask an architecture question \u2014 returns graph-traced context with relevant functions, files, and call chains. Use this to understand how code flows through the project.",
+    "Ask an architecture question \xC3\xA2\xE2\u201A\xAC\xC2\x9D returns graph-traced context with relevant functions, files, and call chains. Use this to understand how code flows through the project.",
     {
       question: external_exports.string().describe("The architecture question or task description"),
       maxHops: external_exports.number().optional().default(4).describe("Graph traversal depth (default: 4)"),
@@ -238674,14 +238782,20 @@ function registerTools(server2, projectRoot) {
       const warning = staleness ? `
 
 ${staleness}` : "";
+      const _rawQC = (tokenBudget ?? 6e3) * 3;
+      const _tokQC = _track(projectRoot, _rawQC, output);
+      const tokLine = `
+
+---
+// tokens: ${JSON.stringify(_tokQC)}`;
       return {
-        content: [{ type: "text", text: output + warning + "\n\n---\nHint: Use mikk_before_edit on any files you plan to modify, then mikk_impact_analysis to see the full blast radius." }]
+        content: [{ type: "text", text: output + warning + "\n\n---\nHint: Use mikk_before_edit on any files you plan to modify, then mikk_impact_analysis to see the full blast radius." + tokLine }]
       };
     }
   );
   server2.tool(
     "mikk_impact_analysis",
-    "Analyze the blast radius of changing a specific file. Returns which functions and modules would be impacted.",
+    "Analyze the blast radius of changing a file. Returns impacted functions classified by severity (critical/high/medium/low). WHEN TO USE: Before refactoring, renaming, or modifying shared code. AFTER THIS: Use mikk_get_function_detail on critical/high items to review them.",
     {
       file: external_exports.string().describe("The file path (relative to project root) to analyze impact for")
     },
@@ -238728,12 +238842,55 @@ ${staleness}` : "";
         warning: staleness,
         hint: "Next: Use mikk_get_function_detail on critical/high items to review them. Then mikk_before_edit to validate your planned changes."
       };
+      const _rawIA = _fileTok(lock, normalizedFile) + result.impacted.length * Math.round(40 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawIA, response);
+      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "mikk_search_functions",
+    "Search for functions by name or ID using a hybrid BM25+substring search. WHEN TO USE: When you need to find a function but are unsure of its exact name or location. AFTER THIS: Use mikk_get_function_detail to get more information about a specific function.",
+    {
+      query: external_exports.string().describe("The search query for function names or IDs"),
+      limit: external_exports.number().optional().default(10).describe("Maximum number of results to return")
+    },
+    async ({ query, limit }) => {
+      const { lock, staleness } = await loadContractAndLock(projectRoot);
+      const allFunctions = Object.values(lock.functions);
+      const queryLower = query.toLowerCase();
+      const substringMatches = allFunctions.filter((fn) => fn.name.toLowerCase().includes(queryLower) || fn.id.toLowerCase().includes(queryLower)).map((fn, i) => ({ id: fn.id, score: 100 - i }));
+      const bm25 = new BM25Index();
+      for (const fn of allFunctions) {
+        bm25.addDocument(fn.id, buildFunctionTokens(fn));
+      }
+      const bm25Matches = bm25.search(query, limit * 2);
+      const fused = reciprocalRankFusion(substringMatches, bm25Matches);
+      const matches = fused.slice(0, limit).map((result) => {
+        const fn = lock.functions[result.id];
+        if (!fn) return null;
+        return {
+          name: fn.name,
+          file: fn.file,
+          module: fn.moduleId,
+          exported: fn.isExported,
+          lines: `${fn.startLine}-${fn.endLine}`,
+          relevance: Math.round(result.score * 1e4) / 1e4
+        };
+      }).filter(Boolean);
+      if (matches.length === 0) {
+        return { content: [{ type: "text", text: `No functions matching "${query}" found.` }] };
+      }
+      const response = {
+        matches,
+        searchMethod: "hybrid (BM25 + substring via RRF)",
+        warning: staleness
+      };
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
   server2.tool(
     "mikk_before_edit",
-    "Call this BEFORE editing any file. Returns the blast radius, exported functions at risk, architectural constraint violations, and circular dependency warnings. This is your safety check.",
+    "MANDATORY: Call BEFORE editing any file. Returns blast radius, exported functions at risk, constraint violations (6 rule types), and circular dependency warnings. WHEN TO USE: ALWAYS before modifying files. AFTER THIS: If constraintStatus is fail, redesign your approach. If pass, proceed with edits. TIP: Pass multiple files for combined blast radius.",
     {
       files: external_exports.array(external_exports.string()).describe("The file paths (relative to project root) you are about to edit")
     },
@@ -238772,7 +238929,7 @@ ${staleness}` : "";
           rule: v.rule,
           from: `${v.from.moduleName}::${v.from.functionName}`,
           to: `${v.to.moduleName}::${v.to.functionName}`,
-          message: `\u274C ${v.from.moduleName}::${v.from.functionName} \u2192 ${v.to.moduleName}::${v.to.functionName} violates: "${v.rule}"`
+          message: `${v.from.moduleName}::${v.from.functionName} -> ${v.to.moduleName}::${v.to.functionName} violates: "${v.rule}"`
         }));
         const circularWarnings = detectCircularDeps(fileFns, lock);
         fileReports[file] = {
@@ -238796,14 +238953,16 @@ ${staleness}` : "";
         constraintStatus: totalViolations === 0 ? "pass" : "fail",
         files: fileReports,
         warning: staleness,
-        hint: totalViolations > 0 ? "\u26A0\uFE0F Constraint violations detected! Review the violations before proceeding. Use mikk_get_constraints for full rule context." : "All constraints satisfied. If safe, proceed with your edits."
+        hint: totalViolations > 0 ? "\xC3\u201A\xC2\x8F Constraint violations detected! Review the violations before proceeding. Use mikk_get_constraints for full rule context." : "All constraints satisfied. If safe, proceed with your edits."
       };
+      const _rawBE = _filesTok(lock, filesToEdit) * 4;
+      response.tokens = _track(projectRoot, _rawBE, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
   server2.tool(
     "mikk_list_modules",
-    "List all declared modules with their file/function counts and descriptions",
+    "List all declared modules with file counts, function counts, entry points, and descriptions. WHEN TO USE: To explore the project structure. Good starting point after mikk_get_session_context. AFTER THIS: Use mikk_get_module_detail with a specific moduleId.",
     {},
     async () => {
       const { contract, lock, staleness } = await loadContractAndLock(projectRoot);
@@ -238829,7 +238988,7 @@ ${staleness}` : "";
   );
   server2.tool(
     "mikk_get_module_detail",
-    "Get detailed information about a specific module: its functions, files, exported API, and internal call graph",
+    "Deep dive into a single module: all functions, files, exported API surface, internal call graph. WHEN TO USE: After mikk_list_modules to understand a specific module. AFTER THIS: Use mikk_get_function_detail for specific functions, or mikk_before_edit if modifying files in this module.",
     {
       moduleId: external_exports.string().describe('The module ID (e.g., "packages-core", "lib-auth")')
     },
@@ -238868,7 +239027,7 @@ ${staleness}` : "";
   );
   server2.tool(
     "mikk_get_function_detail",
-    "Get detailed info about a specific function by name: params, return type, call graph, error handling, etc.",
+    "360-degree view of a function: params, return type, source body, call graph (who calls it + what it calls), error handling, edge cases. WHEN TO USE: When you need to understand a specific function in depth. AFTER THIS: Use mikk_find_usages to see all callers. TIP: Pass full qualified name (e.g. GraphBuilder.build) for class methods.",
     {
       name: external_exports.string().describe('Function name to search for (e.g., "parseFiles", "GraphBuilder.build")')
     },
@@ -238914,36 +239073,9 @@ ${staleness}` : "";
       return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
     }
   );
-  server2.tool(
-    "mikk_search_functions",
-    "Search for functions by name pattern (substring match). Returns matching function names, files, and modules.",
-    {
-      query: external_exports.string().describe("Search query \u2014 matched against function names (case-insensitive)"),
-      limit: external_exports.number().optional().default(20).describe("Max results to return (default: 20)")
-    },
-    async ({ query, limit }) => {
-      const { lock, staleness } = await loadContractAndLock(projectRoot);
-      const queryLower = query.toLowerCase();
-      const matches = Object.values(lock.functions).filter((fn) => fn.name.toLowerCase().includes(queryLower) || fn.id.toLowerCase().includes(queryLower)).slice(0, limit).map((fn) => ({
-        name: fn.name,
-        file: fn.file,
-        module: fn.moduleId,
-        exported: fn.isExported,
-        lines: `${fn.startLine}-${fn.endLine}`
-      }));
-      if (matches.length === 0) {
-        return { content: [{ type: "text", text: `No functions matching "${query}" found.` }] };
-      }
-      const response = {
-        matches,
-        warning: staleness
-      };
-      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
-    }
-  );
   server2.tool(
     "mikk_semantic_search",
-    "Find functions by meaning, not by name. Uses local vector embeddings (Xenova/all-MiniLM-L6-v2) to rank functions by semantic similarity to a natural-language query. Requires @xenova/transformers to be installed.",
+    'Find functions by meaning using local vector embeddings. Query "validate JWT" returns verifyToken ranked by cosine similarity. WHEN TO USE: When you dont know the function name but know what it does. Complements mikk_search_functions (keyword). AFTER THIS: Use mikk_get_function_detail on top matches. Requires @xenova/transformers (22MB model, downloads once).',
     {
       query: external_exports.string().describe('Natural-language description of what you are looking for (e.g. "validate a JWT token", "send an email notification")'),
       topK: external_exports.number().optional().default(10).describe("Number of results to return (default: 10)")
@@ -238955,7 +239087,7 @@ ${staleness}` : "";
           content: [{
             type: "text",
             text: [
-              "\u274C Semantic search requires @xenova/transformers.",
+              "\xC3\u201A\xC2\x9D\xC3\u2026\xE2\u20AC\u2122 Semantic search requires @xenova/transformers.",
               "",
               "Install it in your project root:",
               "  npm install @xenova/transformers",
@@ -238984,7 +239116,7 @@ ${staleness}` : "";
   );
   server2.tool(
     "mikk_get_constraints",
-    "Get all declared architectural constraints and design decisions for this project",
+    "Get all architectural constraints and ADRs. WHEN TO USE: Before cross-module changes, or when mikk_before_edit reports violations. Understand WHY a constraint exists. AFTER THIS: Use mikk_manage_adr to add/update decisions. 6 constraint types: no-import, must-use, no-call, layer, naming, max-files.",
     {},
     async () => {
       const { contract, staleness } = await loadContractAndLock(projectRoot);
@@ -238999,7 +239131,7 @@ ${staleness}` : "";
   );
   server2.tool(
     "mikk_get_file",
-    "Read the raw source content of any file in the project. Use this to see the actual code before editing.",
+    "Read raw source of a file. TIP: Prefer mikk_read_file with function names to save tokens. WHEN TO USE: When you need entire file content (config files, small files). AFTER THIS: Use mikk_before_edit before making changes.",
     {
       file: external_exports.string().describe('File path relative to project root (e.g., "src/auth/verify.ts")')
     },
@@ -239033,7 +239165,7 @@ ${content}`
   );
   server2.tool(
     "mikk_find_usages",
-    "Find everything that calls a specific function. Essential before renaming or changing a function signature.",
+    "Find every function that calls a specific function. Essential before renaming or changing signatures. WHEN TO USE: Before renaming, refactoring, or changing a function interface. AFTER THIS: Review each caller to ensure your change wont break them. Use mikk_read_file to see caller code.",
     {
       name: external_exports.string().describe("Function name to find callers of")
     },
@@ -239067,7 +239199,7 @@ ${content}`
   );
   server2.tool(
     "mikk_get_routes",
-    "Get all detected HTTP routes (Express/Koa/Hono style) with their methods, paths, handlers, and middlewares",
+    "Get all detected HTTP routes with methods, paths, handlers, and middleware chains. WHEN TO USE: When working on API endpoints. Shows Express/Koa/Hono route registrations detected from AST. AFTER THIS: Use mikk_get_function_detail on a handler to see its implementation.",
     {},
     async () => {
       const { lock, staleness } = await loadContractAndLock(projectRoot);
@@ -239084,7 +239216,7 @@ ${content}`
   );
   server2.tool(
     "mikk_dead_code",
-    "Detect dead code \u2014 functions with zero callers after exempting exports, entry points, route handlers, tests, and constructors. Use this before refactoring or cleanup.",
+    "Detect dead code \xC3\xA2\xE2\u201A\xAC\xC2\x9D functions with zero callers after exempting exports, entry points, route handlers, tests, and constructors. Use this before refactoring or cleanup.",
     {
       moduleId: external_exports.string().optional().describe("Filter results to a specific module ID")
     },
@@ -239109,7 +239241,7 @@ ${content}`
   );
   server2.tool(
     "mikk_manage_adr",
-    "Manage Architectural Decision Records (ADRs) in mikk.json. Actions: list, get, add, update, remove. ADRs document WHY architectural constraints exist.",
+    "CRUD for Architectural Decision Records (ADRs) in mikk.json. Actions: list, get, add, update, remove. WHEN TO USE: When making architectural changes \xC3\xA2\xE2\u201A\xAC\xE2\u20AC\x9D document WHY so future AI agents understand. AFTER THIS: ADRs automatically surface in mikk_query_context responses. Required for add: id, title, reason.",
     {
       action: external_exports.enum(["list", "get", "add", "update", "remove"]).describe("The CRUD action to perform"),
       id: external_exports.string().optional().describe("ADR id (required for get, update, remove)"),
@@ -239166,7 +239298,7 @@ ${content}`
   );
   server2.tool(
     "mikk_get_changes",
-    "Detect files that have changed since last analysis. Call this at the start of every AI session to understand what's different. Returns added, modified, and deleted files.",
+    "Detect files added, modified, and deleted since last mikk analyze. WHEN TO USE: At session start (after mikk_get_session_context), or after making edits to see what drifted. AFTER THIS: Run mikk analyze to update the lock, then mikk_impact_analysis on modified files. Uses SHA-256 hash comparison for accurate drift detection.",
     {},
     async () => {
       const { lock, staleness } = await loadContractAndLock(projectRoot);
@@ -239212,12 +239344,14 @@ ${content}`
         warning: staleness,
         hint: modified.length + added.length > 0 ? "Run `mikk analyze` to update the lock file with these changes." : "Codebase is in sync with the lock file."
       };
+      const _rawGC = Math.min(50, Object.keys(lock.files).length) * Math.round(60 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawGC, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
   server2.tool(
     "mikk_read_file",
-    "Read file content scoped to specific functions. Returns function bodies with metadata headers (params, returnType, calledBy) instead of dumping the whole file. Use this instead of mikk_get_file when you know which functions you need.",
+    "Read file scoped to specific functions. Returns bodies with metadata headers (params, calls, calledBy). WHEN TO USE: When you know which functions you need \xC3\xA2\xE2\u201A\xAC\xE2\u20AC\x9D saves tokens vs mikk_get_file. AFTER THIS: Use mikk_before_edit before making changes. TIP: This is the preferred way to read code \xC3\xA2\xE2\u201A\xAC\xE2\u20AC\x9D always specify function names when possible.",
     {
       file: external_exports.string().describe("File path relative to project root"),
       functions: external_exports.array(external_exports.string()).optional().describe("Function names to extract. If omitted, returns the whole file.")
@@ -239257,11 +239391,11 @@ ${content}` }]
           (f) => (f.name === fnName || f.name.endsWith(`.${fnName}`)) && (f.file === normalizedFile || f.file.endsWith("/" + normalizedFile))
         );
         if (!fn) {
-          sections.push(`// \u274C Function "${fnName}" not found in ${file}`);
+          sections.push(`// \xC3\u201A\xC2\x9D\xC3\u2026\xE2\u20AC\u2122 Function "${fnName}" not found in ${file}`);
           continue;
         }
         const header = [
-          `// \u2500\u2500 ${fn.name} \u2500\u2500`,
+          `//  ${fn.name} `,
           `// File: ${fn.file}:${fn.startLine}-${fn.endLine}`,
           `// Module: ${fn.moduleId}`,
           fn.purpose ? `// Purpose: ${fn.purpose}` : null,
@@ -239280,12 +239414,15 @@ ${body}`);
       const warningText = staleness ? `
 
 ${staleness}` : "";
-      return { content: [{ type: "text", text: output + warningText }] };
+      const _rawRF = _fileTok(lock, file.replace(/\\/g, "/"));
+      const _tokRF = _track(projectRoot, _rawRF, output);
+      return { content: [{ type: "text", text: output + warningText + `
+// tokens: ${JSON.stringify(_tokRF)}` }] };
     }
   );
   server2.tool(
     "mikk_get_session_context",
-    "One-shot context for AI session start. Combines project overview + recent changes + hot modules + constraint status in a single call. Call this at the beginning of every new AI conversation.",
+    "CALL THIS FIRST. One-shot context for session start: project overview + constraint status + hot modules + recently modified files + active decisions. WHEN TO USE: At the very beginning of every AI conversation. This is your onboarding. AFTER THIS: Use mikk_query_context with your task description, or mikk_get_changes for detailed drift.",
     {},
     async () => {
       const { contract, lock, staleness } = await loadContractAndLock(projectRoot);
@@ -239344,6 +239481,140 @@ ${staleness}` : "";
         warning: staleness,
         hint: changedCount > 0 ? `${changedCount} file(s) may have changed. Run \`mikk analyze\` for accurate results, or use mikk_get_changes for details.` : "Codebase is in sync. Use mikk_query_context with your task description to get started."
       };
+      const _rawSC = Math.min(20, Object.keys(lock.files).length) * Math.round(100 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawSC, response);
+      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "mikk_git_diff_impact",
+    "Map git diff hunks to affected symbols. Shows which functions were modified/added/deleted. WHEN TO USE: After commits/merges to understand symbol-level changes. AFTER THIS: Use mikk_impact_analysis on affected files.",
+    {
+      ref: external_exports.string().optional().default("HEAD~1").describe("Git ref to diff against (default: HEAD~1)"),
+      staged: external_exports.boolean().optional().default(false).describe("If true, diff staged changes only")
+    },
+    async ({ ref, staged }) => {
+      const { lock, staleness } = await loadContractAndLock(projectRoot);
+      try {
+        const diffArgs = staged ? "--cached" : ref;
+        const rawDiff = (0, import_node_child_process.execSync)(`git diff ${diffArgs} --unified=0 --no-color`, {
+          cwd: projectRoot,
+          encoding: "utf-8",
+          maxBuffer: 10 * 1024 * 1024
+        });
+        if (!rawDiff.trim()) {
+          return { content: [{ type: "text", text: "No changes found in git diff." }] };
+        }
+        const fileHunks = parseDiffHunks(rawDiff);
+        const affectedSymbols = [];
+        for (const hunk of fileHunks) {
+          const fileFns = Object.values(lock.functions).filter((fn) => fn.file === hunk.file || fn.file.endsWith(hunk.file));
+          const affected = fileFns.filter((fn) => hunk.changedLines.some((l) => l >= fn.startLine && l <= fn.endLine));
+          if (affected.length > 0 || hunk.isNew || hunk.isDeleted) {
+            affectedSymbols.push({
+              file: hunk.file,
+              type: hunk.isNew ? "added" : hunk.isDeleted ? "deleted" : "modified",
+              functions: affected.map((fn) => ({ name: fn.name, moduleId: fn.moduleId }))
+            });
+          }
+        }
+        const totalFns = affectedSymbols.reduce((s, f) => s + f.functions.length, 0);
+        return { content: [{ type: "text", text: JSON.stringify({
+          summary: `${affectedSymbols.length} file(s), ${totalFns} function(s) affected`,
+          affectedSymbols,
+          warning: staleness
+        }, null, 2) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Git diff failed: ${err.message}` }], isError: true };
+      }
+    }
+  );
+  server2.tool(
+    "mikk_rename",
+    "Plan a coordinated multi-file rename. Finds all call sites and import locations for a function and provides a step-by-step edit plan. WHEN TO USE: Before renaming any function \xC3\xA2\xE2\u201A\xAC\xE2\u20AC\x9D ensures you update ALL call sites. AFTER THIS: Execute the edit plan, then run mikk analyze.",
+    {
+      functionName: external_exports.string().describe("The current function name to rename"),
+      newName: external_exports.string().describe("The desired new name")
+    },
+    async ({ functionName, newName }) => {
+      const { lock, staleness } = await loadContractAndLock(projectRoot);
+      const targetFn = Object.values(lock.functions).find(
+        (fn) => fn.name === functionName || fn.id.endsWith(`:${functionName}`)
+      );
+      if (!targetFn) {
+        return {
+          content: [{
+            type: "text",
+            text: `Function "${functionName}" not found. Use mikk_search_functions to find the correct name.`
+          }],
+          isError: true
+        };
+      }
+      const callers = targetFn.calledBy.map((callerId) => lock.functions[callerId]).filter(Boolean).map((fn) => ({
+        callerName: fn.name,
+        file: fn.file,
+        module: fn.moduleId,
+        lineRange: `${fn.startLine}-${fn.endLine}`
+      }));
+      const filesImporting = Object.values(lock.files).filter(
+        (file) => file.imports?.some((imp) => imp.includes(functionName) || imp.includes(targetFn.file))
+      );
+      const instructions = [
+        `1. Rename definition in ${targetFn.file}:${targetFn.startLine}`,
+        ...callers.map((c, i) => `${i + 2}. Update call in ${c.file} (${c.callerName}, lines ${c.lineRange})`),
+        ...targetFn.isExported ? filesImporting.map((f, i) => `${callers.length + i + 2}. Update import in ${f.path}`) : [],
+        `${callers.length + (targetFn.isExported ? filesImporting.length : 0) + 2}. Run \`mikk analyze\` to update the lock`
+      ];
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            target: {
+              currentName: functionName,
+              newName,
+              file: targetFn.file,
+              line: targetFn.startLine,
+              module: targetFn.moduleId,
+              isExported: targetFn.isExported
+            },
+            callSites: callers,
+            importSites: filesImporting.map((f) => ({ file: f.path, module: f.moduleId })),
+            totalEdits: 1 + callers.length + filesImporting.length,
+            instructions,
+            warning: staleness
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server2.tool(
+    "mikk_token_stats",
+    "Show token savings for this session \u2014 how many tokens Mikk saved vs. the agent reading raw source files. WHEN TO USE: Any time. Useful at end of session to see cumulative efficiency. Returns per-session totals and cost estimates.",
+    {},
+    async () => {
+      const t = _tally(projectRoot);
+      const { lock } = await loadContractAndLock(projectRoot);
+      const totalFileLine = Object.values(lock.functions).reduce((s, f) => s + (f.endLine - f.startLine + 1), 0);
+      const fullCodebaseTok = Math.round(totalFileLine * _ALC / _CPT);
+      const elapsedMin = Math.round((Date.now() - t.start) / 6e4);
+      const response = {
+        session: {
+          calls: t.calls,
+          elapsedMinutes: elapsedMin
+        },
+        tokens: {
+          used: t.used,
+          rawWouldHaveCost: t.raw,
+          saved: t.saved,
+          savingsPercent: t.raw > 0 ? Math.round(t.saved / t.raw * 100) : 0
+        },
+        context: {
+          fullCodebaseTokens: fullCodebaseTok,
+          percentOfCodebaseRead: t.raw > 0 ? Math.round(t.used / fullCodebaseTok * 100) : 0,
+          note: "Full codebase = if agent read every tracked source line once"
+        },
+        interpretation: t.saved > 0 ? `Mikk saved ~${t.saved.toLocaleString()} tokens this session (${Math.round(t.saved / t.raw * 100)}% reduction). Roughly ${Math.round(t.saved / 1e3)}k tokens = ~${(t.saved * 3e-6).toFixed(3)} USD at GPT-4o rates.` : "No tools called yet this session."
+      };
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
@@ -239360,7 +239631,7 @@ async function loadContractAndLock(projectRoot) {
   const syncStatus = lock.syncState?.status ?? "unknown";
   let staleness = null;
   if (syncStatus === "drifted" || syncStatus === "conflict") {
-    staleness = `\u26A0\uFE0F Lock file is ${syncStatus}. Run \`mikk analyze\` for accurate results.`;
+    staleness = `\xC3\u201A\xC2\x8F Lock file is ${syncStatus}. Run \`mikk analyze\` for accurate results.`;
   }
   if (!staleness) {
     const fileEntries = Object.entries(lock.files);
@@ -239383,7 +239654,7 @@ async function loadContractAndLock(projectRoot) {
       }
     }
     if (mismatched > 0) {
-      staleness = `\u26A0\uFE0F STALE: ${mismatched} file(s) changed since last analysis (${mismatchedFiles.slice(0, 3).join(", ")}${mismatched > 3 ? "..." : ""}). Run \`mikk analyze\`.`;
+      staleness = `\xC3\u201A\xC2\x8F STALE: ${mismatched} file(s) changed since last analysis (${mismatchedFiles.slice(0, 3).join(", ")}${mismatched > 3 ? "..." : ""}). Run \`mikk analyze\`.`;
     }
   }
   const graph = buildGraphFromLock(lock);
@@ -239455,7 +239726,7 @@ function detectCircularDeps(fns, lock) {
         const cycleStart = cyclePath.indexOf(id);
         const cycle = cyclePath.slice(cycleStart).map((cid) => lock.functions[cid]?.name ?? cid);
         cycle.push(lock.functions[id]?.name ?? id);
-        warnings.push(`\u26A0\uFE0F Circular: ${cycle.join(" \u2192 ")}`);
+        warnings.push(`\xC3\u201A\xC2\x8F Circular: ${cycle.join(" \xC3\xA2\xE2\u201A\xAC\xC2\xA0\xC3\xA2\xE2\u201A\xAC\xE2\u201E\xA2 ")}`);
         return true;
       }
       if (visited.has(id)) return false;
@@ -239501,6 +239772,35 @@ function isSourceFile(filePath) {
   const ext = path4.extname(filePath);
   return [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".go", ".py"].includes(ext);
 }
+function parseDiffHunks(diff) {
+  const files = /* @__PURE__ */ new Map();
+  let currentFile = "";
+  let nextIsNew = false;
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("--- ") && line.includes("/dev/null")) {
+      nextIsNew = true;
+    } else if (line.startsWith("+++ ")) {
+      currentFile = line.slice(6);
+      if (currentFile !== "/dev/null" && !files.has(currentFile)) {
+        files.set(currentFile, { changedLines: [], isNew: nextIsNew, isDeleted: false });
+      }
+      if (currentFile === "/dev/null") {
+        const prev = [...files.keys()].pop();
+        if (prev) files.get(prev).isDeleted = true;
+      }
+      nextIsNew = false;
+    } else if (line.startsWith("@@ ") && currentFile && files.has(currentFile)) {
+      const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+      if (match) {
+        const start = parseInt(match[1], 10);
+        const count = parseInt(match[2] ?? "1", 10);
+        const entry = files.get(currentFile);
+        for (let i = 0; i < count; i++) entry.changedLines.push(start + i);
+      }
+    }
+  }
+  return [...files.entries()].map(([file, data]) => ({ file, ...data }));
+}
 
 // src/resources.ts
 var path5 = __toESM(require("node:path"), 1);
@@ -239561,7 +239861,7 @@ async function safeRead(filePath) {
 }
 
 // src/server.ts
-var VERSION = true ? "1.8.1" : "0.0.0-dev";
+var VERSION = true ? "1.9.1" : "0.0.0-dev";
 function createMikkMcpServer(projectRoot) {
   const server2 = new McpServer({
     name: "mikk",
@@ -239671,9 +239971,6 @@ async function startStdioServer() {
   const transport = new StdioServerTransport();
   await server2.connect(transport);
 }
-
-// src/index.ts
-startStdioServer();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createMikkMcpServer,