@plumpslabs/kuma 2.0.5 → 2.1.1

package/dist/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
+import * as readline from "readline";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -74,6 +75,21 @@ function validateFilePath(filePath, projectRoot) {
         };
       }
     }
+    try {
+      if (fs.existsSync(resolvedPath)) {
+        const realPath = fs.realpathSync(resolvedPath);
+        const normalizedRealPath = path.normalize(realPath).toLowerCase();
+        if (!normalizedRealPath.startsWith(normalizedRoot)) {
+          return {
+            valid: false,
+            error: new Error(
+              `PATH_TRAVERSAL: Symlink escape detected. Path "${filePath}" resolves to "${realPath}" which is outside project root "${resolvedRoot}".`
+            )
+          };
+        }
+      }
+    } catch {
+    }
     if (normalizedPath.includes("node_modules")) {
       return {
         valid: true,
@@ -579,6 +595,10 @@ No unresolved issues.`;
     });
     return results.slice(0, limit);
   }
+  getConventions() {
+    this.ensureInit();
+    return this.state.conventions;
+  }
   pruneMemory() {
     this.ensureInit();
     this.state.toolCalls = this.state.toolCalls.slice(-3);
@@ -899,7 +919,11 @@ async function handleSmartFilePicker(params) {
     const content = fs4.readFileSync(resolvedPath, "utf-8");
     const lines = content.split("\n");
     const totalLines = lines.length;
-    sessionMemory.recordToolCall("smart_file_picker", { filePath, chunkStrategy, totalLines });
+    sessionMemory.recordToolCall("smart_file_picker", {
+      filePath,
+      chunkStrategy,
+      totalLines
+    });
     if (startLine !== void 0 || endLine !== void 0) {
       const start = startLine ?? 1;
       const end = endLine ?? totalLines;
@@ -915,7 +939,13 @@ async function handleSmartFilePicker(params) {
       case "smart":
         return handleSmartStrategy(filePath, lines, totalLines);
       default:
-        return formatOutput(filePath, lines.slice(0, CHUNK_THRESHOLD), 1, totalLines, true);
+        return formatOutput(
+          filePath,
+          lines.slice(0, CHUNK_THRESHOLD),
+          1,
+          totalLines,
+          true
+        );
     }
   } catch (err) {
     return 'Error reading file "' + filePath + '": ' + (err instanceof Error ? err.message : String(err));
@@ -940,7 +970,8 @@ async function handleOutlineStrategy(filePath, lines, totalLines) {
   const exportLines = [];
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
-    if (line.startsWith("//") || line.startsWith("#") || line.startsWith("/*") || line.startsWith("*")) continue;
+    if (line.startsWith("//") || line.startsWith("#") || line.startsWith("/*") || line.startsWith("*"))
+      continue;
     if (line.startsWith("import ") || line.startsWith("from ") || line.startsWith("require(")) {
       importLines.push(line);
       continue;
@@ -974,10 +1005,15 @@ async function handleSmartStrategy(filePath, lines, totalLines) {
   }
   if (headerEnd < tailStart) {
     smartLines.push({ line: -1, text: "" });
-    smartLines.push({ line: -1, text: "  ... " + (tailStart - headerEnd) + " lines hidden ..." });
+    smartLines.push({
+      line: -1,
+      text: "  ... " + (tailStart - headerEnd) + " lines hidden ..."
+    });
     smartLines.push({ line: -1, text: "" });
   }
-  const keyDeclarations = extractKeyDeclarations(lines.slice(headerEnd, tailStart));
+  const keyDeclarations = extractKeyDeclarations(
+    lines.slice(headerEnd, tailStart)
+  );
   for (const decl of keyDeclarations) {
     smartLines.push({ line: decl.line + 1 + headerEnd, text: decl.text });
   }
@@ -1020,7 +1056,9 @@ function extractKeyDeclarations(lines) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
     if (!line || line.startsWith("//") || line.startsWith("#")) continue;
-    if (/^(export\s+)?(async\s+)?(function|class|interface|type|enum|const|let|var|def)\s/.test(line)) {
+    if (/^(export\s+)?(async\s+)?(function|class|interface|type|enum|const|let|var|def)\s/.test(
+      line
+    )) {
       decls.push({ line: i, text: line.substring(0, 150) });
     }
   }
@@ -1576,140 +1614,565 @@ function formatBatchResult(results, totalRequested) {
 }
 
 // src/tools/safeTerminalExec.ts
-import { spawn } from "child_process";
-var TASK_COMMANDS = {
-  test: "npm test",
-  build: "npm run build",
-  lint: "npm run lint",
-  typecheck: "npx tsc --noEmit"
-};
-var DANGEROUS_PATTERNS = [
-  "rm -rf",
-  "rm -fr",
-  "del /f",
-  "rd /s",
-  "rmdir /s",
-  "git push",
-  "git commit",
-  "npm publish",
-  "npx publish",
-  "yarn publish",
-  "pnpm publish",
-  "> /dev/sda",
-  "format",
-  "mkfs",
-  "dd if=",
-  ":(){ :|:& };:",
-  // fork bomb
-  "curl ",
-  "wget "
-];
-async function handleSafeTerminalExec(params) {
-  const { task, customCommand, timeout = 60 } = params;
-  if (task === "custom" && !customCommand) {
-    return "Error: Task 'custom' requires the 'customCommand' parameter.";
-  }
-  let command;
-  if (task === "custom") {
-    command = customCommand;
-  } else {
-    command = TASK_COMMANDS[task];
-  }
-  const cbResult = circuitBreaker.check("safe_terminal_exec", { task, command });
-  if (!cbResult.allowed) {
-    return `\u26A0\uFE0F Circuit breaker: ${cbResult.reason}
+import fs8 from "fs";
+import path8 from "path";
 
-Fix the code first before running the task again.`;
-  }
-  const dangerousPattern = DANGEROUS_PATTERNS.find((p) => command.toLowerCase().includes(p.toLowerCase()));
-  if (dangerousPattern) {
-    return `\u{1F6AB} BLOCKED: Command contains a dangerous pattern: "${dangerousPattern}".
-This command is not permitted.`;
+// src/utils/conventionsDetector.ts
+import fs7 from "fs";
+import path7 from "path";
+var cachedConventions = null;
+async function detectConventions(forceRescan = false) {
+  if (cachedConventions && !forceRescan) {
+    return cachedConventions;
   }
   const projectRoot = getProjectRoot();
+  const workspaces = detectWorkspaces(projectRoot);
+  const conventions = {
+    framework: detectFramework(projectRoot),
+    projectType: detectProjectType(projectRoot),
+    testRunner: detectTestRunner(projectRoot),
+    styling: detectStyling(projectRoot),
+    importAlias: detectImportAlias(projectRoot),
+    lintRules: detectLintRules(projectRoot),
+    packageManager: detectPackageManager(),
+    moduleSystem: detectModuleSystem(projectRoot),
+    language: detectLanguage(projectRoot),
+    features: detectFeatures(projectRoot),
+    isMonorepo: workspaces.length > 0,
+    workspaces
+  };
+  cachedConventions = conventions;
+  return conventions;
+}
+function detectFramework(root) {
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (pkg) {
+    const pkgDeps = pkg.dependencies ?? {};
+    const pkgDevDeps = pkg.devDependencies ?? {};
+    const deps = { ...pkgDeps, ...pkgDevDeps };
+    if (deps.next) return "Next.js";
+    if (deps["@remix-run/react"]) return "Remix";
+    if (deps.gatsby) return "Gatsby";
+    if (deps.nuxt || deps["@nuxt/core"]) return "Nuxt.js";
+    if (deps.vue) return "Vue";
+    if (deps.react) return "React";
+    if (deps.svelte) return "Svelte";
+    if (deps.astro) return "Astro";
+    if (deps.solid || deps["solid-js"]) return "SolidJS";
+    if (deps.qwik || deps["@builder.io/qwik"]) return "Qwik";
+    if (deps.vite) return "Vite";
+    if (deps["@nestjs/core"]) return "NestJS";
+    if (deps.fastify) return "Fastify";
+    if (deps.express) return "Express";
+    if (deps.koa) return "Koa";
+    if (deps.hono) return "Hono";
+    if (deps["@hapi/hapi"]) return "Hapi";
+    if (deps["@modelcontextprotocol/sdk"]) return "MCP Server";
+    if (deps["@anthropic-ai/claude-agent-sdk"]) return "Claude Agent SDK";
+    if (deps.commander) return "Commander CLI";
+    if (deps.yargs) return "Yargs CLI";
+    if (deps["@oclif/core"] || deps.oclif) return "Oclif CLI";
+    if (deps.ink) return "Ink (React CLI)";
+    if (pkg.bin) return "CLI Tool";
+    if (pkg.main || pkg.exports) return "Library";
+  }
+  const subFrameworks = scanSubProjectFrameworks(root);
+  if (subFrameworks.length > 0) {
+    const freq = /* @__PURE__ */ new Map();
+    for (const fw of subFrameworks) {
+      freq.set(fw, (freq.get(fw) ?? 0) + 1);
+    }
+    const [topFw] = [...freq.entries()].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (topFw) return `${topFw} (monorepo)`;
+  }
+  return "unknown";
+}
+function scanSubProjectFrameworks(root) {
+  const frameworks = [];
   try {
-    sessionMemory.recordToolCall("execute_safe_test", { task, command });
-    const result = await executeWithTimeout(command, projectRoot, timeout);
-    const output = formatExecResult(result, command, task);
-    if (result.exitCode !== 0) {
-      sessionMemory.addFailedFile(task, result.stderr || result.stdout);
+    const entries = fs7.readdirSync(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const subDir = path7.join(root, entry.name);
+      const subPkg = readJsonSafe(path7.join(subDir, "package.json"));
+      if (!subPkg) continue;
+      const subDeps = { ...subPkg.dependencies ?? {}, ...subPkg.devDependencies ?? {} };
+      if (subDeps.next) frameworks.push("Next.js");
+      else if (subDeps.react) frameworks.push("React");
+      else if (subDeps.vue) frameworks.push("Vue");
+      else if (subDeps.svelte) frameworks.push("Svelte");
+      else if (subDeps.astro) frameworks.push("Astro");
+      else if (subDeps["@nestjs/core"]) frameworks.push("NestJS");
+      else if (subDeps.express) frameworks.push("Express");
+      else if (subDeps.hono) frameworks.push("Hono");
+      else if (subDeps.vite) frameworks.push("Vite");
+      else if (subDeps["@modelcontextprotocol/sdk"]) frameworks.push("MCP Server");
     }
-    return output;
-  } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
-    const isTimeout = errorMsg.toLowerCase().includes("timeout");
-    if (isTimeout) {
-      return formatTimeoutResult(command, timeout);
+  } catch {
+  }
+  return frameworks;
+}
+function detectProjectType(root) {
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (pkg) {
+    const pkgDeps = pkg.dependencies ?? {};
+    const pkgDevDeps = pkg.devDependencies ?? {};
+    const deps = { ...pkgDeps, ...pkgDevDeps };
+    if (deps["@modelcontextprotocol/sdk"]) return "mcp-server";
+    if (deps.next || deps.react || deps.vue || deps.svelte || deps.astro || deps.gatsby || deps.nuxt || deps["@remix-run/react"] || deps.solid) {
+      return "web-app";
     }
-    return `Error running "${command}": ${errorMsg}`;
+    if (deps.express || deps.fastify || deps.koa || deps.hono || deps["@nestjs/core"] || deps["@hapi/hapi"]) {
+      return "backend";
+    }
+    if (deps.commander || deps.yargs || deps["@oclif/core"] || deps.oclif || deps.ink) {
+      return "cli";
+    }
+    if (pkg.bin) return "cli";
+    if (pkg.main || pkg.exports) return "library";
   }
+  const subFrameworks = scanSubProjectFrameworks(root);
+  if (subFrameworks.length > 0) return "web-app";
+  return "unknown";
 }
-async function executeWithTimeout(command, cwd, timeoutSeconds) {
-  return new Promise((resolve, reject) => {
-    const parts = command.split(" ");
-    const cmd = parts[0];
-    const args = parts.slice(1);
-    const proc = spawn(cmd, args, {
-      cwd,
-      shell: process.platform === "win32",
-      // Use shell on Windows
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: timeoutSeconds * 1e3
-    });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    const timeoutId = setTimeout(() => {
-      timedOut = true;
-      proc.kill("SIGTERM");
-      if (process.platform === "win32") {
-        try {
-          spawn("taskkill", ["/pid", String(proc.pid), "/f", "/t"], { stdio: "ignore" });
-        } catch {
-        }
-      }
-    }, timeoutSeconds * 1e3);
-    proc.stdout?.on("data", (data) => {
-      stdout += data.toString();
-    });
-    proc.stderr?.on("data", (data) => {
-      stderr += data.toString();
-    });
-    proc.on("close", (code) => {
-      clearTimeout(timeoutId);
-      resolve({
-        stdout: truncateOutput(stdout, 5e3),
-        stderr: truncateOutput(stderr, 2e3),
-        exitCode: code ?? -1,
-        timedOut
+function detectWorkspaces(root) {
+  const results = [];
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  const pnpmWorkspace = readYamlLite(path7.join(root, "pnpm-workspace.yaml"));
+  const patterns = /* @__PURE__ */ new Set();
+  const pkgWorkspaces = pkg?.workspaces;
+  if (Array.isArray(pkgWorkspaces)) {
+    for (const p of pkgWorkspaces) if (typeof p === "string") patterns.add(p);
+  } else if (pkgWorkspaces && typeof pkgWorkspaces === "object") {
+    const packages = pkgWorkspaces.packages;
+    if (Array.isArray(packages)) {
+      for (const p of packages) if (typeof p === "string") patterns.add(p);
+    }
+  }
+  if (Array.isArray(pnpmWorkspace?.packages)) {
+    for (const p of pnpmWorkspace.packages) if (typeof p === "string") patterns.add(p);
+  }
+  patterns.add("apps/*");
+  patterns.add("packages/*");
+  patterns.add("services/*");
+  for (const pattern of patterns) {
+    const match = pattern.match(/^([^*]+)\/\*$/);
+    if (!match) continue;
+    const dir = path7.join(root, match[1]);
+    if (!fs7.existsSync(dir)) continue;
+    let entries = [];
+    try {
+      entries = fs7.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const pkgPath = path7.join(dir, entry.name, "package.json");
+      const subPkg = readJsonSafe(pkgPath);
+      if (!subPkg) continue;
+      const workspacePath = path7.join(dir, entry.name);
+      results.push({
+        path: path7.relative(root, workspacePath),
+        name: subPkg.name ?? entry.name,
+        framework: detectFramework(workspacePath),
+        packageManager: detectPackageManagerForDir(workspacePath)
       });
-    });
-    proc.on("error", (err) => {
-      clearTimeout(timeoutId);
-      reject(err);
-    });
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return results.filter((w) => {
+    if (seen.has(w.path)) return false;
+    seen.add(w.path);
+    return true;
   });
 }
-function truncateOutput(output, maxChars) {
-  if (output.length <= maxChars) return output;
-  return output.slice(0, maxChars) + `
-
-[...truncated, ${output.length - maxChars} more characters]`;
-}
-function formatExecResult(result, command, task) {
-  const status = result.exitCode === 0 ? "\u2705 PASS" : "\u274C FAIL";
-  const lines = [
-    `\u{1F4BB} ${status} \u2014 Task: ${task}`,
-    `$ ${command}`,
-    `Exit code: ${result.exitCode}`,
-    `Duration: ${result.timedOut ? "TIMEOUT" : "completed"}`,
-    ""
-  ];
-  if (result.stdout.trim()) {
-    lines.push("\u{1F4E4} STDOUT:", "```", result.stdout, "```", "");
-  }
-  if (result.stderr.trim()) {
-    lines.push("\u{1F4E4} STDERR:", "```", result.stderr, "```", "");
+function readYamlLite(filePath) {
+  try {
+    if (!fs7.existsSync(filePath)) return null;
+    const text = fs7.readFileSync(filePath, "utf-8");
+    const packages = [];
+    let inPackages = false;
+    for (const rawLine of text.split("\n")) {
+      const line = rawLine.replace(/#.*$/, "").trimEnd();
+      if (/^packages:\s*$/.test(line)) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        const m = line.match(/^\s*-\s*['"]?([^'"]+)['"]?\s*$/);
+        if (m) packages.push(m[1]);
+        else if (/^\S/.test(line)) inPackages = false;
+      }
+    }
+    return { packages };
+  } catch {
+    return null;
+  }
+}
+function detectTestRunner(root) {
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (!pkg) return "unknown";
+  const pkgDeps2 = pkg.dependencies ?? {};
+  const pkgDevDeps2 = pkg.devDependencies ?? {};
+  const deps = { ...pkgDeps2, ...pkgDevDeps2 };
+  if (deps.vitest) return "Vitest";
+  if (deps.jest) return "Jest";
+  if (deps.mocha) return "Mocha";
+  if (deps.ava) return "AVA";
+  if (deps.cypress) return "Cypress";
+  if (deps.playwright) return "Playwright";
+  if (deps["@testing-library/react"]) return "React Testing Library";
+  const scripts = pkg.scripts ?? {};
+  if (scripts.test) {
+    if (scripts.test.includes("vitest")) return "Vitest";
+    if (scripts.test.includes("jest")) return "Jest";
+    if (scripts.test.includes("mocha")) return "Mocha";
+  }
+  return "unknown";
+}
+function detectStyling(root) {
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (!pkg) return "unknown";
+  const pkgDeps3 = pkg.dependencies ?? {};
+  const pkgDevDeps3 = pkg.devDependencies ?? {};
+  const deps = { ...pkgDeps3, ...pkgDevDeps3 };
+  if (deps.tailwindcss) return "Tailwind CSS";
+  if (deps["styled-components"]) return "Styled Components";
+  if (deps["@emotion/react"]) return "Emotion";
+  if (deps.linaria) return "Linaria";
+  if (deps.sass || deps["node-sass"]) return "SCSS";
+  if (deps.less) return "Less";
+  if (deps["@vanilla-extract/css"]) return "Vanilla Extract";
+  if (deps.cssmodules || hasCSSModules(root)) return "CSS Modules";
+  const srcDir = path7.join(root, "src");
+  if (fs7.existsSync(srcDir)) {
+    const cssFiles = findFiles(srcDir, [".css", ".scss", ".less"]);
+    if (cssFiles.length > 0) return "Plain CSS/SCSS";
+  }
+  return "unknown";
+}
+function detectImportAlias(root) {
+  const tsconfig = readJsonSafe(path7.join(root, "tsconfig.json"));
+  const tsconfigPaths = tsconfig?.compilerOptions;
+  if (tsconfigPaths?.paths) {
+    const paths = tsconfigPaths.paths;
+    const alias = Object.keys(paths)[0];
+    if (alias) return alias.replace("/*", "");
+  }
+  const jsconfig = readJsonSafe(path7.join(root, "jsconfig.json"));
+  const jsconfigPaths = jsconfig?.compilerOptions;
+  if (jsconfigPaths?.paths) {
+    const paths = jsconfigPaths.paths;
+    const alias = Object.keys(paths)[0];
+    if (alias) return alias.replace("/*", "");
+  }
+  return void 0;
+}
+function detectLintRules(root) {
+  const rules = [];
+  if (fs7.existsSync(path7.join(root, ".eslintrc"))) rules.push("ESLint (.eslintrc)");
+  if (fs7.existsSync(path7.join(root, ".eslintrc.js"))) rules.push("ESLint (.eslintrc.js)");
+  if (fs7.existsSync(path7.join(root, ".eslintrc.json"))) rules.push("ESLint (.eslintrc.json)");
+  if (fs7.existsSync(path7.join(root, "eslint.config.js"))) rules.push("ESLint (flat config)");
+  if (fs7.existsSync(path7.join(root, ".prettierrc"))) rules.push("Prettier");
+  if (fs7.existsSync(path7.join(root, ".prettierrc.json"))) rules.push("Prettier");
+  if (fs7.existsSync(path7.join(root, ".prettierrc.js"))) rules.push("Prettier");
+  if (fs7.existsSync(path7.join(root, ".stylelintrc"))) rules.push("StyleLint");
+  if (fs7.existsSync(path7.join(root, ".stylelintrc.json"))) rules.push("StyleLint");
+  return rules;
+}
+function detectPackageManager() {
+  const root = getProjectRoot();
+  return detectPackageManagerForDir(root);
+}
+function detectPackageManagerForDir(dir) {
+  const root = getProjectRoot();
+  let currentDir = path7.resolve(dir);
+  while (currentDir.startsWith(root)) {
+    if (fs7.existsSync(path7.join(currentDir, "pnpm-lock.yaml"))) return "pnpm";
+    if (fs7.existsSync(path7.join(currentDir, "yarn.lock"))) return "yarn";
+    if (fs7.existsSync(path7.join(currentDir, "package-lock.json"))) return "npm";
+    if (fs7.existsSync(path7.join(currentDir, "bun.lockb"))) return "bun";
+    if (currentDir === root) break;
+    currentDir = path7.dirname(currentDir);
+  }
+  return "npm";
+}
+function detectModuleSystem(root) {
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (pkg?.type === "module") return "esm";
+  const srcDir = path7.join(root, "src");
+  if (fs7.existsSync(srcDir)) {
+    const tsFiles = findFiles(srcDir, [".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+    for (const file of tsFiles.slice(0, 20)) {
+      try {
+        const content = fs7.readFileSync(file, "utf-8");
+        if (content.includes("import ") || content.includes("export ")) return "esm";
+      } catch {
+        continue;
+      }
+    }
+  }
+  return "cjs";
+}
+function detectLanguage(root) {
+  if (fs7.existsSync(path7.join(root, "tsconfig.json"))) return "typescript";
+  const srcDir = path7.join(root, "src");
+  if (fs7.existsSync(srcDir)) {
+    const tsFiles = findFiles(srcDir, [".ts", ".tsx"]);
+    if (tsFiles.length > 0) return "typescript";
+  }
+  return "javascript";
+}
+function detectFeatures(root) {
+  const features = [];
+  const pkg = readJsonSafe(path7.join(root, "package.json"));
+  if (!pkg) return features;
+  const pkgDeps4 = pkg.dependencies ?? {};
+  const pkgDevDeps4 = pkg.devDependencies ?? {};
+  const deps = { ...pkgDeps4, ...pkgDevDeps4 };
+  if (deps["@prisma/client"] || deps.prisma) features.push("Prisma ORM");
+  if (deps.typeorm) features.push("TypeORM");
+  if (deps["drizzle-orm"]) features.push("Drizzle ORM");
+  if (deps.graphql || deps["@graphql-tools"]) features.push("GraphQL");
+  if (deps.trpc || deps["@trpc/client"]) features.push("tRPC");
+  if (deps["socket.io"] || deps.ws) features.push("WebSockets");
+  if (deps["@reduxjs/toolkit"] || deps.redux) features.push("Redux");
+  if (deps.zustand) features.push("Zustand");
+  if (deps["react-router"] || deps["react-router-dom"]) features.push("React Router");
+  if (deps["next-auth"] || deps["next-auth/react"]) features.push("NextAuth");
+  if (deps["@tanstack/react-query"]) features.push("React Query");
+  if (deps.jest || deps.vitest) features.push("Unit Testing");
+  if (deps.cypress || deps.playwright) features.push("E2E Testing");
+  if (deps.storybook || deps["@storybook/react"]) features.push("Storybook");
+  if (deps.i18next || deps["react-i18next"]) features.push("i18n");
+  return features;
+}
+function readJsonSafe(filePath) {
+  try {
+    if (fs7.existsSync(filePath)) {
+      return JSON.parse(fs7.readFileSync(filePath, "utf-8"));
+    }
+  } catch {
+  }
+  return null;
+}
+function hasCSSModules(root) {
+  const srcDir = path7.join(root, "src");
+  if (!fs7.existsSync(srcDir)) return false;
+  const files = findFiles(srcDir, [".module.css", ".module.scss", ".module.less"]);
+  return files.length > 0;
+}
+function findFiles(dir, extensions) {
+  const results = [];
+  try {
+    const entries = fs7.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path7.join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        results.push(...findFiles(fullPath, extensions));
+      } else if (entry.isFile()) {
+        if (extensions.some((ext) => entry.name.endsWith(ext))) {
+          results.push(fullPath);
+        }
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+
+// src/utils/processRunner.ts
+import { spawn } from "child_process";
+var DEFAULT_MAX_STDOUT = 5e3;
+var DEFAULT_MAX_STDERR = 2e3;
+var DEFAULT_TIMEOUT = 60;
+function spawnProcess(command, options) {
+  const {
+    cwd,
+    timeoutSeconds = DEFAULT_TIMEOUT,
+    useShell = false,
+    maxStdout = DEFAULT_MAX_STDOUT,
+    maxStderr = DEFAULT_MAX_STDERR
+  } = options;
+  return new Promise((resolve) => {
+    const parts = command.split(" ");
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    const proc = spawn(cmd, args, {
+      cwd,
+      shell: useShell,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      proc.kill("SIGTERM");
+      if (process.platform === "win32") {
+        try {
+          spawn("taskkill", ["/pid", String(proc.pid), "/f", "/t"], {
+            stdio: "ignore"
+          });
+        } catch {
+        }
+      }
+    }, timeoutSeconds * 1e3);
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timeoutId);
+      resolve({
+        stdout: truncateOutput(stdout, maxStdout),
+        stderr: truncateOutput(stderr, maxStderr),
+        exitCode: code ?? -1,
+        timedOut
+      });
+    });
+    proc.on("error", () => {
+      clearTimeout(timeoutId);
+      resolve({
+        stdout,
+        stderr: `Failed to spawn process: ${cmd}`,
+        exitCode: -1,
+        timedOut: false
+      });
+    });
+  });
+}
+function spawnShell(command, options) {
+  return spawnProcess(command, { ...options, useShell: true });
+}
+function truncateOutput(output, maxChars) {
+  if (output.length <= maxChars) return output;
+  return output.slice(0, maxChars) + `
+
+[...truncated, ${output.length - maxChars} more characters]`;
+}
+
+// src/tools/safeTerminalExec.ts
+function buildTaskCommand(task, cwd) {
+  const pm = detectPackageManagerForDir(cwd);
+  const prefix = pm === "pnpm" ? "pnpm" : pm === "yarn" ? "yarn" : pm === "bun" ? "bun" : "npm";
+  const npx = pm === "pnpm" ? "pnpm" : pm === "bun" ? "bunx" : "npx";
+  switch (task) {
+    case "test":
+      return `${prefix} test`;
+    case "build":
+      return `${prefix} run build`;
+    case "lint":
+      return `${prefix} run lint`;
+    case "typecheck":
+      return `${npx} tsc --noEmit`;
+    default:
+      return `${prefix} test`;
+  }
+}
+var DANGEROUS_PATTERNS = [
+  "rm -rf",
+  "rm -fr",
+  "del /f",
+  "rd /s",
+  "rmdir /s",
+  "git push",
+  "git commit",
+  "npm publish",
+  "npx publish",
+  "yarn publish",
+  "pnpm publish",
+  "> /dev/sda",
+  "format",
+  "mkfs",
+  "dd if=",
+  ":(){ :|:& };:",
+  "curl ",
+  "wget "
+];
+async function handleSafeTerminalExec(params) {
+  const { task, customCommand, timeout = 60, cwd: inputCwd, workspace } = params;
+  if (task === "custom" && !customCommand) {
+    return "Error: Task 'custom' requires the 'customCommand' parameter.";
+  }
+  const projectRoot = getProjectRoot();
+  let workingDir = projectRoot;
+  let resolvedFrom = "root";
+  if (workspace) {
+    const conventions = sessionMemory.getConventions();
+    const workspaces = conventions?.workspaces;
+    const matched = workspaces?.find((w) => w.name === workspace || w.path === workspace);
+    if (matched) {
+      workingDir = path8.resolve(projectRoot, matched.path);
+      resolvedFrom = `workspace "${matched.name}" \u2192 ${matched.path}`;
+    } else {
+      return `\u26A0\uFE0F Workspace "${workspace}" not found. Run project_conventions first to detect workspaces, or use 'cwd' parameter with a direct path.
+
+Available workspaces: ${workspaces?.map((w) => `"${w.name}" (${w.path})`).join(", ") || "none detected"}`;
+    }
+  } else if (inputCwd) {
+    const resolved = path8.resolve(projectRoot, inputCwd);
+    const normalizedResolved = path8.normalize(resolved).toLowerCase();
+    const normalizedRoot = path8.normalize(projectRoot).toLowerCase();
+    if (!normalizedResolved.startsWith(normalizedRoot)) {
+      return `\u{1F6AB} BLOCKED: Path "${inputCwd}" resolves outside project root "${projectRoot}".`;
+    }
+    if (!fs8.existsSync(resolved)) {
+      return `\u26A0\uFE0F Directory "${inputCwd}" does not exist at "${resolved}".`;
+    }
+    workingDir = resolved;
+    resolvedFrom = `cwd: ${inputCwd}`;
+  }
+  const command = task === "custom" ? customCommand : buildTaskCommand(task, workingDir);
+  const cbResult = circuitBreaker.check("safe_terminal_exec", { task, command });
+  if (!cbResult.allowed) {
+    return `\u26A0\uFE0F Circuit breaker: ${cbResult.reason}
+
+Fix the code first before running the task again.`;
+  }
+  const dangerousPattern = DANGEROUS_PATTERNS.find((p) => command.toLowerCase().includes(p.toLowerCase()));
+  if (dangerousPattern) {
+    return `\u{1F6AB} BLOCKED: Command contains a dangerous pattern: "${dangerousPattern}".
+This command is not permitted.`;
+  }
+  try {
+    sessionMemory.recordToolCall("execute_safe_test", { task, command, cwd: workingDir });
+    const result = await spawnShell(command, {
+      cwd: workingDir,
+      timeoutSeconds: timeout
+    });
+    const output = formatExecResult(result, command, task, resolvedFrom);
+    if (result.exitCode !== 0) {
+      sessionMemory.addFailedFile(task, result.stderr || result.stdout);
+    }
+    return output;
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    if (errorMsg.toLowerCase().includes("timeout")) {
+      return formatTimeoutResult(command, timeout);
+    }
+    return `Error running "${command}": ${errorMsg}`;
+  }
+}
+function formatExecResult(result, command, task, resolvedFrom) {
+  const status = result.exitCode === 0 ? "\u2705 PASS" : "\u274C FAIL";
+  const lines = [
+    `\u{1F4BB} ${status} \u2014 Task: ${task}`,
+    `$ ${command}`,
+    ...resolvedFrom ? [`\u{1F4CD} ${resolvedFrom}`] : [],
+    `Exit code: ${result.exitCode}`,
+    `Duration: ${result.timedOut ? "TIMEOUT" : "completed"}`,
+    ""
+  ];
+  if (result.stdout.trim()) {
+    lines.push("\u{1F4E4} STDOUT:", "```", result.stdout, "```", "");
+  }
+  if (result.stderr.trim()) {
+    lines.push("\u{1F4E4} STDERR:", "```", result.stderr, "```", "");
   }
   if (result.exitCode !== 0) {
     lines.push(
@@ -1741,8 +2204,8 @@ function formatTimeoutResult(command, timeout) {
 }
 
 // src/agents/codeReviewer.ts
-import fs7 from "fs";
-import path7 from "path";
+import fs9 from "fs";
+import path9 from "path";
 import { execSync } from "child_process";
 var CODE_EXTENSIONS = [
   ".ts",
@@ -1774,7 +2237,7 @@ function getGitChangedFiles() {
       if (filePath.startsWith('"') && filePath.endsWith('"')) {
         filePath = filePath.substring(1, filePath.length - 1);
       }
-      const ext = path7.extname(filePath).toLowerCase();
+      const ext = path9.extname(filePath).toLowerCase();
       if (CODE_EXTENSIONS.includes(ext)) files.push(filePath);
     }
     return files.slice(0, 10);
@@ -1811,7 +2274,7 @@ Pass an explicit 'files' array to review specific files.`;
       continue;
     }
     const resolvedPath = validation.resolvedPath;
-    if (!fs7.existsSync(resolvedPath)) {
+    if (!fs9.existsSync(resolvedPath)) {
       allIssues.push({
         file: filePath,
         line: 0,
@@ -1823,7 +2286,7 @@ Pass an explicit 'files' array to review specific files.`;
       continue;
     }
     try {
-      const content = fs7.readFileSync(resolvedPath, "utf-8");
+      const content = fs9.readFileSync(resolvedPath, "utf-8");
       filesReviewed++;
       checkGeneral(filePath, content, allIssues);
       switch (focus) {
@@ -1917,7 +2380,7 @@ function isTestFile(filePath) {
   return /\.(test|spec)\.[a-z]+$/i.test(filePath) || /__tests__/.test(filePath);
 }
 function isTsLike(filePath) {
-  const ext = path7.extname(filePath).toLowerCase();
+  const ext = path9.extname(filePath).toLowerCase();
   return ext === ".ts" || ext === ".tsx";
 }
 function checkGeneral(filePath, content, issues) {
@@ -2249,567 +2712,212 @@ function checkPerformance(filePath, content, issues) {
         file: filePath,
         line: lineNum,
         severity: "info",
-        rule: "perf/spread-in-loop",
-        message: "Spread inside a loop is O(n)",
-        suggestion: "Use push() or concat() to grow arrays in loops"
-      });
-    }
-    if (/\b(readFileSync|writeFileSync|existsSync)\s*\(/.test(line) && /\b(for|while|forEach|map)\b/.test(lines[Math.max(0, i - 2)] + lines[Math.max(0, i - 1)] + lines[i])) {
-      issues.push({
-        file: filePath,
-        line: lineNum,
-        severity: "warning",
-        rule: "perf/sync-io-in-loop",
-        message: "Synchronous I/O inside a loop",
-        suggestion: "Use the async variant and await in parallel where safe"
-      });
-    }
-  }
-}
-function checkOverEngineering(filePath, content, issues) {
-  const lines = content.split("\n");
-  const text = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
-  const classBodies = findBlockBodies(lines, /^\s*(export\s+)?(abstract\s+)?class\s+\w+/);
-  for (const { body, nameLine, name } of classBodies) {
-    const methodCount = (body.match(/^\s*(public|private|protected|static|async)?\s*\w+\s*\([^)]*\)\s*{/gm) || []).length;
-    if (methodCount <= 1 && body.length > 0) {
-      const trimmed = body.trim();
-      const nonEmptyLines = trimmed ? trimmed.split("\n").filter((l) => l.trim()).length : 0;
-      if (nonEmptyLines <= 3) {
-        issues.push({
-          file: filePath,
-          line: nameLine,
-          severity: "info",
-          rule: "over-engineering/wrapper-class",
-          message: `Class "${name}" has only 1 method \u2014 likely a wrapper that could be a plain function`,
-          suggestion: "Replace with a standalone function or a utility module export"
-        });
-      }
-    }
-  }
-  const factoryMatches = text.matchAll(/^\s*(export\s+)?function\s+(create\w+|make\w+|build\w+|factory\w+)\s*\(/gm);
-  for (const match of factoryMatches) {
-    const funcName = match[2];
-    const body = extractBodyAfter(lines, match);
-    const creationCount = (body.match(/\bnew\s+\w+/g) || []).length;
-    if (creationCount <= 1) {
-      issues.push({
-        file: filePath,
-        line: lines.findIndex((l) => l.includes(funcName)) + 1,
-        severity: "warning",
-        rule: "over-engineering/single-product-factory",
-        message: `Factory "${funcName}" produces only 1 product \u2014 unnecessary abstraction`,
-        suggestion: "Inline the construction or drop the factory pattern"
-      });
-    }
-  }
-  const interfaceNames = [];
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/^\s*(export\s+)?interface\s+(\w+)/);
-    if (m) interfaceNames.push(m[2]);
-  }
-  for (const iface of interfaceNames) {
-    const implCount = (text.match(new RegExp(`implements\\s+.*\\b${iface}\\b`, "g")) || []).length;
-    if (implCount <= 1) {
-      const lineNum = lines.findIndex((l) => l.includes(`interface ${iface}`)) + 1;
-      issues.push({
-        file: filePath,
-        line: lineNum,
-        severity: "info",
-        rule: "over-engineering/single-impl-interface",
-        message: `Interface "${iface}" has only 1 implementation \u2014 unnecessary unless more planned`,
-        suggestion: "Remove the interface or inline the type"
-      });
-    }
-  }
-  const configObjPattern = /^\s*(export\s+)?(const|let|var)\s+(\w+)\s*[=:]\s*\{/;
-  for (let i = 0; i < lines.length; i++) {
-    const cm = lines[i].match(configObjPattern);
-    if (!cm || !/config|setting|option|default/i.test(cm[3])) continue;
-    const configName = cm[3];
-    const refs = (text.match(new RegExp(`\\b${configName}\\b`, "g")) || []).length;
-    if (refs <= 2) {
-      issues.push({
-        file: filePath,
-        line: i + 1,
-        severity: "info",
-        rule: "over-engineering/unused-config",
-        message: `Config "${configName}" is referenced ${refs === 0 ? "nowhere" : `only ${refs - 1}x outside definition`}`,
-        suggestion: refs === 0 ? "Remove the dead config" : "Inline the value or remove if unused elsewhere"
-      });
-    }
-  }
-  const stdlibPatterns = [
-    { pattern: /function\s+\w+\s*\([^)]*\)\s*\{[^}]*fs\.readFileSync[^}]*\}/, rule: "over-engineering/hand-rolled-file-read", msg: "Hand-rolled file reader \u2014 use fs.readFileSync directly", suggestion: "Call fs.readFileSync directly instead of wrapping" },
-    { pattern: /function\s+\w+\s*\([^)]*\)\s*\{[^}]*crypto\.createHash[^}]*\}/, rule: "over-engineering/hand-rolled-hash", msg: "Hand-rolled hash \u2014 use crypto directly", suggestion: "Call crypto.createHash directly" },
-    { pattern: /function\s+uuid\s*\(|function\s+generateId\s*\(/, rule: "over-engineering/hand-rolled-uuid", msg: "Hand-rolled UUID \u2014 use crypto.randomUUID()", suggestion: "Replace with crypto.randomUUID() (Node 19+) or the uuid package" },
-    { pattern: /function\s+debounce\s*\(|function\s+throttle\s*\(/, rule: "over-engineering/hand-rolled-debounce", msg: "Hand-rolled debounce/throttle \u2014 utility lib or native", suggestion: "Use lodash.debounce or a 3-line inline version" }
-  ];
-  for (const sp of stdlibPatterns) {
-    const sl = text.match(sp.pattern);
-    if (sl) {
-      const matchIndex = sl.index ?? 0;
-      const preText = text.substring(0, matchIndex);
-      const lineNum = preText.split("\n").length;
-      issues.push({
-        file: filePath,
-        line: lineNum,
-        severity: "info",
-        rule: sp.rule,
-        message: sp.msg,
-        suggestion: sp.suggestion
+        rule: "perf/spread-in-loop",
+        message: "Spread inside a loop is O(n)",
+        suggestion: "Use push() or concat() to grow arrays in loops"
       });
     }
-  }
-  const exportDecls = [];
-  for (let i = 0; i < lines.length; i++) {
-    const ed = lines[i].match(/^\s*export\s+(const|let|var|function|class)\s+(\w+)/);
-    if (ed) exportDecls.push({ name: ed[2], line: i + 1 });
-  }
-  for (const decl of exportDecls) {
-    const refCount = (text.match(new RegExp(`\\b${decl.name}\\b`, "g")) || []).length;
-    const isReactComponent = /^[A-Z]/.test(decl.name) && /return\s+<|React\./.test(text);
-    if (refCount <= 1 && decl.name !== "default" && !isReactComponent) {
+    if (/\b(readFileSync|writeFileSync|existsSync)\s*\(/.test(line) && /\b(for|while|forEach|map)\b/.test(lines[Math.max(0, i - 2)] + lines[Math.max(0, i - 1)] + lines[i])) {
       issues.push({
         file: filePath,
-        line: decl.line,
-        severity: "info",
-        rule: "over-engineering/unused-export",
-        message: `"${decl.name}" is exported but referenced only in its declaration`,
-        suggestion: "Check if it is imported elsewhere; if not, remove or inline"
+        line: lineNum,
+        severity: "warning",
+        rule: "perf/sync-io-in-loop",
+        message: "Synchronous I/O inside a loop",
+        suggestion: "Use the async variant and await in parallel where safe"
       });
     }
   }
 }
-function findBlockBodies(lines, startPattern) {
-  const results = [];
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(startPattern);
-    if (!m) continue;
-    const name = m[0].match(/class\s+(\w+)/)?.[1] ?? "Unknown";
-    const body = collectBlockLines(lines, i);
-    results.push({ body: body.join("\n"), nameLine: i + 1, name });
-  }
-  return results;
-}
-function collectBlockLines(lines, startIdx) {
-  let depth = 0;
-  let started = false;
-  const block = [];
-  for (let j = startIdx; j < lines.length; j++) {
-    const line = lines[j];
-    block.push(line);
-    for (const ch of line) {
-      if (ch === "{") {
-        depth++;
-        started = true;
-      } else if (ch === "}") depth--;
-    }
-    if (started && depth <= 0) break;
-  }
-  return block;
-}
-function extractBodyAfter(lines, match) {
-  const startIdx = lines.findIndex((l) => l.includes(match[0].trim().split(/\s+/).pop() ?? ""));
-  if (startIdx < 0) return "";
-  return collectBlockLines(lines, startIdx).join("\n");
-}
-function formatReviewOutput(issues, filesReviewed, totalFiles, focus, customCriteria, autoDetected) {
-  const errors = issues.filter((i) => i.severity === "error");
-  const warnings = issues.filter((i) => i.severity === "warning");
-  const infos = issues.filter((i) => i.severity === "info");
-  const lines = [
-    `\u{1F50D} **Code Review \u2014 Focus: ${focus}**`,
-    ...focus === "over-engineering" ? ["\u{1F4A1} **The Ladder:** 1. Does this code need to exist? 2. Does stdlib cover it? 3. Is there a one-liner? 4. Only then, write it."] : [],
-    ...autoDetected ? [`\u{1F4C2} Auto-detected ${totalFiles} changed file(s) from git`] : [],
-    ...customCriteria ? [`\u{1F4CB} **Custom Criteria:** ${customCriteria}`] : [],
-    `\u{1F4C1} ${filesReviewed}/${totalFiles} files reviewed`,
-    `\u{1F534} ${errors.length} errors | \u{1F7E1} ${warnings.length} warnings | \u{1F535} ${infos.length} info`,
-    ""
-  ];
-  if (issues.length === 0) {
-    lines.push("\u2705 No issues found.");
-    return lines.join("\n");
-  }
-  const grouped = /* @__PURE__ */ new Map();
-  for (const issue of issues) {
-    const existing = grouped.get(issue.file) ?? [];
-    existing.push(issue);
-    grouped.set(issue.file, existing);
-  }
-  for (const [file, fileIssues] of grouped) {
-    lines.push(`**\u{1F4C4} ${file}:**`);
-    for (const issue of fileIssues) {
-      const icon = issue.severity === "error" ? "\u{1F534}" : issue.severity === "warning" ? "\u{1F7E1}" : "\u{1F535}";
-      lines.push(`  ${icon} [L${issue.line}] [${issue.rule}] ${issue.message}`);
-      if (issue.suggestion) lines.push(`     \u{1F4A1} ${issue.suggestion}`);
-    }
-    lines.push("");
-  }
-  if (errors.length > 0) {
-    lines.push("\u26A0\uFE0F Fix errors first, then warnings.");
-    lines.push("\u{1F4A1} Use precise_diff_editor to apply fixes.");
-  } else if (warnings.length > 0) {
-    lines.push("\u{1F4A1} Address warnings before merging.");
-  } else {
-    lines.push("\u2705 Only informational issues \u2014 ready for testing.");
-  }
-  return lines.join("\n");
-}
-
-// src/utils/conventionsDetector.ts
-import fs8 from "fs";
-import path8 from "path";
-var cachedConventions = null;
-async function detectConventions(forceRescan = false) {
-  if (cachedConventions && !forceRescan) {
-    return cachedConventions;
-  }
-  const projectRoot = getProjectRoot();
-  const workspaces = detectWorkspaces(projectRoot);
-  const conventions = {
-    framework: detectFramework(projectRoot),
-    projectType: detectProjectType(projectRoot),
-    testRunner: detectTestRunner(projectRoot),
-    styling: detectStyling(projectRoot),
-    importAlias: detectImportAlias(projectRoot),
-    lintRules: detectLintRules(projectRoot),
-    packageManager: detectPackageManager(),
-    moduleSystem: detectModuleSystem(projectRoot),
-    language: detectLanguage(projectRoot),
-    features: detectFeatures(projectRoot),
-    isMonorepo: workspaces.length > 0,
-    workspaces
-  };
-  cachedConventions = conventions;
-  return conventions;
-}
-function detectFramework(root) {
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (pkg) {
-    const pkgDeps = pkg.dependencies ?? {};
-    const pkgDevDeps = pkg.devDependencies ?? {};
-    const deps = { ...pkgDeps, ...pkgDevDeps };
-    if (deps.next) return "Next.js";
-    if (deps["@remix-run/react"]) return "Remix";
-    if (deps.gatsby) return "Gatsby";
-    if (deps.nuxt || deps["@nuxt/core"]) return "Nuxt.js";
-    if (deps.vue) return "Vue";
-    if (deps.react) return "React";
-    if (deps.svelte) return "Svelte";
-    if (deps.astro) return "Astro";
-    if (deps.solid || deps["solid-js"]) return "SolidJS";
-    if (deps.qwik || deps["@builder.io/qwik"]) return "Qwik";
-    if (deps.vite) return "Vite";
-    if (deps["@nestjs/core"]) return "NestJS";
-    if (deps.fastify) return "Fastify";
-    if (deps.express) return "Express";
-    if (deps.koa) return "Koa";
-    if (deps.hono) return "Hono";
-    if (deps["@hapi/hapi"]) return "Hapi";
-    if (deps["@modelcontextprotocol/sdk"]) return "MCP Server";
-    if (deps["@anthropic-ai/claude-agent-sdk"]) return "Claude Agent SDK";
-    if (deps.commander) return "Commander CLI";
-    if (deps.yargs) return "Yargs CLI";
-    if (deps["@oclif/core"] || deps.oclif) return "Oclif CLI";
-    if (deps.ink) return "Ink (React CLI)";
-    if (pkg.bin) return "CLI Tool";
-    if (pkg.main || pkg.exports) return "Library";
-  }
-  const subFrameworks = scanSubProjectFrameworks(root);
-  if (subFrameworks.length > 0) {
-    const freq = /* @__PURE__ */ new Map();
-    for (const fw of subFrameworks) {
-      freq.set(fw, (freq.get(fw) ?? 0) + 1);
-    }
-    const [topFw] = [...freq.entries()].sort((a, b) => b[1] - a[1])[0] ?? [];
-    if (topFw) return `${topFw} (monorepo)`;
-  }
-  return "unknown";
-}
-function scanSubProjectFrameworks(root) {
-  const frameworks = [];
-  try {
-    const entries = fs8.readdirSync(root, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const subDir = path8.join(root, entry.name);
-      const subPkg = readJsonSafe(path8.join(subDir, "package.json"));
-      if (!subPkg) continue;
-      const subDeps = { ...subPkg.dependencies ?? {}, ...subPkg.devDependencies ?? {} };
-      if (subDeps.next) frameworks.push("Next.js");
-      else if (subDeps.react) frameworks.push("React");
-      else if (subDeps.vue) frameworks.push("Vue");
-      else if (subDeps.svelte) frameworks.push("Svelte");
-      else if (subDeps.astro) frameworks.push("Astro");
-      else if (subDeps["@nestjs/core"]) frameworks.push("NestJS");
-      else if (subDeps.express) frameworks.push("Express");
-      else if (subDeps.hono) frameworks.push("Hono");
-      else if (subDeps.vite) frameworks.push("Vite");
-      else if (subDeps["@modelcontextprotocol/sdk"]) frameworks.push("MCP Server");
-    }
-  } catch {
-  }
-  return frameworks;
-}
-function detectProjectType(root) {
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (pkg) {
-    const pkgDeps = pkg.dependencies ?? {};
-    const pkgDevDeps = pkg.devDependencies ?? {};
-    const deps = { ...pkgDeps, ...pkgDevDeps };
-    if (deps["@modelcontextprotocol/sdk"]) return "mcp-server";
-    if (deps.next || deps.react || deps.vue || deps.svelte || deps.astro || deps.gatsby || deps.nuxt || deps["@remix-run/react"] || deps.solid) {
-      return "web-app";
-    }
-    if (deps.express || deps.fastify || deps.koa || deps.hono || deps["@nestjs/core"] || deps["@hapi/hapi"]) {
-      return "backend";
-    }
-    if (deps.commander || deps.yargs || deps["@oclif/core"] || deps.oclif || deps.ink) {
-      return "cli";
+function checkOverEngineering(filePath, content, issues) {
+  const lines = content.split("\n");
+  const text = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  const classBodies = findBlockBodies(lines, /^\s*(export\s+)?(abstract\s+)?class\s+\w+/);
+  for (const { body, nameLine, name } of classBodies) {
+    const methodCount = (body.match(/^\s*(public|private|protected|static|async)?\s*\w+\s*\([^)]*\)\s*{/gm) || []).length;
+    if (methodCount <= 1 && body.length > 0) {
+      const trimmed = body.trim();
+      const nonEmptyLines = trimmed ? trimmed.split("\n").filter((l) => l.trim()).length : 0;
+      if (nonEmptyLines <= 3) {
+        issues.push({
+          file: filePath,
+          line: nameLine,
+          severity: "info",
+          rule: "over-engineering/wrapper-class",
+          message: `Class "${name}" has only 1 method \u2014 likely a wrapper that could be a plain function`,
+          suggestion: "Replace with a standalone function or a utility module export"
+        });
+      }
     }
-    if (pkg.bin) return "cli";
-    if (pkg.main || pkg.exports) return "library";
   }
-  const subFrameworks = scanSubProjectFrameworks(root);
-  if (subFrameworks.length > 0) return "web-app";
-  return "unknown";
-}
-function detectWorkspaces(root) {
-  const results = [];
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  const pnpmWorkspace = readYamlLite(path8.join(root, "pnpm-workspace.yaml"));
-  const patterns = /* @__PURE__ */ new Set();
-  const pkgWorkspaces = pkg?.workspaces;
-  if (Array.isArray(pkgWorkspaces)) {
-    for (const p of pkgWorkspaces) if (typeof p === "string") patterns.add(p);
-  } else if (pkgWorkspaces && typeof pkgWorkspaces === "object") {
-    const packages = pkgWorkspaces.packages;
-    if (Array.isArray(packages)) {
-      for (const p of packages) if (typeof p === "string") patterns.add(p);
+  const factoryMatches = text.matchAll(/^\s*(export\s+)?function\s+(create\w+|make\w+|build\w+|factory\w+)\s*\(/gm);
+  for (const match of factoryMatches) {
+    const funcName = match[2];
+    const body = extractBodyAfter(lines, match);
+    const creationCount = (body.match(/\bnew\s+\w+/g) || []).length;
+    if (creationCount <= 1) {
+      issues.push({
+        file: filePath,
+        line: lines.findIndex((l) => l.includes(funcName)) + 1,
+        severity: "warning",
+        rule: "over-engineering/single-product-factory",
+        message: `Factory "${funcName}" produces only 1 product \u2014 unnecessary abstraction`,
+        suggestion: "Inline the construction or drop the factory pattern"
+      });
     }
   }
-  if (Array.isArray(pnpmWorkspace?.packages)) {
-    for (const p of pnpmWorkspace.packages) if (typeof p === "string") patterns.add(p);
+  const interfaceNames = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*(export\s+)?interface\s+(\w+)/);
+    if (m) interfaceNames.push(m[2]);
   }
-  patterns.add("apps/*");
-  patterns.add("packages/*");
-  patterns.add("services/*");
-  for (const pattern of patterns) {
-    const match = pattern.match(/^([^*]+)\/\*$/);
-    if (!match) continue;
-    const dir = path8.join(root, match[1]);
-    if (!fs8.existsSync(dir)) continue;
-    let entries = [];
-    try {
-      entries = fs8.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
+  for (const iface of interfaceNames) {
+    const implCount = (text.match(new RegExp(`implements\\s+.*\\b${iface}\\b`, "g")) || []).length;
+    if (implCount <= 1) {
+      const lineNum = lines.findIndex((l) => l.includes(`interface ${iface}`)) + 1;
+      issues.push({
+        file: filePath,
+        line: lineNum,
+        severity: "info",
+        rule: "over-engineering/single-impl-interface",
+        message: `Interface "${iface}" has only 1 implementation \u2014 unnecessary unless more planned`,
+        suggestion: "Remove the interface or inline the type"
+      });
     }
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const pkgPath = path8.join(dir, entry.name, "package.json");
-      const subPkg = readJsonSafe(pkgPath);
-      if (!subPkg) continue;
-      results.push({
-        path: path8.relative(root, path8.join(dir, entry.name)),
-        name: subPkg.name ?? entry.name,
-        framework: detectFramework(path8.join(dir, entry.name))
+  }
+  const configObjPattern = /^\s*(export\s+)?(const|let|var)\s+(\w+)\s*[=:]\s*\{/;
+  for (let i = 0; i < lines.length; i++) {
+    const cm = lines[i].match(configObjPattern);
+    if (!cm || !/config|setting|option|default/i.test(cm[3])) continue;
+    const configName = cm[3];
+    const refs = (text.match(new RegExp(`\\b${configName}\\b`, "g")) || []).length;
+    if (refs <= 2) {
+      issues.push({
+        file: filePath,
+        line: i + 1,
+        severity: "info",
+        rule: "over-engineering/unused-config",
+        message: `Config "${configName}" is referenced ${refs === 0 ? "nowhere" : `only ${refs - 1}x outside definition`}`,
+        suggestion: refs === 0 ? "Remove the dead config" : "Inline the value or remove if unused elsewhere"
       });
     }
   }
-  const seen = /* @__PURE__ */ new Set();
-  return results.filter((w) => {
-    if (seen.has(w.path)) return false;
-    seen.add(w.path);
-    return true;
-  });
-}
-function readYamlLite(filePath) {
-  try {
-    if (!fs8.existsSync(filePath)) return null;
-    const text = fs8.readFileSync(filePath, "utf-8");
-    const packages = [];
-    let inPackages = false;
-    for (const rawLine of text.split("\n")) {
-      const line = rawLine.replace(/#.*$/, "").trimEnd();
-      if (/^packages:\s*$/.test(line)) {
-        inPackages = true;
-        continue;
-      }
-      if (inPackages) {
-        const m = line.match(/^\s*-\s*['"]?([^'"]+)['"]?\s*$/);
-        if (m) packages.push(m[1]);
-        else if (/^\S/.test(line)) inPackages = false;
-      }
+  const stdlibPatterns = [
+    { pattern: /function\s+\w+\s*\([^)]*\)\s*\{[^}]*fs\.readFileSync[^}]*\}/, rule: "over-engineering/hand-rolled-file-read", msg: "Hand-rolled file reader \u2014 use fs.readFileSync directly", suggestion: "Call fs.readFileSync directly instead of wrapping" },
+    { pattern: /function\s+\w+\s*\([^)]*\)\s*\{[^}]*crypto\.createHash[^}]*\}/, rule: "over-engineering/hand-rolled-hash", msg: "Hand-rolled hash \u2014 use crypto directly", suggestion: "Call crypto.createHash directly" },
+    { pattern: /function\s+uuid\s*\(|function\s+generateId\s*\(/, rule: "over-engineering/hand-rolled-uuid", msg: "Hand-rolled UUID \u2014 use crypto.randomUUID()", suggestion: "Replace with crypto.randomUUID() (Node 19+) or the uuid package" },
+    { pattern: /function\s+debounce\s*\(|function\s+throttle\s*\(/, rule: "over-engineering/hand-rolled-debounce", msg: "Hand-rolled debounce/throttle \u2014 utility lib or native", suggestion: "Use lodash.debounce or a 3-line inline version" }
+  ];
+  for (const sp of stdlibPatterns) {
+    const sl = text.match(sp.pattern);
+    if (sl) {
+      const matchIndex = sl.index ?? 0;
+      const preText = text.substring(0, matchIndex);
+      const lineNum = preText.split("\n").length;
+      issues.push({
+        file: filePath,
+        line: lineNum,
+        severity: "info",
+        rule: sp.rule,
+        message: sp.msg,
+        suggestion: sp.suggestion
+      });
     }
-    return { packages };
-  } catch {
-    return null;
   }
-}
-function detectTestRunner(root) {
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (!pkg) return "unknown";
-  const pkgDeps2 = pkg.dependencies ?? {};
-  const pkgDevDeps2 = pkg.devDependencies ?? {};
-  const deps = { ...pkgDeps2, ...pkgDevDeps2 };
-  if (deps.vitest) return "Vitest";
-  if (deps.jest) return "Jest";
-  if (deps.mocha) return "Mocha";
-  if (deps.ava) return "AVA";
-  if (deps.cypress) return "Cypress";
-  if (deps.playwright) return "Playwright";
-  if (deps["@testing-library/react"]) return "React Testing Library";
-  const scripts = pkg.scripts ?? {};
-  if (scripts.test) {
-    if (scripts.test.includes("vitest")) return "Vitest";
-    if (scripts.test.includes("jest")) return "Jest";
-    if (scripts.test.includes("mocha")) return "Mocha";
+  const exportDecls = [];
+  for (let i = 0; i < lines.length; i++) {
+    const ed = lines[i].match(/^\s*export\s+(const|let|var|function|class)\s+(\w+)/);
+    if (ed) exportDecls.push({ name: ed[2], line: i + 1 });
   }
-  return "unknown";
-}
-function detectStyling(root) {
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (!pkg) return "unknown";
-  const pkgDeps3 = pkg.dependencies ?? {};
-  const pkgDevDeps3 = pkg.devDependencies ?? {};
-  const deps = { ...pkgDeps3, ...pkgDevDeps3 };
-  if (deps.tailwindcss) return "Tailwind CSS";
-  if (deps["styled-components"]) return "Styled Components";
-  if (deps["@emotion/react"]) return "Emotion";
-  if (deps.linaria) return "Linaria";
-  if (deps.sass || deps["node-sass"]) return "SCSS";
-  if (deps.less) return "Less";
-  if (deps["@vanilla-extract/css"]) return "Vanilla Extract";
-  if (deps.cssmodules || hasCSSModules(root)) return "CSS Modules";
-  const srcDir = path8.join(root, "src");
-  if (fs8.existsSync(srcDir)) {
-    const cssFiles = findFiles(srcDir, [".css", ".scss", ".less"]);
-    if (cssFiles.length > 0) return "Plain CSS/SCSS";
+  for (const decl of exportDecls) {
+    const refCount = (text.match(new RegExp(`\\b${decl.name}\\b`, "g")) || []).length;
+    const isReactComponent = /^[A-Z]/.test(decl.name) && /return\s+<|React\./.test(text);
+    if (refCount <= 1 && decl.name !== "default" && !isReactComponent) {
+      issues.push({
+        file: filePath,
+        line: decl.line,
+        severity: "info",
+        rule: "over-engineering/unused-export",
+        message: `"${decl.name}" is exported but referenced only in its declaration`,
+        suggestion: "Check if it is imported elsewhere; if not, remove or inline"
+      });
+    }
   }
-  return "unknown";
 }
-function detectImportAlias(root) {
-  const tsconfig = readJsonSafe(path8.join(root, "tsconfig.json"));
-  const tsconfigPaths = tsconfig?.compilerOptions;
-  if (tsconfigPaths?.paths) {
-    const paths = tsconfigPaths.paths;
-    const alias = Object.keys(paths)[0];
-    if (alias) return alias.replace("/*", "");
-  }
-  const jsconfig = readJsonSafe(path8.join(root, "jsconfig.json"));
-  const jsconfigPaths = jsconfig?.compilerOptions;
-  if (jsconfigPaths?.paths) {
-    const paths = jsconfigPaths.paths;
-    const alias = Object.keys(paths)[0];
-    if (alias) return alias.replace("/*", "");
+function findBlockBodies(lines, startPattern) {
+  const results = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(startPattern);
+    if (!m) continue;
+    const name = m[0].match(/class\s+(\w+)/)?.[1] ?? "Unknown";
+    const body = collectBlockLines(lines, i);
+    results.push({ body: body.join("\n"), nameLine: i + 1, name });
   }
-  return void 0;
-}
-function detectLintRules(root) {
-  const rules = [];
-  if (fs8.existsSync(path8.join(root, ".eslintrc"))) rules.push("ESLint (.eslintrc)");
-  if (fs8.existsSync(path8.join(root, ".eslintrc.js"))) rules.push("ESLint (.eslintrc.js)");
-  if (fs8.existsSync(path8.join(root, ".eslintrc.json"))) rules.push("ESLint (.eslintrc.json)");
-  if (fs8.existsSync(path8.join(root, "eslint.config.js"))) rules.push("ESLint (flat config)");
-  if (fs8.existsSync(path8.join(root, ".prettierrc"))) rules.push("Prettier");
-  if (fs8.existsSync(path8.join(root, ".prettierrc.json"))) rules.push("Prettier");
-  if (fs8.existsSync(path8.join(root, ".prettierrc.js"))) rules.push("Prettier");
-  if (fs8.existsSync(path8.join(root, ".stylelintrc"))) rules.push("StyleLint");
-  if (fs8.existsSync(path8.join(root, ".stylelintrc.json"))) rules.push("StyleLint");
-  return rules;
-}
-function detectPackageManager() {
-  const root = getProjectRoot();
-  if (fs8.existsSync(path8.join(root, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs8.existsSync(path8.join(root, "yarn.lock"))) return "yarn";
-  if (fs8.existsSync(path8.join(root, "package-lock.json"))) return "npm";
-  if (fs8.existsSync(path8.join(root, "bun.lockb"))) return "bun";
-  return "npm";
+  return results;
 }
-function detectModuleSystem(root) {
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (pkg?.type === "module") return "esm";
-  const srcDir = path8.join(root, "src");
-  if (fs8.existsSync(srcDir)) {
-    const tsFiles = findFiles(srcDir, [".ts", ".tsx", ".js", ".jsx", ".mjs"]);
-    for (const file of tsFiles.slice(0, 20)) {
-      try {
-        const content = fs8.readFileSync(file, "utf-8");
-        if (content.includes("import ") || content.includes("export ")) return "esm";
-      } catch {
-        continue;
-      }
+function collectBlockLines(lines, startIdx) {
+  let depth = 0;
+  let started = false;
+  const block = [];
+  for (let j = startIdx; j < lines.length; j++) {
+    const line = lines[j];
+    block.push(line);
+    for (const ch of line) {
+      if (ch === "{") {
+        depth++;
+        started = true;
+      } else if (ch === "}") depth--;
     }
+    if (started && depth <= 0) break;
   }
-  return "cjs";
-}
-function detectLanguage(root) {
-  if (fs8.existsSync(path8.join(root, "tsconfig.json"))) return "typescript";
-  const srcDir = path8.join(root, "src");
-  if (fs8.existsSync(srcDir)) {
-    const tsFiles = findFiles(srcDir, [".ts", ".tsx"]);
-    if (tsFiles.length > 0) return "typescript";
-  }
-  return "javascript";
+  return block;
 }
-function detectFeatures(root) {
-  const features = [];
-  const pkg = readJsonSafe(path8.join(root, "package.json"));
-  if (!pkg) return features;
-  const pkgDeps4 = pkg.dependencies ?? {};
-  const pkgDevDeps4 = pkg.devDependencies ?? {};
-  const deps = { ...pkgDeps4, ...pkgDevDeps4 };
-  if (deps["@prisma/client"] || deps.prisma) features.push("Prisma ORM");
-  if (deps.typeorm) features.push("TypeORM");
-  if (deps["drizzle-orm"]) features.push("Drizzle ORM");
-  if (deps.graphql || deps["@graphql-tools"]) features.push("GraphQL");
-  if (deps.trpc || deps["@trpc/client"]) features.push("tRPC");
-  if (deps["socket.io"] || deps.ws) features.push("WebSockets");
-  if (deps["@reduxjs/toolkit"] || deps.redux) features.push("Redux");
-  if (deps.zustand) features.push("Zustand");
-  if (deps["react-router"] || deps["react-router-dom"]) features.push("React Router");
-  if (deps["next-auth"] || deps["next-auth/react"]) features.push("NextAuth");
-  if (deps["@tanstack/react-query"]) features.push("React Query");
-  if (deps.jest || deps.vitest) features.push("Unit Testing");
-  if (deps.cypress || deps.playwright) features.push("E2E Testing");
-  if (deps.storybook || deps["@storybook/react"]) features.push("Storybook");
-  if (deps.i18next || deps["react-i18next"]) features.push("i18n");
-  return features;
+function extractBodyAfter(lines, match) {
+  const startIdx = lines.findIndex((l) => l.includes(match[0].trim().split(/\s+/).pop() ?? ""));
+  if (startIdx < 0) return "";
+  return collectBlockLines(lines, startIdx).join("\n");
 }
-function readJsonSafe(filePath) {
-  try {
-    if (fs8.existsSync(filePath)) {
-      return JSON.parse(fs8.readFileSync(filePath, "utf-8"));
-    }
-  } catch {
+function formatReviewOutput(issues, filesReviewed, totalFiles, focus, customCriteria, autoDetected) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  const infos = issues.filter((i) => i.severity === "info");
+  const lines = [
+    `\u{1F50D} **Code Review \u2014 Focus: ${focus}**`,
+    ...focus === "over-engineering" ? ["\u{1F4A1} **The Ladder:** 1. Does this code need to exist? 2. Does stdlib cover it? 3. Is there a one-liner? 4. Only then, write it."] : [],
+    ...autoDetected ? [`\u{1F4C2} Auto-detected ${totalFiles} changed file(s) from git`] : [],
+    ...customCriteria ? [`\u{1F4CB} **Custom Criteria:** ${customCriteria}`] : [],
+    `\u{1F4C1} ${filesReviewed}/${totalFiles} files reviewed`,
+    `\u{1F534} ${errors.length} errors | \u{1F7E1} ${warnings.length} warnings | \u{1F535} ${infos.length} info`,
+    ""
+  ];
+  if (issues.length === 0) {
+    lines.push("\u2705 No issues found.");
+    return lines.join("\n");
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const existing = grouped.get(issue.file) ?? [];
+    existing.push(issue);
+    grouped.set(issue.file, existing);
   }
-  return null;
-}
-function hasCSSModules(root) {
-  const srcDir = path8.join(root, "src");
-  if (!fs8.existsSync(srcDir)) return false;
-  const files = findFiles(srcDir, [".module.css", ".module.scss", ".module.less"]);
-  return files.length > 0;
-}
-function findFiles(dir, extensions) {
-  const results = [];
-  try {
-    const entries = fs8.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path8.join(dir, entry.name);
-      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
-        results.push(...findFiles(fullPath, extensions));
-      } else if (entry.isFile()) {
-        if (extensions.some((ext) => entry.name.endsWith(ext))) {
-          results.push(fullPath);
-        }
-      }
+  for (const [file, fileIssues] of grouped) {
+    lines.push(`**\u{1F4C4} ${file}:**`);
+    for (const issue of fileIssues) {
+      const icon = issue.severity === "error" ? "\u{1F534}" : issue.severity === "warning" ? "\u{1F7E1}" : "\u{1F535}";
+      lines.push(`  ${icon} [L${issue.line}] [${issue.rule}] ${issue.message}`);
+      if (issue.suggestion) lines.push(`     \u{1F4A1} ${issue.suggestion}`);
     }
-  } catch {
+    lines.push("");
   }
-  return results;
+  if (errors.length > 0) {
+    lines.push("\u26A0\uFE0F Fix errors first, then warnings.");
+    lines.push("\u{1F4A1} Use precise_diff_editor to apply fixes.");
+  } else if (warnings.length > 0) {
+    lines.push("\u{1F4A1} Address warnings before merging.");
+  } else {
+    lines.push("\u2705 Only informational issues \u2014 ready for testing.");
+  }
+  return lines.join("\n");
 }
 
 // src/agents/projectConventions.ts
@@ -2868,20 +2976,26 @@ function formatConventionsOutput(conventions) {
   return lines.join("\n");
 }
 
+// src/utils/gitUtils.ts
+import { execSync as execSync2 } from "child_process";
+function runGitCommand(command) {
+  const root = getProjectRoot();
+  return execSync2(command, {
+    cwd: root,
+    encoding: "utf-8",
+    maxBuffer: 2 * 1024 * 1024
+  });
+}
+
 // src/tools/gitLog.ts
-import child_process from "child_process";
 async function handleGitLog(params) {
   const { maxCount = 10, filePath } = params;
-  const root = getProjectRoot();
   try {
     let command = `git log -n ${maxCount} --oneline`;
     if (filePath) {
       command += ` -- "${filePath}"`;
     }
-    const stdout = child_process.execSync(command, {
-      cwd: root,
-      encoding: "utf-8"
-    });
+    const stdout = runGitCommand(command);
     sessionMemory.recordToolCall("git_log", { maxCount, filePath });
     if (!stdout.trim()) {
       return `\u2139\uFE0F No commit history found${filePath ? ` for file "${filePath}"` : ""}.`;
@@ -2895,10 +3009,8 @@ ${stdout}`;
 }
 
 // src/tools/gitDiff.ts
-import child_process2 from "child_process";
 async function handleGitDiff(params) {
   const { filePath, staged = false, contextLines = 3, baseRef, targetRef } = params;
-  const root = getProjectRoot();
   try {
     let command = "git diff";
     if (staged) {
@@ -2914,11 +3026,7 @@ async function handleGitDiff(params) {
     if (filePath) {
       command += ' -- "' + filePath + '"';
     }
-    const stdout = child_process2.execSync(command, {
-      cwd: root,
-      encoding: "utf-8",
-      maxBuffer: 2 * 1024 * 1024
-    });
+    const stdout = runGitCommand(command);
     sessionMemory.recordToolCall("git_diff", { filePath, staged, baseRef, targetRef });
     if (!stdout.trim()) {
       if (staged) {
@@ -3000,8 +3108,8 @@ async function handleGitDiff(params) {
 }
 
 // src/tools/projectStructure.ts
-import fs9 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path10 from "path";
 var DEFAULT_IGNORE = [
   "node_modules",
   ".git",
@@ -3018,6 +3126,8 @@ var DEFAULT_IGNORE = [
   ".DS_Store",
   "*.log"
 ];
+var treeCache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS2 = 6e4;
 async function handleProjectStructure(params) {
   const {
     depth = 3,
@@ -3027,10 +3137,16 @@ async function handleProjectStructure(params) {
   } = params;
   const root = getProjectRoot();
   const clampedDepth = Math.max(1, Math.min(depth, 6));
+  const cacheKey = `${root}:${clampedDepth}:${folderOnly}:${includePattern ?? ""}:${excludePattern ?? ""}`;
+  const cached = treeCache.get(cacheKey);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS2) {
+    sessionMemory.recordToolCall("project_structure", { depth: clampedDepth, folderOnly, cached: true });
+    return cached.result;
+  }
   sessionMemory.recordToolCall("project_structure", { depth: clampedDepth, folderOnly });
   try {
     const tree = buildTree(root, root, clampedDepth, 0, folderOnly, includePattern, excludePattern);
-    const projectName = path9.basename(root);
+    const projectName = path10.basename(root);
     const lines = [
       "[Project Structure] - " + projectName,
       "Depth: " + clampedDepth + " | " + (folderOnly ? "Folders only" : "Files and folders"),
@@ -3041,7 +3157,9 @@ async function handleProjectStructure(params) {
       "Increase depth (max 6) for deeper structure.",
       "Use folderOnly: true for high-level overview."
     ];
-    return lines.join("\n");
+    const result = lines.join("\n");
+    treeCache.set(cacheKey, { result, timestamp: Date.now() });
+    return result;
   } catch (err) {
     return "Error building project structure: " + (err instanceof Error ? err.message : String(err));
   }
@@ -3051,7 +3169,7 @@ function buildTree(root, currentDir, maxDepth, currentDepth, folderOnly, include
   const lines = [];
   let entries = [];
   try {
-    entries = fs9.readdirSync(currentDir, { withFileTypes: true });
+    entries = fs10.readdirSync(currentDir, { withFileTypes: true });
   } catch {
     return lines;
   }
@@ -3060,12 +3178,12 @@ function buildTree(root, currentDir, maxDepth, currentDepth, folderOnly, include
     if (!a.isDirectory() && b.isDirectory()) return 1;
     return a.name.localeCompare(b.name);
   });
-  const relativeDir = path9.relative(root, currentDir) || ".";
+  const relativeDir = path10.relative(root, currentDir) || ".";
   const prefix = getPrefix(currentDepth);
   for (const entry of entries) {
     if (shouldIgnore(entry.name, relativeDir, root)) continue;
-    const fullPath = path9.join(currentDir, entry.name);
-    const relativePath = path9.relative(root, fullPath);
+    const fullPath = path10.join(currentDir, entry.name);
+    const relativePath = path10.relative(root, fullPath);
     if (includePattern && !entry.name.includes(includePattern) && !relativePath.includes(includePattern)) {
       if (!entry.isDirectory()) continue;
     }
@@ -3076,11 +3194,11 @@ function buildTree(root, currentDir, maxDepth, currentDepth, folderOnly, include
       lines.push(prefix + "[D] " + entry.name + "/");
       let subEntries = [];
       try {
-        subEntries = fs9.readdirSync(fullPath, { withFileTypes: true });
+        subEntries = fs10.readdirSync(fullPath, { withFileTypes: true });
       } catch {
       }
       const hasVisibleContent = subEntries.some(
-        (e) => !shouldIgnore(e.name, path9.relative(root, fullPath), root)
+        (e) => !shouldIgnore(e.name, path10.relative(root, fullPath), root)
       );
       if (hasVisibleContent) {
         const subLines = buildTree(root, fullPath, maxDepth, currentDepth + 1, folderOnly, includePattern, excludePattern);
@@ -3111,7 +3229,7 @@ function getPrefix(depth) {
 }
 function getFileSize(fullPath) {
   try {
-    const stat = fs9.statSync(fullPath);
+    const stat = fs10.statSync(fullPath);
     if (stat.size < 1024) return stat.size + "B";
     if (stat.size < 1024 * 1024) return (stat.size / 1024).toFixed(0) + "KB";
     const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
@@ -3122,9 +3240,8 @@ function getFileSize(fullPath) {
 }
 
 // src/tools/staticAnalysis.ts
-import { spawn as spawn2 } from "child_process";
-import fs10 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path11 from "path";
 async function handleStaticAnalysis(params) {
   const { tool = "all", files, autoFix = false, timeout = 60 } = params;
   const root = getProjectRoot();
@@ -3179,11 +3296,11 @@ function detectAvailableTools(root) {
     "eslint.config.js",
     "eslint.config.mjs"
   ];
-  const hasEslintConfig = eslintConfigs.some((cfg) => fs10.existsSync(path10.join(root, cfg)));
+  const hasEslintConfig = eslintConfigs.some((cfg) => fs11.existsSync(path11.join(root, cfg)));
   if (hasEslintConfig && depNames.has("eslint")) {
     tools.push("eslint");
   }
-  if (fs10.existsSync(path10.join(root, "tsconfig.json")) && depNames.has("typescript")) {
+  if (fs11.existsSync(path11.join(root, "tsconfig.json")) && depNames.has("typescript")) {
     tools.push("tsc");
   }
   const prettierConfigs = [
@@ -3194,20 +3311,20 @@ function detectAvailableTools(root) {
     ".prettierrc.toml",
     "prettier.config.js"
   ];
-  const hasPrettierConfig = prettierConfigs.some((cfg) => fs10.existsSync(path10.join(root, cfg)));
+  const hasPrettierConfig = prettierConfigs.some((cfg) => fs11.existsSync(path11.join(root, cfg)));
   if (hasPrettierConfig && depNames.has("prettier")) {
     tools.push("prettier");
   }
-  if (fs10.existsSync(path10.join(root, "ruff.toml")) || fs10.existsSync(path10.join(root, ".ruff.toml"))) {
+  if (fs11.existsSync(path11.join(root, "ruff.toml")) || fs11.existsSync(path11.join(root, ".ruff.toml"))) {
     tools.push("ruff");
   }
   return tools;
 }
 function readPackageJson(root) {
   try {
-    const pkgPath = path10.join(root, "package.json");
-    if (fs10.existsSync(pkgPath)) {
-      return JSON.parse(fs10.readFileSync(pkgPath, "utf-8"));
+    const pkgPath = path11.join(root, "package.json");
+    if (fs11.existsSync(pkgPath)) {
+      return JSON.parse(fs11.readFileSync(pkgPath, "utf-8"));
     }
   } catch {
   }
@@ -3216,45 +3333,14 @@ function readPackageJson(root) {
 async function runTool(tool, cwd, files, autoFix, timeoutSeconds) {
   const cmd = buildToolCommand(tool, files, autoFix);
   if (!cmd) return null;
-  return new Promise((resolve) => {
-    const parts = cmd.split(" ");
-    const command = parts[0];
-    const args = parts.slice(1);
-    const proc = spawn2(command, args, {
-      cwd,
-      shell: process.platform === "win32",
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    const timeoutId = setTimeout(() => {
-      proc.kill("SIGTERM");
-      if (process.platform === "win32") {
-        try {
-          spawn2("taskkill", ["/pid", String(proc.pid), "/f", "/t"], { stdio: "ignore" });
-        } catch {
-        }
-      }
-    }, (timeoutSeconds ?? 60) * 1e3);
-    proc.stdout?.on("data", (data) => {
-      stdout += data.toString();
-    });
-    proc.stderr?.on("data", (data) => {
-      stderr += data.toString();
-    });
-    proc.on("close", (code) => {
-      clearTimeout(timeoutId);
-      resolve({
-        stdout,
-        stderr,
-        exitCode: code ?? -1
-      });
-    });
-    proc.on("error", () => {
-      clearTimeout(timeoutId);
-      resolve(null);
-    });
+  const result = await spawnProcess(cmd, {
+    cwd,
+    timeoutSeconds: timeoutSeconds ?? 60,
+    maxStdout: 1e5,
+    // Tool output can be large
+    maxStderr: 5e4
   });
+  return result;
 }
 function buildToolCommand(tool, files, autoFix) {
   const pm = detectPackageManagerPrefix();
@@ -3283,8 +3369,8 @@ function buildToolCommand(tool, files, autoFix) {
 }
 function detectPackageManagerPrefix() {
   const root = getProjectRoot();
-  if (fs10.existsSync(path10.join(root, "pnpm-lock.yaml"))) return "pnpm ";
-  if (fs10.existsSync(path10.join(root, "yarn.lock"))) return "yarn ";
+  if (fs11.existsSync(path11.join(root, "pnpm-lock.yaml"))) return "pnpm ";
+  if (fs11.existsSync(path11.join(root, "yarn.lock"))) return "yarn ";
   return "npx --no-install ";
 }
 function parseToolOutput(tool, stdout, stderr, projectRoot) {
@@ -3303,7 +3389,7 @@ function parseToolOutput(tool, stdout, stderr, projectRoot) {
 }
 function resolveToolPath(filePath, projectRoot) {
   const trimmed = filePath.trim();
-  return path10.isAbsolute(trimmed) ? path10.relative(projectRoot, trimmed) : trimmed.replace(/^\.\//, "");
+  return path11.isAbsolute(trimmed) ? path11.relative(projectRoot, trimmed) : trimmed.replace(/^\.\//, "");
 }
 function parseEslintOutput(output, projectRoot) {
   const issues = [];
@@ -3483,7 +3569,7 @@ function formatToolNotAvailable(requested, available) {
 }
 
 // src/tools/kumaReflect.ts
-import { execSync as execSync2 } from "child_process";
+import { execSync as execSync3 } from "child_process";
 async function handleReflect(params) {
   const summary = sessionMemory.getSummary();
   const goal = params.goal || summary.currentGoal || "";
@@ -3505,7 +3591,7 @@ async function handleReflect(params) {
   let gitStat = "";
   try {
     const root = getProjectRoot();
-    gitStat = execSync2("git diff --stat", {
+    gitStat = execSync3("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout: 5e3
@@ -3576,10 +3662,465 @@ async function handleReflect(params) {
   );
 }
 
+// src/tools/kumaGuard.ts
+import { execSync as execSync6 } from "child_process";
+
+// src/guards/antiPatternDetector.ts
+import fs12 from "fs";
+import path12 from "path";
+import { execSync as execSync4 } from "child_process";
+var SCRIPT_PATCH_PATTERNS = [
+  "writeFileSync",
+  "writeFile",
+  "replace(",
+  "replaceAll(",
+  "sed",
+  "awk",
+  "fs.write",
+  "patch",
+  "modify"
+];
+var BASH_GREP_PATTERNS = [
+  "grep -rn",
+  "grep -r",
+  "grep -n",
+  "| grep",
+  "ripgrep",
+  "rg ",
+  "ag "
+];
+var SCRIPT_EXTENSIONS = [".py", ".js", ".mjs", ".cjs", ".ts"];
+function findPatchScripts(projectRoot) {
+  const warnings = [];
+  const recentFiles = scanRecentFiles(projectRoot);
+  for (const file of recentFiles) {
+    const ext = path12.extname(file).toLowerCase();
+    if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
+    const relativePath = path12.relative(projectRoot, file);
+    if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".")) {
+      continue;
+    }
+    try {
+      const content = fs12.readFileSync(file, "utf-8").toLowerCase();
+      const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
+      if (matchedPattern) {
+        warnings.push({
+          severity: "high",
+          pattern: "script-patching",
+          message: `Created script file that modifies other files: ${path12.basename(file)}`,
+          suggestion: "Use **precise_diff_editor** instead \u2014 it has fuzzy matching, auto-backup, and rollback support",
+          evidence: `File: ${relativePath} contains '${matchedPattern}'`,
+          filePath: relativePath
+        });
+      }
+    } catch {
+    }
+  }
+  return warnings;
+}
+function detectBashGrepUsage() {
+  const warnings = [];
+  const toolCalls = sessionMemory.getToolCallHistory(100);
+  for (const call of toolCalls) {
+    if (call.toolName !== "execute_safe_test") continue;
+    const cmd = call.params?.customCommand || call.params?.command || "";
+    const matchedPattern = BASH_GREP_PATTERNS.find((p) => cmd.toLowerCase().includes(p));
+    if (matchedPattern) {
+      warnings.push({
+        severity: "medium",
+        pattern: "bash-grep",
+        message: `Used bash grep instead of smart_grep`,
+        suggestion: "Use **smart_grep** \u2014 it returns line numbers + context, caches results, respects .gitignore",
+        evidence: `Command: ${cmd.substring(0, 120)}`
+      });
+      break;
+    }
+  }
+  return warnings;
+}
+function scanRecentFiles(projectRoot) {
+  const recent = [];
+  try {
+    const entries = fs12.readdirSync(projectRoot, { withFileTypes: true });
+    const now = Date.now();
+    const recentThreshold = 30 * 60 * 1e3;
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      try {
+        const stat = fs12.statSync(path12.join(projectRoot, entry.name));
+        if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
+          recent.push(path12.join(projectRoot, entry.name));
+        }
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+  }
+  return recent;
+}
+function detectGitPatchScripts(projectRoot) {
+  const warnings = [];
+  try {
+    const statusStdout = execSync4("git status --porcelain", {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 3e3
+    }).trim();
+    if (statusStdout) {
+      const lines = statusStdout.split("\n").filter(Boolean);
+      for (const line of lines) {
+        const prefix = line.substring(0, 2);
+        if (prefix !== "??" && prefix !== "A ") continue;
+        const file = line.substring(3).trim();
+        const ext = path12.extname(file).toLowerCase();
+        if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
+        const isRootLevel = !file.includes("/");
+        const isScriptsDir = file.startsWith("scripts/") || file.startsWith("patches/");
+        if (!isRootLevel && !isScriptsDir) continue;
+        const fullPath = path12.join(projectRoot, file);
+        if (fs12.existsSync(fullPath)) {
+          const content = fs12.readFileSync(fullPath, "utf-8").toLowerCase();
+          const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
+          if (matchedPattern) {
+            warnings.push({
+              severity: "high",
+              pattern: "script-patching",
+              message: `Patch script detected: ${file}`,
+              suggestion: "Use **precise_diff_editor** instead \u2014 it has fuzzy matching, auto-backup, and rollback support",
+              evidence: `File: ${file} (contains '${matchedPattern}')`,
+              filePath: file
+            });
+          }
+        }
+      }
+    }
+    const deletedStdout = execSync4("git diff --name-only --diff-filter=D HEAD", {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 3e3
+    }).trim();
+    if (deletedStdout) {
+      const deletedFiles = deletedStdout.split("\n").filter(Boolean);
+      for (const file of deletedFiles) {
+        const ext = path12.extname(file).toLowerCase();
+        if (SCRIPT_EXTENSIONS.includes(ext)) {
+          warnings.push({
+            severity: "high",
+            pattern: "script-patching",
+            message: `Patch script was tracked then deleted: ${file}`,
+            suggestion: "Use **precise_diff_editor** instead of creating disposable scripts. It has auto-backup + rollback.",
+            evidence: `Git shows ${file} was deleted`,
+            filePath: file
+          });
+        }
+      }
+    }
+  } catch {
+  }
+  return warnings;
+}
+function detectBashSedUsage() {
+  const warnings = [];
+  const toolCalls = sessionMemory.getToolCallHistory(100);
+  const SED_PATTERNS = [
+    "sed -i",
+    "sed \\'",
+    "sed '",
+    "awk '",
+    "awk \\'",
+    "cat <<",
+    '>> "$file',
+    ">> '$file",
+    'echo " >> ',
+    "echo ' >> ",
+    "printf '%s' >"
+  ];
+  for (const call of toolCalls) {
+    if (call.toolName !== "execute_safe_test") continue;
+    const cmd = call.params?.customCommand || call.params?.command || "";
+    if (SED_PATTERNS.some((p) => cmd.includes(p))) {
+      warnings.push({
+        severity: "high",
+        pattern: "bash-sed-editing",
+        message: "Used bash sed/awk to edit source files instead of precise_diff_editor",
+        suggestion: 'Use **precise_diff_editor** for all file modifications \u2014 it has fuzzy matching, auto-backup, and rollback.\n\n\u2705 Correct format:\nprecise_diff_editor({\n  filePath: "src/file.ts",\n  edits: [\n    { searchBlock: "old code", replaceBlock: "new code" }\n  ]\n})',
+        evidence: `Command: ${cmd.substring(0, 150)}`
+      });
+      break;
+    }
+  }
+  return warnings;
+}
+function detectAllAntiPatterns() {
+  const projectRoot = getProjectRoot();
+  const warnings = [];
+  warnings.push(...findPatchScripts(projectRoot));
+  warnings.push(...detectBashGrepUsage());
+  warnings.push(...detectGitPatchScripts(projectRoot));
+  warnings.push(...detectBashSedUsage());
+  return warnings;
+}
+
+// src/engine/contextSnapshot.ts
+import fs13 from "fs";
+import path13 from "path";
+import { execSync as execSync5 } from "child_process";
+var SNAPSHOT_DIR = "context-snapshots";
+function snapshotDir() {
+  return path13.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+}
+function ensureSnapshotDir() {
+  const dir = snapshotDir();
+  if (!fs13.existsSync(dir)) {
+    fs13.mkdirSync(dir, { recursive: true });
+  }
+}
+function snapshotFilePath(timestamp) {
+  return path13.join(snapshotDir(), `${timestamp}.json`);
+}
+function saveSnapshot(goal) {
+  try {
+    ensureSnapshotDir();
+  } catch {
+    return null;
+  }
+  const summary = sessionMemory.getSummary();
+  const snapshot = {
+    version: 1,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    goal: goal || summary.currentGoal || "",
+    modifiedFiles: summary.modifiedFiles || [],
+    unresolvedFailures: summary.unresolvedFailures || [],
+    toolCallCount: summary.toolCallCount || 0,
+    gitDiffStat: getGitDiffStat(),
+    completedSteps: summary.completedSteps || [],
+    hasConventions: !!summary.hasConventions
+  };
+  try {
+    fs13.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
+  } catch {
+  }
+  sessionMemory.recordToolCall("kuma_context", { action: "save", goal: snapshot.goal });
+  return snapshot;
+}
+function listSnapshots() {
+  const dir = snapshotDir();
+  if (!fs13.existsSync(dir)) return [];
+  try {
+    const files = fs13.readdirSync(dir).filter((f) => f.endsWith(".json")).sort((a, b) => b.localeCompare(a));
+    return files.map((f) => {
+      try {
+        const content = fs13.readFileSync(path13.join(dir, f), "utf-8");
+        return JSON.parse(content);
+      } catch {
+        return null;
+      }
+    }).filter((s) => s !== null);
+  } catch {
+    return [];
+  }
+}
+function formatSnapshot(snapshot) {
+  const lines = [
+    `\u{1F4F8} **Context Snapshot** \u2014 ${snapshot.timestamp}`,
+    "",
+    `\u{1F3AF} **Goal:** ${snapshot.goal || "(not set)"}`,
+    `\u{1F4C1} **Modified Files:** ${snapshot.modifiedFiles.length}`,
+    `\u274C **Unresolved Failures:** ${snapshot.unresolvedFailures.length}`,
+    `\u{1F527} **Tool Calls:** ${snapshot.toolCallCount}`,
+    `\u{1F4CA} **Git Diff:** ${snapshot.gitDiffStat || "clean"}`,
+    `\u2705 **Completed Steps:** ${snapshot.completedSteps.length}`,
+    `\u{1F4D0} **Conventions:** ${snapshot.hasConventions ? "detected" : "not detected"}`,
+    ""
+  ];
+  if (snapshot.modifiedFiles.length > 0) {
+    lines.push("**Modified Files:**");
+    for (const f of snapshot.modifiedFiles) {
+      lines.push(`  - ${f.filePath} (${f.status})`);
+    }
+    lines.push("");
+  }
+  if (snapshot.unresolvedFailures.length > 0) {
+    lines.push("**Unresolved Failures:**");
+    for (const f of snapshot.unresolvedFailures) {
+      lines.push(`  - [${f.task}] ${f.error.substring(0, 150)}`);
+    }
+    lines.push("");
+  }
+  lines.push('\u{1F4A1} Use kuma_guard({ check: "context" }) to create a new snapshot.');
+  return lines.join("\n");
+}
+function getGitDiffStat() {
+  try {
+    const root = getProjectRoot();
+    const stdout = execSync5("git diff --stat", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout: 3e3
+    }).trim();
+    return stdout || "clean";
+  } catch {
+    return "clean";
+  }
+}
+
+// src/tools/kumaGuard.ts
+async function handleKumaGuard(params) {
+  const { check = "all", goal: inputGoal } = params;
+  const summary = sessionMemory.getSummary();
+  const goal = inputGoal || summary.currentGoal || "";
+  sessionMemory.recordToolCall("kuma_guard", { check, goal });
+  const warnings = [];
+  if (check === "all" || check === "anti-pattern") {
+    warnings.push(...detectAllAntiPatterns());
+  }
+  const loop = check === "all" || check === "loop" ? sessionMemory.detectLoop() : { isLooping: false };
+  if (loop.isLooping) {
+    warnings.push({
+      severity: "high",
+      pattern: "tool-loop",
+      message: loop.message ?? "Detected potential tool call loop",
+      suggestion: "Switch approach \u2014 try reading the file first with smart_file_picker"
+    });
+  }
+  const drifts = [];
+  const toolCalls = sessionMemory.getToolCallHistory(50);
+  const hasRunTests = toolCalls.some((c) => c.toolName === "execute_safe_test");
+  if (check === "all" || check === "drift") {
+    const modifiedFiles = sessionMemory.getModifiedFiles();
+    const failedFiles = sessionMemory.getFailedFiles();
+    let unresolvedCount = 0;
+    for (const f of failedFiles) {
+      for (const ff of f.failures) {
+        if (!ff.resolved) unresolvedCount++;
+      }
+    }
+    if (modifiedFiles.length > 0 && !hasRunTests) {
+      drifts.push(`${modifiedFiles.length} file(s) edited but no test run`);
+      warnings.push({
+        severity: "medium",
+        pattern: "no-test-after-edit",
+        message: `${modifiedFiles.length} file(s) modified without running tests`,
+        suggestion: 'Run execute_safe_test({ task: "typecheck" }) to verify changes'
+      });
+    }
+    if (unresolvedCount > 0) {
+      drifts.push(`${unresolvedCount} unresolved failure(s)`);
+    }
+    try {
+      const root = getProjectRoot();
+      const gitStat = execSync6("git diff --stat", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 3e3
+      }).trim();
+      if (gitStat) {
+        drifts.push(`Git diff: ${gitStat}`);
+      }
+    } catch {
+    }
+    const editCalls = toolCalls.filter(
+      (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
+    ).length;
+    if (editCalls > 5) {
+      warnings.push({
+        severity: "low",
+        pattern: "excessive-edits",
+        message: `${editCalls} file operations in a row`,
+        suggestion: "Consider if all edits are needed. Run tests before making more changes."
+      });
+    }
+  }
+  if (check === "context") {
+    const snapshot = saveSnapshot(goal);
+    if (!snapshot) {
+      return "\u26A0\uFE0F Could not create context snapshot. The .kuma directory might not be accessible.";
+    }
+    return formatSnapshot(snapshot);
+  }
+  const hasWarnings = warnings.length > 0;
+  const hasDrifts = drifts.length > 0;
+  const onTrack = !hasWarnings && !hasDrifts;
+  let suggestion;
+  if (warnings.some((w) => w.severity === "high" && w.pattern === "script-patching")) {
+    suggestion = "Remove patch scripts and use precise_diff_editor for all file modifications";
+  } else if (warnings.some((w) => w.pattern === "tool-loop")) {
+    suggestion = "Switch approach \u2014 current tool is not making progress";
+  } else if (warnings.some((w) => w.pattern === "no-test-after-edit")) {
+    suggestion = "Run tests to verify your changes before continuing";
+  } else if (warnings.some((w) => w.pattern === "bash-grep")) {
+    suggestion = "Use smart_grep for code search instead of bash grep";
+  } else if (warnings.some((w) => w.pattern === "excessive-edits")) {
+    suggestion = "Pause and review: are all these edits necessary?";
+  } else if (!goal) {
+    suggestion = "No goal set \u2014 use goal parameter or setGoal to track intent";
+  } else {
+    suggestion = "On track \u2014 continue with current approach";
+  }
+  const report = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    onTrack,
+    warnings,
+    drifts,
+    suggestion,
+    stats: {
+      goal,
+      modifiedFiles: summary.modifiedFiles.length,
+      toolCalls: summary.toolCallCount ?? 0,
+      unresolvedFailures: summary.unresolvedFailures ? summary.unresolvedFailures.length : 0,
+      hasLoop: loop.isLooping,
+      hasRunTests
+    }
+  };
+  return JSON.stringify(report, null, 2);
+}
+
+// src/tools/kumaContext.ts
+async function handleKumaContext(params) {
+  const { action, goal } = params;
+  switch (action) {
+    case "save": {
+      const snapshot = saveSnapshot(goal);
+      if (!snapshot) {
+        return "\u26A0\uFE0F Could not create context snapshot. The .kuma directory might not be accessible.";
+      }
+      return formatSnapshot(snapshot);
+    }
+    case "list": {
+      const snapshots = listSnapshots();
+      if (snapshots.length === 0) {
+        return '\u{1F4F8} **No snapshots found.**\n\nRun `kuma_guard({ check: "context" })` or `kuma_context({ action: "save" })` to create one.';
+      }
+      const lines = [
+        `\u{1F4F8} **Context Snapshots** \u2014 ${snapshots.length} available`,
+        ""
+      ];
+      for (let i = 0; i < snapshots.length; i++) {
+        const s = snapshots[i];
+        const fileCount = s.modifiedFiles.length;
+        const failureCount = s.unresolvedFailures.length;
+        lines.push(
+          `[${i + 1}] ${s.timestamp}`,
+          `    \u{1F3AF} Goal: ${s.goal || "(not set)"}`,
+          `    \u{1F4C1} ${fileCount} files, \u274C ${failureCount} failures, \u{1F527} ${s.toolCallCount} tool calls`,
+          `    \u{1F4CA} Git: ${s.gitDiffStat || "clean"}`,
+          ""
+        );
+      }
+      lines.push('\u{1F4A1} Use kuma_context({ action: "save" }) to create a new snapshot.');
+      lines.push('\u{1F4A1} Or kuma_guard({ check: "context" }) to save and get full context.');
+      return lines.join("\n");
+    }
+    default:
+      return `Error: Action "${action}" not supported. Use "save" or "list".`;
+  }
+}
+
 // src/engine/lspClient.ts
-import { spawn as spawn3 } from "child_process";
-import path11 from "path";
-import fs11 from "fs";
+import { spawn as spawn2 } from "child_process";
+import path14 from "path";
+import fs14 from "fs";
 var LSPClient = class {
   process = null;
   requestId = 0;
@@ -3617,11 +4158,11 @@ var LSPClient = class {
       console.error(`[LSP] typescript-language-server not found. LSP features will fallback to regex.`);
       return;
     }
-    const tsconfigPath = path11.join(root, "tsconfig.json");
-    if (!fs11.existsSync(tsconfigPath)) {
+    const tsconfigPath = path14.join(root, "tsconfig.json");
+    if (!fs14.existsSync(tsconfigPath)) {
       console.error(`[LSP] Warning: tsconfig.json not found at "${root}". Running in implicit project mode.`);
     }
-    this.process = spawn3(lspBinary, ["--stdio", "--log-level=4"], {
+    this.process = spawn2(lspBinary, ["--stdio", "--log-level=4"], {
       cwd: root,
       stdio: ["pipe", "pipe", "pipe"],
       env: { ...process.env }
@@ -3680,19 +4221,19 @@ var LSPClient = class {
   /** Resolve the typescript-language-server binary from local or global install */
   resolveLspBinary(projectRoot) {
     const candidates = [
-      path11.join(projectRoot, "node_modules", ".bin", "typescript-language-server"),
-      path11.join(projectRoot, "..", "node_modules", ".bin", "typescript-language-server")
+      path14.join(projectRoot, "node_modules", ".bin", "typescript-language-server"),
+      path14.join(projectRoot, "..", "node_modules", ".bin", "typescript-language-server")
     ];
     for (const candidate of candidates) {
-      if (fs11.existsSync(candidate)) {
+      if (fs14.existsSync(candidate)) {
         return candidate;
       }
     }
     try {
       const envPath = process.env.PATH ?? "";
-      for (const dir of envPath.split(path11.delimiter)) {
-        const binPath = path11.join(dir, "typescript-language-server");
-        if (fs11.existsSync(binPath)) {
+      for (const dir of envPath.split(path14.delimiter)) {
+        const binPath = path14.join(dir, "typescript-language-server");
+        if (fs14.existsSync(binPath)) {
           return binPath;
         }
       }
@@ -3713,7 +4254,7 @@ var LSPClient = class {
     this.openDocuments.add(filePath);
     let content;
     try {
-      content = fs11.readFileSync(filePath, "utf-8");
+      content = fs14.readFileSync(filePath, "utf-8");
     } catch {
       content = "";
     }
@@ -3930,8 +4471,8 @@ var LSPClient = class {
 var lspClient = new LSPClient();
 
 // src/tools/lspTools.ts
-import fs12 from "fs";
-import path12 from "path";
+import fs15 from "fs";
+import path15 from "path";
 async function handleFindReferences(params) {
   const { filePath, line, character } = params;
   const validation = validateFilePath(filePath);
@@ -3939,7 +4480,7 @@ async function handleFindReferences(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs15.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -3961,7 +4502,7 @@ async function handleFindReferences(params) {
     const enrichedRefs = references.map((ref) => {
       let lineContent = "";
       try {
-        const content = fs12.readFileSync(ref.filePath, "utf-8");
+        const content = fs15.readFileSync(ref.filePath, "utf-8");
         const lines2 = content.split("\n");
         lineContent = lines2[ref.line]?.trim() ?? "";
       } catch {
@@ -3977,11 +4518,11 @@ async function handleFindReferences(params) {
     const projectRoot = getProjectRoot();
     const lines = [
       `\u{1F50D} **Find References** \u2014 ${enrichedRefs.length} references found`,
-      `\u{1F4CD} File: ${path12.relative(projectRoot, resolvedPath)}:${line + 1}:${character + 1}`,
+      `\u{1F4CD} File: ${path15.relative(projectRoot, resolvedPath)}:${line + 1}:${character + 1}`,
       ""
     ];
     for (const [file, refs] of grouped) {
-      const relPath = path12.relative(projectRoot, file);
+      const relPath = path15.relative(projectRoot, file);
       lines.push(`**\u{1F4C4} ${relPath}:**`);
       for (const ref of refs) {
         const loc = `L${ref.line + 1}:${ref.character + 1}`;
@@ -4002,7 +4543,7 @@ async function handleGoToDefinition(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs15.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -4022,10 +4563,10 @@ async function handleGoToDefinition(params) {
 \u26A0\uFE0F Cannot find definition for symbol at this position.`;
     }
     const projectRoot = getProjectRoot();
-    const relPath = path12.relative(projectRoot, definition.filePath);
+    const relPath = path15.relative(projectRoot, definition.filePath);
     let lineContent = "";
     try {
-      const content = fs12.readFileSync(definition.filePath, "utf-8");
+      const content = fs15.readFileSync(definition.filePath, "utf-8");
       const lines2 = content.split("\n");
       lineContent = lines2[definition.line]?.trim() ?? "";
     } catch {
@@ -4057,7 +4598,7 @@ async function handleRenameSymbol(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs15.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -4086,7 +4627,7 @@ Make sure:
     const fileChanges = [];
     for (const change of result.changes) {
       try {
-        const content = fs12.readFileSync(change.filePath, "utf-8");
+        const content = fs15.readFileSync(change.filePath, "utf-8");
         const lines2 = content.split("\n");
         const sortedEdits = [...change.edits].sort((a, b) => {
           if (b.line !== a.line) return b.line - a.line;
@@ -4100,10 +4641,10 @@ Make sure:
             lines2[edit.line] = before + edit.newText + after;
           }
         }
-        fs12.writeFileSync(change.filePath, lines2.join("\n"), "utf-8");
+        fs15.writeFileSync(change.filePath, lines2.join("\n"), "utf-8");
         totalEdits += change.edits.length;
         fileChanges.push({
-          filePath: path12.relative(projectRoot, change.filePath),
+          filePath: path15.relative(projectRoot, change.filePath),
           editCount: change.edits.length
         });
       } catch (err) {
@@ -4130,13 +4671,13 @@ async function handleGetTypeInfo(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs15.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
     sessionMemory.recordToolCall("lsp_query", { action: "type", filePath, line, character, fallback: "line-context" });
     try {
-      const fileContent = fs12.readFileSync(resolvedPath, "utf-8");
+      const fileContent = fs15.readFileSync(resolvedPath, "utf-8");
       const fileLines = fileContent.split("\n");
       const targetLine = fileLines[line];
       if (!targetLine) {
@@ -4144,7 +4685,7 @@ async function handleGetTypeInfo(params) {
       }
       const symbolName = extractSymbolAtPosition(resolvedPath, line, character);
       const projectRoot = getProjectRoot();
-      const relPath = path12.relative(projectRoot, resolvedPath);
+      const relPath = path15.relative(projectRoot, resolvedPath);
       const contextStart = Math.max(0, line - 3);
       const contextEnd = Math.min(fileLines.length, line + 4);
       const contextLines = [];
@@ -4182,7 +4723,7 @@ async function handleGetTypeInfo(params) {
 \u26A0\uFE0F No type info for this position.`;
     }
     const projectRoot = getProjectRoot();
-    const relPath = path12.relative(projectRoot, resolvedPath);
+    const relPath = path15.relative(projectRoot, resolvedPath);
     const lines = [
       `\u{1F4CB} **Type Info** \u2014 \`${relPath}:${line + 1}:${character + 1}\``,
       "",
@@ -4223,7 +4764,7 @@ async function handleLspQuery(params) {
 }
 function extractSymbolAtPosition(filePath, line, character) {
   try {
-    const content = fs12.readFileSync(filePath, "utf-8");
+    const content = fs15.readFileSync(filePath, "utf-8");
     const lines = content.split("\n");
     const targetLine = lines[line];
     if (!targetLine) return null;
@@ -4254,7 +4795,7 @@ async function fallbackGrepReferences(symbolName, _filePath, _line, _character)
     const regex = new RegExp(`\\b${escapedSymbol}\\b`, "g");
     for (const file of tsFiles.slice(0, 100)) {
       try {
-        const content = fs12.readFileSync(file, "utf-8");
+        const content = fs15.readFileSync(file, "utf-8");
         const lines2 = content.split("\n");
         for (let i = 0; i < lines2.length; i++) {
           if (regex.test(lines2[i])) {
@@ -4283,8 +4824,28 @@ async function fallbackGrepReferences(symbolName, _filePath, _line, _character)
       `\u26A0\uFE0F Regex results may be less accurate than LSP (includes comments/strings).`,
       ""
     ];
+    if (grouped.size > 1) {
+      const fileList = [...grouped.keys()].map((f) => path15.relative(projectRoot, f)).join(", ");
+      lines.push(`\u26A0\uFE0F **Ambiguity warning:** Found matches across ${grouped.size} different files (${fileList}).`);
+      lines.push(`   Regex fallback cannot distinguish between different scopes with the same symbol name.`);
+      lines.push(`   If you intended only one scope, clarify which file or location you mean.`);
+      lines.push(`   \u{1F4A1} Install typescript-language-server for scope-aware disambiguation.`);
+      lines.push("");
+    } else if (results.length > 1) {
+      const filePath = [...grouped.keys()][0];
+      const refs = grouped.get(filePath);
+      const matchLines = refs.map((r) => r.line);
+      const minLine = Math.min(...matchLines);
+      const maxLine = Math.max(...matchLines);
+      if (maxLine - minLine > 15) {
+        lines.push(`\u26A0\uFE0F **Ambiguity warning:** Found ${results.length} matches for "${symbolName}" spanning lines ${minLine}-${maxLine} in the same file.`);
+        lines.push(`   They may be in different function scopes \u2014 regex cannot distinguish them.`);
+        lines.push(`   \u{1F4A1} Verify each match is the intended symbol before editing.`);
+        lines.push("");
+      }
+    }
     for (const [file, refs] of grouped) {
-      const relPath = path12.relative(projectRoot, file);
+      const relPath = path15.relative(projectRoot, file);
       lines.push(`**\u{1F4C4} ${relPath}:**`);
       for (const ref of refs) {
         lines.push(`  \u2514 L${ref.line} \u2014 ${ref.content}`);
@@ -4318,14 +4879,14 @@ async function fallbackGrepDefinition(symbolName) {
     ];
     for (const file of tsFiles) {
       try {
-        const content = fs12.readFileSync(file, "utf-8");
+        const content = fs15.readFileSync(file, "utf-8");
         const lines = content.split("\n");
         for (let i = 0; i < lines.length; i++) {
           const trimmed = lines[i].trim();
           for (const pattern of declPatterns) {
             if (pattern.test(trimmed)) {
               const projectRoot = getProjectRoot();
-              const relPath = path12.relative(projectRoot, file);
+              const relPath = path15.relative(projectRoot, file);
               return [
                 `\u{1F4CD} **Go to Definition** (regex fallback)`,
                 `\u{1F4C4} File: \`${relPath}\``,
@@ -4356,7 +4917,7 @@ function registerAllTools(server) {
     "smart_grep",
     "Narrow down to the specific code you need. Locates functions or text patterns \u2014 returns filename, line number, and 3 lines of context.",
     {
-      query: z.string().min(1).describe("Regex pattern to search for"),
+      query: z.string({ invalid_type_error: 'smart_grep: "query" must be a string regex pattern.\n\n\u2705 Example: { query: "function handleUser" }' }).min(1).describe("Regex pattern to search for. Example: 'function handleAuth' or 'console\\.log'"),
       targetFolder: z.string().optional().describe("Target folder (default: project root, max depth 3)"),
       maxResults: z.number().min(1).max(100).optional().default(30).describe("Max results to return"),
       extensions: z.array(z.string()).optional().describe("Filter results by file extensions (e.g. ['ts', 'js'])")
@@ -4392,15 +4953,17 @@ function registerAllTools(server) {
     "precise_diff_editor",
     "Edit code with safety net. Search-and-replace with fuzzy fallback + automatic versioned backup. Use action:'rollback' to undo edits.",
     {
-      filePath: z.string().min(1).describe("Path to the file to edit"),
-      action: z.enum(["rollback"]).optional().describe("Set to 'rollback' to restore from backup"),
+      filePath: z.string({ invalid_type_error: 'precise_diff_editor: "filePath" must be a string path relative to project root.\n\n\u2705 Example: "src/example.ts"' }).min(1).describe("Path to the file to edit"),
+      action: z.enum(["rollback"]).optional().describe("Set to 'rollback' to restore from backup. Only use when restoring from backup."),
       edits: z.array(z.object({
-        searchBlock: z.string().min(1).describe("Code block to replace (MUST be exact or fuzzy match)"),
-        replaceBlock: z.string().describe("Replacement code block"),
+        searchBlock: z.string({ invalid_type_error: '"searchBlock" must be a string of the exact code to replace' }).min(1).describe("Code block to replace (MUST be exact or fuzzy match)"),
+        replaceBlock: z.string({ invalid_type_error: '"replaceBlock" must be a string of the replacement code' }).describe("Replacement code block"),
         allowMultiple: z.boolean().optional().default(false).describe("Allow multiple replacements"),
         fuzzyThreshold: z.number().min(0).max(1).optional().default(0.85).describe("Fuzzy match threshold (0.0-1.0)")
-      })).min(1).max(10).optional().describe("Array of edits (max 10)"),
-      dryRun: z.boolean().optional().default(false).describe("Preview changes without writing to disk"),
+      }), {
+        invalid_type_error: 'precise_diff_editor: "edits" must be an ARRAY of { searchBlock, replaceBlock } objects.\n\n\u2705 Correct format:\n{\n  edits: [\n    { searchBlock: "old code", replaceBlock: "new code" }\n  ]\n}'
+      }).min(1).max(10).optional().describe("Array of edits (max 10). Each edit has: searchBlock (code to find), replaceBlock (new code)"),
+      dryRun: z.boolean().optional().default(false).describe("Preview changes without writing to disk. Set dryRun: true to preview first."),
       version: z.union([z.number().min(1), z.literal("list")]).optional().describe("Backup version to restore (1=newest, omit=latest, 'list'=show versions)")
     },
     async (params) => {
@@ -4420,7 +4983,10 @@ function registerAllTools(server) {
         filePath: z.string().min(1).describe("File path to create"),
         content: z.string().describe("File content"),
         instructions: z.string().min(1).describe("Reason for creating the file")
-      })).min(1).max(15).describe("Array of files to create (max 15)")
+      }), {
+        invalid_type_error: 'batch_file_writer: "files" must be an ARRAY of objects.\n\n\u2705 Correct format:\n{\n  files: [\n    { filePath: "src/example.ts", content: "// code", instructions: "reason" }\n  ]\n}',
+        required_error: 'batch_file_writer: "files" is required.\n\n\u2705 Correct format:\n{\n  files: [\n    { filePath: "src/example.ts", content: "// code", instructions: "reason" }\n  ]\n}'
+      }).min(1).max(15).describe("Array of files to create (max 15). Example: [{ filePath: 'src/x.ts', content: '...', instructions: 'why' }]")
     },
     async (params) => {
       try {
@@ -4433,11 +4999,13 @@ function registerAllTools(server) {
   );
   server.tool(
     "execute_safe_test",
-    "Run tests, lint, or typecheck with timeout protection and circuit breaker. Use after every edit to verify you didn't break anything.",
+    "Run tests, lint, or typecheck with timeout protection and circuit breaker. Supports monorepo workspaces via 'workspace' or relative 'cwd'. Use after every edit to verify you didn't break anything.",
     {
-      task: z.enum(["test", "build", "lint", "typecheck", "custom"]).describe("Task to execute"),
-      customCommand: z.string().optional().describe("Custom command (only if task='custom')"),
-      timeout: z.number().min(5).max(180).optional().default(60).describe("Timeout in seconds (default: 60s, max: 180s)")
+      task: z.enum(["test", "build", "lint", "typecheck", "custom"]).describe("Task to execute: test, build, lint, typecheck, or custom"),
+      customCommand: z.string({ invalid_type_error: '"customCommand" must be a string command like "npm run my-script"' }).optional().describe("Custom command (required only if task='custom')"),
+      timeout: z.number({ invalid_type_error: '"timeout" must be a number in seconds (5-180)' }).min(5).max(180).optional().default(60).describe("Timeout in seconds (default: 60s, max: 180s)"),
+      cwd: z.string().optional().describe("Relative directory from project root (e.g. 'packages/web'). Defaults to project root."),
+      workspace: z.string().optional().describe("Workspace name from project_conventions (e.g. 'frontend', 'api'). Auto-resolves to path.")
     },
     async (params) => {
       try {
@@ -4485,7 +5053,7 @@ function registerAllTools(server) {
     "get_session_memory",
     "Check what you've done this session: modified files, unresolved failures, tool history, memories. Accepts optional topic to load a specific memory file.",
     {
-      topic: z.enum(MEMORY_TOPICS).optional().describe("Load a specific memory topic (decisions, glossary, architecture, conventions, known-issues)")
+      topic: z.enum(MEMORY_TOPICS).optional().describe("Load a specific memory topic: decisions, glossary, architecture, conventions, known-issues. Example: { topic: 'decisions' }")
     },
     async (params) => {
       try {
@@ -4500,11 +5068,11 @@ function registerAllTools(server) {
     "lsp_query",
     "Jump to definition, find references, inspect types, or rename symbols. Uses TypeScript Language Server \u2014 falls back to regex when LSP is unavailable.",
     {
-      filePath: z.string().min(1).describe("Path to the file containing the symbol"),
-      line: z.number().min(0).describe("Line number (0-indexed)"),
-      character: z.number().min(0).describe("Character position (0-indexed)"),
-      action: z.enum(["def", "refs", "type", "rename"]).describe("Action: def/go to definition, refs/find references, type/get type info, rename/rename symbol"),
-      newName: z.string().optional().describe("New name (required for action:'rename')")
+      filePath: z.string({ invalid_type_error: 'lsp_query: "filePath" must be a string path.\n\n\u2705 Example: { filePath: "src/index.ts", line: 10, character: 5, action: "def" }' }).min(1).describe("Path to the file containing the symbol"),
+      line: z.number({ invalid_type_error: '"line" must be a number (0-indexed). Line 0 = first line.' }).min(0).describe("Line number (0-indexed)"),
+      character: z.number({ invalid_type_error: '"character" must be a number (0-indexed). Position within the line.' }).min(0).describe("Character position (0-indexed)"),
+      action: z.enum(["def", "refs", "type", "rename"]).describe("Action: def=go to definition, refs=find references, type=get type info, rename=rename symbol"),
+      newName: z.string().optional().describe("New name (required for action:'rename'). Example: { action: 'rename', newName: 'newFunctionName' }")
     },
     async (params) => {
       try {
@@ -4612,7 +5180,23 @@ function registerAllTools(server) {
         const result = searchSessionMemory(params);
         return { content: [{ type: "text", text: result }] };
       } catch (err) {
-        return { content: [{ type: "text", text: `Error in search_session_memory: ${err}` }], isError: true };
+        return { content: [{ type: "text", text: `Error in search_session_memory: ${err}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "kuma_guard",
+    "Context safety net. Checks for anti-patterns (script patching, bash grep), loops, drift (edits without tests, unresolved failures). Run this after every few edits to stay on track.",
+    {
+      check: z.enum(["all", "anti-pattern", "loop", "drift", "context"]).optional().default("all").describe("Check type: all=everything, anti-pattern=script/grep detection, loop=loop detection, drift=edit vs test balance"),
+      goal: z.string({ invalid_type_error: 'kuma_guard: "goal" must be a string describing what you are working on.\n\n\u2705 Example: { goal: "refactor auth module" }' }).optional().describe("Optional goal to check against. Example: 'refactor auth module'")
+    },
+    async (params) => {
+      try {
+        const result = await handleKumaGuard(params);
+        return { content: [{ type: "text", text: result }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error in kuma_guard: ${err}` }], isError: true };
       }
     }
   );
@@ -4634,7 +5218,827 @@ function registerAllTools(server) {
       }
     }
   );
-  console.error("[Manifest] Registered 16 tools.");
+  server.tool(
+    "kuma_context",
+    "Context snapshot manager. Save a snapshot of current project state (modified files, errors, git diff) or list previous snapshots. Run this before risky operations to have a restore point.",
+    {
+      action: z.enum(["save", "list"]).describe("Action: save=create a snapshot, list=show all snapshots"),
+      goal: z.string().optional().describe("Optional goal to associate with the snapshot")
+    },
+    async (params) => {
+      try {
+        const result = await handleKumaContext(params);
+        return { content: [{ type: "text", text: result }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
+      }
+    }
+  );
+  console.error("[Manifest] Registered 17 tools.");
+}
+
+// src/cli/init.ts
+import fs16 from "fs";
+import path16 from "path";
+var ALL_CONFIG_TYPES = [
+  "claude",
+  "cursor",
+  "windsurf",
+  "copilot",
+  "cline",
+  "aider",
+  "antigravity",
+  "opencode",
+  "codex",
+  "qwen",
+  "kiro",
+  "openclaw",
+  "codewhale"
+];
+var CONFIG_LABELS = {
+  claude: "Claude Code (CLAUDE.md / plugin)",
+  cursor: "Cursor (.cursor/rules/*.mdc)",
+  windsurf: "Windsurf (.windsurfrules)",
+  copilot: "GitHub Copilot Editor (AGENTS.md + Skill)",
+  cline: "Cline (.clinerules/*.md)",
+  aider: "Aider (CONVENTIONS.md via .aider.conf.yml)",
+  antigravity: "Antigravity CLI (.agents/skills/)",
+  opencode: "OpenCode (opencode.json)",
+  codex: "Codex CLI (AGENTS.md + .codex/config.toml)",
+  qwen: "Qwen Code (AGENTS.md + settings.json)",
+  kiro: "Kiro (.kiro/steering/*.md)",
+  openclaw: "OpenClaw (skills/)",
+  codewhale: "CodeWhale (skills/ + .codewhale/mcp.json)"
+};
+function configFilePath(type) {
+  switch (type) {
+    case "claude":
+      return "CLAUDE.md";
+    case "cursor":
+      return ".cursor/rules/kuma.mdc";
+    case "windsurf":
+      return ".windsurfrules";
+    case "copilot":
+      return "AGENTS.md";
+    case "cline":
+      return ".clinerules/kuma.md";
+    case "aider":
+      return "CONVENTIONS.md";
+    case "antigravity":
+      return ".agents/skills/kuma/SKILL.md";
+    case "opencode":
+      return "opencode.json";
+    case "codex":
+      return "AGENTS.md";
+    case "qwen":
+      return "AGENTS.md";
+    case "kiro":
+      return ".kiro/steering/kuma.md";
+    case "openclaw":
+      return "skills/kuma/SKILL.md";
+    case "codewhale":
+      return "skills/kuma/SKILL.md";
+  }
+}
+var CORE_RULES = [
+  "## AI Agent Usage Guidelines",
+  "",
+  "Kuma MCP tools are available. Use them correctly:",
+  "",
+  "### Code Search",
+  "- Use the **smart_grep** tool to search code - NOT bash grep/ripgrep manually",
+  "- smart_grep returns line numbers + context, caches results, respects .gitignore",
+  `- **Example:** smart_grep({ query: "function handleAuth", extensions: ['ts'] })`,
+  "",
+  "### Reading Code",
+  "- Use the **smart_file_picker** tool to read files with smart chunking",
+  "- For large files, use startLine/endLine to read specific ranges",
+  '- **Example:** smart_file_picker({ filePath: "src/index.ts", chunkStrategy: "outline" })',
+  '- **Example:** smart_file_picker({ filePath: "src/index.ts", startLine: 10, endLine: 30 })',
+  "",
+  "### Editing Code",
+  "- Use the **precise_diff_editor** tool to edit files (fuzzy matching + auto-backup)",
+  "- DO NOT create Python/Node scripts to patch files; use precise_diff_editor directly",
+  "- DO NOT use bash sed/cat/awk to modify source files",
+  '- **Example:** precise_diff_editor({ filePath: "src/app.ts", edits: [{ searchBlock: "old code", replaceBlock: "new code" }] })',
+  '- **Example:** precise_diff_editor({ filePath: "src/app.ts", dryRun: true, edits: [...] })',
+  '- **Example:** precise_diff_editor({ filePath: "src/app.ts", action: "rollback" })',
+  "",
+  "### Creating Files",
+  "- Use the **batch_file_writer** tool to create new files (up to 15 at once)",
+  '- **Example:** batch_file_writer({ files: [{ filePath: "src/util.ts", content: "// code", instructions: "reason for creating" }] })',
+  "",
+  "### Running Tasks",
+  "- Use the **execute_safe_test** tool for test/build/lint/typecheck",
+  "- Always run typecheck after editing TypeScript files",
+  '- **Example:** execute_safe_test({ task: "typecheck" })',
+  '- **Example:** execute_safe_test({ task: "custom", customCommand: "npm run lint" })',
+  "",
+  "### Code Review",
+  "- Use the **code_reviewer** tool after changes",
+  "- Supports focus: correctness, security, performance, over-engineering",
+  '- **Example:** code_reviewer({ focus: "security" })',
+  '- **Example:** code_reviewer({ files: ["src/auth.ts"], format: "json" })',
+  "",
+  "### Git Operations",
+  "- Use the **git_diff** tool for structured diff output",
+  "- Use the **git_log** tool for commit history",
+  "- **Example:** git_log({ maxCount: 5 })",
+  "- **Example:** git_diff({ staged: true })",
+  "",
+  "### Session Awareness",
+  "- Use the **kuma_reflect** tool to check on-track/drift/loops",
+  "- Use the **kuma_guard** tool for deeper safety checks (anti-patterns, auto-detection)",
+  "- Use the **get_session_memory** tool to recall session state",
+  '- **Example:** kuma_reflect({ goal: "refactor auth" })',
+  '- **Example:** kuma_guard({ check: "all", goal: "refactor auth" })',
+  "",
+  "### LSP / Code Intelligence",
+  "- Use the **lsp_query** tool for go-to-definition, find references, type info",
+  '- **Example:** lsp_query({ filePath: "src/index.ts", line: 5, character: 10, action: "def" })',
+  '- **Example:** lsp_query({ filePath: "src/index.ts", line: 5, character: 10, action: "refs" })',
+  "",
+  "### Static Analysis",
+  "- Use the **static_analysis** tool to run ESLint/TSC/Prettier/Ruff",
+  '- **Example:** static_analysis({ tool: "eslint", autoFix: true })',
+  "",
+  "### Project Structure",
+  "- Use the **project_structure** tool to see project layout",
+  "- **Example:** project_structure({ depth: 2, folderOnly: true })",
+  "",
+  "### Write Memory",
+  "- Use the **write_memory** tool to persist decisions and glossary",
+  '- **Example:** write_memory({ topic: "decisions", content: "## Reason for using X" })',
+  "",
+  "### General Rules",
+  "- When you error, READ the error carefully before acting",
+  "- After 3+ edits without running tests, stop and verify",
+  "- If a tool fails, check the message - don't retry blindly",
+  "- Detect conventions first with the **project_conventions** tool",
+  "- **Example:** project_conventions({ forceRescan: true })"
+].join("\n");
+var KUMA_CORE_INSTRUCTIONS = CORE_RULES;
+function claudeTemplate() {
+  return [
+    "# Kuma AI Agent Guidelines",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## Workflow Pipeline",
+    "",
+    "For best results:",
+    "1. **project_conventions** - detect stack",
+    "2. **smart_grep** / **smart_file_picker** - understand code",
+    "3. **precise_diff_editor** / **batch_file_writer** - make changes",
+    "4. **execute_safe_test** - verify (typecheck + test)",
+    "5. **code_reviewer** - review changes"
+  ].join("\n");
+}
+function cursorRulesTemplate() {
+  return [
+    "---",
+    "description: Kuma MCP tool usage rules for AI coding agents",
+    "alwaysApply: true",
+    "---",
+    "",
+    "You are an expert engineer. Kuma MCP tools are available.",
+    "",
+    "## Critical Rules",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## NEVER",
+    "- Never create Python/Node scripts to patch code",
+    "- Never use bash sed/cat/awk to edit source files",
+    "- Never run git push/git commit through bash"
+  ].join("\n");
+}
+function windsurfRulesTemplate() {
+  return [
+    "# Windsurf Cascade Rules with Kuma",
+    "",
+    KUMA_CORE_INSTRUCTIONS
+  ].join("\n");
+}
+function copilotTemplate() {
+  return [
+    "## GitHub Copilot Editor",
+    "",
+    "Kuma MCP tools are available. Use them correctly:",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "### Copilot Editor-Specific",
+    "- Copilot Editor reads AGENTS.md at project root for persistent instructions",
+    "- Configure MCP servers via VS Code settings (cmd+shift+P \u2192 Developer: Reload Window after adding Kuma)",
+    "- Use kuma_guard periodically to check for anti-patterns"
+  ].join("\n");
+}
+function clineRulesTemplate() {
+  return [
+    "---",
+    "description: Kuma MCP tool usage rules for AI coding agents",
+    "paths:",
+    '  - "*"',
+    "---",
+    "",
+    KUMA_CORE_INSTRUCTIONS
+  ].join("\n");
+}
+function aiderTemplate() {
+  return [
+    "# Kuma MCP - Aider Coding Conventions",
+    "",
+    "These conventions are loaded by Aider via the `read:` field in .aider.conf.yml",
+    "",
+    KUMA_CORE_INSTRUCTIONS
+  ].join("\n");
+}
+function opencodeTemplate() {
+  const config = {
+    mcp: {
+      kuma: {
+        type: "local",
+        command: ["npx", "-y", "@plumpslabs/kuma"],
+        enabled: true
+      }
+    },
+    instructions: ["CLAUDE.md"]
+  };
+  const header = [
+    "// Generated by Kuma MCP - https://github.com/plumpslabs/kuma",
+    "// OpenCode config with Kuma MCP tools. Edit opencode.json to customize.",
+    ""
+  ].join("\n");
+  return header + JSON.stringify(config, null, 2) + "\n";
+}
+function codexTemplate() {
+  return [
+    "## Codex CLI (OpenAI)",
+    "",
+    "Kuma MCP tools are available. Use them correctly:",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "### Codex-Specific",
+    "- Codex uses cascading AGENTS.md files (global ~/.codex/AGENTS.md -> project AGENTS.md)",
+    "- MCP config is in .codex/config.toml (auto-generated by kuma init)",
+    "- Use kuma_guard periodically to check for anti-patterns"
+  ].join("\n");
+}
+function codexConfigTomlTemplate() {
+  return [
+    "# Generated by Kuma MCP - https://github.com/plumpslabs/kuma",
+    "# Kuma MCP server config for Codex CLI",
+    "",
+    "[mcp_servers.kuma]",
+    'command = "npx"',
+    'args = ["-y", "@plumpslabs/kuma"]',
+    ""
+  ].join("\n");
+}
+function qwenTemplate() {
+  return [
+    "## Qwen Code",
+    "",
+    "Kuma MCP tools are available. Use them correctly:",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "### Qwen-Specific",
+    "- Qwen reads AGENTS.md at project root for persistent instructions",
+    "- MCP config is in settings.json (auto-generated by kuma init)",
+    "- Use kuma_guard periodically to check for anti-patterns"
+  ].join("\n");
+}
+function qwenSettingsTemplate() {
+  const config = {
+    mcpServers: {
+      kuma: {
+        command: "npx",
+        args: ["-y", "@plumpslabs/kuma"],
+        env: {}
+      }
+    }
+  };
+  return JSON.stringify(config, null, 2) + "\n";
+}
+function kiroRulesTemplate() {
+  return [
+    "---",
+    "name: kuma-mcp",
+    "description: Kuma safety toolkit - use smart_grep for search, precise_diff_editor for edits",
+    "inclusion: always",
+    "---",
+    "",
+    "# Kuma MCP - Kiro Steering",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## Kiro-Specific",
+    "- Kiro reads steering files from .kiro/steering/ for project instructions",
+    "- Configure MCP servers via IDE settings or global Kiro config",
+    "- Use kuma_guard periodically to check for anti-patterns"
+  ].join("\n");
+}
+function openclawSkillTemplate() {
+  return [
+    "---",
+    "name: kuma-mcp",
+    "description: Kuma safety toolkit for AI coding agents. Use smart_grep for search, precise_diff_editor for edits, execute_safe_test for verification.",
+    "---",
+    "",
+    "# Kuma MCP - OpenClaw Skill",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## OpenClaw-Specific",
+    "- OpenClaw loads skills/ from workspace root or ~/.openclaw/skills for global",
+    "- Configure Kuma MCP server via ~/.openclaw/openclaw.json or agents standard",
+    "- Use kuma_guard periodically to check for anti-patterns",
+    "",
+    "## Verification",
+    "- After edits, run execute_safe_test to verify no breakage",
+    "- Use code_reviewer for correctness/security review",
+    "- Check kuma_reflect to confirm on-track"
+  ].join("\n");
+}
+function codewhaleTemplate() {
+  return [
+    "---",
+    "name: kuma-mcp",
+    "description: Kuma safety toolkit for AI coding agents. Use smart_grep for search, precise_diff_editor for edits, execute_safe_test for verification.",
+    "---",
+    "",
+    "# Kuma MCP - CodeWhale Skill",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## CodeWhale-Specific",
+    "- CodeWhale loads SKILL.md from skills/ (workspace-local), .agents/skills/, or ~/.codewhale/skills/",
+    "- MCP config is in ~/.codewhale/mcp.json or ~/.deepseek/mcp.json",
+    "- Use kuma_guard periodically to check for anti-patterns",
+    "",
+    "## Verification",
+    "- After edits, run execute_safe_test to verify no breakage",
+    "- Use code_reviewer for correctness/security review",
+    "- Check kuma_reflect to confirm on-track"
+  ].join("\n");
+}
+function antigravitySkillTemplate() {
+  return [
+    "---",
+    "name: kuma-mcp",
+    "description: Kuma safety toolkit for AI coding agents. Use smart_grep for search, precise_diff_editor for edits, execute_safe_test for verification.",
+    "---",
+    "",
+    "# Kuma MCP - Antigravity Skill",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "## Verification",
+    "- After edits, run execute_safe_test to verify no breakage",
+    "- Use code_reviewer for correctness/security review",
+    "- Check kuma_reflect to confirm on-track"
+  ].join("\n");
+}
+function antigravityMcpConfigTemplate() {
+  const config = {
+    mcpServers: {
+      kuma: {
+        command: "npx",
+        args: ["-y", "@plumpslabs/kuma"],
+        env: {}
+      }
+    }
+  };
+  return JSON.stringify(config, null, 2) + "\n";
+}
+var TEMPLATES = {
+  claude: claudeTemplate,
+  cursor: cursorRulesTemplate,
+  windsurf: windsurfRulesTemplate,
+  copilot: copilotTemplate,
+  cline: clineRulesTemplate,
+  aider: aiderTemplate,
+  antigravity: antigravitySkillTemplate,
+  opencode: opencodeTemplate,
+  codex: codexTemplate,
+  qwen: qwenTemplate,
+  kiro: kiroRulesTemplate,
+  openclaw: openclawSkillTemplate,
+  codewhale: codewhaleTemplate
+};
+var APPEND_SEPARATOR = "\n\n---\n_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_\n\n";
+function handleOpencodeSecondary(root, results) {
+  const claudePath = path16.resolve(root, "CLAUDE.md");
+  if (!fs16.existsSync(claudePath)) {
+    try {
+      fs16.writeFileSync(claudePath, [
+        "# Kuma MCP - OpenCode Instructions",
+        "",
+        KUMA_CORE_INSTRUCTIONS
+      ].join("\n"), "utf-8");
+      results.push({ type: "opencode", filePath: "CLAUDE.md", action: "created" });
+    } catch (err) {
+      results.push({
+        type: "opencode",
+        filePath: "CLAUDE.md",
+        action: "error",
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+}
+function handleCodexSecondary(root, results) {
+  const tomlPath = path16.resolve(root, ".codex/config.toml");
+  if (results.some((r) => r.filePath === ".codex/config.toml")) return;
+  try {
+    const dir = path16.dirname(tomlPath);
+    if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+    if (fs16.existsSync(tomlPath)) {
+      const existingContent = fs16.readFileSync(tomlPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
+        return;
+      }
+      fs16.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
+    } else {
+      fs16.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
+      results.push({ type: "codex", filePath: ".codex/config.toml", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "codex",
+      filePath: ".codex/config.toml",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function handleQwenSecondary(root, results) {
+  const settingsPath = path16.resolve(root, "settings.json");
+  if (results.some((r) => r.filePath === "settings.json")) return;
+  try {
+    if (fs16.existsSync(settingsPath)) {
+      const existingContent = fs16.readFileSync(settingsPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        if (!existingContent.includes("_Generated by Kuma MCP_")) {
+          try {
+            const parsed = JSON.parse(existingContent);
+            parsed.mcpServers = parsed.mcpServers || {};
+            if (!parsed.mcpServers.kuma) {
+              parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
+              fs16.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+              results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
+              return;
+            }
+          } catch {
+          }
+        }
+        results.push({ type: "qwen", filePath: "settings.json", action: "skipped" });
+        return;
+      }
+      try {
+        const parsed = JSON.parse(existingContent);
+        parsed.mcpServers = parsed.mcpServers || {};
+        if (!parsed.mcpServers.kuma) {
+          parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
+          fs16.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
+        }
+      } catch {
+      }
+    } else {
+      fs16.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
+      results.push({ type: "qwen", filePath: "settings.json", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "qwen",
+      filePath: "settings.json",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+var AGENTS_MD_TYPES = ["codex", "qwen", "copilot"];
+function getAgentsMdHeader() {
+  return [
+    "# Kuma MCP - Combined Agent Instructions",
+    "",
+    "This file contains instructions for AI coding agents that read AGENTS.md.",
+    "Each section applies to a specific agent. Unused sections can be safely removed.",
+    "",
+    "---",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_",
+    ""
+  ].join("\n");
+}
+function getCombinedAgentsMd(selectedTypes) {
+  const sections = [getAgentsMdHeader()];
+  const agentOrder = ["codex", "qwen", "copilot"];
+  for (const t of agentOrder) {
+    if (selectedTypes.has(t)) {
+      sections.push(TEMPLATES[t]());
+    }
+  }
+  return sections.join("\n\n---\n\n");
+}
+function handleAntigravityMcpConfig(root, results) {
+  const mcpPath = path16.resolve(root, ".agents/mcp_config.json");
+  if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
+  try {
+    const mcpDir = path16.dirname(mcpPath);
+    if (fs16.existsSync(mcpPath)) {
+      const existingContent = fs16.readFileSync(mcpPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        if (!existingContent.includes("_Generated by Kuma MCP_")) {
+          const trimmed = existingContent.trimEnd();
+          if (trimmed.endsWith("}")) {
+            const updated = trimmed.slice(0, -1).trimEnd() + ',\n  "_kuma_note": "Kuma MCP - Generated by kuma init"\n}\n';
+            fs16.writeFileSync(mcpPath, updated, "utf-8");
+            results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
+          }
+        }
+        return;
+      }
+      const parsed = JSON.parse(existingContent);
+      parsed.mcpServers = parsed.mcpServers || {};
+      parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
+      fs16.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
+    } else {
+      if (!fs16.existsSync(mcpDir)) fs16.mkdirSync(mcpDir, { recursive: true });
+      fs16.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "antigravity",
+      filePath: ".agents/mcp_config.json",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function handleAiderSecondary(root, results) {
+  const ymlPath = path16.resolve(root, ".aider.conf.yml");
+  if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
+  try {
+    const conventionsRef = "read: CONVENTIONS.md";
+    if (fs16.existsSync(ymlPath)) {
+      const existingContent = fs16.readFileSync(ymlPath, "utf-8");
+      if (existingContent.includes("CONVENTIONS.md") || existingContent.includes("kuma")) {
+        results.push({ type: "aider", filePath: ".aider.conf.yml", action: "skipped" });
+        return;
+      }
+      const newContent = existingContent.trimEnd() + "\n\n# Kuma MCP conventions\n" + conventionsRef + "\n";
+      fs16.writeFileSync(ymlPath, newContent, "utf-8");
+      results.push({ type: "aider", filePath: ".aider.conf.yml", action: "appended" });
+    } else {
+      const content = [
+        "# Generated by Kuma MCP - https://github.com/plumpslabs/kuma",
+        "# Aider will read CONVENTIONS.md for coding conventions",
+        "",
+        conventionsRef,
+        ""
+      ].join("\n");
+      fs16.writeFileSync(ymlPath, content, "utf-8");
+      results.push({ type: "aider", filePath: ".aider.conf.yml", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "aider",
+      filePath: ".aider.conf.yml",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function handleCopilotSecondary(root, results) {
+  const skillPath = path16.resolve(root, ".github/skills/kuma/SKILL.md");
+  if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
+  try {
+    const dir = path16.dirname(skillPath);
+    const content = [
+      "---",
+      "name: kuma-mcp",
+      "description: Kuma safety toolkit for AI coding agents. Use smart_grep for search, precise_diff_editor for edits, execute_safe_test for verification.",
+      "---",
+      "",
+      "# Kuma MCP - Copilot Editor Skill",
+      "",
+      KUMA_CORE_INSTRUCTIONS
+    ].join("\n");
+    if (fs16.existsSync(skillPath)) {
+      const existingContent = fs16.readFileSync(skillPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
+        return;
+      }
+      fs16.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
+    } else {
+      if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+      fs16.writeFileSync(skillPath, content, "utf-8");
+      results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "copilot",
+      filePath: ".github/skills/kuma/SKILL.md",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function handleOpenclawSecondary(root, results) {
+  const mcpPath = path16.resolve(root, ".agents/mcp_config.json");
+  if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
+  try {
+    const dir = path16.dirname(mcpPath);
+    if (fs16.existsSync(mcpPath)) {
+      const existingContent = fs16.readFileSync(mcpPath, "utf-8");
+      if (existingContent.includes("kuma")) return;
+      const parsed = JSON.parse(existingContent);
+      parsed.mcpServers = parsed.mcpServers || {};
+      parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
+      fs16.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
+    } else {
+      if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+      fs16.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "openclaw",
+      filePath: ".agents/mcp_config.json",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function handleCodewhaleSecondary(root, results) {
+  const mcpPath = path16.resolve(root, ".codewhale/mcp.json");
+  if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
+  try {
+    const dir = path16.dirname(mcpPath);
+    if (fs16.existsSync(mcpPath)) {
+      const existingContent = fs16.readFileSync(mcpPath, "utf-8");
+      if (existingContent.includes("kuma")) return;
+      const parsed = JSON.parse(existingContent);
+      parsed.mcpServers = parsed.mcpServers || {};
+      parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
+      fs16.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
+    } else {
+      if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+      const config = {
+        mcpServers: {
+          kuma: {
+            command: "npx",
+            args: ["-y", "@plumpslabs/kuma"],
+            env: {}
+          }
+        }
+      };
+      fs16.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "codewhale",
+      filePath: ".codewhale/mcp.json",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function runInit(types, projectRoot) {
+  const root = projectRoot ?? getProjectRoot();
+  const selected = types.length > 0 ? types : ALL_CONFIG_TYPES;
+  const results = [];
+  const selectedSet = new Set(selected);
+  const agentsMdSelected = AGENTS_MD_TYPES.filter((t) => selectedSet.has(t));
+  let agentsMdHandled = false;
+  for (const type of selected) {
+    const relativePath = configFilePath(type);
+    const fullPath = path16.resolve(root, relativePath);
+    const getTemplate = TEMPLATES[type];
+    try {
+      if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
+        agentsMdHandled = true;
+        const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
+        if (fs16.existsSync(fullPath)) {
+          const existingContent = fs16.readFileSync(fullPath, "utf-8");
+          if (existingContent.includes("_Generated by Kuma MCP_")) {
+            results.push({ type, filePath: relativePath, action: "skipped" });
+          } else {
+            fs16.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+            results.push({ type, filePath: relativePath, action: "appended" });
+          }
+        } else {
+          const dir = path16.dirname(fullPath);
+          if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+          fs16.writeFileSync(fullPath, combinedContent, "utf-8");
+          results.push({ type, filePath: relativePath, action: "created" });
+        }
+        if (selectedSet.has("codex")) handleCodexSecondary(root, results);
+        if (selectedSet.has("qwen")) handleQwenSecondary(root, results);
+        if (selectedSet.has("copilot")) handleCopilotSecondary(root, results);
+      } else if (AGENTS_MD_TYPES.includes(type) && agentsMdHandled) {
+        results.push({ type, filePath: relativePath, action: "skipped" });
+        continue;
+      } else {
+        const template = getTemplate();
+        if (fs16.existsSync(fullPath)) {
+          const existingContent = fs16.readFileSync(fullPath, "utf-8");
+          if (existingContent.includes("_Generated by Kuma MCP_")) {
+            if (type === "antigravity") {
+              handleAntigravityMcpConfig(root, results);
+            } else if (type === "openclaw") {
+              handleOpenclawSecondary(root, results);
+            } else if (type === "codewhale") {
+              handleCodewhaleSecondary(root, results);
+            }
+            results.push({ type, filePath: relativePath, action: "skipped" });
+            continue;
+          }
+          const newContent = existingContent.trimEnd() + APPEND_SEPARATOR + template;
+          fs16.writeFileSync(fullPath, newContent, "utf-8");
+          results.push({ type, filePath: relativePath, action: "appended" });
+        } else {
+          const dir = path16.dirname(fullPath);
+          if (!fs16.existsSync(dir)) {
+            fs16.mkdirSync(dir, { recursive: true });
+          }
+          fs16.writeFileSync(fullPath, template, "utf-8");
+          results.push({ type, filePath: relativePath, action: "created" });
+        }
+        if (type === "antigravity") {
+          handleAntigravityMcpConfig(root, results);
+        } else if (type === "openclaw") {
+          handleOpenclawSecondary(root, results);
+        } else if (type === "codewhale") {
+          handleCodewhaleSecondary(root, results);
+        } else if (type === "aider") {
+          handleAiderSecondary(root, results);
+        } else if (type === "opencode") {
+          handleOpencodeSecondary(root, results);
+        }
+      }
+    } catch (err) {
+      results.push({
+        type,
+        filePath: relativePath,
+        action: "error",
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return results;
+}
+function formatInitResults(results) {
+  const lines = [
+    "\u{1F43B} **Kuma Init - AI Agent Config Generator**",
+    ""
+  ];
+  for (const r of results) {
+    const label = CONFIG_LABELS[r.type];
+    switch (r.action) {
+      case "created":
+        lines.push("  \u2705 " + label);
+        lines.push("     \u2192 Created: " + r.filePath);
+        break;
+      case "appended":
+        lines.push("  \u2795 " + label);
+        lines.push("     \u2192 Appended to: " + r.filePath);
+        break;
+      case "skipped":
+        lines.push("  \u23ED " + label);
+        lines.push("     \u2192 Skipped (already has Kuma): " + r.filePath);
+        break;
+      case "error":
+        lines.push("  \u274C " + label);
+        lines.push("     \u2192 Error: " + (r.error ?? "unknown"));
+        break;
+    }
+  }
+  const created = results.filter((r) => r.action === "created").length;
+  const appended = results.filter((r) => r.action === "appended").length;
+  const skipped = results.filter((r) => r.action === "skipped").length;
+  const errors = results.filter((r) => r.action === "error").length;
+  lines.push(
+    "",
+    "\u{1F4CA} Summary: " + created + " created, " + appended + " appended, " + skipped + " skipped, " + errors + " errors",
+    "",
+    "\u{1F4A1} Config files teach your AI how to use Kuma tools.",
+    "\u{1F4A1} Run again to generate additional config files anytime."
+  );
+  return lines.join("\n");
 }
 
 // src/index.ts
@@ -4642,7 +6046,92 @@ var SERVER_NAME = "kuma";
 var SERVER_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf-8")
 ).version;
+function printHelp() {
+  console.error(`
+\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Zero-setup safety toolkit for AI coding agents
+
+Usage:
+  npx @plumpslabs/kuma              Start MCP server (default)
+  npx @plumpslabs/kuma init         Generate AI agent config files
+  npx @plumpslabs/kuma init --all   Generate ALL config files
+  npx @plumpslabs/kuma init --claude --cursor  Generate specific files
+  npx @plumpslabs/kuma init --help  Show this help
+
+Available config files:
+  --claude     CLAUDE.md                    (Claude Code)
+  --cursor     .cursor/rules/kuma.mdc       (Cursor)
+  --windsurf   .windsurfrules               (Windsurf)
+  --copilot    AGENTS.md + .github/skills/  (GitHub Copilot Editor)
+  --cline      .clinerules/kuma.md          (Cline)
+  --aider      CONVENTIONS.md + .aider.conf.yml  (Aider)
+  --antigravity .agents/skills/kuma/SKILL.md    (Antigravity CLI)
+  --opencode    opencode.json                (OpenCode)
+  --codex       AGENTS.md + .codex/          (Codex CLI - OpenAI)
+  --qwen        AGENTS.md + settings.json    (Qwen Code)
+  --kiro        .kiro/steering/kuma.md       (Kiro)
+  --openclaw    skills/kuma/SKILL.md         (OpenClaw)
+  --codewhale   skills/kuma/SKILL.md + .codewhale/  (CodeWhale)
+
+If no flags specified, you'll be prompted to select files interactively.
+  `);
+}
 async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === "init") {
+    const flags = args.slice(1);
+    if (flags.includes("--help") || flags.includes("-h")) {
+      printHelp();
+      process.exit(0);
+    }
+    const requestedFlags = flags.filter((f) => f.startsWith("--"));
+    let selectedTypes;
+    if (requestedFlags.length === 0) {
+      console.error("\u{1F43B} Kuma Init \u2014 AI Agent Config Generator");
+      console.error("");
+      console.error("Select config files to generate. Press Ctrl+C to skip.");
+      console.error("");
+      selectedTypes = await interactiveSelect();
+      if (selectedTypes.length === 0) {
+        console.error("\n\u26A0\uFE0F No files selected. Exiting.");
+        process.exit(0);
+      }
+    } else {
+      if (requestedFlags.includes("--all")) {
+        selectedTypes = ALL_CONFIG_TYPES;
+      } else {
+        const flagToType = {
+          "--claude": "claude",
+          "--cursor": "cursor",
+          "--windsurf": "windsurf",
+          "--copilot": "copilot",
+          "--cline": "cline",
+          "--aider": "aider",
+          "--antigravity": "antigravity",
+          "--opencode": "opencode",
+          "--codex": "codex",
+          "--qwen": "qwen",
+          "--kiro": "kiro",
+          "--openclaw": "openclaw",
+          "--codewhale": "codewhale"
+        };
+        selectedTypes = [];
+        for (const flag of requestedFlags) {
+          const type = flagToType[flag];
+          if (type) {
+            selectedTypes.push(type);
+          }
+        }
+        if (selectedTypes.length === 0) {
+          console.error("\u26A0\uFE0F No valid flags provided. Use --help to see options.");
+          process.exit(1);
+        }
+      }
+    }
+    const results = runInit(selectedTypes, process.cwd());
+    const output = formatInitResults(results);
+    console.log(output);
+    process.exit(0);
+  }
   sessionMemory.init({
     projectRoot: process.cwd(),
     startTime: Date.now()
@@ -4653,7 +6142,6 @@ async function main() {
       version: SERVER_VERSION
     },
     {
-      // Capabilities declaration
       capabilities: {
         tools: {},
         resources: {}
@@ -4672,6 +6160,66 @@ async function main() {
     `[${SERVER_NAME}] Server connected via stdio. Waiting for requests...`
   );
 }
+function interactiveSelect() {
+  const labels = [
+    { type: "claude", label: "1) Claude Code (CLAUDE.md)" },
+    { type: "cursor", label: "2) Cursor (.cursor/rules/kuma.mdc)" },
+    { type: "windsurf", label: "3) Windsurf (.windsurfrules)" },
+    { type: "copilot", label: "4) GitHub Copilot Editor (AGENTS.md + Skill)" },
+    { type: "cline", label: "5) Cline (.clinerules/kuma.md)" },
+    { type: "aider", label: "6) Aider (CONVENTIONS.md via .aider.conf.yml)" },
+    { type: "antigravity", label: "7) Antigravity CLI (.agents/skills/)" },
+    { type: "opencode", label: "8) OpenCode (opencode.json)" },
+    { type: "codex", label: "9) Codex CLI - OpenAI (AGENTS.md + .codex/config.toml)" },
+    { type: "qwen", label: "10) Qwen Code (AGENTS.md + settings.json)" },
+    { type: "kiro", label: "11) Kiro (.kiro/steering/kuma.md)" },
+    { type: "openclaw", label: "12) OpenClaw (skills/kuma/SKILL.md)" },
+    { type: "codewhale", label: "13) CodeWhale (skills/kuma/SKILL.md + .codewhale/mcp.json)" }
+  ];
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  return new Promise((resolve) => {
+    console.error("");
+    for (const l of labels) {
+      console.error(l.label);
+    }
+    console.error("");
+    rl.question("Enter numbers separated by space (e.g. '1 3 5'), or 'all': ", (answer) => {
+      rl.close();
+      const input = answer.trim().toLowerCase();
+      if (input === "all") {
+        resolve(ALL_CONFIG_TYPES);
+        return;
+      }
+      const nums = input.split(/\s+/).map(Number).filter((n) => n >= 1 && n <= 13);
+      const typeMap = {
+        1: "claude",
+        2: "cursor",
+        3: "windsurf",
+        4: "copilot",
+        5: "cline",
+        6: "aider",
+        7: "antigravity",
+        8: "opencode",
+        9: "codex",
+        10: "qwen",
+        11: "kiro",
+        12: "openclaw",
+        13: "codewhale"
+      };
+      const selected = [];
+      for (const n of nums) {
+        const t = typeMap[n];
+        if (t && !selected.includes(t)) {
+          selected.push(t);
+        }
+      }
+      resolve(selected);
+    });
+  });
+}
 main().catch((err) => {
   console.error(`[${SERVER_NAME}] Fatal error:`, err);
   process.exit(1);