@ajdev0/token-shrink 2.0.1 → 2.0.3

package/dist/mcp.cjs

@@ -184,6 +184,8 @@ __export(mcp_exports, {
   CLINE_RULE_SENTINEL: () => CLINE_RULE_SENTINEL,
   CURSOR_RULE_PATH: () => CURSOR_RULE_PATH,
   RULE_TARGET_PATH: () => RULE_TARGET_PATH,
+  RULE_VERSION: () => RULE_VERSION,
+  RULE_VERSION_MARKER: () => RULE_VERSION_MARKER,
   createAutoRule: () => createAutoRule,
   createCursorRule: () => createCursorRule,
   startMcpServer: () => startMcpServer
@@ -192,104 +194,180 @@ module.exports = __toCommonJS(mcp_exports);
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_zod = require("zod");
-var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_fs7 = __toESM(require("fs"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
 
 // src/server/assembler.ts
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
-function assemble(activeFilePath, cache, opts = {}) {
-  const { includeStats = false, maxSkeletons = 50, pruneActiveFile = false } = opts;
-  const abs = import_node_path.default.resolve(activeFilePath);
-  const activeSource = import_node_fs.default.existsSync(abs) ? import_node_fs.default.readFileSync(abs, "utf8") : "";
-  const activeEntry = cache.get(abs);
+var MARKDOWN_OVERHEAD_TOKENS = 40;
+function assembleMany(activeFiles, cache, opts = {}) {
+  const {
+    includeStats = false,
+    maxSkeletons = 50,
+    maxTokens,
+    pruneActiveFile = false
+  } = opts;
+  const absList = activeFiles.map((p) => import_node_path.default.resolve(p));
+  const sources = absList.map((abs) => {
+    try {
+      return import_node_fs.default.readFileSync(abs, "utf8");
+    } catch {
+      return "";
+    }
+  });
+  const activeSet = new Set(absList);
+  const ring0Texts = absList.map((abs, i) => {
+    const entry = cache.get(abs);
+    return pruneActiveFile && entry ? entry.skeleton : sources[i];
+  });
   const included = [];
   const unresolved = [];
   const seen = /* @__PURE__ */ new Set();
-  if (activeEntry) {
-    for (const imp of activeEntry.imports) {
-      const entry = cache.get(imp);
-      if (!entry) {
-        unresolved.push(imp);
-        continue;
-      }
-      if (seen.has(imp)) continue;
-      seen.add(imp);
-      included.push({ filePath: imp, language: entry.language });
-      if (included.length >= maxSkeletons) break;
-    }
-  }
-  if (!activeEntry && activeSource) {
-    const specifiers = extractSpecifiers(activeSource);
-    for (const spec of specifiers) {
-      const resolved = resolveLocal(abs, spec);
-      if (!resolved) {
-        unresolved.push(spec);
-        continue;
-      }
-      if (seen.has(resolved)) continue;
-      seen.add(resolved);
-      const cached = cache.get(resolved);
-      included.push({ filePath: resolved, language: cached?.language ?? null });
-      if (included.length >= maxSkeletons) break;
+  const addUnresolved = (p) => {
+    if (!unresolved.includes(p)) unresolved.push(p);
+  };
+  const addIncluded = (p, allowUncached) => {
+    if (seen.has(p)) return;
+    const entry = cache.get(p);
+    if (!entry && !allowUncached) {
+      addUnresolved(p);
+      return;
     }
+    seen.add(p);
+    included.push({ filePath: p, language: entry?.language ?? null });
+  };
+  for (let i = 0; i < absList.length; i++) {
+    const abs = absList[i];
+    const entry = cache.get(abs);
+    if (entry) {
+      for (const imp of entry.imports) {
+        if (activeSet.has(imp)) continue;
+        addIncluded(imp, false);
+      }
+    } else if (sources[i]) {
+      for (const spec of extractSpecifiers(sources[i])) {
+        const resolved = resolveLocal(abs, spec);
+        if (!resolved) {
+          addUnresolved(spec);
+          continue;
+        }
+        if (activeSet.has(resolved)) continue;
+        addIncluded(resolved, true);
+      }
+    }
+  }
+  const ordered = maxTokens === void 0 ? included : rankByRelevance(included, cache);
+  const budget = maxTokens === void 0 ? void 0 : Math.max(0, maxTokens - MARKDOWN_OVERHEAD_TOKENS);
+  const selected = [];
+  let trimmed = 0;
+  let dependencyTokens = 0;
+  for (const cand of ordered) {
+    if (selected.length >= maxSkeletons) break;
+    const entry = cache.get(cand.filePath);
+    const cost = entry ? approximateTokens(entry.skeleton) : 8;
+    if (budget !== void 0 && dependencyTokens + cost > budget) {
+      trimmed++;
+      continue;
+    }
+    selected.push(cand);
+    dependencyTokens += cost;
   }
+  const activeTokens = ring0Texts.reduce(
+    (acc, t) => acc + approximateTokens(t),
+    0
+  );
   const lines = [];
   lines.push("# Compressed Code Context", "");
-  lines.push(`Active file: \`${rel(abs)}\``, "");
-  lines.push("## Ring 0 \u2014 Active file (full text)", "");
-  const ring0 = pruneActiveFile && activeEntry ? activeEntry.skeleton : activeSource;
-  lines.push(`\`\`\`${ext(activeFilePath)}`);
-  lines.push(ring0.trim() || "(empty or unreadable file)");
-  lines.push("```", "");
+  if (absList.length === 1) {
+    lines.push(`Active file: \`${rel(absList[0])}\``, "");
+  } else {
+    lines.push("Active files:", "");
+    for (const p of absList) lines.push(`- \`${rel(p)}\``);
+    lines.push("");
+  }
   lines.push(
-    `## Ring 1 \u2014 Pruned dependencies (${included.length})`,
+    absList.length === 1 ? "## Ring 0 \u2014 Active file (full text)" : "## Ring 0 \u2014 Active files (full text)",
+    ""
+  );
+  for (let i = 0; i < absList.length; i++) {
+    if (absList.length > 1) lines.push(`### \`${rel(absList[i])}\``, "");
+    const body = ring0Texts[i].trim() || "(empty or unreadable file)";
+    lines.push(`\`\`\`${ext(absList[i])}`, body, "```", "");
+  }
+  lines.push(
+    `## Ring 1 \u2014 Pruned dependencies (${selected.length})`,
     "",
     "Implementation bodies removed; type signatures, interfaces and exports retained.",
     ""
   );
-  if (included.length === 0) {
+  if (selected.length === 0) {
     lines.push("_No local dependency skeletons available._", "");
   }
-  for (const inc of included) {
+  for (const inc of selected) {
     const entry = cache.get(inc.filePath);
     const label = rel(inc.filePath);
     lines.push(`### \`${label}\``, "");
     if (entry) {
-      lines.push(`\`\`\`${ext(inc.filePath)}`);
-      lines.push(entry.skeleton.trim());
-      lines.push("```", "");
+      lines.push(`\`\`\`${ext(inc.filePath)}`, entry.skeleton.trim(), "```", "");
     } else {
       lines.push("_Unindexed file._", "");
     }
   }
+  if (maxTokens !== void 0 && trimmed > 0) {
+    lines.push(
+      `_Note: token budget of ${maxTokens} excluded ${trimmed} lower-priority dependenc${trimmed === 1 ? "y" : "ies"}._`,
+      ""
+    );
+  }
   if (unresolved.length > 0) {
     lines.push("## Unresolved imports", "");
     for (const u of unresolved) lines.push(`- \`${u}\``);
     lines.push("");
   }
   if (includeStats) {
-    const depTokens = included.reduce(
-      (acc, inc) => {
-        const e = cache.get(inc.filePath);
-        return e ? acc + approximateTokens(e.skeleton) : acc;
-      },
-      0
-    );
-    lines.push("---", "");
+    const budgetNote = maxTokens !== void 0 ? ` \xB7 budget ${maxTokens} (${trimmed} deps trimmed)` : "";
     lines.push(
-      `_Token estimate \u2014 active: ${approximateTokens(activeSource)} \xB7 pruned deps: ${depTokens}._`,
+      "---",
+      "",
+      `_Token estimate \u2014 active: ${activeTokens} \xB7 pruned deps: ${dependencyTokens}${budgetNote}._`,
       ""
     );
   }
   return {
     markdown: lines.join("\n"),
-    activeFilePath: abs,
-    activeSource,
-    included,
-    unresolved
+    activeFilePath: absList[0] ?? "",
+    activeFilePaths: absList,
+    activeSource: sources.join("\n"),
+    included: selected,
+    unresolved,
+    tokenStats: {
+      activeTokens,
+      dependencyTokens,
+      totalTokens: activeTokens + dependencyTokens,
+      ...maxTokens !== void 0 ? { budget: maxTokens } : {},
+      trimmed
+    }
   };
 }
+function rankByRelevance(candidates, cache) {
+  const fanIn = /* @__PURE__ */ new Map();
+  for (const entry of cache.values()) {
+    for (const imp of entry.imports) fanIn.set(imp, (fanIn.get(imp) ?? 0) + 1);
+  }
+  return candidates.map((cand, idx) => ({ cand, idx })).sort((a, b) => {
+    const fa = fanIn.get(a.cand.filePath) ?? 0;
+    const fb = fanIn.get(b.cand.filePath) ?? 0;
+    if (fa !== fb) return fb - fa;
+    const da = pathDepth(a.cand.filePath);
+    const db = pathDepth(b.cand.filePath);
+    if (da !== db) return da - db;
+    return a.idx - b.idx;
+  }).map((x) => x.cand);
+}
+function pathDepth(p) {
+  return p.split(/[/\\]+/).filter(Boolean).length;
+}
 function extractSpecifiers(source) {
   const found = [];
   const re = /(?:from\s+['"`]|import\s+['"`]|require\s*\(\s*['"`])([^'"`]+)['"`]/g;
@@ -346,12 +424,12 @@ function approximateTokens(text) {
 }
 
 // src/watcher/sync.ts
-var import_node_fs3 = __toESM(require("fs"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_fs4 = __toESM(require("fs"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 var import_node_crypto = require("crypto");
 var import_chokidar = __toESM(require("chokidar"), 1);
 
-// src/parser/pruner.ts
+// src/parser/analyze.ts
 var import_web_tree_sitter = __toESM(require("web-tree-sitter"), 1);
 var import_node_module = require("module");
 var import_node_path4 = __toESM(require("path"), 1);
@@ -426,7 +504,97 @@ async function getGrammar(spec, force = false) {
   return download(spec);
 }
 
-// src/parser/pruner.ts
+// src/parser/symbols.ts
+var KIND_BY_TYPE = {
+  // TypeScript / JavaScript / TSX / JSX
+  function_declaration: "function",
+  generator_function_declaration: "function",
+  function_expression: "function",
+  function_signature_item: "function",
+  method_definition: "method",
+  method_signature: "method",
+  class_declaration: "class",
+  abstract_class_declaration: "class",
+  interface_declaration: "interface",
+  enum_declaration: "enum",
+  type_alias_declaration: "type",
+  // Python
+  function_definition: "function",
+  class_definition: "class",
+  // Go
+  method_declaration: "method",
+  type_spec: "type",
+  // Rust
+  function_item: "function",
+  struct_item: "class",
+  enum_item: "enum",
+  trait_item: "interface",
+  type_item: "type",
+  // Java / Kotlin / PHP / Dart / Swift (best-effort generic names)
+  constructor_declaration: "method",
+  module_declaration: "class",
+  protocol_declaration: "interface"
+};
+var SIGNATURE_MAX = 200;
+function collectSymbols(root, source) {
+  const out = [];
+  const walk2 = (node) => {
+    const kind = KIND_BY_TYPE[node.type];
+    if (kind) {
+      const nameNode = node.childForFieldName("name");
+      if (nameNode && nameNode.text.trim()) {
+        out.push(symbolFrom(nameNode.text.trim(), kind, node.startIndex, node.endIndex, source));
+      }
+    } else if (node.type === "variable_declarator") {
+      const value = node.childForFieldName("value");
+      const valueType = value?.type;
+      if (valueType === "arrow_function" || valueType === "function_expression") {
+        const nameNode = node.childForFieldName("name");
+        if (nameNode && nameNode.text.trim()) {
+          out.push(
+            symbolFrom(nameNode.text.trim(), "arrow", node.startIndex, node.endIndex, source)
+          );
+        }
+      }
+    }
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child) walk2(child);
+    }
+  };
+  walk2(root);
+  return out;
+}
+function matchSymbols(symbols, query, kind) {
+  const q = query.trim();
+  if (!q) return [];
+  const pool = kind ? symbols.filter((s) => s.kind === kind) : symbols;
+  const byName = pool.filter((s) => s.name === q);
+  if (byName.length > 0) return byName;
+  const byNameCi = pool.filter((s) => s.name.toLowerCase() === q.toLowerCase());
+  if (byNameCi.length > 0) return byNameCi;
+  const lower = q.toLowerCase();
+  const bySubstring = pool.filter((s) => s.name.toLowerCase().includes(lower));
+  return bySubstring.length > 0 ? bySubstring : pool.filter((s) => (s.signature ?? "").toLowerCase().includes(lower));
+}
+function symbolFrom(name, kind, start, end, source) {
+  return {
+    name,
+    kind,
+    line: source.slice(0, start).split("\n").length,
+    start,
+    end,
+    signature: signaturePreview(source, start, end)
+  };
+}
+function signaturePreview(source, start, end) {
+  const nl = source.indexOf("\n", start);
+  const endOfLine = nl === -1 ? end : nl;
+  const first = source.slice(start, Math.min(endOfLine, end)).trim();
+  return first.length > SIGNATURE_MAX ? `${first.slice(0, SIGNATURE_MAX)}\u2026` : first;
+}
+
+// src/parser/analyze.ts
 var languageCache = /* @__PURE__ */ new Map();
 var initPromise = null;
 function ensureParserInit() {
@@ -459,35 +627,6 @@ function loadLanguage(spec, force = false) {
     return language;
   })();
 }
-async function prune(filePath, source, opts = {}) {
-  const spec = languageForFile(filePath);
-  if (!spec || spec.rules.length === 0) {
-    return { code: source, language: null, removed: 0 };
-  }
-  const language = await loadLanguage(spec, opts.forceDownload);
-  const parser = new import_web_tree_sitter.default();
-  parser.setLanguage(language);
-  const tree = parser.parse(source);
-  const ranges = [];
-  for (const rule of spec.rules) {
-    const query = language.query(rule.query);
-    const captures = query.captures(tree.rootNode);
-    for (const cap of captures) {
-      if (cap.node.startIndex === cap.node.endIndex) continue;
-      if (rule.replacement.keepIf?.test(cap.node.text)) continue;
-      ranges.push({
-        start: cap.node.startIndex,
-        end: cap.node.endIndex,
-        token: rule.replacement.token
-      });
-    }
-    query.delete();
-  }
-  tree.delete();
-  parser.delete();
-  const { code, removed } = spliceRanges(source, ranges);
-  return { code, language: spec.name, removed };
-}
 function spliceRanges(source, ranges) {
   let removed = 0;
   const sorted = [...ranges].sort((a, b) => b.start - a.start);
@@ -499,6 +638,163 @@ function spliceRanges(source, ranges) {
   }
   return { code: out, removed };
 }
+async function analyze(filePath, source, opts = {}) {
+  const spec = languageForFile(filePath);
+  if (!spec || spec.rules.length === 0) {
+    return { code: source, language: null, removed: 0, symbols: [] };
+  }
+  let language;
+  try {
+    language = await loadLanguage(spec, opts.forceDownload);
+  } catch {
+    return { code: source, language: null, removed: 0, symbols: [] };
+  }
+  const parser = new import_web_tree_sitter.default();
+  parser.setLanguage(language);
+  const tree = parser.parse(source);
+  try {
+    const symbols = collectSymbols(tree.rootNode, source);
+    if (opts.skipPrune) {
+      return { code: source, language: spec.name, removed: 0, symbols };
+    }
+    const keepRanges = [
+      ...opts.keepBlocksInside ?? [],
+      ...opts.preserveAnnotations?.length ? annotatedKeepRanges(symbols, source, opts.preserveAnnotations) : []
+    ];
+    const isProtected = (start, end) => keepRanges.some((k) => k.start <= start && end <= k.end);
+    const ranges = [];
+    for (const rule of spec.rules) {
+      const query = language.query(rule.query);
+      const captures = query.captures(tree.rootNode);
+      for (const cap of captures) {
+        if (cap.node.startIndex === cap.node.endIndex) continue;
+        if (rule.replacement.keepIf?.test(cap.node.text)) continue;
+        if (isProtected(cap.node.startIndex, cap.node.endIndex)) continue;
+        ranges.push({
+          start: cap.node.startIndex,
+          end: cap.node.endIndex,
+          token: rule.replacement.token
+        });
+      }
+      query.delete();
+    }
+    const { code, removed } = spliceRanges(source, ranges);
+    return { code, language: spec.name, removed, symbols };
+  } finally {
+    tree.delete();
+    parser.delete();
+  }
+}
+var ANNOTATION_WINDOW = 240;
+function annotatedKeepRanges(symbols, source, annotations) {
+  if (annotations.length === 0) return [];
+  const markers = annotations.filter(Boolean).map(escapeRegExp);
+  if (markers.length === 0) return [];
+  const re = new RegExp(`@(${markers.join("|")})\\b`, "i");
+  return symbols.filter((s) => {
+    const windowStart = Math.max(0, s.start - ANNOTATION_WINDOW);
+    const tail = source.slice(windowStart, s.start);
+    const cut = Math.max(tail.lastIndexOf("}\n"), tail.lastIndexOf(";\n"));
+    const relevant = cut === -1 ? tail : tail.slice(cut + 1);
+    return re.test(relevant);
+  }).map((s) => ({ start: s.start, end: s.end }));
+}
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/config.ts
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
+var CONFIG_FILE_NAME = ".tokenshrinkrc.json";
+var EMPTY_CONFIG = {
+  ignorePatterns: [],
+  keepUnpruned: [],
+  preserveAnnotations: []
+};
+function configPathFor(root) {
+  return import_node_path5.default.join(root, CONFIG_FILE_NAME);
+}
+function loadConfig(root, warn) {
+  const file = configPathFor(root);
+  let raw;
+  try {
+    if (!import_node_fs3.default.existsSync(file)) return { ...EMPTY_CONFIG };
+    raw = JSON.parse(import_node_fs3.default.readFileSync(file, "utf8"));
+  } catch (err) {
+    warn?.(`Invalid ${CONFIG_FILE_NAME} at ${file}: ${err.message}`);
+    return { ...EMPTY_CONFIG };
+  }
+  return normalizeConfig(raw, warn, file);
+}
+function normalizeConfig(raw, warn, file) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    warn?.(`Invalid ${CONFIG_FILE_NAME}${file ? ` at ${file}` : ""}: expected a JSON object.`);
+    return { ...EMPTY_CONFIG };
+  }
+  const obj = raw;
+  const asStrings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+  return {
+    ignorePatterns: asStrings(obj.ignorePatterns),
+    keepUnpruned: asStrings(obj.keepUnpruned),
+    preserveAnnotations: asStrings(obj.preserveAnnotations),
+    ...typeof obj.autoWorkflow === "boolean" ? { autoWorkflow: obj.autoWorkflow } : {}
+  };
+}
+function matchesAny(file, patterns) {
+  const rel2 = normalizeSlashes(file);
+  for (const raw of patterns) {
+    if (!raw) continue;
+    const pattern = normalizeSlashes(raw).replace(/^\.\//, "");
+    if (matchesGlob(rel2, pattern)) return true;
+  }
+  return false;
+}
+function matchesGlob(file, pattern) {
+  if (file === pattern) return true;
+  if (!/[?*[]/.test(pattern)) {
+    return file.endsWith(`/${pattern}`);
+  }
+  const re = globToRegExp(pattern);
+  return re.test(file);
+}
+function globToRegExp(glob) {
+  let re = "^";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        i++;
+        if (glob[i + 1] === "/") {
+          i++;
+          re += "(?:.*/)?";
+        } else {
+          re += ".*";
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (c === "[") {
+      const close = glob.indexOf("]", i);
+      if (close === -1) {
+        re += "\\[";
+      } else {
+        const inner = glob.slice(i + 1, close).replace(/\\/g, "\\\\");
+        re += `[${inner}]`;
+        i = close;
+      }
+    } else {
+      re += c.replace(/[.+^${}()|\\]/g, "\\$&");
+    }
+  }
+  re += "$";
+  return new RegExp(re);
+}
+function normalizeSlashes(p) {
+  return p.split(import_node_path5.default.sep).join("/").replace(/^\.\//, "");
+}
 
 // src/watcher/sync.ts
 var DEFAULT_IGNORED = [
@@ -518,7 +814,7 @@ var ContextCache = class {
   }
   /** Returns the cached skeleton for a file, if present. */
   getSkeleton(filePath) {
-    return this.entries.get(import_node_path5.default.resolve(filePath)) ?? null;
+    return this.entries.get(import_node_path6.default.resolve(filePath)) ?? null;
   }
   get imports() {
     return this.entries;
@@ -540,18 +836,18 @@ function extractImports(_filePath, source) {
 function resolveImport(importer, specifier, root) {
   if (!/^[.~@]/.test(specifier)) {
     if (specifier.startsWith("@/")) {
-      return resolveCandidate(import_node_path5.default.join(root, specifier.slice(2)));
+      return resolveCandidate(import_node_path6.default.join(root, specifier.slice(2)));
     }
     if (specifier.startsWith("@")) {
       return null;
     }
     if (specifier.startsWith("~")) {
-      return resolveCandidate(import_node_path5.default.join(root, specifier.slice(1)));
+      return resolveCandidate(import_node_path6.default.join(root, specifier.slice(1)));
     }
     return null;
   }
-  const base = import_node_path5.default.dirname(import_node_path5.default.resolve(importer));
-  return resolveCandidate(import_node_path5.default.resolve(base, specifier));
+  const base = import_node_path6.default.dirname(import_node_path6.default.resolve(importer));
+  return resolveCandidate(import_node_path6.default.resolve(base, specifier));
 }
 function resolveCandidate(p) {
   const candidates = [
@@ -574,29 +870,34 @@ function resolveCandidate(p) {
     `${p}.h`,
     `${p}.hpp`,
     `${p}.php`,
-    import_node_path5.default.join(p, "index.ts"),
-    import_node_path5.default.join(p, "index.js"),
-    import_node_path5.default.join(p, "index.tsx"),
-    import_node_path5.default.join(p, "index.jsx"),
-    import_node_path5.default.join(p, "index.py")
+    import_node_path6.default.join(p, "index.ts"),
+    import_node_path6.default.join(p, "index.js"),
+    import_node_path6.default.join(p, "index.tsx"),
+    import_node_path6.default.join(p, "index.jsx"),
+    import_node_path6.default.join(p, "index.py")
   ];
   for (const c of candidates) {
-    if (import_node_fs3.default.existsSync(c) && import_node_fs3.default.statSync(c).isFile()) return import_node_path5.default.resolve(c);
+    if (import_node_fs4.default.existsSync(c) && import_node_fs4.default.statSync(c).isFile()) return import_node_path6.default.resolve(c);
   }
   return null;
 }
 function createWatcher(opts) {
   const cache = new ContextCache();
-  const { root, ignored = DEFAULT_IGNORED, onIndexed } = opts;
+  const { root, ignored = DEFAULT_IGNORED, config, onIndexed, onRemoved } = opts;
+  const rel2 = (abs) => import_node_path6.default.relative(root, abs);
+  const effectiveIgnored = [
+    ...ignored,
+    ...config?.ignorePatterns?.length ? [(_abs) => matchesAny(rel2(String(_abs)), config.ignorePatterns)] : []
+  ];
   const pending = /* @__PURE__ */ new Map();
   const DEBOUNCE_MS = 100;
   async function handle(filePath) {
-    const abs = import_node_path5.default.resolve(filePath);
+    const abs = import_node_path6.default.resolve(filePath);
     let source;
     try {
-      const st = import_node_fs3.default.statSync(abs);
+      const st = import_node_fs4.default.statSync(abs);
       if (!st.isFile()) return;
-      source = import_node_fs3.default.readFileSync(abs, "utf8");
+      source = import_node_fs4.default.readFileSync(abs, "utf8");
     } catch {
       return;
     }
@@ -604,13 +905,18 @@ function createWatcher(opts) {
     const cached = cache.entries.get(abs);
     if (cached && cached.hash === hash) return;
     await cache.ensureInit();
-    const { code, language } = await prune(abs, source);
-    const imports = await extractImports(abs, source);
+    const keepFull = config?.keepUnpruned?.length ? matchesAny(import_node_path6.default.relative(root, abs), config.keepUnpruned) : false;
+    const { code, language, symbols } = await analyze(abs, source, {
+      skipPrune: keepFull,
+      preserveAnnotations: config?.preserveAnnotations
+    });
+    const imports = extractImports(abs, source);
     const entry = {
       hash,
       skeleton: code,
       language,
-      imports: imports.map((spec) => resolveImport(abs, spec, root)).filter((p) => p !== null)
+      imports: imports.map((spec) => resolveImport(abs, spec, root)).filter((p) => p !== null),
+      ...symbols.length > 0 ? { symbols } : {}
     };
     cache.entries.set(abs, entry);
     onIndexed?.(abs, entry);
@@ -620,7 +926,7 @@ function createWatcher(opts) {
     // sockets) are never opened with fs.watch (which raises UVException).
     ignored(_p, stats) {
       if (stats && !stats.isFile() && !stats.isDirectory()) return true;
-      return isIgnored(import_node_path5.default.resolve(String(_p)), ignored);
+      return isIgnored(import_node_path6.default.resolve(String(_p)), effectiveIgnored);
     },
     alwaysStat: true,
     ignoreInitial: true,
@@ -628,7 +934,7 @@ function createWatcher(opts) {
     awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 }
   });
   function debounce(filePath) {
-    const abs = import_node_path5.default.resolve(filePath);
+    const abs = import_node_path6.default.resolve(filePath);
     const existing = pending.get(abs);
     if (existing) clearTimeout(existing);
     if (!existing) void handle(abs);
@@ -640,8 +946,9 @@ function createWatcher(opts) {
   watcher.on("add", debounce);
   watcher.on("change", debounce);
   watcher.on("unlink", (filePath) => {
-    const abs = import_node_path5.default.resolve(filePath);
+    const abs = import_node_path6.default.resolve(filePath);
     cache.entries.delete(abs);
+    onRemoved?.(abs);
   });
   return {
     cache,
@@ -654,7 +961,7 @@ function createWatcher(opts) {
      */
     async indexAll() {
       const files = [];
-      await walk(root, (f) => files.push(f), ignored);
+      await walk(root, (f) => files.push(f), effectiveIgnored);
       let ok = 0;
       for (const f of files) {
         try {
@@ -669,9 +976,9 @@ function createWatcher(opts) {
   };
 }
 async function walk(root, push, ignored) {
-  const entries = await import_node_fs3.default.promises.readdir(root, { withFileTypes: true });
+  const entries = await import_node_fs4.default.promises.readdir(root, { withFileTypes: true });
   for (const e of entries) {
-    const abs = import_node_path5.default.join(root, e.name);
+    const abs = import_node_path6.default.join(root, e.name);
     if (isIgnored(abs, ignored)) continue;
     if (e.isDirectory()) {
       await walk(abs, push, ignored);
@@ -682,18 +989,298 @@ async function walk(root, push, ignored) {
 }
 function isIgnored(abs, ignored) {
   for (const m of ignored) {
+    if (typeof m === "function") {
+      if (m(abs)) return true;
+      continue;
+    }
     if (typeof m === "string" && abs.includes(m)) return true;
     if (m instanceof RegExp && m.test(abs)) return true;
   }
   return false;
 }
 
+// src/detect.ts
+var import_node_fs5 = __toESM(require("fs"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
+var VCS_MARKER_DIRS = [".git", ".hg", ".svn"];
+var PROJECT_MANIFEST_FILES = [
+  // JavaScript / TypeScript
+  "package.json",
+  "tsconfig.json",
+  // Python
+  "pyproject.toml",
+  "setup.py",
+  "setup.cfg",
+  "requirements.txt",
+  // Go / Rust / Dart / Swift
+  "go.mod",
+  "Cargo.toml",
+  "pubspec.yaml",
+  "Package.swift",
+  // Java / Kotlin
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "settings.gradle",
+  "settings.gradle.kts",
+  // PHP / Ruby / Elixir
+  "composer.json",
+  "Gemfile",
+  "mix.exs"
+];
+var MANIFEST_FILE_SET = new Set(PROJECT_MANIFEST_FILES);
+var MAX_WALK_DEPTH = 64;
+function detectProjectRoot(fromPath) {
+  const resolved = import_node_path7.default.resolve(fromPath);
+  let dir = isDirectory(resolved) ? resolved : import_node_path7.default.dirname(resolved);
+  let nearestManifest = null;
+  for (let depth = 0; depth < MAX_WALK_DEPTH; depth++) {
+    const names = readDirNames(dir);
+    if (names) {
+      if (VCS_MARKER_DIRS.some((vcs) => names.has(vcs))) return dir;
+      if (nearestManifest === null && hasManifest(names)) nearestManifest = dir;
+    }
+    const parent = import_node_path7.default.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return nearestManifest;
+}
+function isDirectory(p) {
+  try {
+    return import_node_fs5.default.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function readDirNames(dir) {
+  try {
+    return new Set(import_node_fs5.default.readdirSync(dir));
+  } catch {
+    return null;
+  }
+}
+function hasManifest(names) {
+  for (const name of names) {
+    if (MANIFEST_FILE_SET.has(name)) return true;
+  }
+  return false;
+}
+
+// src/mcp.ts
+init_registry();
+
+// src/search/index.ts
+function words(text) {
+  const out = /* @__PURE__ */ new Set();
+  for (const part of text.split(/[^A-Za-z0-9_$]+/)) {
+    if (!part) continue;
+    for (const seg of part.split(/(?<=[a-z0-9])(?=[A-Z])/)) {
+      const w = seg.toLowerCase();
+      if (w) out.add(w);
+    }
+    for (const seg of part.split("_")) {
+      const w = seg.toLowerCase();
+      if (w) out.add(w);
+    }
+  }
+  return [...out];
+}
+var SymbolSearch = class {
+  docs = [];
+  byFile = /* @__PURE__ */ new Map();
+  inverted = /* @__PURE__ */ new Map();
+  get size() {
+    return this.docs.length;
+  }
+  /** Replace the docs for one file (or remove when `symbols` is empty). */
+  setFile(filePath, symbols) {
+    this.removeFile(filePath);
+    if (symbols.length === 0) return;
+    const docs = symbols.map((s) => ({ ...s, filePath }));
+    const ids = docs.map((d) => {
+      const id = this.docs.length;
+      this.docs.push(d);
+      for (const w of words(`${d.name}`)) {
+        const list = this.inverted.get(w) ?? [];
+        list.push(id);
+        this.inverted.set(w, list);
+      }
+      return id;
+    });
+    this.byFile.set(filePath, docs);
+    void ids;
+  }
+  removeFile(filePath) {
+    const docs = this.byFile.get(filePath);
+    if (!docs) return;
+    const removed = new Set(docs);
+    this.docs = this.docs.filter((d) => !removed.has(d));
+    this.byFile.delete(filePath);
+    this.rebuildInverted();
+  }
+  /** Bulk-load a whole cache (used at attach time and cold lazy builds). */
+  loadCache(entries) {
+    this.docs = [];
+    this.byFile.clear();
+    for (const [abs, entry] of entries) {
+      if (!entry.symbols || entry.symbols.length === 0) continue;
+      const docs = entry.symbols.map((s) => ({ ...s, filePath: abs }));
+      this.byFile.set(abs, docs);
+      this.docs.push(...docs);
+    }
+    this.rebuildInverted();
+  }
+  /** Ranked symbol hits for `query`. */
+  search(query, opts = {}) {
+    const maxResults = opts.maxResults ?? 10;
+    const q = query.trim().toLowerCase();
+    if (!q) return [];
+    const queryWords = words(q);
+    let candidates;
+    if (queryWords.length > 0) {
+      const ids = /* @__PURE__ */ new Set();
+      for (const w of queryWords) {
+        const post = this.inverted.get(w);
+        if (post) for (const id of post) ids.add(id);
+      }
+      candidates = [...ids].map((id) => this.docs[id]);
+    } else {
+      candidates = this.docs;
+    }
+    if (opts.kind) candidates = candidates.filter((d) => d.kind === opts.kind);
+    const scored = candidates.map((d) => this.score(d, q, queryWords)).filter((s) => s !== null).sort((a, b) => b.score - a.score || a.line - b.line).slice(0, maxResults);
+    return scored.map((s) => ({ ...s, label: this.label(s) }));
+  }
+  score(d, q, queryWords) {
+    const name = d.name.toLowerCase();
+    let score = 0;
+    if (name === q) score += 100;
+    if (name.startsWith(q)) score += 60;
+    if (name.includes(q)) score += 30;
+    if ((d.signature ?? "").toLowerCase().includes(q)) score += 8;
+    for (const w of queryWords) {
+      if (name.includes(w)) score += 4;
+      if ((d.signature ?? "").toLowerCase().includes(w)) score += 1;
+    }
+    if (score <= 0) return null;
+    return { ...d, score };
+  }
+  label(d) {
+    const sig = d.signature && d.signature.length > 0 ? ` \u2014 ${d.signature}` : "";
+    return `${d.filePath}:${d.line}${sig}`;
+  }
+  rebuildInverted() {
+    this.inverted.clear();
+    this.docs.forEach((d, id) => {
+      for (const w of words(d.name)) {
+        const list = this.inverted.get(w) ?? [];
+        list.push(id);
+        this.inverted.set(w, list);
+      }
+    });
+  }
+};
+
+// src/git.ts
+var import_node_child_process = require("child_process");
+var import_node_path8 = __toESM(require("path"), 1);
+var import_node_fs6 = __toESM(require("fs"), 1);
+function runGit(root, args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)("git", ["--no-pager", ...args], {
+      cwd: root,
+      env: { ...process.env, LC_ALL: "C" },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => {
+      out += d;
+    });
+    child.stderr.on("data", (d) => {
+      err += d;
+    });
+    child.on("error", (e) => resolve({ ok: false, out: "", err: e.message }));
+    child.on("close", (code) => resolve({ ok: code === 0, out, err }));
+  });
+}
+function parseNames(out) {
+  return out.split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function isFatal(err) {
+  if (!err) return void 0;
+  const e = err.trim();
+  if (/not a git repository|fatal:/i.test(e)) return e;
+  return void 0;
+}
+async function gitChangedFiles(root, opts) {
+  const scope = opts.scope ?? "worktree";
+  const filter = "--diff-filter=ACMRT";
+  let relative = [];
+  if (scope === "staged") {
+    const r = await runGit(root, ["diff", "--cached", "--name-only", filter]);
+    const fatal = isFatal(r.err);
+    if (!r.ok) return { files: [], ...fatal ? { error: fatal } : {} };
+    relative = parseNames(r.out);
+  } else if (scope === "branch") {
+    const base = opts.base ?? "HEAD~1";
+    const head = opts.head ?? "HEAD";
+    const r = await runGit(root, ["diff", "--name-only", `${base}...${head}`, filter]);
+    const fatal = isFatal(r.err);
+    if (!r.ok) return { files: [], ...fatal ? { error: fatal } : {} };
+    relative = parseNames(r.out);
+  } else {
+    const [unstaged, staged] = await Promise.all([
+      runGit(root, ["diff", "--name-only", filter]),
+      runGit(root, ["diff", "--cached", "--name-only", filter])
+    ]);
+    const fatal = isFatal(unstaged.err) ?? isFatal(staged.err);
+    if (!unstaged.ok && !staged.ok) {
+      return { files: [], ...fatal ? { error: fatal } : {} };
+    }
+    const merged = /* @__PURE__ */ new Set([...parseNames(unstaged.out), ...parseNames(staged.out)]);
+    if (opts.includeUntracked) {
+      const ut = await runGit(root, ["ls-files", "--others", "--exclude-standard"]);
+      for (const f of parseNames(ut.out)) merged.add(f);
+    }
+    relative = [...merged];
+  }
+  const files = relative.map((rel2) => import_node_path8.default.resolve(root, rel2)).filter((abs) => {
+    try {
+      return import_node_fs6.default.statSync(abs).isFile();
+    } catch {
+      return false;
+    }
+  });
+  return { files };
+}
+
 // src/mcp.ts
 var RULE_TARGET_PATH = {
   cursor: ".cursor/rules/token-shrink.mdc",
   claude: ".claude/rules/token-shrink.md",
   cline: ".clinerules/token-shrink.md"
 };
+var RULE_VERSION = 3;
+var RULE_VERSION_MARKER = `# token-shrink rule v${RULE_VERSION}`;
+var WORKFLOW_GUIDANCE = [
+  "When a pruned skeleton is not enough to write or change code correctly, expand the exact",
+  "definition with expand_symbol.",
+  "",
+  "Call search_symbol_signatures automatically for any identifier you reference that the",
+  "context does not already define, so you always work from exact signatures.",
+  "",
+  "Before multi-file edits, reviews, or work on code with uncommitted or staged changes, call",
+  "git_diff_context and use its impact payload (changed files and their callers) as context.",
+  "",
+  "Pass activeFiles to get_compressed_code_context when a task spans several files, and",
+  "maxTokens whenever the payload must fit a token budget."
+].join("\n");
+var LIGHT_GUIDANCE = [
+  "Use expand_symbol when a pruned body is not enough, git_diff_context for changed or",
+  "multi-file work, and search_symbol_signatures to locate definitions repo-wide."
+].join("\n");
 var AUTO_RULE_SENTINEL = "# auto-generated by token-shrink";
 var CURSOR_RULE_PATH = RULE_TARGET_PATH.cursor;
 var AUTO_RULE_PATH = CURSOR_RULE_PATH;
@@ -714,6 +1301,9 @@ Before working on a file in this repo, call the \`get_compressed_code_context\`
 that file's path, and use the returned Ring 0 + Ring 1 payload as the context for that file
 and its direct imports.
 
+${WORKFLOW_GUIDANCE}
+
+${RULE_VERSION_MARKER}
 ${AUTO_RULE_SENTINEL}
 `
   },
@@ -728,6 +1318,9 @@ Before working on a file in this repo, call the \`get_compressed_code_context\`
 that file's path, and use the returned Ring 0 + Ring 1 payload as the context for that file
 and its direct imports.
 
+${WORKFLOW_GUIDANCE}
+
+${RULE_VERSION_MARKER}
 ${CLAUDE_RULE_SENTINEL}
 `
   },
@@ -742,23 +1335,32 @@ Before working on a file in this repo, call the \`get_compressed_code_context\`
 that file's path, and use the returned Ring 0 + Ring 1 payload as the context for that file
 and its direct imports.
 
+${WORKFLOW_GUIDANCE}
+
+${RULE_VERSION_MARKER}
 ${CLINE_RULE_SENTINEL}
 `
   }
 };
 function createAutoRule(root, target) {
   const spec = ruleTargets[target];
-  const rulePath = import_node_path6.default.join(root, spec.relPath);
+  const rulePath = import_node_path9.default.join(root, spec.relPath);
+  const autoWorkflow = loadConfig(root).autoWorkflow !== false;
+  const body = autoWorkflow ? spec.body : spec.body.replace(WORKFLOW_GUIDANCE, LIGHT_GUIDANCE);
   try {
-    if (import_node_fs4.default.existsSync(rulePath)) {
-      const existing = import_node_fs4.default.readFileSync(rulePath, "utf8");
+    if (import_node_fs7.default.existsSync(rulePath)) {
+      const existing = import_node_fs7.default.readFileSync(rulePath, "utf8");
       if (existing.includes(spec.sentinel)) {
-        return { created: false, skipped: "exists", filePath: rulePath };
+        if (existing.includes(RULE_VERSION_MARKER)) {
+          return { created: false, skipped: "exists", filePath: rulePath };
+        }
+        import_node_fs7.default.writeFileSync(rulePath, body, "utf8");
+        return { created: true, skipped: "none", filePath: rulePath };
       }
       return { created: false, skipped: "user", filePath: rulePath };
     }
-    import_node_fs4.default.mkdirSync(import_node_path6.default.dirname(rulePath), { recursive: true });
-    import_node_fs4.default.writeFileSync(rulePath, spec.body, "utf8");
+    import_node_fs7.default.mkdirSync(import_node_path9.default.dirname(rulePath), { recursive: true });
+    import_node_fs7.default.writeFileSync(rulePath, body, "utf8");
     return { created: true, skipped: "none", filePath: rulePath };
   } catch (err) {
     process.stderr.write(
@@ -777,27 +1379,154 @@ function resolveTargets(ruleTarget) {
   if (list.includes("all")) return ["cursor", "claude", "cline"];
   return list;
 }
+function isWithin(parent, child) {
+  const rel2 = import_node_path9.default.relative(import_node_path9.default.resolve(parent), import_node_path9.default.resolve(child));
+  return rel2 === "" || !rel2.startsWith("..") && !import_node_path9.default.isAbsolute(rel2);
+}
+function resolveActiveFiles(single, many) {
+  if (many && many.length > 0) {
+    if (single) {
+      throw new Error("Pass either `activeFilePath` or `activeFiles`, not both.");
+    }
+    return many;
+  }
+  if (single) return [single];
+  throw new Error("`activeFilePath` or `activeFiles` is required");
+}
 async function startMcpServer(opts = {}) {
-  const root = import_node_path6.default.resolve(opts.root ?? process.env.ROOT ?? process.cwd());
   const log = (msg) => {
     if (!opts.silent) process.stderr.write(`[token-shrink] ${msg}
 `);
   };
-  const watcher = createWatcher({ root, ignored: opts.ignored });
-  if (!opts.silent) {
-    log(`Indexing ${root} in the background\u2026`);
-  }
-  if (opts.createRule !== false) {
+  const textReply = (text) => ({
+    content: [{ type: "text", text }]
+  });
+  const explicitRoot = opts.root?.trim() || process.env.ROOT?.trim() || "";
+  const autoMode = explicitRoot === "";
+  let root = "";
+  let watcher = null;
+  let searchIndex = null;
+  let lifecycle = Promise.resolve();
+  let config = { ...EMPTY_CONFIG };
+  let configFsw = null;
+  let configReloadTimer = null;
+  const stopConfigWatch = () => {
+    if (configReloadTimer) {
+      clearTimeout(configReloadTimer);
+      configReloadTimer = null;
+    }
+    if (configFsw) {
+      configFsw.close();
+      configFsw = null;
+    }
+  };
+  const reloadForRoot = async (r) => {
+    const next = loadConfig(r, (m) => log(m));
+    const changed = JSON.stringify(next) !== JSON.stringify(config);
+    config = next;
+    if (!changed || !watcher || root !== r) return;
+    log(".tokenshrinkrc.json changed \u2014 re-indexing with the new rules.");
+    stopConfigWatch();
+    const old = watcher;
+    watcher = null;
+    root = "";
+    await old.close().catch(() => {
+    });
+    await attachWatcher(r, false);
+  };
+  const startConfigWatch = (r) => {
+    stopConfigWatch();
+    const cfgPath = configPathFor(r);
+    if (!import_node_fs7.default.existsSync(cfgPath)) return;
+    try {
+      configFsw = import_node_fs7.default.watch(cfgPath, () => {
+        if (configReloadTimer) clearTimeout(configReloadTimer);
+        configReloadTimer = setTimeout(() => {
+          void enqueue(() => reloadForRoot(r));
+        }, 200);
+      });
+    } catch {
+    }
+  };
+  const writeRules = (r) => {
+    if (opts.createRule === false) return;
     for (const target of resolveTargets(opts.ruleTarget)) {
-      const res = createAutoRule(root, target);
+      const res = createAutoRule(r, target);
       if (res.created) {
         log(`Wrote ${target} rule to ${res.filePath}`);
       } else if (res.skipped === "user") {
         log(`${target} rule exists (user-authored); leaving it untouched.`);
       }
     }
+  };
+  const attachWatcher = (r, waitForIndex) => {
+    stopConfigWatch();
+    config = loadConfig(r, (m) => log(m));
+    const search = new SymbolSearch();
+    const w = createWatcher({
+      root: r,
+      ignored: opts.ignored,
+      config,
+      onIndexed: (abs, entry) => {
+        if (entry.symbols && entry.symbols.length > 0) search.setFile(abs, entry.symbols);
+        else search.removeFile(abs);
+      },
+      onRemoved: (abs) => search.removeFile(abs)
+    });
+    searchIndex = search;
+    root = r;
+    watcher = w;
+    writeRules(r);
+    log(`Indexing ${r} in the background\u2026`);
+    const indexed = w.indexAll().then((n) => log(`Indexed ${n} files.`)).catch((err) => log(`Indexing ${r} failed: ${err?.message ?? err}`));
+    startConfigWatch(r);
+    return waitForIndex ? indexed : Promise.resolve();
+  };
+  const enqueue = (fn) => {
+    const run = lifecycle.then(fn);
+    lifecycle = run.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return run;
+  };
+  if (explicitRoot) {
+    void enqueue(() => attachWatcher(import_node_path9.default.resolve(explicitRoot), false));
+  } else {
+    const fromCwd = detectProjectRoot(process.cwd());
+    if (fromCwd) {
+      log(`Auto-detected project root ${fromCwd} (from cwd). Pass --root to pin it.`);
+      void enqueue(() => attachWatcher(fromCwd, false));
+    } else {
+      log(
+        "No --root and no project markers around the current directory \u2014 will auto-detect the project from the first tool call."
+      );
+    }
   }
-  void watcher.indexAll().then((n) => log(`Indexed ${n} files.`));
+  const ensureReadyFor = (activeFilePath) => enqueue(async () => {
+    const abs = import_node_path9.default.resolve(activeFilePath);
+    if (watcher && root) {
+      if (!autoMode || isWithin(root, abs)) return;
+      const next = detectProjectRoot(abs);
+      if (!next || next === root) return;
+      log(`Active file is in a different project (${next}); re-indexing (was ${root}).`);
+      await watcher.close().catch(() => {
+      });
+      watcher = null;
+      root = "";
+    }
+    if (root) return;
+    const detected = detectProjectRoot(abs);
+    const target = detected ?? process.cwd();
+    if (detected) {
+      log(`Auto-detected project root ${target} from ${abs}.`);
+    } else {
+      log(`No project markers around ${abs}; falling back to ${target}.`);
+    }
+    await attachWatcher(target, true);
+  });
   const server = new import_mcp.McpServer(
     { name: "token-shrink", version: "2.0.0" },
     { capabilities: { tools: {} } }
@@ -806,18 +1535,28 @@ async function startMcpServer(opts = {}) {
     "get_compressed_code_context",
     {
       title: "Get Compressed Code Context",
-      description: "Returns a compressed, framework-aware AST context payload for a file: the active file\u2019s full source (Ring 0) plus pruned skeletons of its direct imports (Ring 1). Implementation bodies are removed but type signatures, interfaces, and module exports are preserved for ~80-90% token reduction.",
+      description: "Returns a compressed, framework-aware AST context payload for one or more files: each active file\u2019s full source (Ring 0) plus pruned skeletons of their direct imports (Ring 1). Implementation bodies are removed but type signatures, interfaces, and module exports are preserved for ~80-90% token reduction. Use `activeFiles` to pin multiple files as Ring 0 and `maxTokens` to cap the payload with a relevance-ranked Ring 1.",
       inputSchema: {
-        activeFilePath: import_zod.z.string().describe("Path to the file the agent is working on"),
+        activeFilePath: import_zod.z.string().optional().describe("Path to the file the agent is working on (or use `activeFiles`)"),
+        activeFiles: import_zod.z.array(import_zod.z.string()).optional().describe("Multiple files to keep as Ring 0 (full text); mutually exclusive with `activeFilePath`"),
         maxSkeletons: import_zod.z.number().int().min(1).max(200).optional().describe("Cap on number of dependency skeletons to include"),
+        maxTokens: import_zod.z.number().int().positive().optional().describe("Hard token budget for the whole payload; Ring 1 is relevance-ranked and packed to fit"),
         includeStats: import_zod.z.boolean().optional().describe("Append approximate token-count stats")
       }
     },
-    async ({ activeFilePath, maxSkeletons, includeStats }) => {
-      const result = assemble(activeFilePath, watcher.cache.entries, {
+    async ({ activeFilePath, activeFiles, maxSkeletons, maxTokens, includeStats }) => {
+      const paths = resolveActiveFiles(activeFilePath, activeFiles);
+      for (const p of paths) await ensureReadyFor(p);
+      if (!watcher) {
+        throw new Error("token-shrink watcher failed to start");
+      }
+      const result = assembleMany(paths, watcher.cache.entries, {
         maxSkeletons,
+        maxTokens,
         includeStats
       });
+      const ts = result.tokenStats;
+      const budgetNote = ts.budget !== void 0 ? ` budget=${ts.budget} trimmed=${ts.trimmed}` : "";
       return {
         content: [
           {
@@ -826,19 +1565,274 @@ async function startMcpServer(opts = {}) {
           },
           {
             type: "text",
-            text: `[stats] active=${result.activeFilePath} dependencies=${result.included.length} unresolved=${result.unresolved.length}`
+            text: `[stats] files=${result.activeFilePaths.length} dependencies=${result.included.length} unresolved=${result.unresolved.length} tokens=${ts.totalTokens}${budgetNote}`
           }
         ]
       };
     }
   );
+  server.registerTool(
+    "expand_symbol",
+    {
+      title: "Expand Symbol",
+      description: "Returns the full, un-pruned source of a named definition (function, method, class, interface, enum, arrow/const function, \u2026) from one file. Use it when a Ring-1 skeleton is not enough \u2014 e.g. you need the exact algorithm inside a pruned body before writing or changing code.",
+      inputSchema: {
+        filePath: import_zod.z.string().describe("Path to the file containing the symbol"),
+        symbolName: import_zod.z.string().describe("Name of the definition to expand (exact name preferred; falls back to case-insensitive/substring)"),
+        maxMatches: import_zod.z.number().int().min(1).max(20).optional().describe("Maximum matching definitions to return (default 5)")
+      }
+    },
+    async ({ filePath, symbolName, maxMatches }) => {
+      await ensureReadyFor(filePath);
+      const abs = import_node_path9.default.resolve(filePath);
+      let source;
+      try {
+        source = import_node_fs7.default.readFileSync(abs, "utf8");
+      } catch {
+        return textReply(`File not found or unreadable: ${filePath}`);
+      }
+      const spec = languageForFile(abs);
+      if (!spec) {
+        return textReply(`No token-shrink grammar for file type: ${filePath}`);
+      }
+      const { symbols } = await analyze(abs, source, { skipPrune: true });
+      if (symbols.length === 0) {
+        return textReply(
+          `No parseable definitions found in ${filePath} \u2014 the grammar may be unavailable (first run offline) or the language exposes no name-carrying definitions yet.`
+        );
+      }
+      const matches = matchSymbols(symbols, symbolName).slice(0, maxMatches ?? 5);
+      if (matches.length === 0) {
+        const names = [...new Set(symbols.map((s) => s.name))].slice(0, 12).join(", ");
+        return textReply(
+          `No symbol named "${symbolName}" in ${filePath}.` + (names ? ` Other definitions there: ${names}.` : "")
+        );
+      }
+      const fence = import_node_path9.default.extname(abs).replace(/^\./, "") || "text";
+      const parts = matches.map((m) => {
+        const body = source.slice(m.start, m.end).trim();
+        return `### ${m.name} (${m.kind}) \u2014 ${abs}:${m.line}
+
+\`\`\`` + fence + "\n" + body + "\n```\n";
+      });
+      const disambig = matches.length > 1 ? `
+_Multiple definitions matched (${matches.length}); each is shown above._` : "";
+      return textReply(parts.join("\n") + disambig);
+    }
+  );
+  server.registerTool(
+    "git_diff_context",
+    {
+      title: "Git Diff Context",
+      description: 'Builds an impact-analysis payload from git changes: every changed file is kept as Ring 0 (full code), their imports AND the files that import them (file-level callers) are attached as pruned Ring-1 skeletons. Use for PR reviews, regression fixes and multi-file tasks where no single "active file" exists.',
+      inputSchema: {
+        scope: import_zod.z.enum(["worktree", "staged", "branch"]).optional().describe("Diff scope: 'worktree' (default, staged+unstaged), 'staged', or 'branch' (base...head)"),
+        base: import_zod.z.string().optional().describe("Base ref for scope=branch (default HEAD~1)"),
+        head: import_zod.z.string().optional().describe("Head ref for scope=branch (default HEAD)"),
+        includeUntracked: import_zod.z.boolean().optional().describe("Include untracked files (worktree scope only)"),
+        maxFiles: import_zod.z.number().int().min(1).max(200).optional().describe("Maximum changed files to include (default 30)"),
+        maxImporters: import_zod.z.number().int().min(0).max(100).optional().describe("Maximum importer skeletons to append (default 20)"),
+        maxSkeletons: import_zod.z.number().int().min(1).max(200).optional().describe("Cap on dependency skeletons per payload"),
+        maxTokens: import_zod.z.number().int().positive().optional().describe("Hard token budget for the whole payload"),
+        includeStats: import_zod.z.boolean().optional().describe("Append approximate token-count stats")
+      }
+    },
+    async ({
+      scope,
+      base,
+      head,
+      includeUntracked,
+      maxFiles,
+      maxImporters,
+      maxSkeletons,
+      maxTokens,
+      includeStats
+    }) => {
+      await ensureReadyFor(process.cwd());
+      if (!watcher || !root) {
+        throw new Error("token-shrink watcher failed to start");
+      }
+      const repoRoot = root;
+      const changedResult = await gitChangedFiles(repoRoot, {
+        scope: scope ?? "worktree",
+        base,
+        head,
+        includeUntracked
+      });
+      if (changedResult.error) {
+        return textReply(`git error: ${changedResult.error}`);
+      }
+      if (changedResult.files.length === 0) {
+        return textReply("No changed files (clean worktree, or empty diff for the requested scope).");
+      }
+      const fileCap = maxFiles ?? 30;
+      const changed = changedResult.files.slice(0, fileCap);
+      const filesTruncated = changedResult.files.length > changed.length;
+      for (const abs of changed) {
+        if (!watcher.cache.entries.has(abs)) {
+          try {
+            await watcher.index(abs);
+          } catch {
+          }
+        }
+      }
+      const assembled = assembleMany(changed, watcher.cache.entries, {
+        maxSkeletons,
+        maxTokens,
+        includeStats
+      });
+      const changedSet = new Set(changed);
+      const importerOf = /* @__PURE__ */ new Map();
+      for (const [fileAbs, entry] of watcher.cache.entries) {
+        for (const imp of entry.imports) {
+          if (!changedSet.has(imp)) continue;
+          const list = importerOf.get(imp) ?? [];
+          list.push(fileAbs);
+          importerOf.set(imp, list);
+        }
+      }
+      const importerList = [...new Set([...importerOf.values()].flat())].filter(
+        (f) => !changedSet.has(f)
+      );
+      const importerCap = maxImporters ?? 20;
+      const importers = importerList.slice(0, importerCap);
+      const importersTruncated = importerList.length > importers.length;
+      const relLabel = (abs) => {
+        const rel2 = import_node_path9.default.relative(repoRoot, abs);
+        return rel2 && !rel2.startsWith("..") ? rel2 : abs;
+      };
+      const fence = (abs) => import_node_path9.default.extname(abs).replace(/^\./, "") || "text";
+      const parts = [];
+      parts.push(
+        `# Git Impact Context (${changed.length} changed file${changed.length === 1 ? "" : "s"})`,
+        ""
+      );
+      parts.push(`- changed files: ${changed.map(relLabel).join(", ")}`);
+      if (importers.length > 0) {
+        parts.push(`- importing files (callers): ${importers.map(relLabel).join(", ")}`);
+      }
+      parts.push("", "---", "");
+      parts.push("## Changed files \u2014 full code", "");
+      for (const abs of changed) {
+        parts.push(`### \`${relLabel(abs)}\``, "");
+        let source = "";
+        try {
+          source = import_node_fs7.default.readFileSync(abs, "utf8");
+        } catch {
+        }
+        parts.push(`\`\`\`${fence(abs)}`, source.trim() || "(unreadable file)", "```", "");
+      }
+      parts.push(`## Ring 1 \u2014 Pruned dependencies (${assembled.included.length})`, "");
+      parts.push("", "Implementation bodies removed; type signatures, interfaces and exports retained.", "");
+      if (assembled.included.length === 0) {
+        parts.push("_No local dependency skeletons available._", "");
+      }
+      for (const inc of assembled.included) {
+        const entry = watcher.cache.entries.get(inc.filePath);
+        const label = relLabel(inc.filePath);
+        parts.push(`### \`${label}\``, "");
+        if (entry) {
+          parts.push(`\`\`\`${fence(inc.filePath)}`, entry.skeleton.trim(), "```", "");
+        } else {
+          parts.push("_Unindexed file._", "");
+        }
+        parts.push("");
+      }
+      if (assembled.tokenStats.budget !== void 0 && assembled.tokenStats.trimmed > 0) {
+        parts.push(
+          `_Note: token budget of ${assembled.tokenStats.budget} excluded ${assembled.tokenStats.trimmed} lower-priority dependencies._`,
+          ""
+        );
+      }
+      if (importers.length > 0) {
+        parts.push(`## Ring 2 \u2014 Files importing the diff (${importers.length})`, "");
+        parts.push("", "Pruned skeletons of modules that call into the changed files.", "");
+        for (const abs of importers) {
+          const entry = watcher.cache.entries.get(abs);
+          parts.push(`### \`${relLabel(abs)}\``, "");
+          if (entry) {
+            parts.push(`\`\`\`${fence(abs)}`, entry.skeleton.trim(), "```", "");
+          } else {
+            parts.push("_Unindexed file._", "");
+          }
+          parts.push("");
+        }
+        if (importersTruncated) {
+          parts.push(
+            `_\u2026and ${importerList.length - importers.length} more importing files (raise maxImporters)._`,
+            ""
+          );
+        }
+      }
+      if (filesTruncated) {
+        parts.push(
+          `_Note: capped to ${fileCap} changed files (${changedResult.files.length} total); raise maxFiles to include more._`,
+          ""
+        );
+      }
+      if (assembled.unresolved.length > 0) {
+        parts.push("## Unresolved imports", "");
+        for (const u of assembled.unresolved) parts.push(`- \`${u}\``);
+        parts.push("");
+      }
+      const ts = assembled.tokenStats;
+      const budgetNote = ts.budget !== void 0 ? ` budget=${ts.budget} trimmed=${ts.trimmed}` : "";
+      const stats = `[git-stats] files=${changed.length} ring1=${assembled.included.length} importers=${importers.length} unresolved=${assembled.unresolved.length} tokens=${ts.totalTokens}${budgetNote}`;
+      return {
+        content: [
+          { type: "text", text: parts.join("\n") },
+          { type: "text", text: stats }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "search_symbol_signatures",
+    {
+      title: "Search Symbol Signatures",
+      description: "Fast, repo-wide lookup of named definitions (functions, methods, classes, interfaces, enums, \u2026). Returns compact `file:line \u2014 signature` lines instead of raw search hits. Use it to discover where a symbol lives and what its exact signature is before reading or editing code.",
+      inputSchema: {
+        query: import_zod.z.string().describe("Search text (matched against symbol names; falls back to signatures)"),
+        maxResults: import_zod.z.number().int().min(1).max(100).optional().describe("Maximum results to return (default 10)"),
+        kind: import_zod.z.enum(["function", "method", "arrow", "class", "interface", "enum", "type", "other"]).optional().describe("Only return definitions of this kind")
+      }
+    },
+    async ({ query, maxResults, kind }) => {
+      await ensureReadyFor(process.cwd());
+      if (!searchIndex) {
+        throw new Error("token-shrink symbol index failed to start");
+      }
+      if (searchIndex.size === 0 && watcher && watcher.cache.entries.size > 0) {
+        searchIndex.loadCache(watcher.cache.entries);
+      }
+      const hits = searchIndex.search(query, {
+        maxResults: maxResults ?? 10,
+        kind
+      });
+      if (hits.length === 0) {
+        return textReply(`No symbols match "${query}". Try a different name or kind.`);
+      }
+      const lines = hits.map((h) => `- \`${h.label}\``);
+      return textReply(
+        `${lines.join("\n")}
+
+_Found ${hits.length} symbol${hits.length === 1 ? "" : "s"} matching "${query}"._`
+      );
+    }
+  );
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   log("MCP server connected.");
   return server;
 }
-var argv1 = process.argv[1] ? import_node_path6.default.basename(process.argv[1]) : "";
-if (argv1 === "mcp.js" || argv1 === "mcp.mjs" || argv1 === "mcp.cjs" || argv1 === "mcp.ts") {
+var argv1 = process.argv[1] ? import_node_path9.default.basename(process.argv[1]) : "";
+var argv1Real = "";
+try {
+  argv1Real = process.argv[1] ? import_node_path9.default.basename(import_node_fs7.default.realpathSync(process.argv[1])) : "";
+} catch {
+}
+var invokedAsMcp = argv1 === "mcp.js" || argv1 === "mcp.mjs" || argv1 === "mcp.cjs" || argv1 === "mcp.ts" || argv1Real === "mcp.js" || argv1Real === "mcp.mjs" || argv1Real === "mcp.cjs" || argv1Real === "mcp.ts";
+if (invokedAsMcp) {
   const rootArg = (() => {
     const i = process.argv.indexOf("--root");
     if (i !== -1 && process.argv[i + 1]) return process.argv[i + 1];
@@ -870,6 +1864,8 @@ if (argv1 === "mcp.js" || argv1 === "mcp.mjs" || argv1 === "mcp.cjs" || argv1 ==
   CLINE_RULE_SENTINEL,
   CURSOR_RULE_PATH,
   RULE_TARGET_PATH,
+  RULE_VERSION,
+  RULE_VERSION_MARKER,
   createAutoRule,
   createCursorRule,
   startMcpServer