trace-mcp 1.21.2 → 1.22.0

package/dist/cli.js

@@ -11,10 +11,10 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __glob = (map) => (path132) => {
-  var fn2 = map[path132];
+var __glob = (map) => (path134) => {
+  var fn2 = map[path134];
   if (fn2) return fn2();
-  throw new Error("Module not found in bundle: " + path132);
+  throw new Error("Module not found in bundle: " + path134);
 };
 var __esm = (fn2, res) => function __init() {
   return fn2 && (res = (0, fn2[__getOwnPropNames(fn2)[0]])(fn2 = 0)), res;
@@ -1197,14 +1197,14 @@ var init_file_repository = __esm({
       }
       db;
       _stmts;
-      insertFile(path132, language, contentHash, byteLength, workspace, mtimeMs, createNode) {
-        const result = this._stmts.insertFile.run(path132, language, contentHash, byteLength, workspace, mtimeMs);
+      insertFile(path134, language, contentHash, byteLength, workspace, mtimeMs, createNode) {
+        const result = this._stmts.insertFile.run(path134, language, contentHash, byteLength, workspace, mtimeMs);
         const fileId = Number(result.lastInsertRowid);
         createNode("file", fileId);
         return fileId;
       }
-      getFile(path132) {
-        return this._stmts.getFile.get(path132);
+      getFile(path134) {
+        return this._stmts.getFile.get(path134);
       }
       getFileById(id) {
         return this._stmts.getFileById.get(id);
@@ -2143,9 +2143,9 @@ var init_store = __esm({
       domain;
       analytics;
       // --- Files (delegates to FileRepository) ---
-      insertFile(path132, language, contentHash, byteLength, workspace, mtimeMs) {
+      insertFile(path134, language, contentHash, byteLength, workspace, mtimeMs) {
         return this.files.insertFile(
-          path132,
+          path134,
           language,
           contentHash,
           byteLength,
@@ -2154,8 +2154,8 @@ var init_store = __esm({
           (nodeType, refId) => this.graph.createNode(nodeType, refId)
         );
       }
-      getFile(path132) {
-        return this.files.getFile(path132);
+      getFile(path134) {
+        return this.files.getFile(path134);
       }
       getFileById(id) {
         return this.files.getFileById(id);
@@ -27818,8 +27818,8 @@ var init_rails = __esm({
 
 // src/indexer/plugins/integration/framework/spring/index.ts
 import { ok as ok42 } from "neverthrow";
-function normalizePath(path132) {
-  return "/" + path132.replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
+function normalizePath(path134) {
+  return "/" + path134.replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
 }
 var SpringPlugin;
 var init_spring = __esm({
@@ -27886,8 +27886,8 @@ var init_spring = __esm({
           const re = new RegExp(`@${annotation}\\s*(?:\\(\\s*(?:value\\s*=\\s*)?["']([^"']*)["']\\s*\\))?`, "g");
           let m;
           while ((m = re.exec(source)) !== null) {
-            const path132 = m[1] ?? "";
-            const uri = normalizePath(classPrefix + "/" + path132);
+            const path134 = m[1] ?? "";
+            const uri = normalizePath(classPrefix + "/" + path134);
             result.routes.push({ method, uri, line: source.substring(0, m.index).split("\n").length });
           }
         }
@@ -32660,8 +32660,8 @@ function extractExpoNavigationCalls(source) {
   }
   const templateRegex = /router\.(push|replace|navigate)\s*\(\s*`([^`]+)`/g;
   while ((match = templateRegex.exec(source)) !== null) {
-    const path132 = match[2].replace(/\$\{[^}]+\}/g, ":param");
-    paths.push(path132);
+    const path134 = match[2].replace(/\$\{[^}]+\}/g, ":param");
+    paths.push(path134);
   }
   const linkRegex = /<Link\s+[^>]*href\s*=\s*(?:\{?\s*)?['"]([^'"]+)['"]/g;
   while ((match = linkRegex.exec(source)) !== null) {
@@ -32673,9 +32673,9 @@ function extractExpoNavigationCalls(source) {
   }
   return [...new Set(paths)];
 }
-function matchExpoRoute(path132, routePattern) {
-  if (path132 === routePattern) return true;
-  const pathParts = path132.split("/").filter(Boolean);
+function matchExpoRoute(path134, routePattern) {
+  if (path134 === routePattern) return true;
+  const pathParts = path134.split("/").filter(Boolean);
   const routeParts = routePattern.split("/").filter(Boolean);
   if (pathParts.length !== routeParts.length) {
     if (routeParts[routeParts.length - 1] === "*" && pathParts.length >= routeParts.length - 1) {
@@ -46089,9 +46089,9 @@ var init_client = __esm({
         this.proc.stderr.on("data", (chunk2) => {
           logger.debug({ lsp: this.command, stderr: chunk2.toString().trim() }, "LSP stderr");
         });
-        this.proc.on("error", (err48) => {
-          logger.warn({ lsp: this.command, error: err48.message }, "LSP process error");
-          this.rejectAll(new Error(`LSP process error: ${err48.message}`));
+        this.proc.on("error", (err49) => {
+          logger.warn({ lsp: this.command, error: err49.message }, "LSP process error");
+          this.rejectAll(new Error(`LSP process error: ${err49.message}`));
         });
         this.proc.on("exit", (code, signal) => {
           logger.debug({ lsp: this.command, code, signal }, "LSP process exited");
@@ -47264,9 +47264,9 @@ var require_backend_impl = __commonJS({
       if (!backend) {
         throw new Error(`no available backend found. ERR: ${errors.map((e) => `[${e.name}] ${e.err}`).join(", ")}`);
       }
-      for (const { name, err: err48 } of errors) {
+      for (const { name, err: err49 } of errors) {
         if (backendHints.includes(name)) {
-          console.warn(`removing requested execution provider "${name}" from session options because it is not available: ${err48}`);
+          console.warn(`removing requested execution provider "${name}" from session options because it is not available: ${err49}`);
         }
       }
       const filteredEps = eps.filter((i) => availableBackendNames.has(typeof i === "string" ? i : i.name));
@@ -49752,27 +49752,27 @@ var require_process = __commonJS({
 var require_filesystem = __commonJS({
   "node_modules/detect-libc/lib/filesystem.js"(exports, module) {
     "use strict";
-    var fs122 = __require("fs");
+    var fs123 = __require("fs");
     var LDD_PATH = "/usr/bin/ldd";
     var SELF_PATH = "/proc/self/exe";
     var MAX_LENGTH = 2048;
-    var readFileSync11 = (path132) => {
-      const fd = fs122.openSync(path132, "r");
+    var readFileSync12 = (path134) => {
+      const fd = fs123.openSync(path134, "r");
       const buffer = Buffer.alloc(MAX_LENGTH);
-      const bytesRead = fs122.readSync(fd, buffer, 0, MAX_LENGTH, 0);
-      fs122.close(fd, () => {
+      const bytesRead = fs123.readSync(fd, buffer, 0, MAX_LENGTH, 0);
+      fs123.close(fd, () => {
       });
       return buffer.subarray(0, bytesRead);
     };
-    var readFile = (path132) => new Promise((resolve4, reject) => {
-      fs122.open(path132, "r", (err48, fd) => {
-        if (err48) {
-          reject(err48);
+    var readFile = (path134) => new Promise((resolve4, reject) => {
+      fs123.open(path134, "r", (err49, fd) => {
+        if (err49) {
+          reject(err49);
         } else {
           const buffer = Buffer.alloc(MAX_LENGTH);
-          fs122.read(fd, buffer, 0, MAX_LENGTH, 0, (_, bytesRead) => {
+          fs123.read(fd, buffer, 0, MAX_LENGTH, 0, (_, bytesRead) => {
             resolve4(buffer.subarray(0, bytesRead));
-            fs122.close(fd, () => {
+            fs123.close(fd, () => {
             });
           });
         }
@@ -49781,7 +49781,7 @@ var require_filesystem = __commonJS({
     module.exports = {
       LDD_PATH,
       SELF_PATH,
-      readFileSync: readFileSync11,
+      readFileSync: readFileSync12,
       readFile
     };
   }
@@ -49830,7 +49830,7 @@ var require_detect_libc = __commonJS({
     "use strict";
     var childProcess = __require("child_process");
     var { isLinux, getReport } = require_process();
-    var { LDD_PATH, SELF_PATH, readFile, readFileSync: readFileSync11 } = require_filesystem();
+    var { LDD_PATH, SELF_PATH, readFile, readFileSync: readFileSync12 } = require_filesystem();
     var { interpreterPath } = require_elf();
     var cachedFamilyInterpreter;
     var cachedFamilyFilesystem;
@@ -49840,8 +49840,8 @@ var require_detect_libc = __commonJS({
     var safeCommand = () => {
       if (!commandOut) {
         return new Promise((resolve4) => {
-          childProcess.exec(command, (err48, out) => {
-            commandOut = err48 ? " " : out;
+          childProcess.exec(command, (err49, out) => {
+            commandOut = err49 ? " " : out;
             resolve4(commandOut);
           });
         });
@@ -49884,11 +49884,11 @@ var require_detect_libc = __commonJS({
       }
       return null;
     };
-    var familyFromInterpreterPath = (path132) => {
-      if (path132) {
-        if (path132.includes("/ld-musl-")) {
+    var familyFromInterpreterPath = (path134) => {
+      if (path134) {
+        if (path134.includes("/ld-musl-")) {
           return MUSL;
-        } else if (path132.includes("/ld-linux-")) {
+        } else if (path134.includes("/ld-linux-")) {
           return GLIBC;
         }
       }
@@ -49922,7 +49922,7 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyFilesystem = null;
       try {
-        const lddContent = readFileSync11(LDD_PATH);
+        const lddContent = readFileSync12(LDD_PATH);
         cachedFamilyFilesystem = getFamilyFromLddContent(lddContent);
       } catch (e) {
       }
@@ -49935,8 +49935,8 @@ var require_detect_libc = __commonJS({
       cachedFamilyInterpreter = null;
       try {
         const selfContent = await readFile(SELF_PATH);
-        const path132 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path132);
+        const path134 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path134);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -49947,9 +49947,9 @@ var require_detect_libc = __commonJS({
       }
       cachedFamilyInterpreter = null;
       try {
-        const selfContent = readFileSync11(SELF_PATH);
-        const path132 = interpreterPath(selfContent);
-        cachedFamilyInterpreter = familyFromInterpreterPath(path132);
+        const selfContent = readFileSync12(SELF_PATH);
+        const path134 = interpreterPath(selfContent);
+        cachedFamilyInterpreter = familyFromInterpreterPath(path134);
       } catch (e) {
       }
       return cachedFamilyInterpreter;
@@ -50011,7 +50011,7 @@ var require_detect_libc = __commonJS({
       }
       cachedVersionFilesystem = null;
       try {
-        const lddContent = readFileSync11(LDD_PATH);
+        const lddContent = readFileSync12(LDD_PATH);
         const versionMatch = lddContent.match(RE_GLIBC_VERSION);
         if (versionMatch) {
           cachedVersionFilesystem = versionMatch[1];
@@ -51668,21 +51668,21 @@ var require_sharp = __commonJS({
       `@img/sharp-${runtimePlatform}/sharp.node`,
       "@img/sharp-wasm32/sharp.node"
     ];
-    var path132;
+    var path134;
     var sharp2;
     var errors = [];
-    for (path132 of paths) {
+    for (path134 of paths) {
       try {
-        sharp2 = __require(path132);
+        sharp2 = __require(path134);
         break;
-      } catch (err48) {
-        errors.push(err48);
+      } catch (err49) {
+        errors.push(err49);
       }
     }
-    if (sharp2 && path132.startsWith("@img/sharp-linux-x64") && !sharp2._isUsingX64V2()) {
-      const err48 = new Error("Prebuilt binaries for linux-x64 require v2 microarchitecture");
-      err48.code = "Unsupported CPU";
-      errors.push(err48);
+    if (sharp2 && path134.startsWith("@img/sharp-linux-x64") && !sharp2._isUsingX64V2()) {
+      const err49 = new Error("Prebuilt binaries for linux-x64 require v2 microarchitecture");
+      err49.code = "Unsupported CPU";
+      errors.push(err49);
       sharp2 = null;
     }
     if (sharp2) {
@@ -51690,12 +51690,12 @@ var require_sharp = __commonJS({
     } else {
       const [isLinux, isMacOs, isWindows] = ["linux", "darwin", "win32"].map((os16) => runtimePlatform.startsWith(os16));
       const help = [`Could not load the "sharp" module using the ${runtimePlatform} runtime`];
-      errors.forEach((err48) => {
-        if (err48.code !== "MODULE_NOT_FOUND") {
-          help.push(`${err48.code}: ${err48.message}`);
+      errors.forEach((err49) => {
+        if (err49.code !== "MODULE_NOT_FOUND") {
+          help.push(`${err49.code}: ${err49.message}`);
         }
       });
-      const messages = errors.map((err48) => err48.message).join(" ");
+      const messages = errors.map((err49) => err49.message).join(" ");
       help.push("Possible solutions:");
       if (isUnsupportedNodeRuntime()) {
         const { found, expected } = isUnsupportedNodeRuntime();
@@ -51748,7 +51748,7 @@ var require_sharp = __commonJS({
           "    brew update && brew upgrade vips"
         );
       }
-      if (errors.some((err48) => err48.code === "ERR_DLOPEN_DISABLED")) {
+      if (errors.some((err49) => err49.code === "ERR_DLOPEN_DISABLED")) {
         help.push("- Run Node.js without using the --no-addons flag");
       }
       if (isWindows && /The specified procedure could not be found/.test(messages)) {
@@ -52502,18 +52502,18 @@ var require_input = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.metadata(this.options, (err48, metadata2) => {
-              if (err48) {
-                callback(is2.nativeError(err48, stack2));
+            sharp2.metadata(this.options, (err49, metadata2) => {
+              if (err49) {
+                callback(is2.nativeError(err49, stack2));
               } else {
                 callback(null, metadata2);
               }
             });
           });
         } else {
-          sharp2.metadata(this.options, (err48, metadata2) => {
-            if (err48) {
-              callback(is2.nativeError(err48, stack2));
+          sharp2.metadata(this.options, (err49, metadata2) => {
+            if (err49) {
+              callback(is2.nativeError(err49, stack2));
             } else {
               callback(null, metadata2);
             }
@@ -52525,9 +52525,9 @@ var require_input = __commonJS({
           return new Promise((resolve4, reject) => {
             const finished = () => {
               this._flattenBufferIn();
-              sharp2.metadata(this.options, (err48, metadata2) => {
-                if (err48) {
-                  reject(is2.nativeError(err48, stack2));
+              sharp2.metadata(this.options, (err49, metadata2) => {
+                if (err49) {
+                  reject(is2.nativeError(err49, stack2));
                 } else {
                   resolve4(metadata2);
                 }
@@ -52541,9 +52541,9 @@ var require_input = __commonJS({
           });
         } else {
           return new Promise((resolve4, reject) => {
-            sharp2.metadata(this.options, (err48, metadata2) => {
-              if (err48) {
-                reject(is2.nativeError(err48, stack2));
+            sharp2.metadata(this.options, (err49, metadata2) => {
+              if (err49) {
+                reject(is2.nativeError(err49, stack2));
               } else {
                 resolve4(metadata2);
               }
@@ -52558,18 +52558,18 @@ var require_input = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.stats(this.options, (err48, stats2) => {
-              if (err48) {
-                callback(is2.nativeError(err48, stack2));
+            sharp2.stats(this.options, (err49, stats2) => {
+              if (err49) {
+                callback(is2.nativeError(err49, stack2));
               } else {
                 callback(null, stats2);
               }
             });
           });
         } else {
-          sharp2.stats(this.options, (err48, stats2) => {
-            if (err48) {
-              callback(is2.nativeError(err48, stack2));
+          sharp2.stats(this.options, (err49, stats2) => {
+            if (err49) {
+              callback(is2.nativeError(err49, stack2));
             } else {
               callback(null, stats2);
             }
@@ -52581,9 +52581,9 @@ var require_input = __commonJS({
           return new Promise((resolve4, reject) => {
             this.on("finish", function() {
               this._flattenBufferIn();
-              sharp2.stats(this.options, (err48, stats2) => {
-                if (err48) {
-                  reject(is2.nativeError(err48, stack2));
+              sharp2.stats(this.options, (err49, stats2) => {
+                if (err49) {
+                  reject(is2.nativeError(err49, stack2));
                 } else {
                   resolve4(stats2);
                 }
@@ -52592,9 +52592,9 @@ var require_input = __commonJS({
           });
         } else {
           return new Promise((resolve4, reject) => {
-            sharp2.stats(this.options, (err48, stats2) => {
-              if (err48) {
-                reject(is2.nativeError(err48, stack2));
+            sharp2.stats(this.options, (err49, stats2) => {
+              if (err49) {
+                reject(is2.nativeError(err49, stack2));
               } else {
                 resolve4(stats2);
               }
@@ -54590,15 +54590,15 @@ var require_color = __commonJS({
       };
     }
     function wrapConversion(toModel, graph) {
-      const path132 = [graph[toModel].parent, toModel];
+      const path134 = [graph[toModel].parent, toModel];
       let fn2 = conversions_default[graph[toModel].parent][toModel];
       let cur = graph[toModel].parent;
       while (graph[cur].parent) {
-        path132.unshift(graph[cur].parent);
+        path134.unshift(graph[cur].parent);
         fn2 = link(conversions_default[graph[cur].parent][cur], fn2);
         cur = graph[cur].parent;
       }
-      fn2.conversion = path132;
+      fn2.conversion = path134;
       return fn2;
     }
     function route(fromModel) {
@@ -55215,7 +55215,7 @@ var require_channel = __commonJS({
 var require_output = __commonJS({
   "node_modules/sharp/lib/output.js"(exports, module) {
     "use strict";
-    var path132 = __require("path");
+    var path134 = __require("path");
     var is2 = require_is();
     var sharp2 = require_sharp();
     var formats = /* @__PURE__ */ new Map([
@@ -55243,19 +55243,19 @@ var require_output = __commonJS({
     var errJp2Save = () => new Error("JP2 output requires libvips with support for OpenJPEG");
     var bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math.log2(colours)));
     function toFile(fileOut, callback) {
-      let err48;
+      let err49;
       if (!is2.string(fileOut)) {
-        err48 = new Error("Missing output file path");
-      } else if (is2.string(this.options.input.file) && path132.resolve(this.options.input.file) === path132.resolve(fileOut)) {
-        err48 = new Error("Cannot use same file for input and output");
-      } else if (jp2Regex.test(path132.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
-        err48 = errJp2Save();
+        err49 = new Error("Missing output file path");
+      } else if (is2.string(this.options.input.file) && path134.resolve(this.options.input.file) === path134.resolve(fileOut)) {
+        err49 = new Error("Cannot use same file for input and output");
+      } else if (jp2Regex.test(path134.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
+        err49 = errJp2Save();
       }
-      if (err48) {
+      if (err49) {
         if (is2.fn(callback)) {
-          callback(err48);
+          callback(err49);
         } else {
-          return Promise.reject(err48);
+          return Promise.reject(err49);
         }
       } else {
         this.options.fileOut = fileOut;
@@ -55969,18 +55969,18 @@ var require_output = __commonJS({
         if (this._isStreamInput()) {
           this.on("finish", () => {
             this._flattenBufferIn();
-            sharp2.pipeline(this.options, (err48, data, info) => {
-              if (err48) {
-                callback(is2.nativeError(err48, stack2));
+            sharp2.pipeline(this.options, (err49, data, info) => {
+              if (err49) {
+                callback(is2.nativeError(err49, stack2));
               } else {
                 callback(null, data, info);
               }
             });
           });
         } else {
-          sharp2.pipeline(this.options, (err48, data, info) => {
-            if (err48) {
-              callback(is2.nativeError(err48, stack2));
+          sharp2.pipeline(this.options, (err49, data, info) => {
+            if (err49) {
+              callback(is2.nativeError(err49, stack2));
             } else {
               callback(null, data, info);
             }
@@ -55991,9 +55991,9 @@ var require_output = __commonJS({
         if (this._isStreamInput()) {
           this.once("finish", () => {
             this._flattenBufferIn();
-            sharp2.pipeline(this.options, (err48, data, info) => {
-              if (err48) {
-                this.emit("error", is2.nativeError(err48, stack2));
+            sharp2.pipeline(this.options, (err49, data, info) => {
+              if (err49) {
+                this.emit("error", is2.nativeError(err49, stack2));
               } else {
                 this.emit("info", info);
                 this.push(data);
@@ -56006,9 +56006,9 @@ var require_output = __commonJS({
             this.emit("finish");
           }
         } else {
-          sharp2.pipeline(this.options, (err48, data, info) => {
-            if (err48) {
-              this.emit("error", is2.nativeError(err48, stack2));
+          sharp2.pipeline(this.options, (err49, data, info) => {
+            if (err49) {
+              this.emit("error", is2.nativeError(err49, stack2));
             } else {
               this.emit("info", info);
               this.push(data);
@@ -56023,9 +56023,9 @@ var require_output = __commonJS({
           return new Promise((resolve4, reject) => {
             this.once("finish", () => {
               this._flattenBufferIn();
-              sharp2.pipeline(this.options, (err48, data, info) => {
-                if (err48) {
-                  reject(is2.nativeError(err48, stack2));
+              sharp2.pipeline(this.options, (err49, data, info) => {
+                if (err49) {
+                  reject(is2.nativeError(err49, stack2));
                 } else {
                   if (this.options.resolveWithObject) {
                     resolve4({ data, info });
@@ -56038,9 +56038,9 @@ var require_output = __commonJS({
           });
         } else {
           return new Promise((resolve4, reject) => {
-            sharp2.pipeline(this.options, (err48, data, info) => {
-              if (err48) {
-                reject(is2.nativeError(err48, stack2));
+            sharp2.pipeline(this.options, (err49, data, info) => {
+              if (err49) {
+                reject(is2.nativeError(err49, stack2));
               } else {
                 if (this.options.resolveWithObject) {
                   resolve4({ data, info });
@@ -58676,9 +58676,9 @@ function memoizePromise(key, factory) {
   }
   const promise = factory().then(
     (value) => value,
-    (err48) => {
+    (err49) => {
       cache.delete(key);
-      return Promise.reject(err48);
+      return Promise.reject(err49);
     }
   );
   cache.put(key, promise);
@@ -58865,8 +58865,8 @@ async function storeCachedResource(path_or_repo_id, filename, cache2, cacheKey,
           headers
         }
       )
-    ).catch((err48) => {
-      logger2.warn(`Unable to add response to browser cache: ${err48}.`);
+    ).catch((err49) => {
+      logger2.warn(`Unable to add response to browser cache: ${err49}.`);
     });
   }
 }
@@ -59049,9 +59049,9 @@ async function getModelFile(path_or_repo_id, filename, fatal = true, options = {
         INFLIGHT_LOADS.delete(key);
         return result;
       },
-      (err48) => {
+      (err49) => {
         INFLIGHT_LOADS.delete(key);
-        throw err48;
+        throw err49;
       }
     );
     INFLIGHT_LOADS.set(key, pending);
@@ -61126,8 +61126,8 @@ async function ensureWasmLoaded() {
             ONNX_ENV.wasm.wasmBinary = wasmBinary;
             wasmBinaryLoaded = true;
           }
-        } catch (err48) {
-          logger2.warn("Failed to pre-load WASM binary:", err48);
+        } catch (err49) {
+          logger2.warn("Failed to pre-load WASM binary:", err49);
         }
       })() : Promise.resolve(),
       // Load and cache the WASM factory as a blob URL
@@ -61137,8 +61137,8 @@ async function ensureWasmLoaded() {
           if (wasmFactoryBlob) {
             ONNX_ENV.wasm.wasmPaths.mjs = wasmFactoryBlob;
           }
-        } catch (err48) {
-          logger2.warn("Failed to pre-load WASM factory:", err48);
+        } catch (err49) {
+          logger2.warn("Failed to pre-load WASM factory:", err49);
         }
       })() : Promise.resolve()
     ]);
@@ -68281,14 +68281,14 @@ var init_transformers_node = __esm({
           try {
             const evaluated = this.evaluateBlock(node.body, scope8);
             result += evaluated.value;
-          } catch (err48) {
-            if (err48 instanceof ContinueControl) {
+          } catch (err49) {
+            if (err49 instanceof ContinueControl) {
               continue;
             }
-            if (err48 instanceof BreakControl) {
+            if (err49 instanceof BreakControl) {
               break;
             }
-            throw err48;
+            throw err49;
           }
           noIteration = false;
         }
@@ -68493,7 +68493,7 @@ var init_transformers_node = __esm({
             start(controller) {
               stream.on("data", (chunk2) => controller.enqueue(chunk2));
               stream.on("end", () => controller.close());
-              stream.on("error", (err48) => controller.error(err48));
+              stream.on("error", (err49) => controller.error(err49));
             },
             cancel() {
               stream.destroy();
@@ -68770,9 +68770,9 @@ var init_transformers_node = __esm({
               break;
             }
             await new Promise((resolve4, reject) => {
-              fileStream.write(value, (err48) => {
-                if (err48) {
-                  reject(err48);
+              fileStream.write(value, (err49) => {
+                if (err49) {
+                  reject(err49);
                   return;
                 }
                 resolve4();
@@ -68783,7 +68783,7 @@ var init_transformers_node = __esm({
             progress_callback?.({ progress, loaded, total });
           }
           await new Promise((resolve4, reject) => {
-            fileStream.close((err48) => err48 ? reject(err48) : resolve4());
+            fileStream.close((err49) => err49 ? reject(err49) : resolve4());
           });
           await fs310.promises.rename(tmpPath, filePath);
         } catch (error) {
@@ -90763,7 +90763,7 @@ var require_package2 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "trace-mcp",
-      version: "1.21.2",
+      version: "1.22.0",
       mcpName: "io.github.nikolai-vysotskyi/trace-mcp",
       description: "Framework-aware code intelligence MCP server \u2014 48+ frameworks, 68 languages",
       type: "module",
@@ -90785,7 +90785,7 @@ var require_package2 = __commonJS({
       engines: {
         node: ">=20.0.0"
       },
-      license: "ELv2",
+      license: "MIT",
       author: "Nikolai Vysotskyi",
       repository: {
         type: "git",
@@ -90855,9 +90855,9 @@ init_schema();
 init_store();
 init_registry();
 init_config();
-import { Command as Command17 } from "commander";
-import path131 from "path";
-import fs121 from "fs";
+import { Command as Command18 } from "commander";
+import path133 from "path";
+import fs122 from "fs";
 import { randomUUID } from "crypto";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -90869,7 +90869,7 @@ import https from "https";
 import { spawnSync } from "child_process";
 import path65 from "path";
 import fs66 from "fs";
-var CURRENT_VERSION = true ? "1.21.2" : "0.0.0-dev";
+var CURRENT_VERSION = true ? "1.22.0" : "0.0.0-dev";
 var UPDATE_CACHE_PATH = path65.join(TRACE_MCP_HOME, "update-check.json");
 function readCache() {
   try {
@@ -91007,15 +91007,15 @@ async function runPostUpdateMigrations() {
       installPrecompactHook2({ global: true });
       installWorktreeHook2({ global: true });
       logger.info("Post-update: hooks upgraded");
-    } catch (err48) {
-      logger.warn({ error: err48 }, "Post-update: hook upgrade failed (non-fatal)");
+    } catch (err49) {
+      logger.warn({ error: err49 }, "Post-update: hook upgrade failed (non-fatal)");
     }
   }
   try {
     updateClaudeMd2(process.cwd(), { scope: "global" });
     logger.info("Post-update: CLAUDE.md updated");
-  } catch (err48) {
-    logger.warn({ error: err48 }, "Post-update: CLAUDE.md update failed (non-fatal)");
+  } catch (err49) {
+    logger.warn({ error: err49 }, "Post-update: CLAUDE.md update failed (non-fatal)");
   }
   const projects = listProjects3();
   if (projects.length > 0) {
@@ -91054,8 +91054,8 @@ async function runPostUpdateMigrations() {
           { root: proj.root, indexed: result.indexed, skipped: result.skipped, errors: result.errors },
           "Post-update: project reindexed"
         );
-      } catch (err48) {
-        logger.warn({ root: proj.root, error: err48 }, "Post-update: project reindex failed (non-fatal)");
+      } catch (err49) {
+        logger.warn({ root: proj.root, error: err49 }, "Post-update: project reindex failed (non-fatal)");
       }
     }
   }
@@ -92883,8 +92883,8 @@ var SessionJournal = class _SessionJournal {
     };
     this.entries.push(entry);
     if (tool === "get_symbol" || tool === "get_outline") {
-      const path132 = params.path ?? params.file_path ?? "";
-      if (path132) this.filesRead.add(path132);
+      const path134 = params.path ?? params.file_path ?? "";
+      if (path134) this.filesRead.add(path134);
     }
     if (resultCount === 0 && this.isSearchTool(tool)) {
       this.zeroResultQueries.set(hash, summary);
@@ -93625,6 +93625,7 @@ var COMPACT_CORE_PARAMS = {
   scan_security: ["file_pattern", "rules"],
   check_quality_gates: ["scope"],
   taint_analysis: ["source_symbol_id", "file_pattern"],
+  export_security_context: ["scope", "depth"],
   audit_config: [],
   // Framework
   get_request_flow: ["route", "method"],
@@ -93650,6 +93651,86 @@ var COMPACT_CORE_PARAMS = {
   batch: ["calls"]
 };
 
+// src/server/tool-annotations.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var INDEX_MUTATING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var FILE_WRITING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var FILE_DESTRUCTIVE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var OUTPUT_WRITING = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var RUNTIME_READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var OVERRIDES = {
+  // ── Refactoring: file-destructive ──
+  apply_codemod: FILE_DESTRUCTIVE,
+  remove_dead_code: FILE_DESTRUCTIVE,
+  // ── Refactoring: file-writing (non-destructive) ──
+  apply_rename: FILE_WRITING,
+  apply_move: FILE_WRITING,
+  change_signature: FILE_WRITING,
+  extract_function: FILE_WRITING,
+  // ── Output generation (writes files but doesn't modify source) ──
+  generate_docs: OUTPUT_WRITING,
+  generate_sbom: OUTPUT_WRITING,
+  visualize_graph: OUTPUT_WRITING,
+  visualize_subproject_topology: OUTPUT_WRITING,
+  // ── Index / store mutation (idempotent) ──
+  reindex: INDEX_MUTATING,
+  register_edit: INDEX_MUTATING,
+  embed_repo: INDEX_MUTATING,
+  subproject_add_repo: INDEX_MUTATING,
+  subproject_sync: INDEX_MUTATING,
+  invalidate_decision: INDEX_MUTATING,
+  index_sessions: INDEX_MUTATING,
+  mine_sessions: INDEX_MUTATING,
+  refresh_co_changes: INDEX_MUTATING,
+  detect_communities: INDEX_MUTATING,
+  // ── Store mutation (not idempotent — creates new records) ──
+  add_decision: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  // ── Runtime intelligence (reads external OTLP data) ──
+  get_runtime_profile: RUNTIME_READ,
+  get_runtime_call_graph: RUNTIME_READ,
+  get_endpoint_analytics: RUNTIME_READ,
+  get_runtime_deps: RUNTIME_READ
+};
+var DEFAULT_ANNOTATIONS = READ_ONLY;
+function getToolAnnotations(toolName) {
+  return OVERRIDES[toolName] ?? DEFAULT_ANNOTATIONS;
+}
+
 // src/server/tool-gate.ts
 function applyParamOverrides(schema, toolOverrides, sharedOverrides) {
   for (const paramName of Object.keys(schema)) {
@@ -93811,9 +93892,23 @@ function installToolGate(server, config, activePreset, savings, journal, j3, ext
         return result;
       };
     }
+    const annotations = getToolAnnotations(name);
+    const lastIdx = args.length - 1;
+    if (typeof args[lastIdx] === "function") {
+      args.splice(lastIdx, 0, annotations);
+    }
     return _originalTool(...args);
   });
-  return { _originalTool, registeredToolNames, toolHandlers };
+  const annotatedOriginalTool = ((...oArgs) => {
+    const oName = oArgs[0];
+    const ann = getToolAnnotations(oName);
+    const oLastIdx = oArgs.length - 1;
+    if (typeof oArgs[oLastIdx] === "function") {
+      oArgs.splice(oLastIdx, 0, ann);
+    }
+    return _originalTool(...oArgs);
+  });
+  return { _originalTool: annotatedOriginalTool, registeredToolNames, toolHandlers };
 }
 
 // src/tools/register/core.ts
@@ -93964,7 +94059,7 @@ function registerCoreTools(server, ctx) {
   const { store, registry, config, projectRoot, guardPath, j: j3, jh, journal, vectorStore, embeddingService, progress } = ctx;
   server.tool(
     "get_index_health",
-    "Get index status, statistics, health information, and pipeline progress (indexing, summarization, embedding)",
+    "Get index status, statistics, health information, and pipeline progress (indexing, summarization, embedding). Read-only, no side effects. Use to verify the index is ready before running queries. Returns JSON: { totalFiles, totalSymbols, languages, frameworks, pipelineProgress }.",
     {},
     async () => {
       const result = getIndexHealth(store, config);
@@ -93976,7 +94071,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "reindex",
-    "Trigger (re)indexing of the project or a subdirectory",
+    "Trigger (re)indexing of the project or a subdirectory. Mutates the local index (SQLite). Use after major file changes; for single-file updates prefer register_edit instead. Idempotent \u2014 safe to re-run. Returns JSON: { status, totalFiles, indexed, skipped, errors, durationMs }.",
     {
       path: z3.string().max(512).optional().describe("Subdirectory to index (default: project root)"),
       force: z3.boolean().optional().describe("Skip hash check and reindex all files")
@@ -93994,7 +94089,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "embed_repo",
-    "Precompute and cache symbol embeddings for semantic / hybrid search. Embeddings are also computed lazily on first semantic query, but calling this once after a fresh index avoids the first-query latency spike. Requires AI provider to be enabled in config (ollama/openai). Set force=true to drop and recompute all existing embeddings.",
+    "Precompute and cache symbol embeddings for semantic / hybrid search. Embeddings are also computed lazily on first semantic query, but calling this once after a fresh index avoids the first-query latency spike. Requires AI provider to be enabled in config (ollama/openai). Set force=true to drop and recompute all existing embeddings. Mutates the vector store; idempotent. Use after reindex when you plan to use semantic search. Returns JSON: { status, indexed_this_run, total_embedded, coverage_pct, duration_ms }.",
     {
       batch_size: z3.number().int().min(1).max(500).optional().describe("Symbols per embedding API batch (default 50)"),
       force: z3.boolean().optional().describe("Drop existing embeddings and re-embed everything (default false \u2014 incremental)")
@@ -94049,7 +94144,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "register_edit",
-    "Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh. Also checks for duplicate symbols \u2014 if `_duplication_warnings` appears in the response, you may be recreating existing logic; review the referenced symbols before continuing.",
+    "Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh \u2014 much lighter than full reindex. Also checks for duplicate symbols \u2014 if `_duplication_warnings` appears in the response, you may be recreating existing logic; review the referenced symbols before continuing. Mutates the index; idempotent. Returns JSON: { status, file, totalFiles, indexed, _duplication_warnings? }.",
     {
       file_path: z3.string().min(1).max(512).describe("Relative path to the edited file")
     },
@@ -94085,7 +94180,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "get_project_map",
-    "Get project overview: detected frameworks, languages, file counts, structure. Call with summary_only=true at session start to orient yourself before diving into code.",
+    "Get project overview: detected frameworks, languages, file counts, structure. Read-only, no side effects. Call with summary_only=true at session start to orient yourself before diving into code. Use instead of manual ls/find. Returns JSON: { frameworks, languages, fileCount, symbolCount, structure }.",
     {
       summary_only: z3.boolean().optional().describe("Return only framework list + counts (default false)")
     },
@@ -94097,7 +94192,7 @@ function registerCoreTools(server, ctx) {
   );
   server.tool(
     "get_env_vars",
-    "List environment variable keys from .env files with inferred value types/formats. Never exposes actual values \u2014 only keys, types (string/number/boolean/empty), and formats (url/email/ip/path/uuid/json/base64/csv/dsn/etc). Use to understand project configuration without accessing secrets.",
+    "List environment variable keys from .env files with inferred value types/formats. Never exposes actual values \u2014 only keys, types (string/number/boolean/empty), and formats (url/email/ip/path/uuid/json/base64/csv/dsn/etc). Read-only, no side effects, safe for secrets. Use to understand project configuration without accessing actual values. Returns JSON grouped by file: { [file]: [{ key, type, format, comment }] }.",
     {
       pattern: z3.string().max(256).optional().describe('Filter keys by pattern (e.g. "DB_" or "REDIS")'),
       file: z3.string().max(512).optional().describe("Filter by specific .env file path")
@@ -95200,9 +95295,9 @@ function deduplicateByFile(rawDeps) {
     }
   }
   const result = [];
-  for (const [path132, entry] of fileMap) {
+  for (const [path134, entry] of fileMap) {
     const dep = {
-      path: path132,
+      path: path134,
       edgeTypes: [...entry.edgeTypes],
       depth: entry.depth
     };
@@ -95781,8 +95876,8 @@ var FileReadCache = class {
     if (buf === void 0) {
       try {
         const absPath = path77.resolve(this.rootPath, file.path);
-        const fs122 = __require("fs");
-        buf = fs122.readFileSync(absPath);
+        const fs123 = __require("fs");
+        buf = fs123.readFileSync(absPath);
       } catch {
         buf = null;
       }
@@ -98594,7 +98689,7 @@ function registerNavigationTools(server, ctx) {
   const { store, projectRoot, guardPath, j: j3, jh, savings, vectorStore, embeddingService, reranker, markExplored, decisionStore } = ctx;
   server.tool(
     "get_symbol",
-    "Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method \u2014 returns only the symbol, not the whole file.",
+    "Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method \u2014 returns only the symbol, not the whole file. For multiple symbols at once, prefer get_context_bundle. Read-only. Returns JSON: { symbol_id, name, kind, fqn, signature, file, line_start, line_end, source }.",
     {
       symbol_id: z4.string().max(512).optional().describe("The symbol_id to look up"),
       fqn: z4.string().max(512).optional().describe("The fully qualified name to look up"),
@@ -98629,7 +98724,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "search",
-    'Search symbols by name, kind, or text. Use instead of Grep when looking for functions, classes, methods, or variables in source code. Supports kind/language/file_pattern filters. Set fuzzy=true for typo-tolerant search (trigram + Levenshtein). For natural-language / conceptual queries set semantic="on" (requires an AI provider configured + embed_repo run once). Set fusion=true for Signal Fusion \u2014 multi-channel ranking (BM25 + PageRank + embeddings + identity match) via Weighted Reciprocal Rank fusion.',
+    'Search symbols by name, kind, or text. Use instead of Grep when looking for functions, classes, methods, or variables in source code. For raw text/string/comment search use search_text instead. For finding who references a known symbol use find_usages instead. Supports kind/language/file_pattern filters. Set fuzzy=true for typo-tolerant search (trigram + Levenshtein). For natural-language / conceptual queries set semantic="on" (requires an AI provider configured + embed_repo run once). Set fusion=true for Signal Fusion \u2014 multi-channel ranking (BM25 + PageRank + embeddings + identity match) via Weighted Reciprocal Rank fusion. Read-only. Returns JSON: { items: [{ symbol_id, name, kind, fqn, signature, file, line, score }], total, search_mode }.',
     {
       query: z4.string().min(1).max(500).describe("Search query"),
       kind: z4.string().max(64).optional().describe("Filter by symbol kind (class, method, function, etc.)"),
@@ -98744,7 +98839,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_outline",
-    "Get all symbols for a file (signatures only, no bodies). Use instead of Read to understand a file before editing \u2014 much cheaper in tokens.",
+    "Get all symbols for a file (signatures only, no bodies). Use instead of Read to understand a file before editing \u2014 much cheaper in tokens. For reading one symbol's source, follow up with get_symbol. Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd }] }.",
     {
       path: z4.string().max(512).describe("Relative file path")
     },
@@ -98770,7 +98865,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_change_impact",
-    "Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Supports diff-aware mode via symbol_ids to scope analysis to only changed symbols.",
+    "Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Supports diff-aware mode via symbol_ids to scope analysis to only changed symbols. Use before modifying code to understand blast radius. For quick risk assessment without full report, use assess_change_risk instead. Read-only. Returns JSON: { risk, dependents, affectedTests, breakingChanges, totalAffected }.",
     {
       file_path: z4.string().max(512).optional().describe("Relative file path to analyze"),
       symbol_id: z4.string().max(512).optional().describe("Symbol ID to analyze"),
@@ -98813,7 +98908,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_feature_context",
-    "Search code by keyword/topic \u2192 returns ranked source code snippets within a token budget. Use when you need to READ actual code for a concept or feature.",
+    "Search code by keyword/topic \u2192 returns ranked source code snippets within a token budget. Use when you need to READ actual code for a concept or feature. For structured task context with tests and entry points, use get_task_context instead. For symbol metadata without source, use search. Read-only. Returns JSON: { items: [{ symbol_id, name, file, source, score }], token_usage }.",
     {
       description: z4.string().min(1).max(2e3).describe("Natural language description of the feature to find context for"),
       token_budget: z4.number().int().min(100).max(1e5).optional().describe("Max tokens for assembled context (default 4000)")
@@ -98832,7 +98927,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "suggest_queries",
-    "Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project.",
+    "Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project. For a structured project map use get_project_map instead. Read-only. Returns JSON: { topFiles, topSymbols, languageStats, exampleQueries }.",
     {},
     async () => {
       const result = suggestQueries(store);
@@ -98841,7 +98936,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_related_symbols",
-    "Find symbols related via co-location (same file), shared importers, and name similarity. Useful for discovering related code when exploring a symbol.",
+    "Find symbols related via co-location (same file), shared importers, and name similarity. Use when exploring a symbol to discover sibling code. For call-graph relationships use get_call_graph instead; for all usages use find_usages. Read-only. Returns JSON: { related: [{ symbol_id, name, kind, file, relation_type, score }] }.",
     {
       symbol_id: z4.string().max(512).describe("Symbol ID to find related symbols for"),
       max_results: z4.number().int().min(1).max(100).optional().describe("Max results (default 20)")
@@ -98856,7 +98951,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_context_bundle",
-    "Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication.",
+    "Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication. Use instead of chaining get_symbol calls \u2014 deduplicates shared imports across symbols. For a single symbol without imports, get_symbol is lighter. Read-only. Returns JSON: { primary: [{ symbol_id, file, source }], imports: [{ file, source }], token_usage }.",
     {
       symbol_id: z4.string().max(512).optional().describe("Single symbol ID"),
       symbol_ids: z4.array(z4.string().max(512)).max(20).optional().describe("Batch: multiple symbol IDs"),
@@ -98887,7 +98982,7 @@ function registerNavigationTools(server, ctx) {
   );
   server.tool(
     "get_task_context",
-    "All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task.",
+    "All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task \u2014 replaces manual chaining of search \u2192 get_symbol \u2192 Read. For narrower feature-code lookup use get_feature_context instead. Read-only. Returns JSON: { symbols: [{ symbol_id, name, file, source }], tests, entryPoints, taskType, token_usage }.",
     {
       task: z4.string().min(1).max(2e3).describe("Natural language description of the task"),
       token_budget: z4.number().int().min(100).max(1e5).optional().describe("Max tokens (default 8000)"),
@@ -100556,7 +100651,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("vue", "nuxt", "inertia")) {
     server.tool(
       "get_component_tree",
-      "Build a component render tree starting from a given .vue file",
+      "Build a component render tree starting from a given .vue file. Use to visualize parent-child component hierarchy. Read-only. Returns JSON: { root, children: [{ component, props, slots, depth }], totalComponents }.",
       {
         component_path: z5.string().max(512).describe("Relative path to the root .vue file"),
         depth: z5.number().int().min(1).max(20).optional().describe("Max tree depth (default 3)"),
@@ -100576,7 +100671,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("express", "nestjs", "laravel", "fastapi", "flask", "drf", "spring", "rails", "fastify", "hono", "trpc")) {
     server.tool(
       "get_request_flow",
-      "Trace request flow for a URL+method: route \u2192 middleware \u2192 controller \u2192 service (Laravel/Express/NestJS/Fastify/Hono/tRPC/FastAPI/Flask/DRF)",
+      "Trace request flow for a URL+method: route \u2192 middleware \u2192 controller \u2192 service (Laravel/Express/NestJS/Fastify/Hono/tRPC/FastAPI/Flask/DRF). Use to understand how a request is handled end-to-end. For middleware-only analysis use get_middleware_chain instead. Read-only. Returns JSON: { route, steps: [{ type, symbol_id, name, file }] }.",
       {
         url: z5.string().max(512).describe("Route URL (e.g. /api/users)"),
         method: z5.string().max(64).optional().describe("HTTP method (default GET)")
@@ -100593,7 +100688,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("express", "nestjs", "fastapi", "flask", "spring")) {
     server.tool(
       "get_middleware_chain",
-      "Trace middleware chain for a route URL (Express/NestJS/FastAPI/Flask)",
+      "Trace middleware chain for a route URL (Express/NestJS/FastAPI/Flask). Use when you only need the middleware stack, not the full request flow. For full route\u2192controller\u2192service flow use get_request_flow instead. Read-only. Returns JSON: { url, middlewares: [{ name, file, order }] }.",
       {
         url: z5.string().max(512).describe("Route URL to trace middleware for")
       },
@@ -100609,7 +100704,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("nestjs")) {
     server.tool(
       "get_module_graph",
-      "Build NestJS module dependency graph (module -> imports -> controllers -> providers -> exports)",
+      "Build NestJS module dependency graph (module -> imports -> controllers -> providers -> exports). Use to understand NestJS module structure and DI wiring. For provider-level DI tree use get_di_tree instead. Read-only. Returns JSON: { module, imports, controllers, providers, exports, edges }.",
       {
         module_name: z5.string().max(256).describe("NestJS module class name (e.g. AppModule)")
       },
@@ -100623,7 +100718,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_di_tree",
-      "Trace NestJS dependency injection tree (what a service injects + who injects it)",
+      "Trace NestJS dependency injection tree (what a service injects + who injects it). Use to understand DI wiring for a specific provider. For module-level graph use get_module_graph instead. Read-only. Returns JSON: { service, injects: [{ name, kind }], injected_by: [{ name, kind }] }.",
       {
         service_name: z5.string().max(256).describe("NestJS service/provider class name")
       },
@@ -100639,7 +100734,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("react-native")) {
     server.tool(
       "get_navigation_graph",
-      "Build React Native navigation tree from screens, navigators, and deep links",
+      "Build React Native navigation tree from screens, navigators, and deep links. Use to understand app navigation structure. For details on a specific screen use get_screen_context instead. Read-only. Returns JSON: { navigators, screens, deepLinks, edges }.",
       {},
       async () => {
         const result = getNavigationGraph(store);
@@ -100651,7 +100746,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_screen_context",
-      "Get full context for a React Native screen: navigator, navigation edges, deep link, platform variants, native modules",
+      "Get full context for a React Native screen: navigator, navigation edges, deep link, platform variants, native modules. Use to understand a specific screen before modifying it. For the full navigation tree use get_navigation_graph instead. Read-only. Returns JSON: { screen, navigator, deepLink, platformVariants, nativeModules, navigationEdges }.",
       {
         screen_name: z5.string().max(256).describe("Screen name (e.g. ProfileScreen or Profile)")
       },
@@ -100667,7 +100762,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel", "mongoose", "sequelize", "prisma", "typeorm", "drizzle", "sqlalchemy")) {
     server.tool(
       "get_model_context",
-      "Get full model context: relationships, schema, and metadata (Eloquent/Mongoose/Sequelize/SQLAlchemy/Prisma/TypeORM/Drizzle)",
+      "Get full model context: relationships, schema, and metadata (Eloquent/Mongoose/Sequelize/SQLAlchemy/Prisma/TypeORM/Drizzle). Use to understand a specific ORM model. For raw table schema without ORM context use get_schema instead. Read-only. Returns JSON: { model, table, relationships: [{ type, related, foreignKey }], fields, metadata }.",
       {
         model_name: z5.string().max(256).describe("Model class name (e.g. User, Post)")
       },
@@ -100681,7 +100776,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_schema",
-      "Get database schema reconstructed from migrations or ORM model definitions",
+      "Get database schema reconstructed from migrations or ORM model definitions. Use to understand table structure. For ORM-level context with relationships use get_model_context instead. Read-only. Returns JSON: { tables: [{ name, columns: [{ name, type, nullable, default }], indexes }] }.",
       {
         table_name: z5.string().max(256).optional().describe("Table/collection/model name (omit for all)")
       },
@@ -100697,7 +100792,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel", "nestjs", "celery", "django", "socketio")) {
     server.tool(
       "get_event_graph",
-      "Get event/signal/task dispatch graph (Laravel events, Django signals, NestJS events, Celery tasks, Socket.io events)",
+      "Get event/signal/task dispatch graph (Laravel events, Django signals, NestJS events, Celery tasks, Socket.io events). Use to understand event-driven architecture and trace event producers/consumers. Read-only. Returns JSON: { events: [{ name, dispatchers, listeners, file }] }.",
       {
         event_name: z5.string().max(256).optional().describe("Filter to a specific event class name")
       },
@@ -100712,7 +100807,7 @@ function registerFrameworkTools(server, ctx) {
   }
   server.tool(
     "find_usages",
-    "Find all places that reference a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages \u2014 understands semantic relationships, not just text matches.",
+    "Find all places that reference a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages \u2014 understands semantic relationships, not just text matches. For bidirectional call graph use get_call_graph instead. Read-only. Returns JSON: { references: [{ file, line, kind, context }], total }.",
     {
       symbol_id: z5.string().max(512).optional().describe("Symbol ID to find references for"),
       fqn: z5.string().max(512).optional().describe("Fully qualified name to find references for"),
@@ -100746,7 +100841,7 @@ function registerFrameworkTools(server, ctx) {
   );
   server.tool(
     "get_call_graph",
-    "Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Use to understand control flow through a function.",
+    "Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Use to understand control flow through a function. For flat list of all references use find_usages instead. Read-only. Returns JSON: { root: { symbol_id, name, calls: [...], called_by: [...] } }.",
     {
       symbol_id: z5.string().max(512).optional().describe("Symbol ID to center the graph on"),
       fqn: z5.string().max(512).optional().describe("Fully qualified name to center the graph on"),
@@ -100779,7 +100874,7 @@ function registerFrameworkTools(server, ctx) {
   );
   server.tool(
     "get_tests_for",
-    "Find test files and test functions that cover a given symbol or file. Use instead of Glob/Grep \u2014 understands test-to-source mapping, not just filename conventions.",
+    "Find test files and test functions that cover a given symbol or file. Use instead of Glob/Grep \u2014 understands test-to-source mapping, not just filename conventions. For project-wide test coverage gaps use get_untested_symbols instead. Read-only. Returns JSON: { tests: [{ file, testName, symbol_id }], total }.",
     {
       symbol_id: z5.string().max(512).optional().describe("Symbol ID to find tests for"),
       fqn: z5.string().max(512).optional().describe("Fully qualified name to find tests for"),
@@ -100814,7 +100909,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("laravel")) {
     server.tool(
       "get_livewire_context",
-      "Get full context for a Livewire component: properties, actions, events, view, child components",
+      "Get full context for a Livewire component: properties, actions, events, view, child components. Use to understand a specific Livewire component before modifying it. Read-only. Returns JSON: { component, properties, actions, events, view, children }.",
       {
         component_name: z5.string().max(256).describe("Livewire component class name or FQN (e.g. UserProfile or App\\Livewire\\UserProfile)")
       },
@@ -100828,7 +100923,7 @@ function registerFrameworkTools(server, ctx) {
     );
     server.tool(
       "get_nova_resource",
-      "Get full context for a Laravel Nova resource: model, fields, actions, filters, lenses, metrics",
+      "Get full context for a Laravel Nova resource: model, fields, actions, filters, lenses, metrics. Use to understand a Nova admin resource before modifying it. Read-only. Returns JSON: { resource, model, fields, actions, filters, lenses, metrics }.",
       {
         resource_name: z5.string().max(256).describe("Nova resource class name or FQN (e.g. User or App\\Nova\\User)")
       },
@@ -100844,7 +100939,7 @@ function registerFrameworkTools(server, ctx) {
   if (has("zustand-redux")) {
     server.tool(
       "get_state_stores",
-      "List all Zustand stores and Redux Toolkit slices with their state fields, actions/reducers, and dispatch sites",
+      "List all Zustand stores and Redux Toolkit slices with their state fields, actions/reducers, and dispatch sites. Use to understand state management architecture. Read-only. Returns JSON: { stores: [{ type, name, handler, metadata }], dispatches, totalStores, totalDispatches }.",
       {},
       async () => {
         const routes = store.getAllRoutes();
@@ -101697,7 +101792,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_implementations",
-    "Find all classes that implement or extend a given interface or base class",
+    "Find all classes that implement or extend a given interface or base class. Use when you know the interface name. For full hierarchy tree (ancestors + descendants) use get_type_hierarchy instead. Read-only. Returns JSON: { implementations: [{ symbol_id, name, kind, file, line }], total }.",
     {
       name: z6.string().max(256).describe("Interface or base class name (e.g. UserRepositoryInterface)")
     },
@@ -101723,7 +101818,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_api_surface",
-    "List all exported symbols (public API) of a file or matching files",
+    "List all exported symbols (public API) of a file or matching files. Use to understand what a module exposes. For finding unused exports use get_dead_exports instead. Read-only. Returns JSON: { files: [{ path, exports: [{ name, kind, signature }] }] }.",
     {
       file_pattern: z6.string().max(512).optional().describe("Glob-style pattern to filter files (e.g. src/services/*.ts)")
     },
@@ -101734,7 +101829,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_plugin_registry",
-    "List all registered indexer plugins and the edge types they emit",
+    "List all registered indexer plugins and the edge types they emit. Use for debugging indexer behavior or understanding which frameworks are supported. Read-only. Returns JSON: { languagePlugins, frameworkPlugins, edgeTypes }.",
     {},
     async () => {
       const result = getPluginRegistry(store, registry, frameworkNames);
@@ -101743,7 +101838,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_type_hierarchy",
-    "Walk TypeScript class/interface hierarchy: ancestors (what it extends/implements) and descendants (what extends/implements it)",
+    "Walk TypeScript class/interface hierarchy: ancestors (what it extends/implements) and descendants (what extends/implements it). Use to understand inheritance trees. For a flat list of implementations only use get_implementations instead. Read-only. Returns JSON: { name, ancestors: [...], descendants: [...] }.",
     {
       name: z6.string().max(256).describe('Class or interface name (e.g. "LanguagePlugin", "Store")'),
       max_depth: z6.number().int().min(1).max(20).optional().describe("Max traversal depth (default 10)")
@@ -101770,7 +101865,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_dead_exports",
-    "Find exported symbols never imported by any other file \u2014 dead code candidates",
+    "Find exported symbols never imported by any other file \u2014 dead code candidates. Use for quick export-level dead code scan. For deeper multi-signal dead code detection (including call graph) use get_dead_code instead. Read-only. Returns JSON: { deadExports: [{ symbol_id, name, kind, file }], total }.",
     {
       file_pattern: z6.string().max(512).optional().describe('Filter files by glob pattern (e.g. "src/tools/*.ts")')
     },
@@ -101781,7 +101876,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_import_graph",
-    "Show file-level dependency graph: what a file imports and what imports it (requires reindex for ESM edge resolution)",
+    "Show file-level dependency graph: what a file imports and what imports it (requires reindex for ESM edge resolution). Use to understand module dependencies for a specific file. For project-wide coupling analysis use get_coupling; for visual diagram use get_dependency_diagram. Read-only. Returns JSON: { file, imports: [{ path }], importedBy: [{ path }] }.",
     {
       file_path: z6.string().max(512).describe('Relative file path to analyze (e.g. "src/server.ts")')
     },
@@ -101794,7 +101889,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_untested_exports",
-    "Find exported public symbols with no matching test file \u2014 test coverage gaps",
+    "Find exported public symbols with no matching test file \u2014 test coverage gaps. For deeper analysis including non-exported symbols use get_untested_symbols instead. Read-only. Returns JSON: { untested: [{ symbol_id, name, kind, file }], total }.",
     {
       file_pattern: z6.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")')
     },
@@ -101805,7 +101900,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_untested_symbols",
-    'Find ALL symbols (not just exports) lacking test coverage. Classifies as "unreached" (no test file imports the source) or "imported_not_called" (test imports file but never references this symbol). Use for thorough coverage gap analysis.',
+    'Find ALL symbols (not just exports) lacking test coverage. Classifies as "unreached" (no test file imports the source) or "imported_not_called" (test imports file but never references this symbol). Use for thorough coverage gap analysis. For exports-only quick scan use get_untested_exports instead. Read-only. Returns JSON: { untested: [{ symbol_id, name, kind, file, classification }], total }.',
     {
       file_pattern: z6.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")'),
       max_results: z6.number().int().min(1).max(500).optional().describe("Cap on returned items (default: all)")
@@ -101815,12 +101910,12 @@ function registerAnalysisTools(server, ctx) {
       return { content: [{ type: "text", text: jh("get_untested_symbols", result) }] };
     }
   );
-  server.tool("self_audit", "Dead code & coverage audit: dead exports, untested public symbols, heritage debt. Use for cleanup and coverage tasks.", {}, async () => {
+  server.tool("self_audit", "Dead code & coverage audit: dead exports, untested public symbols, heritage debt. Use as a one-shot health check combining dead exports + untested symbols + heritage debt. For individual checks use get_dead_exports, get_untested_symbols, or get_dead_code separately. Read-only. Returns JSON: { deadExports, untestedSymbols, heritageDebt, summary }.", {}, async () => {
     return { content: [{ type: "text", text: j3(selfAudit(store)) }] };
   });
   server.tool(
     "get_coupling",
-    "Coupling analysis: afferent (Ca), efferent (Ce), instability index per file. Shows which modules are stable vs unstable",
+    "Coupling analysis: afferent (Ca), efferent (Ce), instability index per file. Shows which modules are stable vs unstable. Use to identify fragile or overly-depended-on modules. For coupling changes over time use get_coupling_trend instead. Read-only. Returns JSON: [{ file, ca, ce, instability, assessment }].",
     {
       limit: z6.number().int().min(1).max(500).optional().describe("Max results (default: all)"),
       assessment: z6.enum(["stable", "neutral", "unstable", "isolated"]).optional().describe("Filter by stability assessment")
@@ -101834,7 +101929,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_circular_imports",
-    "Find circular dependency chains in the import graph (Kosaraju SCC algorithm)",
+    "Find circular dependency chains in the import graph (Kosaraju SCC algorithm). Use to detect and break dependency cycles. Read-only. Returns JSON: { total_cycles, cycles: [[file1, file2, ...]] }.",
     {},
     async () => {
       const cycles = getDependencyCycles(store);
@@ -101853,7 +101948,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_pagerank",
-    "File importance ranking via PageRank on the import graph. Shows most central/important files",
+    "File importance ranking via PageRank on the import graph. Shows most central/important files. Use to identify architecturally critical files. For combined health metrics use get_project_health instead. Read-only. Returns JSON: [{ file, score }].",
     {
       limit: z6.number().int().min(1).max(200).optional().describe("Max results (default: 50)")
     },
@@ -101864,7 +101959,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_refactor_candidates",
-    "Find functions with high complexity called from many files \u2014 candidates for extraction to shared modules",
+    "Find functions with high complexity called from many files \u2014 candidates for extraction to shared modules. Use during architecture review to identify hotspots worth refactoring. Read-only. Returns JSON: [{ symbol_id, name, file, cyclomatic, callerCount }].",
     {
       min_cyclomatic: z6.number().int().min(1).optional().describe("Min cyclomatic complexity (default: 5)"),
       min_callers: z6.number().int().min(1).optional().describe("Min distinct caller files (default: 2)"),
@@ -101881,7 +101976,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_project_health",
-    "Structural health: coupling instability, dependency cycles, PageRank rankings, refactor candidates. Use for architecture review.",
+    "Structural health: coupling instability, dependency cycles, PageRank rankings, refactor candidates. Use for architecture review as a single aggregated report. For individual metrics use get_coupling, get_circular_imports, or get_pagerank separately. Read-only. Returns JSON: { coupling, cycles, pagerank, refactorCandidates, hotspots }.",
     {},
     async () => {
       const result = getRepoHealth(store);
@@ -101891,7 +101986,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "check_architecture",
-    "Check architectural layer rules: detect forbidden imports between layers (e.g. domain importing infrastructure). Supports auto-detected presets (clean-architecture, hexagonal) or custom layers.",
+    "Check architectural layer rules: detect forbidden imports between layers (e.g. domain importing infrastructure). Supports auto-detected presets (clean-architecture, hexagonal) or custom layers. Use to enforce architectural boundaries. Read-only. Returns JSON: { violations: [{ from, to, rule, file, line }], total, preset }.",
     {
       preset: z6.enum(["clean-architecture", "hexagonal"]).optional().describe("Use a built-in layer preset (auto-detected if omitted)"),
       layers: z6.array(z6.object({
@@ -101920,7 +102015,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_code_owners",
-    "Git-based code ownership: who contributed most to specific files (git shortlog). Requires git.",
+    "Git-based code ownership: who contributed most to specific files (git shortlog). Requires git. Use to identify who to ask about specific files. For symbol-level ownership use get_symbol_owners instead. Read-only. Returns JSON: [{ file, owners: [{ author, commits, percentage }] }].",
     {
       file_paths: z6.array(z6.string().max(512)).min(1).max(20).describe("File paths to check ownership for")
     },
@@ -101938,7 +102033,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_symbol_owners",
-    "Git blame-based symbol ownership: who wrote which lines of a specific symbol. Requires git.",
+    "Git blame-based symbol ownership: who wrote which lines of a specific symbol. Requires git. Use for fine-grained ownership of a specific function/class. For file-level ownership use get_code_owners instead. Read-only. Returns JSON: { symbol_id, owners: [{ author, lines, percentage }] }.",
     {
       symbol_id: z6.string().max(512).describe("Symbol ID to check ownership for")
     },
@@ -101952,7 +102047,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_complexity_trend",
-    "File complexity over git history: cyclomatic complexity at past commits. Shows if a file is getting more or less complex.",
+    "File complexity over git history: cyclomatic complexity at past commits. Shows if a file is getting more or less complex. Requires git. Use to track whether a file is improving or degrading. For current snapshot use get_complexity_report; for symbol-level trends use get_symbol_complexity_trend. Read-only. Returns JSON: { file, snapshots: [{ commit, date, complexity }] }.",
     {
       file_path: z6.string().max(512).describe("File path to analyze"),
       snapshots: z6.number().int().min(2).max(20).optional().describe("Number of historical snapshots (default: 5)")
@@ -101969,7 +102064,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_coupling_trend",
-    "File coupling over git history: Ca/Ce/instability at past commits. Shows if a module is stabilizing or destabilizing.",
+    "File coupling over git history: Ca/Ce/instability at past commits. Shows if a module is stabilizing or destabilizing. Requires git. Use to track module stability over time. For current coupling snapshot use get_coupling instead. Read-only. Returns JSON: { file, snapshots: [{ commit, date, ca, ce, instability }] }.",
     {
       file_path: z6.string().max(512).describe("File path to analyze"),
       since_days: z6.number().int().min(1).optional().describe("Analyze last N days (default: 90)"),
@@ -101990,7 +102085,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "get_symbol_complexity_trend",
-    "Single symbol complexity over git history: cyclomatic, nesting, params, lines at past commits.",
+    "Single symbol complexity over git history: cyclomatic, nesting, params, lines at past commits. Requires git. Use to track a specific function's complexity evolution. For file-level trends use get_complexity_trend instead. Read-only. Returns JSON: { symbol_id, snapshots: [{ commit, date, cyclomatic, nesting, params, lines }] }.",
     {
       symbol_id: z6.string().min(1).max(512).describe("Symbol ID to analyze (from search or outline)"),
       since_days: z6.number().int().min(1).optional().describe("Analyze last N days (default: all history)"),
@@ -102009,7 +102104,7 @@ function registerAnalysisTools(server, ctx) {
   );
   server.tool(
     "check_duplication",
-    "Check if a function/class name already exists elsewhere in the codebase before creating it. Prevents duplicating existing logic. Call with just a name when planning new code, or symbol_id to check an existing symbol. Returns scored matches \u2014 score \u22650.7 means high likelihood of duplication, review the existing symbol before proceeding.",
+    "Check if a function/class name already exists elsewhere in the codebase before creating it. Prevents duplicating existing logic. Call with just a name when planning new code, or symbol_id to check an existing symbol. Returns scored matches \u2014 score \u22650.7 means high likelihood of duplication, review the existing symbol before proceeding. Read-only. Returns JSON: { duplicates: [{ symbol_id, name, file, score }], hasDuplication }.",
     {
       symbol_id: z6.string().max(512).optional().describe("Existing symbol ID to check for duplicates"),
       name: z6.string().max(256).optional().describe("Function/class name to check (when symbol_id not available)"),
@@ -105178,7 +105273,7 @@ function registerGitTools(server, ctx) {
   const detectedFrameworks = registry.getAllFrameworkPlugins().map((p5) => p5.manifest.name);
   server.tool(
     "get_git_churn",
-    "Per-file git churn: commits, unique authors, frequency, volatility assessment. Requires git.",
+    "Per-file git churn: commits, unique authors, frequency, volatility assessment. Requires git. Use to identify frequently-changed files. For combined churn+complexity hotspots use get_risk_hotspots instead. Read-only. Returns JSON: { results: [{ file, commits, authors, frequency, volatility }], total }.",
     {
       since_days: z7.number().int().min(1).optional().describe("Analyze commits from last N days (default: all history)"),
       limit: z7.number().int().min(1).max(500).optional().describe("Max results (default: 50)"),
@@ -105198,7 +105293,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_risk_hotspots",
-    "Code hotspots: files with both high complexity AND high git churn (Adam Tornhill methodology). Score = complexity \xD7 log(1 + commits). Each entry includes a confidence_level (low/medium/multi_signal) counting how many of the two independent signals fired strongly. Result envelope includes _methodology disclosure and _warnings when git is unavailable.",
+    "Code hotspots: files with both high complexity AND high git churn (Adam Tornhill methodology). Score = complexity \xD7 log(1 + commits). Each entry includes a confidence_level (low/medium/multi_signal) counting how many of the two independent signals fired strongly. Result envelope includes _methodology disclosure and _warnings when git is unavailable. Requires git. Use to prioritize refactoring. For per-file bug prediction use predict_bugs instead. Read-only. Returns JSON: { hotspots: [{ file, score, complexity, commits, confidence_level }], total }.",
     {
       since_days: z7.number().int().min(1).optional().describe("Git churn window in days (default: 90)"),
       limit: z7.number().int().min(1).max(100).optional().describe("Max results (default: 20)"),
@@ -105229,7 +105324,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_dead_code",
-    'Dead code detection. Two modes: (1) "multi-signal" (default) combines import graph, call graph, and barrel export analysis with confidence scores. (2) "reachability" runs forward BFS from auto-detected entry points (tests, package.json main/bin, src/{cli,main,index}, routes, framework-tagged controllers) \u2014 stricter but more accurate when entry points are enumerable. Pass entry_points to add custom roots. Both modes emit _methodology and _warnings.',
+    'Dead code detection. Two modes: (1) "multi-signal" (default) combines import graph, call graph, and barrel export analysis with confidence scores. (2) "reachability" runs forward BFS from auto-detected entry points (tests, package.json main/bin, src/{cli,main,index}, routes, framework-tagged controllers) \u2014 stricter but more accurate when entry points are enumerable. Pass entry_points to add custom roots. Both modes emit _methodology and _warnings. Use for comprehensive dead code analysis. For quick export-only scan use get_dead_exports; to safely remove detected dead code use remove_dead_code. Read-only. Returns JSON: { dead_symbols: [{ symbol_id, name, file, confidence, signals }], total }.',
     {
       file_pattern: z7.string().max(512).optional().describe('Filter by file glob pattern (e.g. "src/tools/%")'),
       threshold: z7.number().min(0).max(1).optional().describe("[multi-signal mode] Min confidence to report (default: 0.5 = at least 2 of 3 signals)"),
@@ -105259,7 +105354,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "scan_security",
-    "Scan project files for OWASP Top-10 security vulnerabilities using pattern matching. Detects SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), hardcoded secrets (CWE-798), insecure crypto (CWE-327), open redirects (CWE-601), and SSRF (CWE-918). Skips test files.",
+    "Scan project files for OWASP Top-10 security vulnerabilities using pattern matching. Detects SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), hardcoded secrets (CWE-798), insecure crypto (CWE-327), open redirects (CWE-601), and SSRF (CWE-918). Skips test files. Use for pattern-based security audit. For data-flow-aware analysis use taint_analysis instead. Read-only. Returns JSON: { findings: [{ rule, severity, cwe, file, line, message }], total, summary }.",
     {
       scope: z7.string().max(512).optional().describe("Directory to scan (default: whole project)"),
       rules: z7.array(z7.enum([
@@ -105293,7 +105388,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "detect_antipatterns",
-    "Detect performance antipatterns: N+1 query risks, missing eager loading, unbounded queries, event listener leaks, circular model dependencies, missing indexes, memory leaks (unbounded caches, closure leaks). Static analysis across all indexed ORMs (Eloquent, Sequelize, Mongoose, Django, Prisma, TypeORM, Drizzle).",
+    "Detect performance antipatterns: N+1 query risks, missing eager loading, unbounded queries, event listener leaks, circular model dependencies, missing indexes, memory leaks (unbounded caches, closure leaks). Static analysis across all indexed ORMs (Eloquent, Sequelize, Mongoose, Django, Prisma, TypeORM, Drizzle). Use to find performance issues. For code quality issues (TODOs, empty functions) use scan_code_smells instead. Read-only. Returns JSON: { findings: [{ category, severity, file, line, message, suggestion }], total }.",
     {
       category: z7.array(z7.enum([
         "n_plus_one_risk",
@@ -105323,7 +105418,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "scan_code_smells",
-    "Find deferred work and shortcuts: TODO/FIXME/HACK/XXX comments, empty functions & stubs, hardcoded values (IPs, URLs, credentials, magic numbers, feature flags). Surfaces technical debt that grep alone misses by combining comment scanning, symbol body analysis, and context-aware false-positive filtering.",
+    "Find deferred work and shortcuts: TODO/FIXME/HACK/XXX comments, empty functions & stubs, hardcoded values (IPs, URLs, credentials, magic numbers, feature flags). Surfaces technical debt that grep alone misses by combining comment scanning, symbol body analysis, and context-aware false-positive filtering. Use for code quality audit. For performance-specific antipatterns use detect_antipatterns; for security issues use scan_security. Read-only. Returns JSON: { findings: [{ category, priority, file, line, message }], total, summary }.",
     {
       category: z7.array(z7.enum([
         "todo_comment",
@@ -105357,7 +105452,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "taint_analysis",
-    "Track flow of untrusted data from sources (HTTP params, env vars, file reads) to dangerous sinks (SQL queries, exec, innerHTML, redirects). Framework-aware: knows Express req.params, Laravel $request->input, Django request.GET, FastAPI Query(), etc. Reports unsanitized flows with CWE IDs and fix suggestions. More accurate than pattern-based scanning \u2014 traces actual data flow paths.",
+    "Track flow of untrusted data from sources (HTTP params, env vars, file reads) to dangerous sinks (SQL queries, exec, innerHTML, redirects). Framework-aware: knows Express req.params, Laravel $request->input, Django request.GET, FastAPI Query(), etc. Reports unsanitized flows with CWE IDs and fix suggestions. More accurate than pattern-based scanning \u2014 traces actual data flow paths. Use for data-flow security analysis. For pattern-based OWASP scanning use scan_security instead. Read-only. Returns JSON: { flows: [{ source, sink, path, sanitized, cwe, suggestion }], total }.",
     {
       scope: z7.string().max(512).optional().describe("Directory to scan (default: whole project)"),
       sources: z7.array(z7.enum([
@@ -105403,7 +105498,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "generate_sbom",
-    "Generate a Software Bill of Materials (SBOM) from package manifests and lockfiles. Supports npm, Composer, pip, Go, Cargo, Bundler, Maven. Outputs CycloneDX, SPDX, or plain JSON. Includes license compliance warnings for copyleft licenses.",
+    "Generate a Software Bill of Materials (SBOM) from package manifests and lockfiles. Supports npm, Composer, pip, Go, Cargo, Bundler, Maven. Outputs CycloneDX, SPDX, or plain JSON. Includes license compliance warnings for copyleft licenses. Use for supply chain audits or compliance reports. Returns JSON/CycloneDX/SPDX: { components: [{ name, version, license, type }], warnings }.",
     {
       format: z7.enum(["cyclonedx", "spdx", "json"]).optional().describe("Output format (default: json)"),
       include_dev: z7.boolean().optional().describe("Include devDependencies (default: false)"),
@@ -105423,7 +105518,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_artifacts",
-    "Surface non-code knowledge from the index: DB schemas (migrations, ORM models), API specs (routes, OpenAPI endpoints), infrastructure (docker-compose services, K8s resources), CI pipelines (jobs, stages), and config (env vars). All data from the existing index \u2014 no extra I/O.",
+    "Surface non-code knowledge from the index: DB schemas (migrations, ORM models), API specs (routes, OpenAPI endpoints), infrastructure (docker-compose services, K8s resources), CI pipelines (jobs, stages), and config (env vars). All data from the existing index \u2014 no extra I/O. Use to discover infrastructure and config artifacts without reading files. Read-only. Returns JSON: { artifacts: [{ category, kind, name, file }], total }.",
     {
       category: z7.enum(["database", "api", "infra", "ci", "config", "all"]).optional().describe("Filter by artifact category (default: all)"),
       query: z7.string().max(256).optional().describe("Text filter on name/kind/file"),
@@ -105440,7 +105535,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "plan_batch_change",
-    "Analyze the impact of updating a package/dependency. Shows all affected files, import references, and generates a PR template with checklist. Use before upgrading a dependency to understand blast radius.",
+    "Analyze the impact of updating a package/dependency. Shows all affected files, import references, and generates a PR template with checklist. Use before upgrading a dependency to understand blast radius. Read-only (analysis only, does not modify files). Returns JSON: { package, affectedFiles, importReferences, prTemplate, checklist }.",
     {
       package: z7.string().min(1).max(256).describe('Package name (e.g. "express", "laravel/framework", "react")'),
       from_version: z7.string().max(64).optional().describe("Current version"),
@@ -105462,7 +105557,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "get_complexity_report",
-    "Get complexity metrics (cyclomatic, max nesting, param count) for symbols in a file or across the project. Useful for identifying complex code before refactoring.",
+    "Get complexity metrics (cyclomatic, max nesting, param count) for symbols in a file or across the project. Use to identify complex code before refactoring. For historical trends use get_complexity_trend instead. Read-only. Returns JSON: { symbols: [{ symbol_id, name, kind, file, line, cyclomatic, max_nesting, param_count }], total }.",
     {
       file_path: z7.string().max(512).optional().describe("File path to report on (omit for project-wide top complex symbols)"),
       min_cyclomatic: z7.number().int().min(1).optional().describe("Min cyclomatic complexity to include (default: 1 for file, 5 for project)"),
@@ -105497,7 +105592,7 @@ function registerGitTools(server, ctx) {
   );
   server.tool(
     "check_rename",
-    "Pre-rename collision detection: checks the symbol's own file and all importing files for existing symbols with the target name",
+    "Pre-rename collision detection: checks the symbol's own file and all importing files for existing symbols with the target name. Use before apply_rename to verify safety. Read-only (does not modify files). Returns JSON: { safe, conflicts: [{ symbol_id, name, file }] }.",
     {
       symbol_id: z7.string().max(512).describe("Symbol ID to rename"),
       target_name: z7.string().min(1).max(256).describe("Proposed new name")
@@ -107363,7 +107458,7 @@ function registerRefactoringTools(server, ctx) {
   const { store, projectRoot, guardPath, j: j3 } = ctx;
   server.tool(
     "apply_rename",
-    "Rename a symbol across all usages (definition + all importing files). Runs collision detection first and aborts on conflicts. Returns the list of edits applied.",
+    'Rename a symbol across all usages (definition + all importing files). Runs collision detection first and aborts on conflicts. Returns the list of edits applied. Modifies source files. Use check_rename first to verify safety; use plan_refactoring with type="rename" to preview edits. Returns JSON: { success, edits: [{ file, old_text, new_text }], filesModified }.',
     {
       symbol_id: z8.string().max(512).describe("Symbol ID to rename (from search or outline)"),
       new_name: z8.string().min(1).max(256).describe("New name for the symbol"),
@@ -107379,7 +107474,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "remove_dead_code",
-    "Safely remove a dead symbol from its file. Verifies the symbol is actually dead (multi-signal detection or zero incoming edges) before removal. Warns about orphaned imports in other files.",
+    "Safely remove a dead symbol from its file. Verifies the symbol is actually dead (multi-signal detection or zero incoming edges) before removal. Warns about orphaned imports in other files. Destructive \u2014 deletes code from source files. Use get_dead_code first to identify candidates. Returns JSON: { success, removed: { symbol_id, file }, orphanedImports }.",
     {
       symbol_id: z8.string().max(512).describe("Symbol ID to remove (from get_dead_code results)"),
       dry_run: z8.boolean().default(false).describe("Preview changes without applying (default: false)")
@@ -107394,7 +107489,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "extract_function",
-    "Extract a range of lines into a new named function. Detects parameters (variables from outer scope) and return values (variables used after the range). Supports TypeScript/JavaScript, Python, and Go.",
+    'Extract a range of lines into a new named function. Detects parameters (variables from outer scope) and return values (variables used after the range). Supports TypeScript/JavaScript, Python, and Go. Modifies source files. Use plan_refactoring with type="extract" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], extractedFunction }.',
     {
       file_path: z8.string().max(512).describe("File path (relative to project root)"),
       start_line: z8.number().int().min(1).describe("First line to extract (1-indexed, inclusive)"),
@@ -107414,7 +107509,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "apply_codemod",
-    "Bulk regex find-and-replace across files. Dry-run by default \u2014 first call shows preview, second call with dry_run=false applies. Use for mechanical changes like adding async/await, renaming patterns, updating imports across many files.",
+    "Bulk regex find-and-replace across files. Dry-run by default \u2014 first call shows preview, second call with dry_run=false applies. Use for mechanical changes like adding async/await, renaming patterns, updating imports across many files. Potentially destructive \u2014 can modify or delete code. Always preview with dry_run=true first. Returns JSON: { success, matchedFiles, changes: [{ file, matches }], applied }.",
     {
       pattern: z8.string().min(1).max(1e3).describe("Regex pattern to match (JavaScript regex syntax)"),
       replacement: z8.string().max(1e3).describe("Replacement string ($1, $2 for capture groups)"),
@@ -107439,7 +107534,7 @@ function registerRefactoringTools(server, ctx) {
   );
   server.tool(
     "apply_move",
-    "Move a symbol to a different file or rename/move a file, updating all import paths across the codebase. Dry-run by default (safe preview).",
+    'Move a symbol to a different file or rename/move a file, updating all import paths across the codebase. Dry-run by default (safe preview). Modifies source files. Use plan_refactoring with type="move" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], filesModified }.',
     {
       symbol_id: z8.string().max(512).optional().describe("Symbol ID to move (mode: symbol)"),
       target_file: z8.string().max(512).optional().describe("Target file path for the symbol (mode: symbol)"),
@@ -107503,7 +107598,7 @@ function registerRefactoringTools(server, ctx) {
   });
   server.tool(
     "change_signature",
-    "Change a function/method signature (add/remove/rename/reorder parameters) and update all call sites. Dry-run by default (safe preview).",
+    'Change a function/method signature (add/remove/rename/reorder parameters) and update all call sites. Dry-run by default (safe preview). Modifies source files. Use plan_refactoring with type="signature" to preview first. Returns JSON: { success, edits: [{ file, old_text, new_text }], callSitesUpdated }.',
     {
       symbol_id: z8.string().max(512).describe("Symbol ID of the function/method to modify"),
       changes: z8.array(signatureChangeSchema).min(1).max(20).describe("Array of changes to apply"),
@@ -107533,7 +107628,7 @@ function registerRefactoringTools(server, ctx) {
   });
   server.tool(
     "plan_refactoring",
-    "Preview any refactoring (rename, move, extract, signature) without applying. Returns all edits as {old_text, new_text} pairs. Use to review changes before applying the real tool.",
+    "Preview any refactoring (rename, move, extract, signature) without applying. Returns all edits as {old_text, new_text} pairs. Read-only (does not modify files). Use to review the blast radius before calling apply_rename, apply_move, change_signature, or extract_function. Returns JSON: { success, type, edits: [{ file, old_text, new_text }], filesAffected }.",
     {
       type: z8.enum(["rename", "move", "extract", "signature"]).describe("Type of refactoring to preview"),
       symbol_id: z8.string().max(512).optional().describe("Symbol ID (for rename, move symbol, signature)"),
@@ -108060,9 +108155,9 @@ var OtlpReceiver = class {
     if (this.options.port === 0) return;
     return new Promise((resolve4, reject) => {
       this.server = createServer((req, res) => this.handleRequest(req, res));
-      this.server.on("error", (err48) => {
-        logger.error({ error: err48 }, "OTLP receiver error");
-        reject(err48);
+      this.server.on("error", (err49) => {
+        logger.error({ error: err49 }, "OTLP receiver error");
+        reject(err49);
       });
       this.server.listen(this.options.port, this.options.host, () => {
         logger.info(
@@ -109682,16 +109777,16 @@ function findShortestPath(store, startNodeId, endNodeId, maxDepth) {
         parent.set(nodeId, { from, edgeType: edge.edge_type_name });
         nextFrontier.push(nodeId);
         if (nodeId === endNodeId) {
-          const path132 = [endNodeId];
+          const path134 = [endNodeId];
           const edgeTypes = [];
           let cur = endNodeId;
           while (cur !== startNodeId) {
             const p5 = parent.get(cur);
-            path132.unshift(p5.from);
+            path134.unshift(p5.from);
             edgeTypes.unshift(p5.edgeType);
             cur = p5.from;
           }
-          return { path: path132, edgeTypes };
+          return { path: path134, edgeTypes };
         }
       }
     }
@@ -110802,6 +110897,7 @@ const preTicks = Math.min(300, Math.max(50, Math.ceil(Math.log(N + 1) * 40)));
 let ticksDone = 0;
 const TICK_BATCH = N > 5000 ? 5 : 15;
 let layoutDone = false;
+let frameRequested = false;
 (function tickBatch() {
   const t0 = performance.now();
   while (ticksDone < preTicks && performance.now() - t0 < 12) { sim.tick(); ticksDone++; }
@@ -110943,7 +111039,6 @@ let highlightSet = null;
 let hoveredNode = null;
 let searchQ = '';
 let animating = false;
-let frameRequested = false;
 
 function scheduleFrame() {
   if (!frameRequested) { frameRequested = true; requestAnimationFrame(frame); }
@@ -112632,7 +112727,7 @@ function registerAdvancedTools(server, ctx) {
     const additionalRepos = config.topology.repos ?? [];
     server.tool(
       "get_service_map",
-      "Get map of all services, their APIs, and inter-service dependencies. Auto-detects services from Docker Compose or treats each repo as a service.",
+      "Get map of all services, their APIs, and inter-service dependencies. Auto-detects services from Docker Compose or treats each repo as a service. Use to understand microservice topology. For subproject-level graph use get_subproject_graph instead. Read-only. Returns JSON: { services: [{ name, endpoints, dependencies }], total }.",
       {
         include_endpoints: z9.boolean().optional().describe("Include full endpoint list per service (default false)")
       },
@@ -112644,7 +112739,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_cross_service_impact",
-      "Analyze cross-service impact of changing an endpoint or event. Shows which services would be affected.",
+      "Analyze cross-service impact of changing an endpoint or event. Shows which services would be affected. Use before modifying a shared endpoint. For within-codebase impact use get_change_impact instead. Read-only. Returns JSON: { service, affectedServices: [{ name, reason }], total }.",
       {
         service: z9.string().min(1).max(256).describe("Service name"),
         endpoint: z9.string().max(512).optional().describe("Endpoint path (e.g. /api/users/{id})"),
@@ -112658,7 +112753,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_api_contract",
-      "Get API contract (OpenAPI/gRPC/GraphQL) for a service. Parses spec files found in the service repo.",
+      "Get API contract (OpenAPI/gRPC/GraphQL) for a service. Parses spec files found in the service repo. Use to inspect a service's public API. For detecting spec-vs-code mismatches use get_contract_drift instead. Read-only. Returns JSON: { service, contract_type, endpoints, schemas }.",
       {
         service: z9.string().min(1).max(256).describe("Service name"),
         contract_type: z9.enum(["openapi", "grpc", "graphql"]).optional().describe("Filter by contract type")
@@ -112671,7 +112766,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_service_deps",
-      "Get external service dependencies: which services this one calls (outgoing) and which call it (incoming).",
+      "Get external service dependencies: which services this one calls (outgoing) and which call it (incoming). Use to understand a single service's dependency profile. For full topology use get_service_map instead. Read-only. Returns JSON: { service, outgoing, incoming }.",
       {
         service: z9.string().min(1).max(256).describe("Service name"),
         direction: z9.enum(["outgoing", "incoming", "both"]).optional().describe("Dependency direction (default both)")
@@ -112684,7 +112779,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_contract_drift",
-      "Detect mismatches between API spec and implementation: endpoints in spec but not in code, or in code but not in spec.",
+      "Detect mismatches between API spec and implementation: endpoints in spec but not in code, or in code but not in spec. Use to verify API contract accuracy. For reading the contract itself use get_api_contract instead. Read-only. Returns JSON: { service, missingInCode, missingInSpec, total }.",
       {
         service: z9.string().min(1).max(256).describe("Service name")
       },
@@ -112696,7 +112791,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_graph",
-      "Show all subprojects and their cross-repo connections. A subproject is any working repository in your project ecosystem (microservices, frontends, backends, shared libraries, CLI tools, etc.). Displays repos, endpoints, client calls, and inter-repo dependency edges.",
+      "Show all subprojects and their cross-repo connections. A subproject is any working repository in your project ecosystem (microservices, frontends, backends, shared libraries, CLI tools, etc.). Displays repos, endpoints, client calls, and inter-repo dependency edges. Use to understand multi-repo topology. Register repos first with subproject_add_repo. Read-only. Returns JSON: { repos, endpoints, clientCalls, edges }.",
       {},
       async () => {
         const result = getSubprojectGraph(topoStore);
@@ -112706,7 +112801,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_impact",
-      "Cross-repo impact analysis: find all client code across subprojects that would break if an endpoint changes. Resolves down to symbol level when per-repo indexes exist.",
+      "Cross-repo impact analysis: find all client code across subprojects that would break if an endpoint changes. Resolves down to symbol level when per-repo indexes exist. Use before modifying a shared API endpoint. Read-only. Returns JSON: { endpoint, affectedClients: [{ repo, file, line, callType }], total }.",
       {
         endpoint: z9.string().max(512).optional().describe("Endpoint path pattern (e.g. /api/users)"),
         method: z9.string().max(10).optional().describe("HTTP method filter (e.g. GET, POST)"),
@@ -112720,7 +112815,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "subproject_add_repo",
-      "Add a repository as a subproject of the current project. A subproject is any working repository in your ecosystem: microservices, frontends, backends, shared libraries, CLI tools. Discovers services, parses API contracts (OpenAPI/gRPC/GraphQL), scans for HTTP client calls, and links them to known endpoints.",
+      "Add a repository as a subproject of the current project. A subproject is any working repository in your ecosystem: microservices, frontends, backends, shared libraries, CLI tools. Discovers services, parses API contracts (OpenAPI/gRPC/GraphQL), scans for HTTP client calls, and links them to known endpoints. Mutates the topology store; idempotent. Use to build multi-repo intelligence. Returns JSON: { added, services, contracts, clientCalls }.",
       {
         repo_path: z9.string().min(1).max(1024).describe("Absolute or relative path to the repository/service"),
         name: z9.string().max(256).optional().describe("Display name for the repo (default: directory basename)"),
@@ -112736,7 +112831,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "subproject_sync",
-      "Re-scan all subprojects: re-discover services, re-parse contracts, re-scan client calls, and re-link everything.",
+      "Re-scan all subprojects: re-discover services, re-parse contracts, re-scan client calls, and re-link everything. Mutates the topology store; idempotent. Use after code changes in subproject repos. Returns JSON: { synced, services, contracts, clientCalls }.",
       {},
       async () => {
         const result = subprojectSync(topoStore);
@@ -112746,7 +112841,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_subproject_clients",
-      "Find all client calls across subprojects that call a specific endpoint. Shows file, line, call type, and confidence.",
+      "Find all client calls across subprojects that call a specific endpoint. Shows file, line, call type, and confidence. Use to find all consumers of an endpoint before modifying it. Read-only. Returns JSON: { endpoint, clients: [{ repo, file, line, callType, confidence }], total }.",
       {
         endpoint: z9.string().min(1).max(512).describe("Endpoint path to search for (e.g. /api/users)"),
         method: z9.string().max(10).optional().describe("HTTP method filter")
@@ -112759,7 +112854,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_contract_versions",
-      "Show version history for a service API contract with breaking change detection between versions. Compares request/response schemas across snapshots to flag removed fields, type changes, and renames.",
+      "Show version history for a service API contract with breaking change detection between versions. Compares request/response schemas across snapshots to flag removed fields, type changes, and renames. Use to review API evolution. For current spec-vs-code drift use get_contract_drift instead. Read-only. Returns JSON: { service, versions: [{ version, date, breakingChanges }] }.",
       {
         service: z9.string().min(1).max(256).describe("Service name"),
         limit: z9.number().int().min(1).max(50).optional().describe("Max versions to show (default 10)")
@@ -112772,7 +112867,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "discover_claude_sessions",
-      "Scan ~/.claude/projects for projects Claude Code has touched on this machine, decode each directory name back to its absolute path, and report which ones still exist plus session-file count and last activity. With add_as_subprojects=true, every existing project is registered as a subproject in one call \u2014 useful for spinning up multi-repo intelligence after a fresh clone.",
+      "Scan ~/.claude/projects for projects Claude Code has touched on this machine, decode each directory name back to its absolute path, and report which ones still exist plus session-file count and last activity. With add_as_subprojects=true, every existing project is registered as a subproject in one call \u2014 useful for spinning up multi-repo intelligence after a fresh clone. Reads local filesystem; with add_as_subprojects=true also mutates topology store. Returns JSON: { projects: [{ path, sessions, lastActivity }], total }.",
       {
         scan_root: z9.string().max(1024).optional().describe("Override the scan root (default: ~/.claude/projects)"),
         exclude_current: z9.boolean().optional().describe("Exclude the current project from results (default: true)"),
@@ -112794,7 +112889,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "visualize_subproject_topology",
-      "Open interactive HTML visualization of the subproject topology: services as nodes, API calls as edges, health/risk indicators per service. Node size = endpoint count, color = health (green/yellow/red).",
+      "Open interactive HTML visualization of the subproject topology: services as nodes, API calls as edges, health/risk indicators per service. Node size = endpoint count, color = health (green/yellow/red). Writes an HTML file to disk. Use for visual architecture review. Returns JSON: { outputPath, services, edges }.",
       {
         output: z9.string().max(512).optional().describe("Output file path (default: /tmp/trace-mcp-subproject-topology.html)"),
         layout: z9.enum(["force", "hierarchical", "radial"]).optional().describe("Graph layout (default force)")
@@ -112816,7 +112911,7 @@ function registerAdvancedTools(server, ctx) {
     runtimeIntelligence.start().catch((e) => logger.error({ error: e }, "Failed to start Runtime Intelligence"));
     server.tool(
       "get_runtime_profile",
-      "Runtime profile for a symbol or route: call count, latency percentiles (p50/p95/p99), error rate, calls per hour. Requires OTLP trace ingestion.",
+      "Runtime profile for a symbol or route: call count, latency percentiles (p50/p95/p99), error rate, calls per hour. Requires OTLP trace ingestion. Read-only, queries external runtime data. Use for performance analysis of specific endpoints. Returns JSON: { symbol_id, callCount, latency: { p50, p95, p99 }, errorRate, callsPerHour }.",
       {
         symbol_id: z9.string().max(512).optional().describe("Symbol ID to profile"),
         fqn: z9.string().max(512).optional().describe("Fully qualified name"),
@@ -112831,7 +112926,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_runtime_call_graph",
-      "Actual call graph from runtime traces (vs static analysis). Shows observed call paths with call counts and latency.",
+      "Actual call graph from runtime traces (vs static analysis). Shows observed call paths with call counts and latency. Requires OTLP trace ingestion. Read-only, queries external runtime data. For static call graph use get_call_graph instead. Returns JSON: { root, calls: [{ symbol, count, latency }] }.",
       {
         symbol_id: z9.string().max(512).optional().describe("Symbol ID as root"),
         fqn: z9.string().max(512).optional().describe("Fully qualified name as root"),
@@ -112846,7 +112941,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_endpoint_analytics",
-      "Per-route analytics: request count, error rate, latency, caller services. Requires OTLP trace ingestion.",
+      "Per-route analytics: request count, error rate, latency, caller services. Requires OTLP trace ingestion. Read-only, queries external runtime data. Use to understand endpoint performance and traffic. Returns JSON: { uri, method, requestCount, errorRate, latency, callerServices }.",
       {
         uri: z9.string().max(512).describe('Route URI (e.g. "/api/users/{id}")'),
         method: z9.string().max(10).optional().describe("HTTP method filter"),
@@ -112860,7 +112955,7 @@ function registerAdvancedTools(server, ctx) {
     );
     server.tool(
       "get_runtime_deps",
-      "Which external services (databases, caches, APIs, queues) does this code actually call at runtime. Based on OTLP traces.",
+      "Which external services (databases, caches, APIs, queues) does this code actually call at runtime. Based on OTLP traces. Read-only, queries external runtime data. Use to discover actual runtime dependencies vs static analysis. Returns JSON: { dependencies: [{ type, name, callCount }] }.",
       {
         symbol_id: z9.string().max(512).optional().describe("Symbol ID"),
         fqn: z9.string().max(512).optional().describe("Fully qualified name"),
@@ -112879,7 +112974,7 @@ function registerAdvancedTools(server, ctx) {
   }
   server.tool(
     "query_by_intent",
-    "Map a business question to domain taxonomy \u2192 returns domain ownership and relevance scores (no source code). Use when you need to know WHICH DOMAIN owns specific functionality.",
+    "Map a business question to domain taxonomy \u2192 returns domain ownership and relevance scores (no source code). Use when you need to know WHICH DOMAIN owns specific functionality. For actual source code use get_feature_context instead. Read-only. Returns JSON: { symbols: [{ symbol_id, domain, relevance }] }.",
     {
       query: z9.string().min(1).max(500).describe("Business-level question about the codebase"),
       limit: z9.number().int().min(1).max(50).optional().describe("Max symbols to return (default 15)")
@@ -112897,7 +112992,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_domain_map",
-    "Get hierarchical map of business domains with key symbols per domain. Auto-builds domain taxonomy on first call using heuristic classification.",
+    "Get hierarchical map of business domains with key symbols per domain. Auto-builds domain taxonomy on first call using heuristic classification. Use to understand business domain boundaries. For specific domain code use get_domain_context instead. Read-only. Returns JSON: { domains: [{ name, children, symbols }] }.",
     {
       depth: z9.number().int().min(1).max(5).optional().describe("Max taxonomy depth (default 3)"),
       include_symbols: z9.boolean().optional().describe("Include top symbols per domain (default true)"),
@@ -112911,7 +113006,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_domain_context",
-    'Get all code related to a specific business domain. Supports "parent/child" notation (e.g. "payments/refunds").',
+    'Get all code related to a specific business domain. Supports "parent/child" notation (e.g. "payments/refunds"). Use to explore code within a domain boundary. For the full domain taxonomy use get_domain_map instead. Read-only. Returns JSON: { domain, symbols: [{ symbol_id, name, file, source }], relatedDomains }.',
     {
       domain: z9.string().min(1).max(256).describe('Domain name (e.g. "payments" or "payments/refunds")'),
       include_related: z9.boolean().optional().describe("Include symbols from related domains (default false)"),
@@ -112925,7 +113020,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_cross_domain_deps",
-    "Show which business domains depend on which. Based on edges between symbols in different domains.",
+    "Show which business domains depend on which. Based on edges between symbols in different domains. Use to understand domain coupling. Read-only. Returns JSON: { dependencies: [{ from, to, edgeCount }] }.",
     {
       domain: z9.string().max(256).optional().describe("Focus on a specific domain (default: all)")
     },
@@ -112937,7 +113032,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "graph_query",
-    'Trace how named symbols relate in the dependency graph \u2192 returns subgraph + Mermaid diagram. Input must contain symbol/class names (e.g. "How does AuthService reach Database?", "What depends on UserModel?").',
+    'Trace how named symbols relate in the dependency graph \u2192 returns subgraph + Mermaid diagram. Input must contain symbol/class names (e.g. "How does AuthService reach Database?", "What depends on UserModel?"). Use for ad-hoc graph exploration. For structured call graph use get_call_graph instead. Read-only. Returns JSON: { nodes, edges, mermaid }.',
     {
       query: z9.string().min(1).max(500).describe("Natural language question about code relationships"),
       depth: z9.number().int().min(1).max(6).optional().describe("Max traversal depth (default 3)"),
@@ -112951,7 +113046,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_dataflow",
-    "Intra-function dataflow analysis: track how each parameter flows through the function body \u2014 into which calls, where it gets mutated, and what is returned. Phase 1: single function scope.",
+    "Intra-function dataflow analysis: track how each parameter flows through the function body \u2014 into which calls, where it gets mutated, and what is returned. Phase 1: single function scope. Use to understand data transformations within a function. For security-focused data flow use taint_analysis instead. Read-only. Returns JSON: { symbol_id, params: [{ name, flows: [{ target, mutated }] }], returnPaths }.",
     {
       symbol_id: z9.string().max(512).optional().describe("Symbol ID of the function/method to analyze"),
       fqn: z9.string().max(512).optional().describe("Fully qualified name of the function/method"),
@@ -112966,7 +113061,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "visualize_graph",
-    "Open interactive HTML graph in browser showing file/symbol dependencies. Supports force/hierarchical/radial layouts, community coloring. Use granularity=symbol to see individual functions/classes/methods as nodes instead of files.",
+    "Open interactive HTML graph in browser showing file/symbol dependencies. Supports force/hierarchical/radial layouts, community coloring. Use granularity=symbol to see individual functions/classes/methods as nodes instead of files. Writes an HTML file to disk. For static Mermaid/DOT output use get_dependency_diagram instead. Returns JSON: { outputPath, nodes, edges }.",
     {
       scope: z9.string().min(1).max(512).describe('Scope: file path, directory (e.g. "src/"), or "project"'),
       depth: z9.number().int().min(1).max(5).optional().describe("Max hops from scope (default 2)"),
@@ -113002,7 +113097,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_dependency_diagram",
-    'Render dependency diagram for a file/directory path as Mermaid or DOT. Input: a path like "src/tools/" \u2014 not a question. Trims to max_nodes most important nodes.',
+    'Render dependency diagram for a file/directory path as Mermaid or DOT. Input: a path like "src/tools/" \u2014 not a question. Trims to max_nodes most important nodes. Read-only. For interactive HTML visualization use visualize_graph instead. Returns JSON: { format, diagram, nodes, edges }.',
     {
       scope: z9.string().min(1).max(512).describe('Scope: file path, directory, or "project"'),
       depth: z9.number().int().min(1).max(5).optional().describe("Max hops from scope (default 2)"),
@@ -113017,7 +113112,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "search_text",
-    "Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages \u2014 anything not captured as a symbol.",
+    "Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages \u2014 anything not captured as a symbol. For symbol search (functions, classes) use search instead. Read-only. Returns JSON: { matches: [{ file, line, text, context }], total_matches }.",
     {
       query: z9.string().min(1).max(1e3).describe("Search string or regex pattern"),
       is_regex: z9.boolean().optional().describe("Treat query as regex (default false)"),
@@ -113048,7 +113143,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "predict_bugs",
-    "Predict which files are most likely to contain bugs. Multi-signal scoring: git churn, fix-commit ratio, complexity, coupling, PageRank importance, author count. Each prediction includes a numeric score, risk bucket (low/medium/high/critical) AND a confidence_level (low/medium/high/multi_signal) counting how many independent signals actually fired. Result envelope includes _methodology disclosure. Cached for 1 hour; use refresh=true to recompute.",
+    "Predict which files are most likely to contain bugs. Multi-signal scoring: git churn, fix-commit ratio, complexity, coupling, PageRank importance, author count. Each prediction includes a numeric score, risk bucket (low/medium/high/critical) AND a confidence_level (low/medium/high/multi_signal) counting how many independent signals actually fired. Result envelope includes _methodology disclosure. Cached for 1 hour; use refresh=true to recompute. Requires git. Use for proactive bug hunting. For complexity+churn hotspots only use get_risk_hotspots instead. Read-only. Returns JSON: { predictions: [{ file, score, risk, confidence_level, signals }], total }.",
     {
       limit: z9.number().int().min(1).max(200).optional().describe("Max results (default: 50)"),
       min_score: z9.number().min(0).max(1).optional().describe("Min bug probability score to include (default: 0)"),
@@ -113071,7 +113166,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "detect_drift",
-    "Detect architectural drift: cross-module co-change anomalies (files in different modules that always change together) and shotgun surgery patterns (commits touching 3+ modules). Requires git.",
+    "Detect architectural drift: cross-module co-change anomalies (files in different modules that always change together) and shotgun surgery patterns (commits touching 3+ modules). Requires git. Use to identify hidden coupling across modules. For file-pair co-changes use get_co_changes instead. Read-only. Returns JSON: { anomalies, shotgunSurgery, total }.",
     {
       since_days: z9.number().int().min(1).optional().describe("Analyze commits from last N days (default: 180)"),
       min_confidence: z9.number().min(0).max(1).optional().describe("Min Jaccard confidence for co-change anomalies (default: 0.3)")
@@ -113088,7 +113183,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_tech_debt",
-    "Per-module tech debt score (A\u2013F grade) combining: complexity, coupling instability, test coverage gaps, and git churn. Includes actionable recommendations.",
+    "Per-module tech debt score (A\u2013F grade) combining: complexity, coupling instability, test coverage gaps, and git churn. Includes actionable recommendations. Use for architecture review and prioritizing cleanup. Read-only. Returns JSON: { modules: [{ module, grade, score, factors, recommendations }] }.",
     {
       module: z9.string().max(256).optional().describe('Focus on a specific module path (e.g. "src/tools")'),
       refresh: z9.boolean().optional().describe("Force recomputation (default: false)")
@@ -113107,7 +113202,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "assess_change_risk",
-    "Before modifying a file or symbol, predict risk level (low/medium/high/critical) with contributing factors and recommended mitigations. Combines blast radius, complexity, git churn, test coverage, and coupling.",
+    "Before modifying a file or symbol, predict risk level (low/medium/high/critical) with contributing factors and recommended mitigations. Combines blast radius, complexity, git churn, test coverage, and coupling. Use as a quick risk check. For full impact report with affected tests and dependents use get_change_impact instead. Read-only. Returns JSON: { risk, level, factors: [{ name, value }], mitigations }.",
     {
       file_path: z9.string().max(512).optional().describe("File path to assess"),
       symbol_id: z9.string().max(512).optional().describe("Symbol ID to assess")
@@ -113129,7 +113224,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_health_trends",
-    "Time-series health metrics for a file or module: bug score, complexity, coupling, churn over time. Populated by predict_bugs runs.",
+    "Time-series health metrics for a file or module: bug score, complexity, coupling, churn over time. Populated by predict_bugs runs. Use to track if a module is improving or degrading. Read-only. Returns JSON: { dataPoints: [{ date, bugScore, complexity, coupling, churn }] }.",
     {
       file_path: z9.string().max(512).optional().describe("File path to check"),
       module: z9.string().max(256).optional().describe("Module path prefix to check"),
@@ -113147,7 +113242,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_workspace_map",
-    "List all detected monorepo workspaces with file counts, symbol counts, and languages. Returns dependency graph between workspaces showing cross-workspace imports.",
+    "List all detected monorepo workspaces with file counts, symbol counts, and languages. Returns dependency graph between workspaces showing cross-workspace imports. Use for monorepo structure overview. For impact of changes on other workspaces use get_cross_workspace_impact instead. Read-only. Returns JSON: { workspaces: [{ name, files, symbols, languages }], dependencies }.",
     {
       include_dependencies: z9.boolean().optional().describe("Include cross-workspace dependency graph (default: true)")
     },
@@ -113178,7 +113273,7 @@ function registerAdvancedTools(server, ctx) {
   );
   server.tool(
     "get_cross_workspace_impact",
-    "Show which workspaces are affected by changes in a given workspace. Lists all cross-workspace edges, affected symbols, and the public API surface consumed by other workspaces.",
+    "Show which workspaces are affected by changes in a given workspace. Lists all cross-workspace edges, affected symbols, and the public API surface consumed by other workspaces. Use before modifying shared code in a monorepo. Read-only. Returns JSON: { workspace, public_api, consumed_by, depends_on, cross_workspace_edges }.",
     {
       workspace: z9.string().max(256).describe("Workspace name to analyze")
     },
@@ -115038,28 +115133,331 @@ function formatGateReport(report) {
   return lines.join("\n");
 }
 
+// src/tools/quality/security-context-export.ts
+import { readFileSync as readFileSync9 } from "fs";
+import path107 from "path";
+import { ok as ok72 } from "neverthrow";
+var CATEGORY_PATTERNS = [
+  // file_read
+  { pattern: /^(?:readFile|readFileSync|readdir|readdirSync|createReadStream|promises\.readFile)$/, category: "file_read" },
+  { pattern: /^(?:fs\.read|fs\.promises\.read|fsPromises\.read)/, category: "file_read" },
+  // file_write
+  { pattern: /^(?:writeFile|writeFileSync|appendFile|appendFileSync|createWriteStream|promises\.writeFile)$/, category: "file_write" },
+  { pattern: /^(?:unlink|unlinkSync|rm|rmSync|rmdir|rmdirSync|rename|renameSync|copyFile|copyFileSync)$/, category: "file_write" },
+  { pattern: /^(?:fs\.write|fs\.promises\.write|fs\.unlink|fs\.rm|fsPromises\.write)/, category: "file_write" },
+  { pattern: /^(?:mkdir|mkdirSync|promises\.mkdir)$/, category: "file_write" },
+  // network_outbound
+  { pattern: /^(?:fetch|request|got|axios)$/, category: "network_outbound" },
+  { pattern: /^(?:http\.request|https\.request|http\.get|https\.get)$/, category: "network_outbound" },
+  { pattern: /^(?:net\.connect|net\.createConnection|tls\.connect)$/, category: "network_outbound" },
+  { pattern: /^(?:XMLHttpRequest|WebSocket)$/, category: "network_outbound" },
+  // env_read
+  { pattern: /^(?:process\.env|env\.)/, category: "env_read" },
+  { pattern: /^(?:getenv|os\.environ|dotenv)/, category: "env_read" },
+  // shell_exec
+  { pattern: /^(?:exec|execSync|execFile|execFileSync|spawn|spawnSync|fork)$/, category: "shell_exec" },
+  { pattern: /^(?:child_process\.|cp\.)/, category: "shell_exec" },
+  // crypto
+  { pattern: /^(?:createHash|createCipher|createCipheriv|createDecipher|createDecipheriv|createSign|createVerify|createHmac)$/, category: "crypto" },
+  { pattern: /^(?:crypto\.)/, category: "crypto" },
+  // serialization
+  { pattern: /^(?:eval|Function)$/, category: "serialization" },
+  { pattern: /^(?:deserialize|unserialize|pickle\.loads|yaml\.load)$/, category: "serialization" }
+];
+function classifyFunction(name) {
+  for (const { pattern, category } of CATEGORY_PATTERNS) {
+    if (pattern.test(name)) return category;
+  }
+  return null;
+}
+var ANNOTATION_RE = /\{\s*(?:readOnlyHint|destructiveHint|idempotentHint|openWorldHint)\s*:/;
+function parseAnnotations(source, toolCallIndex) {
+  const searchRegion = source.slice(toolCallIndex, toolCallIndex + 2e3);
+  const annotationMatch = searchRegion.match(
+    /\{\s*(readOnlyHint\s*:\s*(true|false)\s*,?\s*)?(destructiveHint\s*:\s*(true|false)\s*,?\s*)?(idempotentHint\s*:\s*(true|false)\s*,?\s*)?(openWorldHint\s*:\s*(true|false)\s*,?\s*)\}/
+  );
+  if (!annotationMatch) return null;
+  const annotations = {};
+  if (annotationMatch[2]) annotations.readOnlyHint = annotationMatch[2] === "true";
+  if (annotationMatch[4]) annotations.destructiveHint = annotationMatch[4] === "true";
+  if (annotationMatch[6]) annotations.idempotentHint = annotationMatch[6] === "true";
+  if (annotationMatch[8]) annotations.openWorldHint = annotationMatch[8] === "true";
+  return Object.keys(annotations).length > 0 ? annotations : null;
+}
+function parseAnnotationsFlexible(source, toolCallIndex) {
+  const searchRegion = source.slice(toolCallIndex, toolCallIndex + 3e3);
+  if (!ANNOTATION_RE.test(searchRegion)) return null;
+  const annotations = {};
+  const hints = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+  for (const hint of hints) {
+    const re = new RegExp(`${hint}\\s*:\\s*(true|false)`);
+    const m = searchRegion.match(re);
+    if (m) annotations[hint] = m[1] === "true";
+  }
+  return Object.keys(annotations).length > 0 ? annotations : null;
+}
+function collectCallsFromGraph(node, visited, results) {
+  if (visited.has(node.symbol_id)) return;
+  visited.add(node.symbol_id);
+  const category = classifyFunction(node.name);
+  if (category && node.file && node.line) {
+    results.push({
+      function: node.name,
+      file: node.file,
+      line: node.line,
+      category
+    });
+  }
+  if (node.calls) {
+    for (const callee of node.calls) {
+      collectCallsFromGraph(callee, visited, results);
+    }
+  }
+}
+var SECURITY_CALL_RE = /\b((?:fs|http|https|net|crypto|child_process|cp)\.\w+|fetch|exec|execSync|spawn|spawnSync|eval|require|writeFile\w*|readFile\w*|unlink\w*|request|axios|got)\s*\(/g;
+var ENV_ACCESS_RE = /process\.env\b/g;
+var GENERIC_CALL_RE = /\b([a-zA-Z_$]\w*)\s*\(/g;
+var SKIP_KEYWORDS = /* @__PURE__ */ new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "return",
+  "typeof",
+  "new",
+  "async",
+  "await",
+  "function",
+  "const",
+  "let",
+  "var",
+  "class",
+  "import",
+  "export",
+  "throw",
+  "delete",
+  "void",
+  "yield",
+  "as",
+  "from"
+]);
+function findHandlerBounds(source, toolCallIndex) {
+  const region = source.slice(toolCallIndex, toolCallIndex + 1e4);
+  const arrowMatch = region.match(/async\s+(?:\([^)]*\)|[^=]*?)\s*=>\s*\{/);
+  const funcMatch = region.match(/async\s+function\s*\([^)]*\)\s*\{/);
+  const match = arrowMatch ?? funcMatch;
+  if (!match || match.index === void 0) return null;
+  const bodyBraceOffset = match.index + match[0].length - 1;
+  const afterBrace = region.slice(bodyBraceOffset);
+  let depth = 1;
+  let end = -1;
+  for (let i = 1; i < afterBrace.length; i++) {
+    if (afterBrace[i] === "{") depth++;
+    else if (afterBrace[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) end = Math.min(afterBrace.length, 5e3);
+  const absStart = toolCallIndex + bodyBraceOffset;
+  const absEnd = toolCallIndex + bodyBraceOffset + end;
+  return { start: absStart, end: absEnd };
+}
+function scanInlineHandler(source, toolCallIndex, filePath, store, projectRoot, depth) {
+  const bounds = findHandlerBounds(source, toolCallIndex);
+  if (!bounds) return { calls: [], calledSymbolIds: [] };
+  const handlerBody = source.slice(bounds.start, bounds.end);
+  const results = [];
+  const calledSymbolIds = [];
+  let m;
+  const secRe = new RegExp(SECURITY_CALL_RE.source, "g");
+  while ((m = secRe.exec(handlerBody)) !== null) {
+    const funcName = m[1];
+    const category = classifyFunction(funcName);
+    if (category) {
+      const lineOffset = source.slice(0, bounds.start + m.index).split("\n").length;
+      results.push({ function: funcName, file: filePath, line: lineOffset, category });
+    }
+  }
+  const envRe = new RegExp(ENV_ACCESS_RE.source, "g");
+  while ((m = envRe.exec(handlerBody)) !== null) {
+    const lineOffset = source.slice(0, bounds.start + m.index).split("\n").length;
+    results.push({ function: "process.env", file: filePath, line: lineOffset, category: "env_read" });
+  }
+  const genericRe = new RegExp(GENERIC_CALL_RE.source, "g");
+  const seenFuncs = /* @__PURE__ */ new Set();
+  while ((m = genericRe.exec(handlerBody)) !== null) {
+    const funcName = m[1];
+    if (SKIP_KEYWORDS.has(funcName) || seenFuncs.has(funcName)) continue;
+    seenFuncs.add(funcName);
+    const sym = store.getSymbolByName(funcName, "function") ?? store.getSymbolByName(funcName, "method");
+    if (!sym) continue;
+    calledSymbolIds.push(sym.symbol_id);
+    const cgResult = getCallGraph(store, { symbolId: sym.symbol_id }, depth);
+    if (cgResult.isOk() && cgResult.value.root) {
+      const visited = /* @__PURE__ */ new Set();
+      collectCallsFromGraph(cgResult.value.root, visited, results);
+    }
+    const file = sym.file_id ? store.getFileById(sym.file_id) : null;
+    if (file && sym.line_start && sym.line_end) {
+      const symAbsPath = path107.resolve(projectRoot, file.path);
+      try {
+        const symSource = readFileSync9(symAbsPath, "utf-8");
+        const lines = symSource.split("\n");
+        const symBody = lines.slice(sym.line_start - 1, sym.line_end).join("\n");
+        scanSourceForSecurityCalls(symBody, file.path, sym.line_start, results);
+      } catch {
+      }
+    }
+  }
+  return { calls: results, calledSymbolIds };
+}
+function scanSourceForSecurityCalls(body, filePath, startLine, results) {
+  let m;
+  const secRe = new RegExp(SECURITY_CALL_RE.source, "g");
+  while ((m = secRe.exec(body)) !== null) {
+    const funcName = m[1];
+    const category = classifyFunction(funcName);
+    if (category) {
+      const lineOffset = startLine + body.slice(0, m.index).split("\n").length - 1;
+      results.push({ function: funcName, file: filePath, line: lineOffset, category });
+    }
+  }
+  const envRe = new RegExp(ENV_ACCESS_RE.source, "g");
+  while ((m = envRe.exec(body)) !== null) {
+    const lineOffset = startLine + body.slice(0, m.index).split("\n").length - 1;
+    results.push({ function: "process.env", file: filePath, line: lineOffset, category: "env_read" });
+  }
+}
+var PKG_VERSION = true ? "1.22.0" : "0.0.0-dev";
+function exportSecurityContext(store, projectRoot, opts = {}) {
+  const depth = Math.min(opts.depth ?? 3, 5);
+  const warnings = [];
+  const allRoutes = store.getAllRoutes();
+  const toolRoutes = allRoutes.filter((r) => r.method === "TOOL");
+  if (toolRoutes.length === 0) {
+    warnings.push("No MCP tool registrations found in the index. Ensure the project uses @modelcontextprotocol/sdk and has been indexed.");
+  }
+  const toolRegistrations = [];
+  const capabilityMap = {};
+  for (const route of toolRoutes) {
+    const fileRow = route.file_id ? store.getFileById(route.file_id) : null;
+    if (!fileRow) continue;
+    if (opts.scope && !fileRow.path.startsWith(opts.scope)) continue;
+    const absPath = path107.resolve(projectRoot, fileRow.path);
+    let source;
+    try {
+      source = readFileSync9(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const toolNameEscaped = route.uri.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const toolCallRe = new RegExp(`\\.tool\\(\\s*['"]${toolNameEscaped}['"]`);
+    const toolCallMatch = toolCallRe.exec(source);
+    const toolCallIndex = toolCallMatch?.index ?? 0;
+    const toolLine = toolCallIndex > 0 ? source.slice(0, toolCallIndex).split("\n").length : route.line ?? 0;
+    const annotations = parseAnnotationsFlexible(source, toolCallIndex) ?? parseAnnotations(source, toolCallIndex);
+    let handlerCalls = [];
+    let handlerResolved = false;
+    if (toolCallIndex > 0) {
+      const scanResult = scanInlineHandler(source, toolCallIndex, fileRow.path, store, projectRoot, depth);
+      handlerCalls = scanResult.calls;
+      handlerResolved = handlerCalls.length > 0 || scanResult.calledSymbolIds.length > 0;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    handlerCalls = handlerCalls.filter((c) => {
+      const key = `${c.function}:${c.file}:${c.line}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    for (const call of handlerCalls) {
+      if (!capabilityMap[call.file]) capabilityMap[call.file] = /* @__PURE__ */ new Set();
+      capabilityMap[call.file].add(call.category);
+    }
+    toolRegistrations.push({
+      name: route.uri,
+      description: route.name ?? null,
+      file: fileRow.path,
+      line: toolLine,
+      annotations,
+      handler_resolved: handlerResolved,
+      handler_calls: handlerCalls
+    });
+  }
+  const sensitiveFlows = [];
+  const mcpServerFiles = new Set(toolRegistrations.map((t) => t.file));
+  if (mcpServerFiles.size > 0) {
+    const mcpDirs = [...new Set([...mcpServerFiles].map((f) => path107.dirname(f)))];
+    for (const dir of mcpDirs) {
+      const taintResult = taintAnalysis(store, projectRoot, {
+        scope: dir,
+        sources: ["env", "file_read"],
+        includeSanitized: false,
+        limit: 50
+      });
+      if (taintResult.isOk()) {
+        for (const flow of taintResult.value.flows) {
+          sensitiveFlows.push({
+            source: {
+              kind: flow.source.kind,
+              name: flow.source.variable,
+              file: flow.file,
+              line: flow.source.line
+            },
+            sink: {
+              kind: flow.sink.kind,
+              file: flow.file,
+              line: flow.sink.line
+            },
+            hops: flow.path.map((step) => `${flow.file}:${step.line}`)
+          });
+        }
+      }
+    }
+  }
+  const capabilityMapOutput = {};
+  for (const [file, categories] of Object.entries(capabilityMap)) {
+    capabilityMapOutput[file] = [...categories].sort();
+  }
+  return ok72({
+    $schema: "https://skill-scan.dev/schemas/enrichment/v1.json",
+    version: "1",
+    generator: `trace-mcp/${PKG_VERSION}`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    tool_registrations: toolRegistrations,
+    sensitive_flows: sensitiveFlows,
+    capability_map: capabilityMapOutput,
+    warnings
+  });
+}
+
 // src/tools/register/quality.ts
 function registerQualityTools(server, ctx) {
   const { store, registry, config, projectRoot, j: j3 } = ctx;
-  server.tool("get_co_changes", "Find files that frequently change together in git history (temporal coupling).", { file: z11.string().min(1).max(512).describe("File path to analyze"), min_confidence: z11.number().min(0).max(1).optional().describe("Minimum confidence threshold (default 0.3)"), min_count: z11.number().int().min(1).optional().describe("Minimum co-change count (default 3)"), window_days: z11.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)"), limit: z11.number().int().min(1).max(100).optional().describe("Max results (default 20)") }, async ({ file, min_confidence, min_count, window_days, limit: lim }) => {
+  server.tool("get_co_changes", "Find files that frequently change together in git history (temporal coupling). Requires git. Use to discover hidden dependencies between files. For cross-module co-change anomalies use detect_drift instead. Read-only. Returns JSON: { file, coChanges: [{ file, confidence, count }] }.", { file: z11.string().min(1).max(512).describe("File path to analyze"), min_confidence: z11.number().min(0).max(1).optional().describe("Minimum confidence threshold (default 0.3)"), min_count: z11.number().int().min(1).optional().describe("Minimum co-change count (default 3)"), window_days: z11.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)"), limit: z11.number().int().min(1).max(100).optional().describe("Max results (default 20)") }, async ({ file, min_confidence, min_count, window_days, limit: lim }) => {
     const result = getCoChanges(store, { file, minConfidence: min_confidence, minCount: min_count, windowDays: window_days, limit: lim });
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("refresh_co_changes", "Rebuild co-change index from git history.", { window_days: z11.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)") }, async ({ window_days }) => {
+  server.tool("refresh_co_changes", "Rebuild co-change index from git history. Mutates the co-change index; idempotent. Use after significant git history changes. Returns JSON: { status, pairs_stored, window_days }.", { window_days: z11.number().int().min(1).max(730).optional().describe("Git history window in days (default 180)") }, async ({ window_days }) => {
     const days = window_days ?? 180;
     const pairs = collectCoChanges(projectRoot, days);
     const count2 = persistCoChanges(store, pairs, projectRoot, days);
     return { content: [{ type: "text", text: j3({ status: "completed", pairs_stored: count2, window_days: days }) }] };
   });
-  server.tool("get_changed_symbols", 'Map a git diff to affected symbols (functions, classes, methods). For PR review. If "since" is omitted, auto-detects main/master as the base.', { since: z11.string().min(1).max(256).optional().describe("Git ref to compare from (SHA, branch, tag). If omitted, auto-detects main/master merge-base"), until: z11.string().max(256).optional().describe("Git ref to compare to (default: HEAD)"), include_blast_radius: z11.boolean().optional().describe("Include blast radius for each changed symbol (default false)"), max_blast_depth: z11.number().int().min(1).max(10).optional().describe("Max blast radius traversal depth (default 3)") }, async ({ since, until, include_blast_radius, max_blast_depth }) => {
+  server.tool("get_changed_symbols", 'Map a git diff to affected symbols (functions, classes, methods). For PR review. If "since" is omitted, auto-detects main/master as the base. Requires git. Use for PR review to see which symbols changed. For full branch comparison with risk assessment use compare_branches instead. Read-only. Returns JSON: { changes: [{ symbol_id, name, kind, file, changeType }], total }.', { since: z11.string().min(1).max(256).optional().describe("Git ref to compare from (SHA, branch, tag). If omitted, auto-detects main/master merge-base"), until: z11.string().max(256).optional().describe("Git ref to compare to (default: HEAD)"), include_blast_radius: z11.boolean().optional().describe("Include blast radius for each changed symbol (default false)"), max_blast_depth: z11.number().int().min(1).max(10).optional().describe("Max blast radius traversal depth (default 3)") }, async ({ since, until, include_blast_radius, max_blast_depth }) => {
     const result = getChangedSymbols(store, projectRoot, { since, until, includeBlastRadius: include_blast_radius, maxBlastDepth: max_blast_depth, defaultBaseBranch: config.git?.defaultBaseBranch });
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
   server.tool(
     "compare_branches",
-    "Compare two branches at symbol level: what was added, modified, removed. Resolves merge-base automatically, groups by category/file/risk, includes blast radius and risk assessment.",
+    "Compare two branches at symbol level: what was added, modified, removed. Resolves merge-base automatically, groups by category/file/risk, includes blast radius and risk assessment. Requires git. Use for comprehensive PR comparison. For a quick list of changed symbols without risk analysis use get_changed_symbols instead. Read-only. Returns JSON: { branch, base, mergeBase, changes: [{ symbol_id, category, risk }], summary }.",
     {
       branch: z11.string().min(1).max(256).describe('Branch to compare (e.g. "feature/payments")'),
       base: z11.string().max(256).optional().describe('Base branch (default: "main")'),
@@ -115080,28 +115478,28 @@ function registerQualityTools(server, ctx) {
       return { content: [{ type: "text", text: j3(result.value) }] };
     }
   );
-  server.tool("detect_communities", "Run Leiden community detection on the file dependency graph. Identifies tightly-coupled file clusters (modules).", { resolution: z11.number().min(0.1).max(5).optional().describe("Resolution parameter \u2014 higher values produce more communities (default 1.0)") }, async ({ resolution }) => {
+  server.tool("detect_communities", "Run Leiden community detection on the file dependency graph. Identifies tightly-coupled file clusters (modules). Mutates the community index (stores results); idempotent. Use before get_communities or get_community. Returns JSON: { communities: [{ id, files, size }], modularity }.", { resolution: z11.number().min(0.1).max(5).optional().describe("Resolution parameter \u2014 higher values produce more communities (default 1.0)") }, async ({ resolution }) => {
     const result = detectCommunities2(store, resolution ?? 1);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("get_communities", "Get previously detected communities (file clusters). Run detect_communities first.", {}, async () => {
+  server.tool("get_communities", "Get previously detected communities (file clusters). Run detect_communities first. Read-only. Returns JSON: { communities: [{ id, files, size }], total }.", {}, async () => {
     const result = getCommunities(store);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("get_community", "Get details for a specific community: files, inter-community dependencies.", { id: z11.number().int().min(0).describe("Community ID") }, async ({ id }) => {
+  server.tool("get_community", "Get details for a specific community: files, inter-community dependencies. Read-only. Use after detect_communities to drill into a specific cluster. Returns JSON: { id, files, interCommunityDeps }.", { id: z11.number().int().min(0).describe("Community ID") }, async ({ id }) => {
     const result = getCommunityDetail(store, id);
     if (result.isErr()) return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
     return { content: [{ type: "text", text: j3(result.value) }] };
   });
-  server.tool("audit_config", "Scan AI agent config files for stale references, dead paths, and token bloat.", { config_files: z11.array(z11.string().max(512)).optional().describe("Specific config files to audit (default: auto-detect)"), fix_suggestions: z11.boolean().optional().describe("Include fix suggestions (default true)") }, async ({ config_files, fix_suggestions }) => {
+  server.tool("audit_config", "Scan AI agent config files for stale references, dead paths, and token bloat. Read-only. Use periodically to clean up CLAUDE.md and settings. Returns JSON: { issues: [{ file, type, message, suggestion }], total }.", { config_files: z11.array(z11.string().max(512)).optional().describe("Specific config files to audit (default: auto-detect)"), fix_suggestions: z11.boolean().optional().describe("Include fix suggestions (default true)") }, async ({ config_files, fix_suggestions }) => {
     const result = auditConfig(store, projectRoot, { configFiles: config_files, fixSuggestions: fix_suggestions ?? true });
     return { content: [{ type: "text", text: j3(result) }] };
   });
   server.tool(
     "get_control_flow",
-    "Build a Control Flow Graph (CFG) for a function/method: if/else branches, loops, try/catch, returns, throws. Shows logical paths through the code. Outputs Mermaid diagram, ASCII, or JSON.",
+    "Build a Control Flow Graph (CFG) for a function/method: if/else branches, loops, try/catch, returns, throws. Shows logical paths through the code. Outputs Mermaid diagram, ASCII, or JSON. Use to understand branching logic before modifying complex functions. For call-level graph (who calls whom) use get_call_graph instead. Read-only. Returns Mermaid/ASCII/JSON: { nodes, edges, entryPoint, exitPoints }.",
     {
       symbol_id: z11.string().max(512).optional().describe("Symbol ID of the function/method"),
       fqn: z11.string().max(512).optional().describe("Fully qualified name of the function/method"),
@@ -115123,7 +115521,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "get_package_deps",
-    "Cross-repo package dependency analysis: find which registered projects depend on a package, or what packages a project publishes. Scans package.json/composer.json/pyproject.toml across all repos in the registry.",
+    "Cross-repo package dependency analysis: find which registered projects depend on a package, or what packages a project publishes. Scans package.json/composer.json/pyproject.toml across all repos in the registry. Use for cross-project dependency mapping. For impact of upgrading a specific package use plan_batch_change instead. Read-only. Returns JSON: { dependents, dependencies, package }.",
     {
       package: z11.string().max(256).optional().describe('Package name to analyze (e.g. "@myorg/shared-utils")'),
       project: z11.string().max(256).optional().describe("Project name \u2014 analyze all packages it publishes"),
@@ -115140,7 +115538,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "generate_docs",
-    "Auto-generate project documentation from the code graph. Produces structured docs with architecture, API surface, data models, components, and dependency analysis.",
+    "Auto-generate project documentation from the code graph. Produces structured docs with architecture, API surface, data models, components, and dependency analysis. Writes output file (markdown or HTML). Use when you need a comprehensive documentation snapshot. Returns JSON: { format, sections, outputPath }.",
     {
       scope: z11.enum(["project", "module", "directory"]).optional().describe("Scope (default: project)"),
       path: z11.string().max(512).optional().describe("Path for module/directory scope"),
@@ -115160,7 +115558,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "pack_context",
-    "Pack project context into a single document for external LLMs. Intelligent selection by graph importance, fits within token budget. Better than Repomix for focused context. Strategies: most_relevant (default \u2014 feature/PageRank ranked), core_first (PageRank always wins, surfaces architecturally central code), compact (signatures only \u2014 drops source bodies, lets outlines cover much more of the repo per token).",
+    "Pack project context into a single document for external LLMs. Intelligent selection by graph importance, fits within token budget. Better than Repomix for focused context. Strategies: most_relevant (default \u2014 feature/PageRank ranked), core_first (PageRank always wins, surfaces architecturally central code), compact (signatures only \u2014 drops source bodies, lets outlines cover much more of the repo per token). Read-only. Use when sharing project context with external tools. Returns XML/Markdown/JSON with selected code within budget.",
     {
       scope: z11.enum(["project", "module", "feature"]).describe("Scope: project (whole repo), module (subdirectory), feature (NL query)"),
       path: z11.string().max(512).optional().describe("Subdirectory path (for module scope)"),
@@ -115190,7 +115588,7 @@ function registerQualityTools(server, ctx) {
   );
   server.tool(
     "check_quality_gates",
-    "Run configurable quality gate checks against the project. Returns pass/fail for each gate (complexity, coupling, circular imports, dead exports, tech debt, security, antipatterns, code smells). Designed for CI integration \u2014 AI can verify gates pass before committing.",
+    "Run configurable quality gate checks against the project. Returns pass/fail for each gate (complexity, coupling, circular imports, dead exports, tech debt, security, antipatterns, code smells). Designed for CI integration \u2014 AI can verify gates pass before committing. Use before PR/commit to ensure quality standards. Read-only. Returns JSON: { passed, gates: [{ name, status, value, threshold }], summary }.",
     {
       scope: z11.enum(["project", "changed"]).optional().describe('Scope: "project" (all) or "changed" (git diff). Default: project'),
       since: z11.string().max(128).optional().describe('Git ref for "changed" scope (e.g. "main")'),
@@ -115235,6 +115633,21 @@ function registerQualityTools(server, ctx) {
       return { content: [{ type: "text", text: j3(report) }] };
     }
   );
+  server.tool(
+    "export_security_context",
+    "Export security context for MCP server analysis. Generates enrichment JSON for skill-scan: tool registrations with annotations, transitive call graphs classified by security category (file_read, file_write, network_outbound, env_read, shell_exec, crypto, serialization), sensitive data flows, and per-file capability maps. Use to analyze MCP server security before installation. Read-only. Returns JSON: { tool_registrations, sensitive_flows, capability_map, warnings }.",
+    {
+      scope: z11.string().max(512).optional().describe("Limit analysis to directory (relative to project root)"),
+      depth: z11.number().int().min(1).max(5).optional().describe("Call graph traversal depth (default: 3)")
+    },
+    async ({ scope: scope8, depth }) => {
+      const result = exportSecurityContext(store, projectRoot, { scope: scope8, depth });
+      if (result.isErr()) {
+        return { content: [{ type: "text", text: j3(formatToolError(result.error)) }], isError: true };
+      }
+      return { content: [{ type: "text", text: j3(result.value) }] };
+    }
+  );
 }
 
 // src/tools/register/session.ts
@@ -115243,7 +115656,7 @@ init_project_context();
 
 // src/tools/ai/ai-tools.ts
 import { z as z12 } from "zod";
-import path107 from "path";
+import path108 from "path";
 function j(value) {
   return JSON.stringify(value);
 }
@@ -115259,7 +115672,7 @@ function symbolToContextItem(sym, file, projectRoot, score = 1) {
 }
 function readSourceSafe(filePath, byteStart, byteEnd, projectRoot, gitignored) {
   try {
-    const absPath = path107.resolve(projectRoot, filePath);
+    const absPath = path108.resolve(projectRoot, filePath);
     return readByteRange(absPath, byteStart, byteEnd, gitignored);
   } catch {
     return null;
@@ -115576,19 +115989,19 @@ function registerAITools(server, ctx) {
 init_logger();
 init_global();
 import Database6 from "better-sqlite3";
-import path108 from "path";
+import path109 from "path";
 import fs99 from "fs";
 import crypto6 from "crypto";
-var BUNDLES_DIR = path108.join(TRACE_MCP_HOME, "bundles");
+var BUNDLES_DIR = path109.join(TRACE_MCP_HOME, "bundles");
 function ensureBundlesDir() {
   fs99.mkdirSync(BUNDLES_DIR, { recursive: true });
 }
 function getBundlePath(packageName, version2) {
   const safeName = packageName.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path108.join(BUNDLES_DIR, `${safeName}-${version2}.bundle.db`);
+  return path109.join(BUNDLES_DIR, `${safeName}-${version2}.bundle.db`);
 }
 function getManifestPath() {
-  return path108.join(BUNDLES_DIR, "manifest.json");
+  return path109.join(BUNDLES_DIR, "manifest.json");
 }
 function loadManifest() {
   const p5 = getManifestPath();
@@ -115757,7 +116170,7 @@ function exportBundle(sourceDbPath, packageName, version2) {
   const entry = {
     package: packageName,
     version: version2,
-    file: path108.basename(bundlePath),
+    file: path109.basename(bundlePath),
     symbols: srcSymbols.length,
     edges: srcEdges.length,
     size_bytes: sizeBytes,
@@ -115782,7 +116195,7 @@ function removeBundle(packageName, version2) {
     (b) => b.package === packageName && (!version2 || b.version === version2)
   );
   for (const entry of toRemove) {
-    const fp = path108.join(BUNDLES_DIR, entry.file);
+    const fp = path109.join(BUNDLES_DIR, entry.file);
     if (fs99.existsSync(fp)) fs99.unlinkSync(fp);
   }
   manifest.bundles = manifest.bundles.filter(
@@ -115848,8 +116261,8 @@ function searchBundles(bundles, query, opts = {}) {
 // src/analytics/analytics-store.ts
 init_global();
 import Database7 from "better-sqlite3";
-import path109 from "path";
-var ANALYTICS_DB_PATH = path109.join(TRACE_MCP_HOME, "analytics.db");
+import path110 from "path";
+var ANALYTICS_DB_PATH = path110.join(TRACE_MCP_HOME, "analytics.db");
 var SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
@@ -116082,9 +116495,9 @@ var AnalyticsStore = class {
 // src/analytics/log-parser.ts
 init_logger();
 import fs100 from "fs";
-import path110 from "path";
+import path111 from "path";
 import os9 from "os";
-var CLAUDE_PROJECTS_DIR = path110.join(os9.homedir(), ".claude", "projects");
+var CLAUDE_PROJECTS_DIR = path111.join(os9.homedir(), ".claude", "projects");
 var CLAW_SESSIONS_DIR_NAME = ".claw/sessions";
 function parseToolName(fullName) {
   const match = fullName.match(/^mcp__([^_]+)__(.+)$/);
@@ -116161,7 +116574,7 @@ function parseSessionFile(filePath, projectPath) {
   try {
     const content = fs100.readFileSync(filePath, "utf-8");
     const lines = content.split("\n").filter((l) => l.trim());
-    const sessionId = path110.basename(filePath, ".jsonl");
+    const sessionId = path111.basename(filePath, ".jsonl");
     const toolCalls = [];
     const toolResults = /* @__PURE__ */ new Map();
     let model = "";
@@ -116282,11 +116695,11 @@ function listProjectDirs() {
   }));
 }
 function listSessionFiles(projectDirName) {
-  const dir = path110.join(CLAUDE_PROJECTS_DIR, projectDirName);
+  const dir = path111.join(CLAUDE_PROJECTS_DIR, projectDirName);
   if (!fs100.existsSync(dir)) return [];
   const entries = fs100.readdirSync(dir, { withFileTypes: true });
   return entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => {
-    const filePath = path110.join(dir, e.name);
+    const filePath = path111.join(dir, e.name);
     const stat = fs100.statSync(filePath);
     return { filePath, mtime: stat.mtimeMs };
   });
@@ -116300,13 +116713,13 @@ function listAllSessions() {
   }
   const clawProjectPaths = discoverClawProjects();
   for (const projectPath of clawProjectPaths) {
-    const sessionsDir = path110.join(projectPath, CLAW_SESSIONS_DIR_NAME);
+    const sessionsDir = path111.join(projectPath, CLAW_SESSIONS_DIR_NAME);
     if (!fs100.existsSync(sessionsDir)) continue;
     try {
       const entries = fs100.readdirSync(sessionsDir, { withFileTypes: true });
       for (const e of entries) {
         if (!e.isFile() || !e.name.endsWith(".jsonl")) continue;
-        const filePath = path110.join(sessionsDir, e.name);
+        const filePath = path111.join(sessionsDir, e.name);
         try {
           const stat = fs100.statSync(filePath);
           results.push({ filePath, projectPath, client: "claw-code", mtime: stat.mtimeMs });
@@ -116321,25 +116734,25 @@ function listAllSessions() {
 function discoverClawProjects() {
   const paths = /* @__PURE__ */ new Set();
   for (const { projectPath } of listProjectDirs()) {
-    if (fs100.existsSync(path110.join(projectPath, CLAW_SESSIONS_DIR_NAME))) {
+    if (fs100.existsSync(path111.join(projectPath, CLAW_SESSIONS_DIR_NAME))) {
       paths.add(projectPath);
     }
   }
   const cwd = process.cwd();
-  if (fs100.existsSync(path110.join(cwd, CLAW_SESSIONS_DIR_NAME))) {
+  if (fs100.existsSync(path111.join(cwd, CLAW_SESSIONS_DIR_NAME))) {
     paths.add(cwd);
   }
   const home = os9.homedir();
   const commonRoots = ["Projects", "projects", "dev", "workspace", "code", "PhpstormProjects", "WebstormProjects", "src"];
   for (const root of commonRoots) {
-    const rootDir = path110.join(home, root);
+    const rootDir = path111.join(home, root);
     if (!fs100.existsSync(rootDir)) continue;
     try {
       const entries = fs100.readdirSync(rootDir, { withFileTypes: true });
       for (const e of entries) {
         if (!e.isDirectory()) continue;
-        const projectDir = path110.join(rootDir, e.name);
-        if (fs100.existsSync(path110.join(projectDir, CLAW_SESSIONS_DIR_NAME))) {
+        const projectDir = path111.join(rootDir, e.name);
+        if (fs100.existsSync(path111.join(projectDir, CLAW_SESSIONS_DIR_NAME))) {
           paths.add(projectDir);
         }
       }
@@ -117045,7 +117458,7 @@ function formatBenchmarkMarkdown(result) {
 
 // src/analytics/tech-detector.ts
 import fs101 from "fs";
-import path111 from "path";
+import path112 from "path";
 
 // src/analytics/known-packages.ts
 var KNOWN_PACKAGES = {
@@ -118709,7 +119122,7 @@ function detectCoverage(projectRoot, opts = {}) {
   const manifestsFound = [];
   const allDeps = [];
   for (const { file, ecosystem, parser } of MANIFEST_PARSERS) {
-    const filePath = path111.join(projectRoot, file);
+    const filePath = path112.join(projectRoot, file);
     if (!fs101.existsSync(filePath)) continue;
     manifestsFound.push(file);
     const rawDeps = parser(filePath);
@@ -119916,7 +120329,7 @@ function registerSessionTools(server, ctx) {
   }
   server.tool(
     "search_bundles",
-    "Search pre-indexed bundles for symbols from popular libraries (React, Express, etc.). Returns symbol definitions from dependency bundles \u2014 useful for go-to-definition into node_modules/vendor. Install bundles via CLI: `trace-mcp bundles export`.",
+    "Search pre-indexed bundles for symbols from popular libraries (React, Express, etc.). Returns symbol definitions from dependency bundles \u2014 useful for go-to-definition into node_modules/vendor. Install bundles via CLI: `trace-mcp bundles export`. For project source code search use search instead. Read-only. Returns JSON: { results: [{ name, kind, signature, bundle }], bundles_searched }.",
     {
       query: z14.string().min(1).max(256).describe("Symbol name or FQN to search"),
       kind: z14.string().max(64).optional().describe("Filter by symbol kind (function, class, interface, etc.)"),
@@ -119934,7 +120347,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "list_bundles",
-    "List installed pre-indexed bundles for dependency libraries. Shows package name, version, symbol/edge counts, and size.",
+    "List installed pre-indexed bundles for dependency libraries. Shows package name, version, symbol/edge counts, and size. Read-only. Returns JSON: { bundles: [{ name, version, symbols, edges, size }], total }.",
     {},
     async () => {
       const bundles = listBundles();
@@ -119943,7 +120356,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_preset_info",
-    "Show active tool preset, available presets, and which tools are registered in this session",
+    "Show active tool preset, available presets, and which tools are registered in this session. Read-only. Returns JSON: { active_preset, registered_tools, tool_names, available_presets }.",
     {},
     async () => {
       const presets = listPresets();
@@ -119962,7 +120375,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_session_analytics",
-    "Analyze AI agent session logs: token usage, cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically.",
+    "Analyze AI agent session logs: token usage, cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically. Read-only. For waste detection use get_optimization_report; for cost trends use get_usage_trends. Returns JSON: { sessions, tokens, cost_usd, tools, models, topFiles }.",
     {
       period: z14.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)"),
       session_id: z14.string().max(128).optional().describe("Specific session ID to analyze")
@@ -119983,7 +120396,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_optimization_report",
-    "Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates.",
+    "Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates. Read-only. For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings. Returns JSON: { patterns: [{ type, description, savings_estimate }], total_waste }.",
     {
       period: z14.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)")
     },
@@ -120003,7 +120416,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "benchmark_project",
-    "Synthetic token efficiency benchmark: compare raw file reads vs trace-mcp compact responses across symbol lookup, file exploration, search, and impact analysis scenarios.",
+    "Synthetic token efficiency benchmark: compare raw file reads vs trace-mcp compact responses across symbol lookup, file exploration, search, and impact analysis scenarios. Read-only, no side effects. Use to quantify token savings. Returns JSON: { scenarios: [{ name, raw_tokens, compact_tokens, savings_pct }], summary }.",
     {
       queries: z14.number().int().min(1).max(50).optional().describe("Queries per scenario (default 10)"),
       seed: z14.number().int().optional().describe("Random seed for reproducibility (default 42)"),
@@ -120019,7 +120432,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_coverage_report",
-    "Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps.",
+    "Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps. Read-only. Returns JSON: { detected, covered, gaps }.",
     {},
     async () => {
       try {
@@ -120032,7 +120445,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_real_savings",
-    "A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown.",
+    "A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown. Read-only. For pattern-based waste detection use get_optimization_report instead. Returns JSON: { files: [{ file, raw_tokens, compact_tokens, savings }], total_savings }.",
     {
       period: z14.enum(["today", "week", "month", "all"]).optional().describe("Time period (default: week)")
     },
@@ -120054,7 +120467,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_usage_trends",
-    "Daily token usage time-series: sessions, tokens, estimated cost, tool calls per day. For spotting cost spikes.",
+    "Daily token usage time-series: sessions, tokens, estimated cost, tool calls per day. For spotting cost spikes. Read-only. For detailed session breakdown use get_session_analytics instead. Returns JSON: { days, daily: [{ date, sessions, tokens, cost_usd, tool_calls }], totals }.",
     {
       days: z14.number().int().min(1).max(365).optional().describe("Number of days to show (default: 30)")
     },
@@ -120081,7 +120494,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "get_session_stats",
-    "Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings.",
+    "Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings. Read-only. Returns JSON: { total_calls, total_raw_tokens, total_compact_tokens, savings_pct, dedup_saved_tokens, per_tool }.",
     {},
     async () => {
       const stats = savings.getFullStats();
@@ -120099,7 +120512,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_journal",
-    "Session history: all tool calls made, files read, zero-result searches, and duplicate queries. Use to avoid repeating work.",
+    "Session history: all tool calls made, files read, zero-result searches, and duplicate queries. Use to avoid repeating work. For a compact snapshot use get_session_snapshot instead. Read-only. Returns JSON: { calls, filesRead, zeroResults, duplicates }.",
     {},
     async () => {
       const summary = journal.getSummary();
@@ -120108,7 +120521,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_snapshot",
-    "Compact session snapshot (~200 tokens) for context recovery after compaction. Returns focus files (by read count), edited files, key searches, and dead ends. Also used by the PreCompact hook to preserve session orientation automatically.",
+    "Compact session snapshot (~200 tokens) for context recovery after compaction. Returns focus files (by read count), edited files, key searches, and dead ends. Also used by the PreCompact hook to preserve session orientation automatically. Read-only. For full journal use get_session_journal; for cross-session context use get_session_resume. Returns JSON: { focusFiles, editedFiles, keySearches, deadEnds }.",
     {
       max_files: z14.number().int().min(1).max(50).optional().describe("Max focus files to include (default: 10)"),
       max_searches: z14.number().int().min(1).max(20).optional().describe("Max key searches to include (default: 5)"),
@@ -120127,7 +120540,7 @@ function registerSessionTools(server, ctx) {
   );
   server.tool(
     "get_session_resume",
-    "Cross-session context carryover: shows what was explored in recent past sessions (files touched, tools used, dead-end searches). Call at session start to orient yourself without re-reading files. Much cheaper than re-exploring the codebase.",
+    "Cross-session context carryover: shows what was explored in recent past sessions (files touched, tools used, dead-end searches). Call at session start to orient yourself without re-reading files. Much cheaper than re-exploring the codebase. Read-only. For decision-aware wake-up use get_wake_up instead. Returns JSON: { sessions: [{ files, tools, deadEnds }], active_decisions }.",
     {
       max_sessions: z14.number().int().min(1).max(20).optional().describe("Number of past sessions to include (default: 5)")
     },
@@ -120146,7 +120559,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "plan_turn",
-    "Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain.",
+    "Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain. Read-only. For broader task context with source code use get_task_context instead. Returns JSON: { verdict, confidence, targets, scaffoldHints, nextSteps }.",
     {
       task: z14.string().min(1).max(512).describe('Natural-language task description (e.g. "add a webhook endpoint for stripe payments")'),
       intent: z14.enum(["bugfix", "new_feature", "refactor", "understand"]).optional().describe("Optional intent hint; auto-classified from task if omitted"),
@@ -120180,7 +120593,7 @@ function registerSessionTools(server, ctx) {
   );
   _originalTool(
     "batch",
-    "Execute multiple trace-mcp tools in a single MCP request. Returns results for all calls. Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together).",
+    "Execute multiple trace-mcp tools in a single MCP request. Returns results for all calls. Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together). Read-only (delegates to other tools). Returns JSON: { batch_results: [{ tool, result }], total }.",
     {
       calls: z14.array(z14.object({
         tool: z14.string().describe('Tool name (e.g., "get_outline", "get_symbol", "search")'),
@@ -120230,7 +120643,7 @@ import { z as z15 } from "zod";
 
 // src/memory/conversation-miner.ts
 import * as fs102 from "fs";
-import * as path112 from "path";
+import * as path113 from "path";
 init_logger();
 var DECISION_PATTERNS = [
   // Architecture decisions: "decided to", "we'll use", "going with", "chose X over Y"
@@ -120458,7 +120871,7 @@ function mineSessions(decisionStore, opts = {}) {
           file_path: d.file_path,
           tags: d.tags,
           valid_from: d.timestamp,
-          session_id: path112.basename(session.filePath, ".jsonl"),
+          session_id: path113.basename(session.filePath, ".jsonl"),
           source: "mined",
           confidence: d.confidence
         }));
@@ -120484,7 +120897,7 @@ function mineSessions(decisionStore, opts = {}) {
 
 // src/memory/session-indexer.ts
 import * as fs103 from "fs";
-import * as path113 from "path";
+import * as path114 from "path";
 init_logger();
 var MAX_CHUNK_CHARS = 2e3;
 var MIN_MESSAGE_CHARS = 50;
@@ -120525,7 +120938,7 @@ function truncateChunk(text) {
 function indexSessionFile(filePath, projectPath, decisionStore) {
   const content = fs103.readFileSync(filePath, "utf-8");
   const lines = content.split("\n").filter((l) => l.trim());
-  const sessionId = path113.basename(filePath, ".jsonl");
+  const sessionId = path114.basename(filePath, ".jsonl");
   const chunks = [];
   let chunkIndex = 0;
   for (const line of lines) {
@@ -120576,7 +120989,7 @@ function indexSessions(decisionStore, opts = {}) {
       skipped++;
       continue;
     }
-    const sessionId = path113.basename(session.filePath, ".jsonl");
+    const sessionId = path114.basename(session.filePath, ".jsonl");
     if (!opts.force && decisionStore.isSessionIndexed(sessionId)) {
       skipped++;
       continue;
@@ -120601,7 +121014,7 @@ function indexSessions(decisionStore, opts = {}) {
 }
 
 // src/memory/wake-up.ts
-import * as path114 from "path";
+import * as path115 from "path";
 function compactDecision(d) {
   const entry = {
     id: d.id,
@@ -120625,7 +121038,7 @@ function assembleWakeUp(decisionStore, projectRoot, opts = {}) {
   const indexedSessions = decisionStore.getIndexedSessionIds(projectRoot);
   const result = {
     project: {
-      name: path114.basename(projectRoot),
+      name: path115.basename(projectRoot),
       root: projectRoot
     },
     decisions: {
@@ -120669,7 +121082,7 @@ function registerMemoryTools(server, ctx) {
   }
   server.tool(
     "mine_sessions",
-    "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Extracts decision-like content using pattern matching (no LLM calls). Skips already-mined sessions unless force=true.",
+    "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Extracts decision-like content using pattern matching (no LLM calls). Skips already-mined sessions unless force=true. Mutates the decision store; idempotent. Use to populate the decision knowledge graph. Returns JSON: { mined, decisions_extracted, sessions_processed }.",
     {
       project_root: z15.string().max(1024).optional().describe("Only mine sessions for this project path (default: all projects)"),
       force: z15.boolean().optional().describe("Re-mine already processed sessions (default: false)"),
@@ -120686,7 +121099,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "add_decision",
-    "Manually record an architectural decision, tech choice, preference, or convention. Links to code symbols/files and optionally to a specific subproject for code-aware memory. Decisions have temporal validity \u2014 they can be invalidated later when they become outdated.",
+    "Manually record an architectural decision, tech choice, preference, or convention. Links to code symbols/files and optionally to a specific subproject for code-aware memory. Decisions have temporal validity \u2014 they can be invalidated later when they become outdated. Mutates the decision store (creates a new record). For automated extraction from session logs use mine_sessions instead. Returns JSON: { added: { id, title, type } }.",
     {
       title: z15.string().min(1).max(200).describe("Short summary of the decision"),
       content: z15.string().min(1).max(5e3).describe("Full decision text \u2014 reasoning, context, tradeoffs"),
@@ -120714,7 +121127,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "query_decisions",
-    'Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code \u2014 "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project.',
+    'Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code \u2014 "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project. Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags }], total_results }.',
     {
       type: z15.enum(DECISION_TYPES).optional().describe("Filter by decision type"),
       service_name: z15.string().max(256).optional().describe('Filter by subproject name (e.g., "auth-api")'),
@@ -120750,14 +121163,14 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "invalidate_decision",
-    "Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed.",
+    "Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed. Mutates the decision store; idempotent. Returns JSON: { invalidated: { id, title, valid_until } }.",
     {
       id: z15.number().int().min(1).describe("Decision ID to invalidate"),
       valid_until: z15.string().max(30).optional().describe("ISO timestamp when decision became invalid (default: now)")
     },
     async ({ id, valid_until }) => {
-      const ok72 = decisionStore.invalidateDecision(id, valid_until);
-      if (!ok72) {
+      const ok73 = decisionStore.invalidateDecision(id, valid_until);
+      if (!ok73) {
         return { content: [{ type: "text", text: j3({ error: `Decision ${id} not found or already invalidated` }) }], isError: true };
       }
       const updated = decisionStore.getDecision(id);
@@ -120766,7 +121179,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_decision_timeline",
-    "Chronological timeline of decisions for a project, symbol, or file. Shows when decisions were made and invalidated \u2014 like git log but for architectural decisions.",
+    "Chronological timeline of decisions for a project, symbol, or file. Shows when decisions were made and invalidated \u2014 like git log but for architectural decisions. Read-only. Use to review decision history. Returns JSON: { timeline: [{ id, title, type, created_at, valid_until }], count }.",
     {
       symbol_id: z15.string().max(512).optional().describe("Filter timeline to decisions about this symbol"),
       file_path: z15.string().max(1024).optional().describe("Filter timeline to decisions about this file"),
@@ -120784,7 +121197,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_decision_stats",
-    "Overview of the decision knowledge graph: total decisions, active/invalidated counts, breakdown by type and source. Shows how much institutional knowledge is captured.",
+    "Overview of the decision knowledge graph: total decisions, active/invalidated counts, breakdown by type and source. Shows how much institutional knowledge is captured. Read-only. Returns JSON: { total, active, invalidated, by_type, by_source, sessions_mined }.",
     {},
     async () => {
       const stats = decisionStore.getStats(projectRoot);
@@ -120796,7 +121209,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "index_sessions",
-    'Index conversation content from Claude Code / Claw Code sessions for cross-session search. Stores chunked messages in FTS5 \u2014 enables "what did we discuss about X?" queries across all past sessions. Skips already-indexed sessions unless force=true.',
+    'Index conversation content from Claude Code / Claw Code sessions for cross-session search. Stores chunked messages in FTS5 \u2014 enables "what did we discuss about X?" queries across all past sessions. Skips already-indexed sessions unless force=true. Mutates the session index; idempotent. Use before search_sessions. Returns JSON: { indexed, sessions_processed, chunks_stored }.',
     {
       project_root: z15.string().max(1024).optional().describe("Only index sessions for this project path (default: current project)"),
       force: z15.boolean().optional().describe("Re-index already processed sessions (default: false)")
@@ -120811,7 +121224,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "search_sessions",
-    'Search across all past session conversations. Finds what was discussed, decided, or debugged in previous sessions. Full-text search with porter stemming \u2014 e.g., "why did we switch to GraphQL", "auth middleware bug", "database migration approach".',
+    'Search across all past session conversations. Finds what was discussed, decided, or debugged in previous sessions. Full-text search with porter stemming \u2014 e.g., "why did we switch to GraphQL", "auth middleware bug", "database migration approach". Requires index_sessions to be run first. Read-only. Returns JSON: { results: [{ session_id, text, score }], total_results }.',
     {
       query: z15.string().min(1).max(500).describe("Search query (FTS5 with porter stemming)"),
       limit: z15.number().int().min(1).max(50).optional().describe("Max results (default: 20)")
@@ -120830,7 +121243,7 @@ function registerMemoryTools(server, ctx) {
   );
   server.tool(
     "get_wake_up",
-    "Compact orientation context (~300 tokens) for session start. Returns: project identity, active architectural decisions (linked to code symbols/files), and memory stats. Auto-mines sessions on first call if no decisions exist yet. Like MemPalace wake-up but code-aware \u2014 decisions are tied to the dependency graph.",
+    "Compact orientation context (~300 tokens) for session start. Returns: project identity, active architectural decisions (linked to code symbols/files), and memory stats. Auto-mines sessions on first call if no decisions exist yet. Like MemPalace wake-up but code-aware \u2014 decisions are tied to the dependency graph. Use at session start for context recovery. For cross-session file/tool history use get_session_resume instead. Returns JSON: { project, decisions, stats }.",
     {
       max_decisions: z15.number().int().min(1).max(30).optional().describe("Max recent decisions to include (default: 10)"),
       auto_mine: z15.boolean().optional().describe("Auto-mine sessions if decision store is empty (default: true)")
@@ -121823,7 +122236,7 @@ var DecisionStore = class {
 };
 
 // src/server/server.ts
-var PKG_VERSION = true ? "1.21.2" : "0.0.0-dev";
+var PKG_VERSION2 = true ? "1.22.0" : "0.0.0-dev";
 function j2(value) {
   return JSON.stringify(value, (_key, val) => val === null || val === void 0 ? void 0 : val);
 }
@@ -121939,7 +122352,7 @@ function createServer2(store, registry, config, rootPath, progress) {
   const detectedFrameworks = [...frameworkNames].join(", ") || "none";
   const instructionsVerbosity = config.tools?.instructions_verbosity ?? "full";
   const server = new McpServer(
-    { name: "trace-mcp", version: PKG_VERSION },
+    { name: "trace-mcp", version: PKG_VERSION2 },
     { instructions: buildInstructions(detectedFrameworks, instructionsVerbosity) }
   );
   const savings = new SavingsTracker(projectRoot);
@@ -122168,7 +122581,7 @@ init_pipeline();
 init_logger();
 init_traceignore();
 import * as parcelWatcher from "@parcel/watcher";
-import path115 from "path";
+import path116 from "path";
 var DEFAULT_DEBOUNCE_MS = 300;
 var FileWatcher = class {
   constructor(_setTimeout = setTimeout, _clearTimeout = clearTimeout) {
@@ -122182,17 +122595,17 @@ var FileWatcher = class {
   pendingPaths = /* @__PURE__ */ new Set();
   async start(rootPath, config, onChanges, debounceMs = DEFAULT_DEBOUNCE_MS, onDeletes) {
     const traceignore = new TraceignoreMatcher(rootPath, config.ignore ?? {});
-    const ignoreDirs = [...traceignore.getSkipDirs()].map((d) => path115.join(rootPath, d));
+    const ignoreDirs = [...traceignore.getSkipDirs()].map((d) => path116.join(rootPath, d));
     this.subscription = await parcelWatcher.subscribe(
       rootPath,
-      async (err48, events) => {
-        if (err48) {
-          logger.error({ error: err48 }, "Watcher error");
+      async (err49, events) => {
+        if (err49) {
+          logger.error({ error: err49 }, "Watcher error");
           return;
         }
         const notIgnored = (p5) => {
           if (ignoreDirs.some((d) => p5.startsWith(d))) return false;
-          const rel = path115.relative(rootPath, p5);
+          const rel = path116.relative(rootPath, p5);
           return !traceignore.isIgnored(rel);
         };
         const changed = events.filter((e) => e.type === "create" || e.type === "update").map((e) => e.path).filter(notIgnored);
@@ -122407,12 +122820,12 @@ import http from "http";
 // src/cli/init.ts
 import { Command as Command3 } from "commander";
 import fs112 from "fs";
-import path124 from "path";
+import path125 from "path";
 import * as p from "@clack/prompts";
 
 // src/init/mcp-client.ts
 import fs104 from "fs";
-import path116 from "path";
+import path117 from "path";
 import os10 from "os";
 var HOME3 = os10.homedir();
 var GUI_CLIENTS = /* @__PURE__ */ new Set([
@@ -122426,17 +122839,17 @@ var GUI_CLIENTS = /* @__PURE__ */ new Set([
 ]);
 function resolveGuiCommand() {
   const SYSTEM_PATH = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin";
-  const nodeBinDir = path116.dirname(process.execPath);
+  const nodeBinDir = path117.dirname(process.execPath);
   const scriptPath = process.argv[1];
-  if (scriptPath && path116.isAbsolute(scriptPath) && fs104.existsSync(scriptPath)) {
-    const scriptBinDir = path116.dirname(scriptPath);
+  if (scriptPath && path117.isAbsolute(scriptPath) && fs104.existsSync(scriptPath)) {
+    const scriptBinDir = path117.dirname(scriptPath);
     const dirs = /* @__PURE__ */ new Set([scriptBinDir, nodeBinDir]);
     return {
       command: scriptPath,
       env: { PATH: [...dirs].join(":") + ":" + SYSTEM_PATH }
     };
   }
-  const candidate = path116.join(nodeBinDir, "trace-mcp");
+  const candidate = path117.join(nodeBinDir, "trace-mcp");
   if (fs104.existsSync(candidate)) {
     return {
       command: candidate,
@@ -122484,8 +122897,8 @@ function configureMcpClients(clientNames, projectRoot, opts) {
         const resolved = resolveGuiCommand();
         const action = writeCodexTomlEntry(configPath2, { ...resolved, args: ["serve"], cwd: projectRoot });
         results.push({ target: configPath2, action, detail: `${name} (${opts.scope})` });
-      } catch (err48) {
-        results.push({ target: configPath2, action: "skipped", detail: `Error: ${err48.message}` });
+      } catch (err49) {
+        results.push({ target: configPath2, action: "skipped", detail: `Error: ${err49.message}` });
       }
       continue;
     }
@@ -122516,14 +122929,14 @@ function configureMcpClients(clientNames, projectRoot, opts) {
     try {
       const action = writeJsonEntry(configPath, entry);
       results.push({ target: configPath, action, detail: `${name} (${opts.scope})` });
-    } catch (err48) {
-      results.push({ target: configPath, action: "skipped", detail: `Error: ${err48.message}` });
+    } catch (err49) {
+      results.push({ target: configPath, action: "skipped", detail: `Error: ${err49.message}` });
     }
   }
   return results;
 }
 function writeJsonEntry(configPath, entry) {
-  const dir = path116.dirname(configPath);
+  const dir = path117.dirname(configPath);
   if (!fs104.existsSync(dir)) fs104.mkdirSync(dir, { recursive: true });
   let config = {};
   let isNew = true;
@@ -122542,7 +122955,7 @@ function writeJsonEntry(configPath, entry) {
   return isNew ? "created" : "updated";
 }
 function writeCodexTomlEntry(configPath, entry) {
-  const dir = path116.dirname(configPath);
+  const dir = path117.dirname(configPath);
   if (!fs104.existsSync(dir)) fs104.mkdirSync(dir, { recursive: true });
   const argsToml = entry.args.map((a) => `"${a}"`).join(", ");
   const section = [
@@ -122574,21 +122987,21 @@ function writeCodexTomlEntry(configPath, entry) {
 function getConfigPath(name, projectRoot, scope8) {
   switch (name) {
     case "claude-code":
-      return scope8 === "global" ? path116.join(HOME3, ".claude.json") : path116.join(projectRoot, ".mcp.json");
+      return scope8 === "global" ? path117.join(HOME3, ".claude.json") : path117.join(projectRoot, ".mcp.json");
     case "claw-code":
-      return scope8 === "global" ? path116.join(HOME3, ".claw", "settings.json") : path116.join(projectRoot, ".claw.json");
+      return scope8 === "global" ? path117.join(HOME3, ".claw", "settings.json") : path117.join(projectRoot, ".claw.json");
     case "claude-desktop":
-      return process.platform === "darwin" ? path116.join(HOME3, "Library", "Application Support", "Claude", "claude_desktop_config.json") : path116.join(process.env.APPDATA ?? path116.join(HOME3, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+      return process.platform === "darwin" ? path117.join(HOME3, "Library", "Application Support", "Claude", "claude_desktop_config.json") : path117.join(process.env.APPDATA ?? path117.join(HOME3, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
     case "cursor":
-      return scope8 === "global" ? path116.join(HOME3, ".cursor", "mcp.json") : path116.join(projectRoot, ".cursor", "mcp.json");
+      return scope8 === "global" ? path117.join(HOME3, ".cursor", "mcp.json") : path117.join(projectRoot, ".cursor", "mcp.json");
     case "windsurf":
-      return scope8 === "global" ? path116.join(HOME3, ".windsurf", "mcp.json") : path116.join(projectRoot, ".windsurf", "mcp.json");
+      return scope8 === "global" ? path117.join(HOME3, ".windsurf", "mcp.json") : path117.join(projectRoot, ".windsurf", "mcp.json");
     case "continue":
-      return scope8 === "global" ? path116.join(HOME3, ".continue", "mcpServers", "mcp.json") : path116.join(projectRoot, ".continue", "mcpServers", "mcp.json");
+      return scope8 === "global" ? path117.join(HOME3, ".continue", "mcpServers", "mcp.json") : path117.join(projectRoot, ".continue", "mcpServers", "mcp.json");
     case "junie":
-      return scope8 === "global" ? path116.join(HOME3, ".junie", "mcp", "mcp.json") : path116.join(projectRoot, ".junie", "mcp", "mcp.json");
+      return scope8 === "global" ? path117.join(HOME3, ".junie", "mcp", "mcp.json") : path117.join(projectRoot, ".junie", "mcp", "mcp.json");
     case "codex":
-      return scope8 === "global" ? path116.join(HOME3, ".codex", "config.toml") : path116.join(projectRoot, ".codex", "config.toml");
+      return scope8 === "global" ? path117.join(HOME3, ".codex", "config.toml") : path117.join(projectRoot, ".codex", "config.toml");
     case "jetbrains-ai":
       return null;
     // Configured through IDE Settings UI, not a file we can write
@@ -122603,7 +123016,7 @@ init_hooks();
 
 // src/init/ide-rules.ts
 import fs105 from "fs";
-import path117 from "path";
+import path118 from "path";
 var START_MARKER2 = "<!-- trace-mcp:start -->";
 var END_MARKER2 = "<!-- trace-mcp:end -->";
 var TOOL_ROUTING_POLICY = `IMPORTANT: For ANY code exploration task, ALWAYS use trace-mcp tools first. NEVER use built-in search/grep/file listing for navigating source code.
@@ -122639,9 +123052,9 @@ alwaysApply: true
 ${TOOL_ROUTING_POLICY}
 `;
 function installCursorRules(projectRoot, opts) {
-  const base = opts.global ? path117.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".cursor") : path117.join(projectRoot, ".cursor");
-  const rulesDir = path117.join(base, "rules");
-  const filePath = path117.join(rulesDir, "trace-mcp.mdc");
+  const base = opts.global ? path118.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".cursor") : path118.join(projectRoot, ".cursor");
+  const rulesDir = path118.join(base, "rules");
+  const filePath = path118.join(rulesDir, "trace-mcp.mdc");
   if (opts.dryRun) {
     if (fs105.existsSync(filePath)) {
       const content = fs105.readFileSync(filePath, "utf-8");
@@ -122670,7 +123083,7 @@ var WINDSURF_BLOCK = `${START_MARKER2}
 ${TOOL_ROUTING_POLICY}
 ${END_MARKER2}`;
 function installWindsurfRules(projectRoot, opts) {
-  const filePath = opts.global ? path117.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".windsurfrules") : path117.join(projectRoot, ".windsurfrules");
+  const filePath = opts.global ? path118.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".windsurfrules") : path118.join(projectRoot, ".windsurfrules");
   if (opts.dryRun) {
     if (!fs105.existsSync(filePath)) {
       return { target: filePath, action: "skipped", detail: "Would create .windsurfrules" };
@@ -122705,18 +123118,18 @@ function escapeRegex7(s) {
 
 // src/init/tweakcc.ts
 import fs106 from "fs";
-import path118 from "path";
+import path119 from "path";
 import os11 from "os";
 import { execSync as execSync5 } from "child_process";
 function getTweakccConfigDir() {
   const envDir = process.env.TWEAKCC_CONFIG_DIR?.trim();
   if (envDir) return envDir;
   const candidates = [
-    path118.join(os11.homedir(), ".tweakcc"),
-    path118.join(os11.homedir(), ".claude", "tweakcc")
+    path119.join(os11.homedir(), ".tweakcc"),
+    path119.join(os11.homedir(), ".claude", "tweakcc")
   ];
   const xdg = process.env.XDG_CONFIG_HOME;
-  if (xdg) candidates.push(path118.join(xdg, "tweakcc"));
+  if (xdg) candidates.push(path119.join(xdg, "tweakcc"));
   for (const dir of candidates) {
     if (fs106.existsSync(dir)) return dir;
   }
@@ -122725,7 +123138,7 @@ function getTweakccConfigDir() {
 function getTweakccSystemPromptsDir() {
   const configDir = getTweakccConfigDir();
   if (!configDir) return null;
-  return path118.join(configDir, "system-prompts");
+  return path119.join(configDir, "system-prompts");
 }
 function isTweakccInstalled() {
   try {
@@ -122741,7 +123154,7 @@ function detectTweakccPrompts() {
     return { installed: isTweakccInstalled(), promptsDir, hasOurPrompts: false };
   }
   const hasOurs = PROMPT_FILES.some(
-    (pf) => fs106.existsSync(path118.join(promptsDir, pf.filename))
+    (pf) => fs106.existsSync(path119.join(promptsDir, pf.filename))
   );
   return { installed: true, promptsDir, hasOurPrompts: hasOurs };
 }
@@ -122874,7 +123287,7 @@ function installTweakccPrompts(opts) {
   if (opts.dryRun) {
     for (const pf of PROMPT_FILES) {
       results.push({
-        target: path118.join(promptsDir, pf.filename),
+        target: path119.join(promptsDir, pf.filename),
         action: "created",
         detail: `Would write ${pf.id}`
       });
@@ -122889,7 +123302,7 @@ function installTweakccPrompts(opts) {
   fs106.mkdirSync(promptsDir, { recursive: true });
   let written = 0;
   for (const pf of PROMPT_FILES) {
-    const filePath = path118.join(promptsDir, pf.filename);
+    const filePath = path119.join(promptsDir, pf.filename);
     const content = generateMarkdown(pf);
     const existed = fs106.existsSync(filePath);
     fs106.writeFileSync(filePath, content, "utf-8");
@@ -122926,7 +123339,7 @@ init_detector();
 
 // src/init/conflict-detector.ts
 import fs107 from "fs";
-import path119 from "path";
+import path120 from "path";
 import os12 from "os";
 var HOME4 = os12.homedir();
 var COMPETING_MCP_SERVERS = {
@@ -123020,9 +123433,9 @@ var COMPETING_PROJECT_FILES = [
   { file: ".greptile.yaml", competitor: "greptile" }
 ];
 var COMPETING_GLOBAL_DIRS = [
-  { dir: path119.join(HOME4, ".code-index"), competitor: "jcodemunch-mcp" },
-  { dir: path119.join(HOME4, ".repomix"), competitor: "repomix" },
-  { dir: path119.join(HOME4, ".aider.tags.cache.v3"), competitor: "aider" }
+  { dir: path120.join(HOME4, ".code-index"), competitor: "jcodemunch-mcp" },
+  { dir: path120.join(HOME4, ".repomix"), competitor: "repomix" },
+  { dir: path120.join(HOME4, ".aider.tags.cache.v3"), competitor: "aider" }
 ];
 function detectConflicts(projectRoot) {
   const conflicts = [];
@@ -123081,55 +123494,55 @@ function getMcpConfigPaths(projectRoot) {
   const paths = [];
   const platform = os12.platform();
   if (projectRoot) {
-    paths.push({ clientName: "claude-code", configPath: path119.join(projectRoot, ".mcp.json") });
+    paths.push({ clientName: "claude-code", configPath: path120.join(projectRoot, ".mcp.json") });
   }
-  paths.push({ clientName: "claude-code", configPath: path119.join(HOME4, ".claude.json") });
-  paths.push({ clientName: "claude-code", configPath: path119.join(HOME4, ".claude", "settings.json") });
+  paths.push({ clientName: "claude-code", configPath: path120.join(HOME4, ".claude.json") });
+  paths.push({ clientName: "claude-code", configPath: path120.join(HOME4, ".claude", "settings.json") });
   if (projectRoot) {
-    paths.push({ clientName: "claw-code", configPath: path119.join(projectRoot, ".claw.json") });
+    paths.push({ clientName: "claw-code", configPath: path120.join(projectRoot, ".claw.json") });
   }
-  paths.push({ clientName: "claw-code", configPath: path119.join(HOME4, ".claw", "settings.json") });
+  paths.push({ clientName: "claw-code", configPath: path120.join(HOME4, ".claw", "settings.json") });
   if (platform === "darwin") {
-    paths.push({ clientName: "claude-desktop", configPath: path119.join(HOME4, "Library", "Application Support", "Claude", "claude_desktop_config.json") });
+    paths.push({ clientName: "claude-desktop", configPath: path120.join(HOME4, "Library", "Application Support", "Claude", "claude_desktop_config.json") });
   } else if (platform === "win32") {
-    const appData = process.env.APPDATA ?? path119.join(HOME4, "AppData", "Roaming");
-    paths.push({ clientName: "claude-desktop", configPath: path119.join(appData, "Claude", "claude_desktop_config.json") });
+    const appData = process.env.APPDATA ?? path120.join(HOME4, "AppData", "Roaming");
+    paths.push({ clientName: "claude-desktop", configPath: path120.join(appData, "Claude", "claude_desktop_config.json") });
   }
-  paths.push({ clientName: "cursor", configPath: path119.join(HOME4, ".cursor", "mcp.json") });
+  paths.push({ clientName: "cursor", configPath: path120.join(HOME4, ".cursor", "mcp.json") });
   if (projectRoot) {
-    paths.push({ clientName: "cursor", configPath: path119.join(projectRoot, ".cursor", "mcp.json") });
+    paths.push({ clientName: "cursor", configPath: path120.join(projectRoot, ".cursor", "mcp.json") });
   }
-  paths.push({ clientName: "windsurf", configPath: path119.join(HOME4, ".windsurf", "mcp.json") });
+  paths.push({ clientName: "windsurf", configPath: path120.join(HOME4, ".windsurf", "mcp.json") });
   if (projectRoot) {
-    paths.push({ clientName: "windsurf", configPath: path119.join(projectRoot, ".windsurf", "mcp.json") });
+    paths.push({ clientName: "windsurf", configPath: path120.join(projectRoot, ".windsurf", "mcp.json") });
   }
-  paths.push({ clientName: "continue", configPath: path119.join(HOME4, ".continue", "mcpServers", "mcp.json") });
-  paths.push({ clientName: "junie", configPath: path119.join(HOME4, ".junie", "mcp", "mcp.json") });
+  paths.push({ clientName: "continue", configPath: path120.join(HOME4, ".continue", "mcpServers", "mcp.json") });
+  paths.push({ clientName: "junie", configPath: path120.join(HOME4, ".junie", "mcp", "mcp.json") });
   if (projectRoot) {
-    paths.push({ clientName: "junie", configPath: path119.join(projectRoot, ".junie", "mcp", "mcp.json") });
+    paths.push({ clientName: "junie", configPath: path120.join(projectRoot, ".junie", "mcp", "mcp.json") });
   }
   return paths;
 }
 function scanHooksInSettings() {
   const conflicts = [];
   const settingsFiles = [
-    path119.join(HOME4, ".claude", "settings.json"),
-    path119.join(HOME4, ".claude", "settings.local.json"),
-    path119.join(HOME4, ".claw", "settings.json"),
-    path119.join(HOME4, ".claw", "settings.local.json")
+    path120.join(HOME4, ".claude", "settings.json"),
+    path120.join(HOME4, ".claude", "settings.local.json"),
+    path120.join(HOME4, ".claw", "settings.json"),
+    path120.join(HOME4, ".claw", "settings.local.json")
   ];
-  const projectsDir = path119.join(HOME4, ".claude", "projects");
+  const projectsDir = path120.join(HOME4, ".claude", "projects");
   if (fs107.existsSync(projectsDir)) {
     try {
       for (const entry of fs107.readdirSync(projectsDir)) {
-        const projDir = path119.join(projectsDir, entry);
+        const projDir = path120.join(projectsDir, entry);
         try {
           if (!fs107.statSync(projDir).isDirectory()) continue;
         } catch {
           continue;
         }
-        settingsFiles.push(path119.join(projDir, "settings.json"));
-        settingsFiles.push(path119.join(projDir, "settings.local.json"));
+        settingsFiles.push(path120.join(projDir, "settings.json"));
+        settingsFiles.push(path120.join(projDir, "settings.local.json"));
       }
     } catch {
     }
@@ -123176,8 +123589,8 @@ function scanHooksInSettings() {
 function scanHookScriptFiles() {
   const conflicts = [];
   const hooksDirs = [
-    path119.join(HOME4, ".claude", "hooks"),
-    path119.join(HOME4, ".claw", "hooks")
+    path120.join(HOME4, ".claude", "hooks"),
+    path120.join(HOME4, ".claw", "hooks")
   ];
   for (const hooksDir of hooksDirs) {
     if (!fs107.existsSync(hooksDir)) continue;
@@ -123191,7 +123604,7 @@ function scanHookScriptFiles() {
       if (file.startsWith("trace-mcp")) continue;
       for (const { pattern, competitor } of COMPETING_HOOK_PATTERNS) {
         if (pattern.test(file)) {
-          const filePath = path119.join(hooksDir, file);
+          const filePath = path120.join(hooksDir, file);
           conflicts.push({
             id: `hook_script:${file}:${competitor}`,
             category: "hook_script",
@@ -123212,23 +123625,23 @@ function scanHookScriptFiles() {
 function scanClaudeMdFiles(projectRoot) {
   const conflicts = [];
   const files = [
-    path119.join(HOME4, ".claude", "CLAUDE.md"),
-    path119.join(HOME4, ".claude", "AGENTS.md")
+    path120.join(HOME4, ".claude", "CLAUDE.md"),
+    path120.join(HOME4, ".claude", "AGENTS.md")
   ];
-  const projectsDir = path119.join(HOME4, ".claude", "projects");
+  const projectsDir = path120.join(HOME4, ".claude", "projects");
   if (fs107.existsSync(projectsDir)) {
     try {
       for (const entry of fs107.readdirSync(projectsDir)) {
-        const projDir = path119.join(projectsDir, entry);
+        const projDir = path120.join(projectsDir, entry);
         if (!fs107.statSync(projDir).isDirectory()) continue;
-        files.push(path119.join(projDir, "CLAUDE.md"));
-        files.push(path119.join(projDir, "AGENTS.md"));
-        const memDir = path119.join(projDir, "memory");
+        files.push(path120.join(projDir, "CLAUDE.md"));
+        files.push(path120.join(projDir, "AGENTS.md"));
+        const memDir = path120.join(projDir, "memory");
         if (fs107.existsSync(memDir)) {
           try {
             for (const memFile of fs107.readdirSync(memDir)) {
               if (memFile.endsWith(".md") && memFile !== "MEMORY.md") {
-                files.push(path119.join(memDir, memFile));
+                files.push(path120.join(memDir, memFile));
               }
             }
           } catch {
@@ -123240,8 +123653,8 @@ function scanClaudeMdFiles(projectRoot) {
   }
   if (projectRoot) {
     files.push(
-      path119.join(projectRoot, "CLAUDE.md"),
-      path119.join(projectRoot, "AGENTS.md")
+      path120.join(projectRoot, "CLAUDE.md"),
+      path120.join(projectRoot, "AGENTS.md")
     );
   }
   for (const filePath of files) {
@@ -123296,35 +123709,35 @@ var COMPETITOR_ALIASES = {
 function scanIdeRuleFiles(projectRoot) {
   const conflicts = [];
   const ruleFiles = [];
-  ruleFiles.push({ path: path119.join(HOME4, ".cursorrules"), type: ".cursorrules (global)" });
-  ruleFiles.push({ path: path119.join(HOME4, ".windsurfrules"), type: ".windsurfrules (global)" });
+  ruleFiles.push({ path: path120.join(HOME4, ".cursorrules"), type: ".cursorrules (global)" });
+  ruleFiles.push({ path: path120.join(HOME4, ".windsurfrules"), type: ".windsurfrules (global)" });
   if (projectRoot) {
-    ruleFiles.push({ path: path119.join(projectRoot, ".cursorrules"), type: ".cursorrules" });
-    ruleFiles.push({ path: path119.join(projectRoot, ".windsurfrules"), type: ".windsurfrules" });
-    ruleFiles.push({ path: path119.join(projectRoot, ".clinerules"), type: ".clinerules" });
-    ruleFiles.push({ path: path119.join(projectRoot, ".continuerules"), type: ".continuerules" });
-    ruleFiles.push({ path: path119.join(projectRoot, ".github", "copilot-instructions.md"), type: "copilot-instructions.md" });
-    const clineRulesDir = path119.join(projectRoot, ".clinerules");
+    ruleFiles.push({ path: path120.join(projectRoot, ".cursorrules"), type: ".cursorrules" });
+    ruleFiles.push({ path: path120.join(projectRoot, ".windsurfrules"), type: ".windsurfrules" });
+    ruleFiles.push({ path: path120.join(projectRoot, ".clinerules"), type: ".clinerules" });
+    ruleFiles.push({ path: path120.join(projectRoot, ".continuerules"), type: ".continuerules" });
+    ruleFiles.push({ path: path120.join(projectRoot, ".github", "copilot-instructions.md"), type: "copilot-instructions.md" });
+    const clineRulesDir = path120.join(projectRoot, ".clinerules");
     if (fs107.existsSync(clineRulesDir)) {
       try {
         const stat = fs107.statSync(clineRulesDir);
         if (stat.isDirectory()) {
           for (const file of fs107.readdirSync(clineRulesDir)) {
-            ruleFiles.push({ path: path119.join(clineRulesDir, file), type: `.clinerules/${file}` });
+            ruleFiles.push({ path: path120.join(clineRulesDir, file), type: `.clinerules/${file}` });
           }
         }
       } catch {
       }
     }
   }
-  const cursorRulesDirs = [path119.join(HOME4, ".cursor", "rules")];
-  if (projectRoot) cursorRulesDirs.push(path119.join(projectRoot, ".cursor", "rules"));
+  const cursorRulesDirs = [path120.join(HOME4, ".cursor", "rules")];
+  if (projectRoot) cursorRulesDirs.push(path120.join(projectRoot, ".cursor", "rules"));
   for (const rulesDir of cursorRulesDirs) {
     if (!fs107.existsSync(rulesDir)) continue;
     try {
       for (const file of fs107.readdirSync(rulesDir)) {
         if (!file.endsWith(".mdc") || file === "trace-mcp.mdc") continue;
-        ruleFiles.push({ path: path119.join(rulesDir, file), type: `.cursor/rules/${file}` });
+        ruleFiles.push({ path: path120.join(rulesDir, file), type: `.cursor/rules/${file}` });
       }
     } catch {
     }
@@ -123358,7 +123771,7 @@ function scanIdeRuleFiles(projectRoot) {
 function scanProjectConfigFiles(projectRoot) {
   const conflicts = [];
   for (const { file, competitor } of COMPETING_PROJECT_FILES) {
-    const filePath = path119.join(projectRoot, file);
+    const filePath = path120.join(projectRoot, file);
     if (!fs107.existsSync(filePath)) continue;
     conflicts.push({
       id: `config:${competitor}:${file}`,
@@ -123382,7 +123795,7 @@ function scanProjectConfigDirs(projectRoot) {
     { dir: ".continue", competitor: "continue.dev" }
   ];
   for (const { dir, competitor } of dirs) {
-    const fullPath = path119.join(projectRoot, dir);
+    const fullPath = path120.join(projectRoot, dir);
     if (!fs107.existsSync(fullPath)) continue;
     let stat;
     try {
@@ -123408,18 +123821,18 @@ function scanProjectConfigDirs(projectRoot) {
 function scanContinueConfigs(projectRoot) {
   const conflicts = [];
   const configPaths = [
-    path119.join(HOME4, ".continue", "config.yaml"),
-    path119.join(HOME4, ".continue", "config.json")
+    path120.join(HOME4, ".continue", "config.yaml"),
+    path120.join(HOME4, ".continue", "config.json")
   ];
   if (projectRoot) {
     configPaths.push(
-      path119.join(projectRoot, ".continue", "config.yaml"),
-      path119.join(projectRoot, ".continue", "config.json")
+      path120.join(projectRoot, ".continue", "config.yaml"),
+      path120.join(projectRoot, ".continue", "config.json")
     );
   }
-  const mcpServersDirs = [path119.join(HOME4, ".continue", "mcpServers")];
+  const mcpServersDirs = [path120.join(HOME4, ".continue", "mcpServers")];
   if (projectRoot) {
-    mcpServersDirs.push(path119.join(projectRoot, ".continue", "mcpServers"));
+    mcpServersDirs.push(path120.join(projectRoot, ".continue", "mcpServers"));
   }
   for (const mcpDir of mcpServersDirs) {
     if (!fs107.existsSync(mcpDir)) continue;
@@ -123431,7 +123844,7 @@ function scanContinueConfigs(projectRoot) {
     }
     for (const file of files) {
       if (!file.endsWith(".json")) continue;
-      const filePath = path119.join(mcpDir, file);
+      const filePath = path120.join(mcpDir, file);
       let content;
       try {
         content = fs107.readFileSync(filePath, "utf-8");
@@ -123460,11 +123873,11 @@ function scanContinueConfigs(projectRoot) {
 }
 function scanGitHooks(projectRoot) {
   const conflicts = [];
-  const hooksDir = path119.join(projectRoot, ".git", "hooks");
+  const hooksDir = path120.join(projectRoot, ".git", "hooks");
   if (!fs107.existsSync(hooksDir)) return conflicts;
   const hookFiles = ["pre-commit", "post-commit", "prepare-commit-msg"];
   for (const hookFile of hookFiles) {
-    const hookPath = path119.join(hooksDir, hookFile);
+    const hookPath = path120.join(hooksDir, hookFile);
     if (!fs107.existsSync(hookPath)) continue;
     let content;
     try {
@@ -123521,7 +123934,7 @@ function truncate(s, maxLen) {
 
 // src/init/conflict-resolver.ts
 import fs108 from "fs";
-import path120 from "path";
+import path121 from "path";
 function fixConflict(conflict, opts = {}) {
   if (!conflict.fixable) {
     return {
@@ -123568,8 +123981,8 @@ function fixMcpServer(conflict, opts) {
     }
     fs108.writeFileSync(configPath, result);
     return { conflictId: conflict.id, action: "disabled", detail: `Commented out "${serverName}" in ${shortPath2(configPath)}`, target: configPath };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update config: ${err48.message}`, target: configPath };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update config: ${err49.message}`, target: configPath };
   }
 }
 function commentOutJsonKey(raw, key) {
@@ -123652,8 +124065,8 @@ function fixHookInSettings(conflict, opts) {
     }
     fs108.writeFileSync(settingsPath2, JSON.stringify(settings, null, 2) + "\n");
     return { conflictId: conflict.id, action: "removed", detail: `Removed ${competitor} hooks from ${shortPath2(settingsPath2)}`, target: settingsPath2 };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update settings: ${err48.message}`, target: settingsPath2 };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update settings: ${err49.message}`, target: settingsPath2 };
   }
 }
 function fixHookScript(conflict, opts) {
@@ -123667,8 +124080,8 @@ function fixHookScript(conflict, opts) {
   try {
     fs108.unlinkSync(scriptPath);
     return { conflictId: conflict.id, action: "removed", detail: `Deleted ${shortPath2(scriptPath)}`, target: scriptPath };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to delete: ${err48.message}`, target: scriptPath };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to delete: ${err49.message}`, target: scriptPath };
   }
 }
 function fixClaudeMdBlock(conflict, opts) {
@@ -123699,8 +124112,8 @@ function fixClaudeMdBlock(conflict, opts) {
     }
     fs108.writeFileSync(filePath, updated);
     return { conflictId: conflict.id, action: "cleaned", detail: `Removed ${conflict.competitor} content from ${shortPath2(filePath)}`, target: filePath };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update: ${err48.message}`, target: filePath };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to update: ${err49.message}`, target: filePath };
   }
 }
 var COMPETITOR_HEADING_NAMES = {
@@ -123747,12 +124160,12 @@ function isEntirelyAboutCompetitor(content, competitor) {
   return false;
 }
 function removeFromMemoryIndex(deletedFilePath) {
-  const memoryDir = path120.dirname(deletedFilePath);
-  const indexPath = path120.join(memoryDir, "MEMORY.md");
+  const memoryDir = path121.dirname(deletedFilePath);
+  const indexPath = path121.join(memoryDir, "MEMORY.md");
   if (!fs108.existsSync(indexPath)) return;
   try {
     const content = fs108.readFileSync(indexPath, "utf-8");
-    const fileName = path120.basename(deletedFilePath);
+    const fileName = path121.basename(deletedFilePath);
     const escaped = fileName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const updated = content.split("\n").filter((line) => !new RegExp(`\\(${escaped}\\)`).test(line)).join("\n");
     if (updated !== content) {
@@ -123777,8 +124190,8 @@ function fixConfigFile(conflict, opts) {
       fs108.unlinkSync(filePath);
     }
     return { conflictId: conflict.id, action: "removed", detail: `Deleted ${shortPath2(filePath)}`, target: filePath };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to delete: ${err48.message}`, target: filePath };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to delete: ${err49.message}`, target: filePath };
   }
 }
 function fixGlobalArtifact(conflict, opts) {
@@ -123792,8 +124205,8 @@ function fixGlobalArtifact(conflict, opts) {
   try {
     fs108.rmSync(dirPath, { recursive: true, force: true });
     return { conflictId: conflict.id, action: "removed", detail: `Removed ${shortPath2(dirPath)}`, target: dirPath };
-  } catch (err48) {
-    return { conflictId: conflict.id, action: "skipped", detail: `Failed to remove: ${err48.message}`, target: dirPath };
+  } catch (err49) {
+    return { conflictId: conflict.id, action: "skipped", detail: `Failed to remove: ${err49.message}`, target: dirPath };
   }
 }
 function shortPath2(p5) {
@@ -124045,13 +124458,13 @@ init_schema();
 // src/project-setup.ts
 init_detector();
 import fs109 from "fs";
-import path121 from "path";
+import path122 from "path";
 init_config();
 init_registry2();
 init_global();
 init_schema();
 function setupProject(projectRoot, opts) {
-  const absRoot = path121.resolve(projectRoot);
+  const absRoot = path122.resolve(projectRoot);
   const existing = getProject(absRoot);
   if (existing && !opts?.force) {
     return { entry: existing, detection: { languages: [], frameworks: [], packageManagers: [], rootMarkers: [] }, dbPath: existing.dbPath, migrated: false, isNew: false };
@@ -124067,7 +124480,7 @@ function setupProject(projectRoot, opts) {
   const dbPath = getDbPath(absRoot);
   let migrated = false;
   if (opts?.migrateOldDb) {
-    const oldDbPath = path121.join(absRoot, ".trace-mcp", "index.db");
+    const oldDbPath = path122.join(absRoot, ".trace-mcp", "index.db");
     if (fs109.existsSync(oldDbPath) && !fs109.existsSync(dbPath)) {
       fs109.copyFileSync(oldDbPath, dbPath);
       migrated = true;
@@ -124088,7 +124501,7 @@ init_pipeline();
 
 // src/cli/install-app.ts
 import fs110 from "fs";
-import path122 from "path";
+import path123 from "path";
 import os13 from "os";
 import https2 from "https";
 import { execSync as execSync6 } from "child_process";
@@ -124097,7 +124510,7 @@ var GITHUB_REPO = "nikolai-vysotskyi/trace-mcp";
 var isMac = process.platform === "darwin";
 var isWin = process.platform === "win32";
 var APP_NAME = isMac ? "trace-mcp.app" : "trace-mcp";
-var INSTALL_DIR = isMac ? path122.join(os13.homedir(), "Applications") : path122.join(process.env.LOCALAPPDATA ?? path122.join(os13.homedir(), "AppData", "Local"), "Programs", "trace-mcp");
+var INSTALL_DIR = isMac ? path123.join(os13.homedir(), "Applications") : path123.join(process.env.LOCALAPPDATA ?? path123.join(os13.homedir(), "AppData", "Local"), "Programs", "trace-mcp");
 function sleep(ms2) {
   return new Promise((resolve4) => setTimeout(resolve4, ms2));
 }
@@ -124179,10 +124592,10 @@ function downloadFile(url2, dest, timeoutMs = 6e4) {
           file.close();
           resolve4();
         });
-      }).on("error", (err48) => {
+      }).on("error", (err49) => {
         fs110.unlink(dest, () => {
         });
-        reject(err48);
+        reject(err49);
       });
     };
     doGet(url2);
@@ -124206,20 +124619,20 @@ function pinToDock(appPath) {
 }
 function createStartMenuShortcut(exePath) {
   try {
-    const startMenuDir = path122.join(
-      process.env.APPDATA ?? path122.join(os13.homedir(), "AppData", "Roaming"),
+    const startMenuDir = path123.join(
+      process.env.APPDATA ?? path123.join(os13.homedir(), "AppData", "Roaming"),
       "Microsoft",
       "Windows",
       "Start Menu",
       "Programs"
     );
     fs110.mkdirSync(startMenuDir, { recursive: true });
-    const shortcutPath = path122.join(startMenuDir, "trace-mcp.lnk");
+    const shortcutPath = path123.join(startMenuDir, "trace-mcp.lnk");
     const ps2 = `
       $ws = New-Object -ComObject WScript.Shell;
       $sc = $ws.CreateShortcut('${shortcutPath.replace(/'/g, "''")}');
       $sc.TargetPath = '${exePath.replace(/'/g, "''")}';
-      $sc.WorkingDirectory = '${path122.dirname(exePath).replace(/'/g, "''")}';
+      $sc.WorkingDirectory = '${path123.dirname(exePath).replace(/'/g, "''")}';
       $sc.Description = 'trace-mcp';
       $sc.Save();
     `.replace(/\n/g, " ");
@@ -124269,17 +124682,17 @@ async function installGuiApp(opts = {}) {
         error: `No ${process.platform}/${arch} archive found in release ${release.tag} (${release.assets.length} assets available: ${release.assets.map((a) => a.name).join(", ") || "none"}). The build may still be in progress \u2014 try again in a few minutes with: trace-mcp install-app`
       };
     }
-    const tmpDir = fs110.mkdtempSync(path122.join(os13.tmpdir(), "trace-mcp-app-"));
-    const archivePath = path122.join(tmpDir, asset.name);
+    const tmpDir = fs110.mkdtempSync(path123.join(os13.tmpdir(), "trace-mcp-app-"));
+    const archivePath = path123.join(tmpDir, asset.name);
     await downloadFile(asset.url, archivePath);
     fs110.mkdirSync(INSTALL_DIR, { recursive: true });
     if (isMac) {
-      const appPath = path122.join(INSTALL_DIR, APP_NAME);
+      const appPath = path123.join(INSTALL_DIR, APP_NAME);
       if (fs110.existsSync(appPath)) {
         fs110.rmSync(appPath, { recursive: true, force: true });
       }
       execSync6(`unzip -q -o "${archivePath}" -d "${INSTALL_DIR}"`, { stdio: "pipe" });
-      fs110.writeFileSync(path122.join(INSTALL_DIR, ".trace-mcp-version"), release.tag, "utf-8");
+      fs110.writeFileSync(path123.join(INSTALL_DIR, ".trace-mcp-version"), release.tag, "utf-8");
       fs110.rmSync(tmpDir, { recursive: true, force: true });
       pinToDock(appPath);
       return { installed: true, path: appPath };
@@ -124293,25 +124706,25 @@ async function installGuiApp(opts = {}) {
         { stdio: "pipe", timeout: 12e4 }
       );
     }
-    fs110.writeFileSync(path122.join(INSTALL_DIR, ".trace-mcp-version"), release.tag, "utf-8");
+    fs110.writeFileSync(path123.join(INSTALL_DIR, ".trace-mcp-version"), release.tag, "utf-8");
     fs110.rmSync(tmpDir, { recursive: true, force: true });
-    const exePath = path122.join(INSTALL_DIR, "trace-mcp.exe");
+    const exePath = path123.join(INSTALL_DIR, "trace-mcp.exe");
     if (fs110.existsSync(exePath)) {
       createStartMenuShortcut(exePath);
     }
     return { installed: true, path: fs110.existsSync(exePath) ? exePath : INSTALL_DIR };
-  } catch (err48) {
-    return { installed: false, error: err48.message };
+  } catch (err49) {
+    return { installed: false, error: err49.message };
   }
 }
 function isAppInstalled() {
   if (isMac) {
-    return fs110.existsSync(path122.join(INSTALL_DIR, APP_NAME));
+    return fs110.existsSync(path123.join(INSTALL_DIR, APP_NAME));
   }
-  return fs110.existsSync(path122.join(INSTALL_DIR, "trace-mcp.exe"));
+  return fs110.existsSync(path123.join(INSTALL_DIR, "trace-mcp.exe"));
 }
 function getInstalledAppVersion() {
-  const markerPath = path122.join(INSTALL_DIR, ".trace-mcp-version");
+  const markerPath = path123.join(INSTALL_DIR, ".trace-mcp-version");
   if (!fs110.existsSync(markerPath)) return null;
   return fs110.readFileSync(markerPath, "utf-8").trim().replace(/^v/, "");
 }
@@ -124356,7 +124769,7 @@ var installAppCommand = new Command("install-app").description("Download and ins
 init_global();
 import { Command as Command2 } from "commander";
 import fs111 from "fs";
-import path123 from "path";
+import path124 from "path";
 import { execSync as execSync7, spawn as spawn2 } from "child_process";
 
 // src/daemon/client.ts
@@ -124382,7 +124795,7 @@ var PLIST_LABEL = "com.trace-mcp.server";
 function getTraceMcpBinary() {
   const argv1 = process.argv[1];
   if (argv1 && fs111.existsSync(argv1)) {
-    return path123.resolve(argv1);
+    return path124.resolve(argv1);
   }
   try {
     return execSync7("which trace-mcp", { encoding: "utf-8" }).trim();
@@ -124391,7 +124804,7 @@ function getTraceMcpBinary() {
   }
 }
 function resolveNodePath() {
-  const nodeDir = path123.dirname(process.execPath);
+  const nodeDir = path124.dirname(process.execPath);
   const fallback = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin";
   return `${nodeDir}:${fallback}`;
 }
@@ -124432,7 +124845,7 @@ function generatePlist(binaryPath, port) {
 function installPlist(port) {
   const binaryPath = getTraceMcpBinary();
   const plistContent = generatePlist(binaryPath, port);
-  const plistDir = path123.dirname(LAUNCHD_PLIST_PATH);
+  const plistDir = path124.dirname(LAUNCHD_PLIST_PATH);
   if (!fs111.existsSync(plistDir)) {
     fs111.mkdirSync(plistDir, { recursive: true });
   }
@@ -124712,9 +125125,9 @@ var initCommand = new Command3("init").description("One-time global setup: confi
     spin.start("Setting up trace-mcp");
     try {
       executeSteps(steps, { selectedClients, installHooks, installTweakcc, claudeMdScope, force: opts.force, dryRun: opts.dryRun });
-    } catch (err48) {
+    } catch (err49) {
       spin.stop("Failed");
-      p.log.error(`Setup failed: ${err48.message}`);
+      p.log.error(`Setup failed: ${err49.message}`);
       process.exit(1);
     }
     spin.stop("Done");
@@ -124746,11 +125159,11 @@ var initCommand = new Command3("init").description("One-time global setup: confi
           }
         }
       }
-    } catch (err48) {
+    } catch (err49) {
       if (!nonInteractive) {
-        p.log.error(`Conflict resolution failed: ${err48.message}`);
+        p.log.error(`Conflict resolution failed: ${err49.message}`);
       } else {
-        console.error(`Conflict resolution failed: ${err48.message}`);
+        console.error(`Conflict resolution failed: ${err49.message}`);
       }
     }
   }
@@ -124816,8 +125229,8 @@ var initCommand = new Command3("init").description("One-time global setup: confi
           });
           updateLastIndexed(proj.root);
           db.close();
-        } catch (err48) {
-          steps.push({ target: proj.root, action: "skipped", detail: `Upgrade failed: ${err48.message}` });
+        } catch (err49) {
+          steps.push({ target: proj.root, action: "skipped", detail: `Upgrade failed: ${err49.message}` });
         }
       }
       spin?.stop("Upgrade complete");
@@ -124937,7 +125350,7 @@ async function runIndexingForProject(projectRoot) {
 }
 async function registerAndIndexProject(dir, opts) {
   let projectRoot = null;
-  const resolvedDir = path124.resolve(dir);
+  const resolvedDir = path125.resolve(dir);
   if (hasRootMarkers(resolvedDir)) {
     projectRoot = resolvedDir;
   } else {
@@ -124978,7 +125391,7 @@ async function registerMultiRootProject(parentDir, childRoots, opts) {
     return {
       target: parentDir,
       action: "skipped",
-      detail: `Would register multi-root with ${childRoots.length} children: ${childRoots.map((r) => path124.basename(r)).join(", ")}`
+      detail: `Would register multi-root with ${childRoots.length} children: ${childRoots.map((r) => path125.basename(r)).join(", ")}`
     };
   }
   const existing = getProject(parentDir);
@@ -124988,14 +125401,14 @@ async function registerMultiRootProject(parentDir, childRoots, opts) {
   const allInclude = [];
   const allExclude = [];
   for (const childRoot of childRoots) {
-    const relPath = path124.relative(parentDir, childRoot).replace(/\\/g, "/");
+    const relPath = path125.relative(parentDir, childRoot).replace(/\\/g, "/");
     const detection = detectProject(childRoot);
     const config = generateConfig(detection);
     for (const pattern of config.include) allInclude.push(`${relPath}/${pattern}`);
     for (const pattern of config.exclude) allExclude.push(`${relPath}/${pattern}`);
   }
   const allProjects = listProjects();
-  const parentPrefix = parentDir + path124.sep;
+  const parentPrefix = parentDir + path125.sep;
   for (const proj of allProjects) {
     if (proj.root !== parentDir && proj.root.startsWith(parentPrefix)) {
       if (fs112.existsSync(proj.dbPath)) fs112.unlinkSync(proj.dbPath);
@@ -125014,7 +125427,7 @@ async function registerMultiRootProject(parentDir, childRoots, opts) {
   db.close();
   const entry = registerProject(parentDir, { type: "multi-root", children: childRoots });
   const indexResult = await runIndexingForProject(parentDir);
-  const detail = indexResult ? `Registered and indexed multi-root: ${entry.name} (${childRoots.length} children) \u2014 ${indexResult.indexed} files in ${formatDuration(indexResult.durationMs)}` : `Registered multi-root (${childRoots.length} children): ${childRoots.map((r) => path124.basename(r)).join(", ")} (indexing failed)`;
+  const detail = indexResult ? `Registered and indexed multi-root: ${entry.name} (${childRoots.length} children) \u2014 ${indexResult.indexed} files in ${formatDuration(indexResult.durationMs)}` : `Registered multi-root (${childRoots.length} children): ${childRoots.map((r) => path125.basename(r)).join(", ")} (indexing failed)`;
   return {
     target: parentDir,
     action: existing ? "updated" : "created",
@@ -125059,11 +125472,11 @@ init_registry2();
 init_global();
 import { Command as Command4 } from "commander";
 import fs113 from "fs";
-import path125 from "path";
+import path126 from "path";
 var upgradeCommand = new Command4("upgrade").description("Upgrade trace-mcp: run DB migrations, reindex with latest plugins, update hooks and CLAUDE.md").argument("[dir]", "Project directory (omit to upgrade all registered projects)").option("--skip-hooks", "Do not update guard hooks").option("--skip-reindex", "Do not trigger reindex").option("--skip-claude-md", "Do not update CLAUDE.md block").option("--dry-run", "Show what would be done without writing files").option("--json", "Output results as JSON").action(async (dir, opts) => {
   const projectRoots = [];
   if (dir) {
-    projectRoots.push(path125.resolve(dir));
+    projectRoots.push(path126.resolve(dir));
   } else {
     const projects = listProjects();
     if (projects.length === 0) {
@@ -125116,9 +125529,9 @@ var upgradeCommand = new Command4("upgrade").description("Upgrade trace-mcp: run
           updateLastIndexed(projectRoot);
         }
         db.close();
-      } catch (err48) {
-        logger.error({ error: err48.message, project: projectRoot }, "Upgrade failed");
-        steps.push({ target: projectRoot, action: "skipped", detail: `Upgrade failed: ${err48.message}` });
+      } catch (err49) {
+        logger.error({ error: err49.message, project: projectRoot }, "Upgrade failed");
+        steps.push({ target: projectRoot, action: "skipped", detail: `Upgrade failed: ${err49.message}` });
       }
     } else {
       steps.push({ target: dbPath, action: "skipped", detail: "Would run migrations" });
@@ -125154,7 +125567,7 @@ var upgradeCommand = new Command4("upgrade").description("Upgrade trace-mcp: run
     console.log(header);
     for (const { projectRoot, steps } of allSteps) {
       console.log(`
-  Project: ${path125.basename(projectRoot)} (${projectRoot})`);
+  Project: ${path126.basename(projectRoot)} (${projectRoot})`);
       for (const step of steps) {
         console.log(`    ${step.action}: ${step.detail ?? step.target}`);
       }
@@ -125166,7 +125579,7 @@ var upgradeCommand = new Command4("upgrade").description("Upgrade trace-mcp: run
 // src/cli/add.ts
 import { Command as Command5 } from "commander";
 import fs114 from "fs";
-import path126 from "path";
+import path127 from "path";
 import * as p2 from "@clack/prompts";
 init_detector();
 init_global();
@@ -125197,9 +125610,9 @@ async function runIndexing(projectRoot, opts) {
     const result = await pipeline2.indexAll(true);
     updateLastIndexed(projectRoot);
     return { indexed: result.indexed, skipped: result.skipped, errors: result.errors, durationMs: result.durationMs };
-  } catch (err48) {
+  } catch (err49) {
     if (!opts.json) {
-      p2.log.warn(`Indexing failed: ${err48.message}`);
+      p2.log.warn(`Indexing failed: ${err49.message}`);
     }
     return null;
   } finally {
@@ -125211,7 +125624,7 @@ function formatDuration2(ms2) {
   return `${(ms2 / 1e3).toFixed(1)}s`;
 }
 var addCommand = new Command5("add").description("Register a project for indexing: detect root, create DB, add to registry").argument("[dir]", "Project directory (default: current directory)", ".").option("--force", "Re-register even if already registered").option("--no-index", "Skip indexing after registration").option("--json", "Output results as JSON").action(async (dir, opts) => {
-  const resolvedDir = path126.resolve(dir);
+  const resolvedDir = path127.resolve(dir);
   if (!fs114.existsSync(resolvedDir)) {
     console.error(`Directory does not exist: ${resolvedDir}`);
     process.exit(1);
@@ -125344,7 +125757,7 @@ async function handleMultiRoot(parentDir, childRoots, opts) {
     p2.note(
       `No project root markers in ${parentDir}
 Discovered ${childRoots.length} child project(s):
-` + childRoots.map((r) => `  ${path126.basename(r)}`).join("\n"),
+` + childRoots.map((r) => `  ${path127.basename(r)}`).join("\n"),
       "Multi-root"
     );
   }
@@ -125363,7 +125776,7 @@ Discovered ${childRoots.length} child project(s):
   const allLanguages = /* @__PURE__ */ new Set();
   const allFrameworks = /* @__PURE__ */ new Set();
   for (const childRoot of childRoots) {
-    const relPath = path126.relative(parentDir, childRoot).replace(/\\/g, "/");
+    const relPath = path127.relative(parentDir, childRoot).replace(/\\/g, "/");
     const detection = detectProject(childRoot);
     const config = generateConfig(detection);
     for (const pattern of config.include) {
@@ -125390,13 +125803,13 @@ Discovered ${childRoots.length} child project(s):
   const allProjects = listProjects();
   const cleaned = [];
   for (const proj of allProjects) {
-    if (proj.root.startsWith(parentDir + path126.sep) || proj.root.startsWith(parentDir + "/")) {
+    if (proj.root.startsWith(parentDir + path127.sep) || proj.root.startsWith(parentDir + "/")) {
       if (fs114.existsSync(proj.dbPath)) {
         fs114.unlinkSync(proj.dbPath);
       }
       unregisterProject(proj.root);
       removeProjectConfigJsonc(proj.root);
-      cleaned.push(path126.basename(proj.root));
+      cleaned.push(path127.basename(proj.root));
     }
   }
   if (isInteractive && cleaned.length > 0) {
@@ -125437,7 +125850,7 @@ Discovered ${childRoots.length} child project(s):
       status: existing ? "re-registered" : "registered",
       type: "multi-root",
       project: entry,
-      children: childRoots.map((r) => path126.basename(r)),
+      children: childRoots.map((r) => path127.basename(r)),
       cleaned,
       indexing: indexResult ?? void 0
     }, null, 2));
@@ -125446,7 +125859,7 @@ Discovered ${childRoots.length} child project(s):
     lines.push(`Project: ${entry.name} (multi-root)`);
     lines.push(`Root: ${parentDir}`);
     lines.push(`DB: ${shortPath4(dbPath)}`);
-    lines.push(`Children: ${childRoots.map((r) => path126.basename(r)).join(", ")}`);
+    lines.push(`Children: ${childRoots.map((r) => path127.basename(r)).join(", ")}`);
     if (indexResult) {
       lines.push(`Indexed: ${indexResult.indexed} files (${indexResult.skipped} skipped, ${indexResult.errors} errors)`);
       lines.push(`Duration: ${formatDuration2(indexResult.durationMs)}`);
@@ -125614,7 +126027,7 @@ init_global();
 init_registry2();
 import { Command as Command7 } from "commander";
 import { execFileSync as execFileSync7 } from "child_process";
-import path127 from "path";
+import path128 from "path";
 import fs115 from "fs";
 
 // src/ci/report-generator.ts
@@ -126372,8 +126785,8 @@ function writeOutput(outputPath, content) {
   if (outputPath === "-" || !outputPath) {
     process.stdout.write(content + "\n");
   } else {
-    const resolved = path127.resolve(outputPath);
-    fs115.mkdirSync(path127.dirname(resolved), { recursive: true });
+    const resolved = path128.resolve(outputPath);
+    fs115.mkdirSync(path128.dirname(resolved), { recursive: true });
     fs115.writeFileSync(resolved, content, "utf-8");
     logger.info({ path: resolved }, "CI report written");
   }
@@ -126686,7 +127099,7 @@ subprojectCommand.command("impact").description("Cross-repo impact analysis: who
 
 // src/cli/memory.ts
 import { Command as Command11 } from "commander";
-import * as path128 from "path";
+import * as path129 from "path";
 init_global();
 function openStore() {
   ensureGlobalDirs();
@@ -126696,7 +127109,7 @@ var memoryCommand = new Command11("memory").description("Decision memory \u2014
 memoryCommand.command("mine").description("Mine Claude Code / Claw Code session logs for decisions").option("--project <path>", "Project root to mine (default: current directory)", process.cwd()).option("--force", "Re-mine already processed sessions").option("--min-confidence <n>", "Minimum confidence threshold (default: 0.6)", "0.6").action((opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     console.log(`Mining sessions for: ${projectRoot}`);
     const result = mineSessions(store, {
       projectRoot,
@@ -126718,7 +127131,7 @@ memoryCommand.command("mine").description("Mine Claude Code / Claw Code session
 memoryCommand.command("index").description("Index session content for cross-session search").option("--project <path>", "Project root to index (default: current directory)", process.cwd()).option("--force", "Re-index already processed sessions").action((opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     console.log(`Indexing session content for: ${projectRoot}`);
     const result = indexSessions(store, {
       projectRoot,
@@ -126739,7 +127152,7 @@ memoryCommand.command("index").description("Index session content for cross-sess
 memoryCommand.command("search <query>").description("Search across past session conversations").option("--project <path>", "Filter to project (default: current directory)", process.cwd()).option("--limit <n>", "Max results (default: 20)", "20").action((query, opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     const results = store.searchSessions(query, {
       project_root: projectRoot,
       limit: parseInt(opts.limit, 10)
@@ -126771,7 +127184,7 @@ memoryCommand.command("search <query>").description("Search across past session
 memoryCommand.command("decisions").description("List decisions in the knowledge graph").option("--project <path>", "Filter to project (default: current directory)", process.cwd()).option("--type <type>", "Filter by type (architecture_decision, tech_choice, bug_root_cause, preference, tradeoff, discovery, convention)").option("--search <query>", "Full-text search query").option("--limit <n>", "Max results (default: 20)", "20").option("--json", "Output as JSON").action((opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     const decisions = store.queryDecisions({
       project_root: projectRoot,
       type: opts.type,
@@ -126803,7 +127216,7 @@ memoryCommand.command("decisions").description("List decisions in the knowledge
 memoryCommand.command("stats").description("Show decision memory statistics").option("--project <path>", "Filter to project (default: current directory)", process.cwd()).option("--json", "Output as JSON").action((opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     const stats = store.getStats(projectRoot);
     const minedCount = store.getMinedSessionCount();
     const chunkCount = store.getSessionChunkCount(projectRoot);
@@ -126846,7 +127259,7 @@ memoryCommand.command("stats").description("Show decision memory statistics").op
 memoryCommand.command("timeline").description("Show chronological timeline of decisions").option("--project <path>", "Filter to project (default: current directory)", process.cwd()).option("--file <path>", "Filter to decisions about this file").option("--symbol <id>", "Filter to decisions about this symbol").option("--limit <n>", "Max entries (default: 50)", "50").action((opts) => {
   const store = openStore();
   try {
-    const projectRoot = path128.resolve(opts.project);
+    const projectRoot = path129.resolve(opts.project);
     const timeline = store.getTimeline({
       project_root: projectRoot,
       file_path: opts.file,
@@ -127231,13 +127644,13 @@ analyticsCommand.command("trends").description("Show daily usage trends: tokens,
 // src/cli/remove.ts
 import { Command as Command13 } from "commander";
 import fs117 from "fs";
-import path129 from "path";
+import path130 from "path";
 import * as p4 from "@clack/prompts";
 init_registry2();
 init_config();
 init_global();
 var removeCommand = new Command13("remove").description("Unregister a project and delete its index").argument("[dir]", "Project directory (default: current directory)", ".").option("--force", "Remove without confirmation").option("--keep-db", "Keep the database file (only unregister)").option("--json", "Output results as JSON").action(async (dir, opts) => {
-  const resolvedDir = path129.resolve(dir);
+  const resolvedDir = path130.resolve(dir);
   const isInteractive = !opts.json;
   let projectRoot;
   try {
@@ -127268,7 +127681,7 @@ var removeCommand = new Command13("remove").description("Unregister a project an
     lines.push(`Root: ${entry.root}`);
     lines.push(`DB: ${shortPath6(entry.dbPath)}`);
     if (entry.type === "multi-root" && entry.children) {
-      lines.push(`Children: ${entry.children.map((c) => path129.basename(c)).join(", ")}`);
+      lines.push(`Children: ${entry.children.map((c) => path130.basename(c)).join(", ")}`);
     }
     p4.note(lines.join("\n"), "Project to remove");
   }
@@ -127321,13 +127734,13 @@ async function handleRemoveFromMultiRoot(childRoot, parent, opts) {
     p4.note(
       `This project is part of multi-root index: ${parent.name}
 Parent root: ${parent.root}
-Child to exclude: ${path129.basename(childRoot)}`,
+Child to exclude: ${path130.basename(childRoot)}`,
       "Multi-root"
     );
   }
   if (!opts.force && isInteractive) {
     const confirm4 = await p4.confirm({
-      message: `Exclude "${path129.basename(childRoot)}" from multi-root "${parent.name}"? (The parent index will be re-registered without this child.)`,
+      message: `Exclude "${path130.basename(childRoot)}" from multi-root "${parent.name}"? (The parent index will be re-registered without this child.)`,
       initialValue: false
     });
     if (p4.isCancel(confirm4) || !confirm4) {
@@ -127336,7 +127749,7 @@ Child to exclude: ${path129.basename(childRoot)}`,
     }
   }
   const currentChildren = parent.children ?? [];
-  const newChildren = currentChildren.filter((c) => path129.resolve(c) !== path129.resolve(childRoot));
+  const newChildren = currentChildren.filter((c) => path130.resolve(c) !== path130.resolve(childRoot));
   if (newChildren.length === 0) {
     if (!opts.keepDb && fs117.existsSync(parent.dbPath)) {
       fs117.unlinkSync(parent.dbPath);
@@ -127367,14 +127780,14 @@ Child to exclude: ${path129.basename(childRoot)}`,
     if (opts.json) {
       console.log(JSON.stringify({
         status: "excluded_from_multi_root",
-        excluded: path129.basename(childRoot),
-        remaining: path129.basename(remainingChild),
+        excluded: path130.basename(childRoot),
+        remaining: path130.basename(remainingChild),
         hint: `Run \`trace-mcp add ${remainingChild}\` to re-register the remaining project individually.`
       }, null, 2));
     } else {
       p4.note(
-        `Excluded: ${path129.basename(childRoot)}
-Only one child remaining: ${path129.basename(remainingChild)}
+        `Excluded: ${path130.basename(childRoot)}
+Only one child remaining: ${path130.basename(remainingChild)}
 Multi-root removed. Run \`trace-mcp add ${remainingChild}\` to re-register individually.`,
         "Converted"
       );
@@ -127391,14 +127804,14 @@ Multi-root removed. Run \`trace-mcp add ${remainingChild}\` to re-register indiv
   if (opts.json) {
     console.log(JSON.stringify({
       status: "excluded_from_multi_root",
-      excluded: path129.basename(childRoot),
-      remaining: newChildren.map((c) => path129.basename(c)),
+      excluded: path130.basename(childRoot),
+      remaining: newChildren.map((c) => path130.basename(c)),
       hint: `Run \`trace-mcp add ${parent.root}\` to re-register with ${newChildren.length} children.`
     }, null, 2));
   } else {
     p4.note(
-      `Excluded: ${path129.basename(childRoot)}
-Remaining children: ${newChildren.map((c) => path129.basename(c)).join(", ")}
+      `Excluded: ${path130.basename(childRoot)}
+Remaining children: ${newChildren.map((c) => path130.basename(c)).join(", ")}
 Run \`trace-mcp add ${parent.root}\` to re-register the multi-root.`,
       "Excluded"
     );
@@ -127522,7 +127935,7 @@ init_global();
 import { execSync as execSync8 } from "child_process";
 import fs119 from "fs";
 import os14 from "os";
-import path130 from "path";
+import path131 from "path";
 import { Command as Command15 } from "commander";
 init_registry2();
 function openInBrowser(filePath) {
@@ -127554,7 +127967,7 @@ var visualizeCommand = new Command15("visualize").alias("viz").description("Gene
   Modes:
     file     each node = one file (default)
     symbol   each node = function/class/method`, "file").option("-k, --symbol-kinds <kinds>", "comma-separated symbol kinds when granularity=symbol (e.g. function,class,method)").option("--hide-isolated", "hide nodes with no edges").option("--max-files <n>", "max seed files for file-level graph (default: 10000)").option("--max-nodes <n>", "max viz nodes for symbol-level graph (default: 100000)").option("-o, --output <path>", "write HTML to this path instead of a temp file").option("--no-open", "write HTML but do not open the browser").option("--dir <dir>", "project directory (default: cwd)").action((scope8, opts) => {
-  const projectDir = opts.dir ? path130.resolve(opts.dir) : process.cwd();
+  const projectDir = opts.dir ? path131.resolve(opts.dir) : process.cwd();
   let projectRoot;
   try {
     projectRoot = findProjectRoot(projectDir);
@@ -127570,7 +127983,7 @@ var visualizeCommand = new Command15("visualize").alias("viz").description("Gene
     console.error(`Run: trace-mcp index ${projectRoot}`);
     process.exit(1);
   }
-  const outputPath = opts.output ?? path130.join(os14.tmpdir(), "trace-mcp-graph.html");
+  const outputPath = opts.output ?? path131.join(os14.tmpdir(), "trace-mcp-graph.html");
   const db = initializeDatabase(dbPath);
   const store = new Store(db);
   let topoStore;
@@ -127606,7 +128019,7 @@ var visualizeCommand = new Command15("visualize").alias("viz").description("Gene
 });
 visualizeCommand.command("subproject").alias("sub").description("Open subproject topology graph in the browser").option("-l, --layout <type>", "graph layout: force | hierarchical | radial", "force").option("-o, --output <path>", "output HTML file path").option("--no-open", "write HTML but do not open the browser").action((opts) => {
   ensureGlobalDirs();
-  const outputPath = opts.output ?? path130.join(os14.tmpdir(), "trace-mcp-subproject-topology.html");
+  const outputPath = opts.output ?? path131.join(os14.tmpdir(), "trace-mcp-subproject-topology.html");
   const topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
   const result = visualizeSubprojectTopology(topoStore, {
     layout: opts.layout,
@@ -127812,6 +128225,85 @@ var askCommand = new Command16("ask").description("Ask questions about your code
   }
 });
 
+// src/cli/export-security-context.ts
+init_schema();
+init_store();
+init_config();
+init_global();
+init_registry2();
+import { Command as Command17 } from "commander";
+import path132 from "path";
+import fs121 from "fs";
+init_logger();
+init_registry();
+init_all();
+init_all2();
+init_pipeline();
+function resolveDbPath6(projectRoot) {
+  const entry = getProject(projectRoot);
+  if (entry) return entry.dbPath;
+  return getDbPath(projectRoot);
+}
+var exportSecurityContextCommand = new Command17("export-security-context").description("Export security context for MCP server analysis (enrichment JSON for skill-scan)").option("-o, --output <path>", "Output file path (default: stdout)", "-").option("--scope <path>", "Limit analysis to directory (relative to project root)").option("--depth <n>", "Call graph traversal depth (default: 3, max: 5)", "3").option("--index", "Re-index project before export", false).action(async (opts) => {
+  let projectRoot;
+  try {
+    projectRoot = findProjectRoot(process.cwd());
+  } catch {
+    projectRoot = process.cwd();
+  }
+  const dbPath = resolveDbPath6(projectRoot);
+  ensureGlobalDirs();
+  const db = initializeDatabase(dbPath);
+  const store = new Store(db);
+  try {
+    if (opts.index) {
+      const configResult = await loadConfig(projectRoot);
+      const config = configResult.isOk() ? configResult.value : {
+        root: projectRoot,
+        include: ["**/*"],
+        exclude: ["vendor/**", "node_modules/**", ".git/**"],
+        db: { path: "" },
+        plugins: [],
+        ignore: { directories: [], patterns: [] },
+        watch: { enabled: false, debounceMs: 2e3 }
+      };
+      const registry = new PluginRegistry();
+      for (const p5 of createAllLanguagePlugins()) registry.registerLanguagePlugin(p5);
+      for (const p5 of createAllIntegrationPlugins()) registry.registerFrameworkPlugin(p5);
+      logger.info("Indexing project...");
+      const pipeline2 = new IndexingPipeline(store, registry, config, projectRoot);
+      await pipeline2.indexAll(false);
+      logger.info("Indexing complete");
+    }
+    const stats = store.getStats();
+    if (stats.totalFiles === 0) {
+      console.error("Error: No files indexed. Run `trace-mcp reindex` first or use --index flag.");
+      process.exit(2);
+    }
+    const depth = Math.min(Math.max(parseInt(opts.depth, 10) || 3, 1), 5);
+    const result = exportSecurityContext(store, projectRoot, {
+      scope: opts.scope,
+      depth
+    });
+    if (result.isErr()) {
+      console.error(`Error: ${result.error.message}`);
+      process.exit(1);
+    }
+    const json = JSON.stringify(result.value, null, 2);
+    if (opts.output === "-") {
+      process.stdout.write(json + "\n");
+    } else {
+      const outputPath = path132.resolve(opts.output);
+      fs121.mkdirSync(path132.dirname(outputPath), { recursive: true });
+      fs121.writeFileSync(outputPath, json, "utf-8");
+      logger.info({ path: outputPath }, "Security context exported");
+      console.error(`Exported to ${outputPath} (${result.value.tool_registrations.length} tool registrations)`);
+    }
+  } finally {
+    db.close();
+  }
+});
+
 // src/cli.ts
 init_hooks();
 init_global();
@@ -127845,8 +128337,8 @@ function runSubprojectAutoSync(projectRoot, config) {
     sm.syncContracts();
     sm.syncClientCalls();
     db.close();
-  } catch (err48) {
-    logger.warn({ error: err48, projectRoot }, "Subproject auto-sync failed (non-fatal)");
+  } catch (err49) {
+    logger.warn({ error: err49, projectRoot }, "Subproject auto-sync failed (non-fatal)");
   }
 }
 var ProjectManager = class {
@@ -127895,14 +128387,14 @@ var ProjectManager = class {
     ) : null;
     const runEmbeddings = () => {
       if (!embeddingPipeline) return;
-      embeddingPipeline.indexUnembedded().catch((err48) => {
-        logger.error({ error: err48, projectRoot }, "Embedding indexing failed");
+      embeddingPipeline.indexUnembedded().catch((err49) => {
+        logger.error({ error: err49, projectRoot }, "Embedding indexing failed");
       });
     };
     const runSummarization = () => {
       if (!summarizationPipeline) return;
-      summarizationPipeline.summarizeUnsummarized().catch((err48) => {
-        logger.error({ error: err48, projectRoot }, "Summarization failed");
+      summarizationPipeline.summarizeUnsummarized().catch((err49) => {
+        logger.error({ error: err49, projectRoot }, "Summarization failed");
       });
     };
     const server = createServer2(store, registry, config, projectRoot, progress);
@@ -127926,10 +128418,10 @@ var ProjectManager = class {
       runEmbeddings();
       runSubprojectAutoSync(projectRoot, config);
       logger.info({ projectRoot }, "Project indexing complete");
-    }).catch((err48) => {
+    }).catch((err49) => {
       managed.status = "error";
-      managed.error = String(err48);
-      logger.error({ error: err48, projectRoot }, "Initial indexing failed");
+      managed.error = String(err49);
+      logger.error({ error: err49, projectRoot }, "Initial indexing failed");
     });
     await watcher.start(projectRoot, config, async (paths) => {
       await pipeline2.indexFiles(paths);
@@ -127986,12 +128478,12 @@ var ProjectManager = class {
 
 // src/cli.ts
 init_global();
-var PKG_VERSION2 = true ? "1.21.2" : "0.0.0-dev";
+var PKG_VERSION3 = true ? "1.22.0" : "0.0.0-dev";
 function registerDefaultPlugins2(registry) {
   for (const p5 of createAllLanguagePlugins()) registry.registerLanguagePlugin(p5);
   for (const p5 of createAllIntegrationPlugins()) registry.registerFrameworkPlugin(p5);
 }
-function resolveDbPath6(projectRoot) {
+function resolveDbPath7(projectRoot) {
   const entry = getProject(projectRoot);
   if (entry) return entry.dbPath;
   return getDbPath(projectRoot);
@@ -128027,8 +128519,8 @@ function runSubprojectAutoSync2(projectRoot, config) {
     logger.warn({ error: e }, "Subproject auto-sync failed (non-fatal)");
   }
 }
-var program = new Command17();
-program.name("trace-mcp").description("Framework-Aware Code Intelligence for Laravel/Vue/Inertia/Nuxt").version(PKG_VERSION2, "-v, --version");
+var program = new Command18();
+program.name("trace-mcp").description("Framework-Aware Code Intelligence for Laravel/Vue/Inertia/Nuxt").version(PKG_VERSION3, "-v, --version");
 program.command("serve", { isDefault: true }).description("Start MCP server (stdio transport)").action(async () => {
   const projectRoot = process.cwd();
   const globalRaw = loadGlobalConfigRaw();
@@ -128049,7 +128541,7 @@ program.command("serve", { isDefault: true }).description("Start MCP server (std
   if (!existing) {
     try {
       const root = findProjectRoot(indexRoot);
-      if (root === path131.resolve(indexRoot)) {
+      if (root === path133.resolve(indexRoot)) {
         setupProject(root);
         logger.info({ root }, "Auto-registered project");
       } else {
@@ -128067,101 +128559,145 @@ program.command("serve", { isDefault: true }).description("Start MCP server (std
   if (config.logging) {
     attachFileLogging(config.logging);
   }
-  const dbPath = resolveDbPath6(indexRoot);
-  ensureGlobalDirs();
-  const db = initializeDatabase(dbPath);
-  writeServerPid(db);
-  const store = new Store(db);
-  const registry = new PluginRegistry();
-  registerDefaultPlugins2(registry);
-  const progress = new ProgressState(db);
+  let shuttingDown = false;
+  const makeShutdown = (cleanup) => {
+    return async (reason) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      logger.info({ reason: reason ?? "unknown" }, "Shutting down trace-mcp server");
+      if (cleanup) await cleanup().catch(() => {
+      });
+      process.exit(0);
+    };
+  };
+  const attachLifecycleHandlers = (shutdown2, idleTimeoutMs) => {
+    process.on("SIGINT", () => shutdown2("SIGINT"));
+    process.on("SIGTERM", () => shutdown2("SIGTERM"));
+    process.stdin.on("end", () => shutdown2("stdin-end"));
+    process.stdin.on("close", () => shutdown2("stdin-close"));
+    let idleTimer = null;
+    const resetIdleTimer = () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => shutdown2("idle-timeout"), idleTimeoutMs);
+      idleTimer.unref();
+    };
+    resetIdleTimer();
+    process.stdin.on("data", resetIdleTimer);
+  };
+  const IDLE_TIMEOUT_MS = config.idle_timeout_minutes ? config.idle_timeout_minutes * 6e4 : 5 * 6e4;
   const daemonActive = await isDaemonRunning(DEFAULT_DAEMON_PORT);
-  let watcher = null;
-  let daemonClientId = null;
   if (daemonActive) {
-    logger.info({ port: DEFAULT_DAEMON_PORT }, "Daemon detected \u2014 skipping indexer, serving MCP over existing DB");
-    daemonClientId = randomUUID();
-    fetch(`http://127.0.0.1:${DEFAULT_DAEMON_PORT}/api/clients`, {
+    const daemonUrl = `http://127.0.0.1:${DEFAULT_DAEMON_PORT}`;
+    const mcpUrl = `${daemonUrl}/mcp?project=${encodeURIComponent(projectRoot)}`;
+    const clientId = randomUUID();
+    await fetch(`${daemonUrl}/api/projects`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ id: daemonClientId, project: projectRoot, transport: "stdio" })
+      body: JSON.stringify({ root: projectRoot })
     }).catch(() => {
     });
-  } else {
-    const pipeline2 = new IndexingPipeline(store, registry, config, projectRoot, progress);
-    watcher = new FileWatcher();
-    const aiProvider = createAIProvider(config);
-    const vectorStore = config.ai?.enabled ? new BlobVectorStore(store.db) : null;
-    const embeddingService = config.ai?.enabled ? aiProvider.embedding() : null;
-    const embeddingPipeline = vectorStore && embeddingService ? new EmbeddingPipeline(store, embeddingService, vectorStore, progress) : null;
-    const inferenceCache = config.ai?.enabled ? new InferenceCache(store.db) : null;
-    inferenceCache?.evictExpired();
-    const summarizationPipeline = config.ai?.enabled && config.ai.summarize_on_index !== false ? new SummarizationPipeline2(
-      store,
-      new CachedInferenceService(aiProvider.fastInference(), inferenceCache, config.ai.fast_model ?? "fast"),
-      projectRoot,
-      {
-        batchSize: config.ai.summarize_batch_size ?? 20,
-        kinds: config.ai.summarize_kinds ?? ["class", "function", "method", "interface", "trait", "enum", "type"],
-        concurrency: config.ai.concurrency ?? 1
-      },
-      progress
-    ) : null;
-    const runEmbeddings = () => {
-      if (!embeddingPipeline) return;
-      embeddingPipeline.indexUnembedded().catch((err48) => {
-        logger.error({ error: err48 }, "Embedding indexing failed");
+    fetch(`${daemonUrl}/api/clients`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id: clientId, project: projectRoot, transport: "stdio-proxy" })
+    }).catch(() => {
+    });
+    const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    const httpTransport = new StreamableHTTPClientTransport(new URL(mcpUrl));
+    const stdioTransport = new StdioServerTransport();
+    stdioTransport.onmessage = (msg) => {
+      httpTransport.send(msg).catch((err49) => {
+        logger.error({ error: err49 }, "Proxy: failed to forward message to daemon");
       });
     };
-    const runSummarization = () => {
-      if (!summarizationPipeline) return;
-      summarizationPipeline.summarizeUnsummarized().catch((err48) => {
-        logger.error({ error: err48 }, "Summarization failed");
+    httpTransport.onmessage = (msg) => {
+      stdioTransport.send(msg).catch((err49) => {
+        logger.error({ error: err49 }, "Proxy: failed to forward message to client");
       });
     };
-    pipeline2.indexAll().then(() => {
-      runSummarization();
-      runEmbeddings();
-      runSubprojectAutoSync2(projectRoot, config);
-    }).catch((err48) => {
-      logger.error({ error: err48 }, "Initial indexing failed");
-    });
-    await watcher.start(projectRoot, config, async (paths) => {
-      await pipeline2.indexFiles(paths);
-      runSummarization();
-      runEmbeddings();
-    }, void 0, async (deleted) => {
-      pipeline2.deleteFiles(deleted);
+    httpTransport.onerror = (err49) => {
+      logger.error({ error: err49 }, "Proxy: HTTP transport error");
+    };
+    const shutdown2 = makeShutdown(async () => {
+      await fetch(`${daemonUrl}/api/clients?id=${clientId}`, { method: "DELETE" }).catch(() => {
+      });
+      await httpTransport.close().catch(() => {
+      });
+      await stdioTransport.close().catch(() => {
+      });
     });
+    attachLifecycleHandlers(shutdown2, IDLE_TIMEOUT_MS);
+    await httpTransport.start();
+    await stdioTransport.start();
+    logger.info({ projectRoot, mode: "proxy", daemonUrl, idleTimeoutMs: IDLE_TIMEOUT_MS }, "trace-mcp proxy started (forwarding to daemon)");
+    return;
   }
-  const shutdown = async () => {
+  const dbPath = resolveDbPath7(indexRoot);
+  ensureGlobalDirs();
+  const db = initializeDatabase(dbPath);
+  writeServerPid(db);
+  const store = new Store(db);
+  const registry = new PluginRegistry();
+  registerDefaultPlugins2(registry);
+  const progress = new ProgressState(db);
+  let watcher = null;
+  const pipeline2 = new IndexingPipeline(store, registry, config, projectRoot, progress);
+  watcher = new FileWatcher();
+  const aiProvider = createAIProvider(config);
+  const vectorStore = config.ai?.enabled ? new BlobVectorStore(store.db) : null;
+  const embeddingService = config.ai?.enabled ? aiProvider.embedding() : null;
+  const embeddingPipeline = vectorStore && embeddingService ? new EmbeddingPipeline(store, embeddingService, vectorStore, progress) : null;
+  const inferenceCache = config.ai?.enabled ? new InferenceCache(store.db) : null;
+  inferenceCache?.evictExpired();
+  const summarizationPipeline = config.ai?.enabled && config.ai.summarize_on_index !== false ? new SummarizationPipeline2(
+    store,
+    new CachedInferenceService(aiProvider.fastInference(), inferenceCache, config.ai.fast_model ?? "fast"),
+    projectRoot,
+    {
+      batchSize: config.ai.summarize_batch_size ?? 20,
+      kinds: config.ai.summarize_kinds ?? ["class", "function", "method", "interface", "trait", "enum", "type"],
+      concurrency: config.ai.concurrency ?? 1
+    },
+    progress
+  ) : null;
+  const runEmbeddings = () => {
+    if (!embeddingPipeline) return;
+    embeddingPipeline.indexUnembedded().catch((err49) => {
+      logger.error({ error: err49 }, "Embedding indexing failed");
+    });
+  };
+  const runSummarization = () => {
+    if (!summarizationPipeline) return;
+    summarizationPipeline.summarizeUnsummarized().catch((err49) => {
+      logger.error({ error: err49 }, "Summarization failed");
+    });
+  };
+  pipeline2.indexAll().then(() => {
+    runSummarization();
+    runEmbeddings();
+    runSubprojectAutoSync2(projectRoot, config);
+  }).catch((err49) => {
+    logger.error({ error: err49 }, "Initial indexing failed");
+  });
+  await watcher.start(projectRoot, config, async (paths) => {
+    await pipeline2.indexFiles(paths);
+    runSummarization();
+    runEmbeddings();
+  }, void 0, async (deleted) => {
+    pipeline2.deleteFiles(deleted);
+  });
+  const shutdown = makeShutdown(async () => {
     clearServerPid(db);
     if (watcher) await watcher.stop();
-    if (daemonClientId) {
-      await fetch(`http://127.0.0.1:${DEFAULT_DAEMON_PORT}/api/clients?id=${daemonClientId}`, { method: "DELETE" }).catch(() => {
-      });
+    try {
+      db.close();
+    } catch {
     }
-    process.exit(0);
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  });
+  attachLifecycleHandlers(shutdown, IDLE_TIMEOUT_MS);
   const server = createServer2(store, registry, config, projectRoot, progress);
   const transport = new StdioServerTransport();
-  if (daemonActive && daemonClientId) {
-    const cid = daemonClientId;
-    server.server.oninitialized = () => {
-      const clientVersion = server.server.getClientVersion();
-      if (clientVersion?.name) {
-        fetch(`http://127.0.0.1:${DEFAULT_DAEMON_PORT}/api/clients`, {
-          method: "PATCH",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ id: cid, name: clientVersion.name })
-        }).catch(() => {
-        });
-      }
-    };
-  }
-  logger.info({ projectRoot, indexRoot, dbPath, daemonActive }, "Starting trace-mcp MCP server...");
+  logger.info({ projectRoot, indexRoot, dbPath, mode: "full", idleTimeoutMs: IDLE_TIMEOUT_MS }, "Starting trace-mcp MCP server...");
   await server.connect(transport);
 });
 program.command("serve-http").description("Start MCP server (HTTP/SSE transport) \u2014 daemon mode, indexes all registered projects").option("-p, --port <port>", "Port to listen on", "3741").option("--host <host>", "Host to bind to", "127.0.0.1").action(async (opts) => {
@@ -128497,7 +129033,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
         const maxNodes = url2.searchParams.has("maxNodes") ? parseInt(url2.searchParams.get("maxNodes"), 10) : void 0;
         let topoStore;
         try {
-          if (fs121.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
+          if (fs122.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
         } catch {
         }
         try {
@@ -128549,7 +129085,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
         const highlightDepth = url2.searchParams.has("highlightDepth") ? parseInt(url2.searchParams.get("highlightDepth"), 10) : void 0;
         let topoStore;
         try {
-          if (fs121.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
+          if (fs122.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
         } catch {
         }
         try {
@@ -128802,7 +129338,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
       try {
         let topoStore;
         try {
-          if (fs121.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
+          if (fs122.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
         } catch {
         }
         if (!topoStore) {
@@ -128875,7 +129411,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
       try {
         let topoStore;
         try {
-          if (fs121.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
+          if (fs122.existsSync(TOPOLOGY_DB_PATH)) topoStore = new TopologyStore(TOPOLOGY_DB_PATH);
         } catch {
         }
         if (!topoStore) {
@@ -128925,8 +129461,8 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
         res.end(JSON.stringify({ error: `Project not found: ${projectRoot}` }));
         return;
       }
-      managed.pipeline.indexAll(true).catch((err48) => {
-        logger.error({ error: err48, projectRoot }, "Reindex failed");
+      managed.pipeline.indexAll(true).catch((err49) => {
+        logger.error({ error: err49, projectRoot }, "Reindex failed");
       });
       res.writeHead(202, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ status: "reindex_started", project: projectRoot }));
@@ -128936,7 +129472,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
       try {
         const body = await collectBody(req);
         const { root } = JSON.parse(body.toString());
-        if (!root || !fs121.existsSync(root)) {
+        if (!root || !fs122.existsSync(root)) {
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Invalid or missing root path" }));
           return;
@@ -129052,7 +129588,7 @@ program.command("serve-http").description("Start MCP server (HTTP/SSE transport)
           if (value !== void 0) merged[key] = value;
         }
         ensureGlobalDirs();
-        fs121.writeFileSync(GLOBAL_CONFIG_PATH, JSON.stringify(merged, null, 2));
+        fs122.writeFileSync(GLOBAL_CONFIG_PATH, JSON.stringify(merged, null, 2));
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ status: "updated", settings: merged }));
       } catch (e) {
@@ -129235,8 +129771,8 @@ ${lastUserMsg.content}`
   });
 });
 program.command("index").description("Index a project directory").argument("<dir>", "Directory to index").option("-f, --force", "Force reindex all files").action(async (dir, opts) => {
-  const resolvedDir = path131.resolve(dir);
-  if (!fs121.existsSync(resolvedDir)) {
+  const resolvedDir = path133.resolve(dir);
+  if (!fs122.existsSync(resolvedDir)) {
     logger.error({ dir: resolvedDir }, "Directory does not exist");
     process.exit(1);
   }
@@ -129246,7 +129782,7 @@ program.command("index").description("Index a project directory").argument("<dir
     process.exit(1);
   }
   const config = configResult.value;
-  const dbPath = resolveDbPath6(resolvedDir);
+  const dbPath = resolveDbPath7(resolvedDir);
   ensureGlobalDirs();
   const db = initializeDatabase(dbPath);
   const store = new Store(db);
@@ -129260,20 +129796,20 @@ program.command("index").description("Index a project directory").argument("<dir
   db.close();
 });
 program.command("index-file").description("Incrementally reindex a single file (called by the PostToolUse auto-reindex hook)").argument("<file>", "Absolute or relative path to the file to reindex").action(async (file) => {
-  const resolvedFile = path131.resolve(file);
-  if (!fs121.existsSync(resolvedFile)) {
+  const resolvedFile = path133.resolve(file);
+  if (!fs122.existsSync(resolvedFile)) {
     process.exit(0);
   }
   let projectRoot;
   try {
-    projectRoot = findProjectRoot(path131.dirname(resolvedFile));
+    projectRoot = findProjectRoot(path133.dirname(resolvedFile));
   } catch {
     process.exit(0);
   }
   const configResult = await loadConfig(projectRoot);
   if (configResult.isErr()) process.exit(0);
   const config = configResult.value;
-  const dbPath = resolveDbPath6(projectRoot);
+  const dbPath = resolveDbPath7(projectRoot);
   ensureGlobalDirs();
   const db = initializeDatabase(dbPath);
   const store = new Store(db);
@@ -129303,7 +129839,7 @@ program.command("list").description("List all registered projects").option("--js
     console.log("Registered projects:\n");
     for (const p5 of projects) {
       const lastIdx = p5.lastIndexed ? new Date(p5.lastIndexed).toLocaleString() : "never";
-      const dbExists = fs121.existsSync(p5.dbPath) ? "ok" : "missing";
+      const dbExists = fs122.existsSync(p5.dbPath) ? "ok" : "missing";
       console.log(`  ${p5.name}`);
       console.log(`    Root: ${p5.root}`);
       console.log(`    DB: ${dbExists}`);
@@ -129328,6 +129864,7 @@ program.addCommand(visualizeCommand);
 program.addCommand(daemonCommand);
 program.addCommand(installAppCommand);
 program.addCommand(askCommand);
+program.addCommand(exportSecurityContextCommand);
 program.parse();
 /*! Bundled license information: