@plumpslabs/kuma 2.0.5 → 2.1.0

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";
 
@@ -899,7 +900,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 +920,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 +951,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 +986,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 +1037,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) });
     }
   }
@@ -1575,8 +1594,80 @@ function formatBatchResult(results, totalRequested) {
   return lines.join("\n");
 }
 
-// src/tools/safeTerminalExec.ts
+// 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
 var TASK_COMMANDS = {
   test: "npm test",
   build: "npm run build",
@@ -1600,7 +1691,6 @@ var DANGEROUS_PATTERNS = [
   "mkfs",
   "dd if=",
   ":(){ :|:& };:",
-  // fork bomb
   "curl ",
   "wget "
 ];
@@ -1609,12 +1699,7 @@ async function handleSafeTerminalExec(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 command = task === "custom" ? customCommand : TASK_COMMANDS[task];
   const cbResult = circuitBreaker.check("safe_terminal_exec", { task, command });
   if (!cbResult.allowed) {
     return `\u26A0\uFE0F Circuit breaker: ${cbResult.reason}
@@ -1629,7 +1714,10 @@ This command is not permitted.`;
   const projectRoot = getProjectRoot();
   try {
     sessionMemory.recordToolCall("execute_safe_test", { task, command });
-    const result = await executeWithTimeout(command, projectRoot, timeout);
+    const result = await spawnShell(command, {
+      cwd: projectRoot,
+      timeoutSeconds: timeout
+    });
     const output = formatExecResult(result, command, task);
     if (result.exitCode !== 0) {
       sessionMemory.addFailedFile(task, result.stderr || result.stdout);
@@ -1637,65 +1725,12 @@ This command is not permitted.`;
     return output;
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    const isTimeout = errorMsg.toLowerCase().includes("timeout");
-    if (isTimeout) {
+    if (errorMsg.toLowerCase().includes("timeout")) {
       return formatTimeoutResult(command, timeout);
     }
     return `Error running "${command}": ${errorMsg}`;
   }
 }
-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
-      });
-    });
-    proc.on("error", (err) => {
-      clearTimeout(timeoutId);
-      reject(err);
-    });
-  });
-}
-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 = [
@@ -2868,20 +2903,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 +2936,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 +2953,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) {
@@ -3018,6 +3053,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,6 +3064,12 @@ 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);
@@ -3041,7 +3084,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));
   }
@@ -3122,7 +3167,6 @@ function getFileSize(fullPath) {
 }
 
 // src/tools/staticAnalysis.ts
-import { spawn as spawn2 } from "child_process";
 import fs10 from "fs";
 import path10 from "path";
 async function handleStaticAnalysis(params) {
@@ -3216,45 +3260,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();
@@ -3483,7 +3496,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 +3518,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,86 +3589,541 @@ async function handleReflect(params) {
   );
 }
 
-// src/engine/lspClient.ts
-import { spawn as spawn3 } from "child_process";
-import path11 from "path";
+// src/tools/kumaGuard.ts
+import { execSync as execSync6 } from "child_process";
+
+// src/guards/antiPatternDetector.ts
 import fs11 from "fs";
-var LSPClient = class {
-  process = null;
-  requestId = 0;
-  pending = /* @__PURE__ */ new Map();
-  buffer = Buffer.alloc(0);
-  initialized = false;
-  initPromise = null;
-  openDocuments = /* @__PURE__ */ new Set();
-  _isAvailable = true;
-  /** Check whether LSP is available (binary installed) */
-  isAvailable() {
-    return this._isAvailable;
+import path11 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 = path11.extname(file).toLowerCase();
+    if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
+    const relativePath = path11.relative(projectRoot, file);
+    if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".")) {
+      continue;
+    }
+    try {
+      const content = fs11.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: ${path11.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 {
+    }
   }
-  async ensureInitialized() {
-    if (this._isAvailable !== void 0 && !this._isAvailable) return;
-    if (this.initialized && this.process) return;
-    if (this.initPromise) {
+  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 = fs11.readdirSync(projectRoot, { withFileTypes: true });
+    const now = Date.now();
+    const recentThreshold = 30 * 60 * 1e3;
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
       try {
-        await this.initPromise;
-        return;
+        const stat = fs11.statSync(path11.join(projectRoot, entry.name));
+        if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
+          recent.push(path11.join(projectRoot, entry.name));
+        }
       } catch {
-        this.initPromise = null;
+        continue;
       }
     }
-    this.initPromise = this.initialize();
-    return this.initPromise;
+  } catch {
   }
-  async initialize() {
-    const root = getProjectRoot();
-    const lspBinary = this.resolveLspBinary(root);
-    if (!lspBinary) {
-      this._isAvailable = false;
-      this.initialized = false;
-      this.initPromise = null;
-      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)) {
-      console.error(`[LSP] Warning: tsconfig.json not found at "${root}". Running in implicit project mode.`);
-    }
-    this.process = spawn3(lspBinary, ["--stdio", "--log-level=4"], {
-      cwd: root,
-      stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env }
-    });
-    this.process.stdout?.on("data", (data) => {
-      this.buffer = Buffer.concat([this.buffer, data]);
-      this.processBuffer();
-    });
-    this.process.stderr?.on("data", (data) => {
-      console.error(`[LSP] ${data.toString().trim()}`);
-    });
-    this.process.on("exit", (code) => {
-      console.error(`[LSP] Process exited with code ${code}`);
-      this.initialized = false;
-      this.process = null;
-      this.initPromise = null;
-      this.openDocuments.clear();
-      this.buffer = Buffer.alloc(0);
-      for (const [, pending] of this.pending) {
-        pending.reject(new Error(`LSP server exited (code ${code})`));
+  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 = path11.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 = path11.join(projectRoot, file);
+        if (fs11.existsSync(fullPath)) {
+          const content = fs11.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
+            });
+          }
+        }
       }
-      this.pending.clear();
-    });
-    this.process.on("error", (err) => {
-      console.error(`[LSP] Process error: ${err.message}. LSP features will fallback to regex.`);
-      this._isAvailable = false;
-      this.process = null;
-      this.initialized = false;
-      this.initPromise = null;
-      this.openDocuments.clear();
-      for (const [, pending] of this.pending) {
-        pending.reject(new Error(`LSP server error: ${err.message}`));
+    }
+    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 = path11.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
+          });
+        }
       }
-      this.pending.clear();
+    }
+  } 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 fs12 from "fs";
+import path12 from "path";
+import { execSync as execSync5 } from "child_process";
+var SNAPSHOT_DIR = "context-snapshots";
+function snapshotDir() {
+  return path12.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+}
+function ensureSnapshotDir() {
+  const dir = snapshotDir();
+  if (!fs12.existsSync(dir)) {
+    fs12.mkdirSync(dir, { recursive: true });
+  }
+}
+function snapshotFilePath(timestamp) {
+  return path12.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 {
+    fs12.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 (!fs12.existsSync(dir)) return [];
+  try {
+    const files = fs12.readdirSync(dir).filter((f) => f.endsWith(".json")).sort((a, b) => b.localeCompare(a));
+    return files.map((f) => {
+      try {
+        const content = fs12.readFileSync(path12.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 spawn2 } from "child_process";
+import path13 from "path";
+import fs13 from "fs";
+var LSPClient = class {
+  process = null;
+  requestId = 0;
+  pending = /* @__PURE__ */ new Map();
+  buffer = Buffer.alloc(0);
+  initialized = false;
+  initPromise = null;
+  openDocuments = /* @__PURE__ */ new Set();
+  _isAvailable = true;
+  /** Check whether LSP is available (binary installed) */
+  isAvailable() {
+    return this._isAvailable;
+  }
+  async ensureInitialized() {
+    if (this._isAvailable !== void 0 && !this._isAvailable) return;
+    if (this.initialized && this.process) return;
+    if (this.initPromise) {
+      try {
+        await this.initPromise;
+        return;
+      } catch {
+        this.initPromise = null;
+      }
+    }
+    this.initPromise = this.initialize();
+    return this.initPromise;
+  }
+  async initialize() {
+    const root = getProjectRoot();
+    const lspBinary = this.resolveLspBinary(root);
+    if (!lspBinary) {
+      this._isAvailable = false;
+      this.initialized = false;
+      this.initPromise = null;
+      console.error(`[LSP] typescript-language-server not found. LSP features will fallback to regex.`);
+      return;
+    }
+    const tsconfigPath = path13.join(root, "tsconfig.json");
+    if (!fs13.existsSync(tsconfigPath)) {
+      console.error(`[LSP] Warning: tsconfig.json not found at "${root}". Running in implicit project mode.`);
+    }
+    this.process = spawn2(lspBinary, ["--stdio", "--log-level=4"], {
+      cwd: root,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    this.process.stdout?.on("data", (data) => {
+      this.buffer = Buffer.concat([this.buffer, data]);
+      this.processBuffer();
+    });
+    this.process.stderr?.on("data", (data) => {
+      console.error(`[LSP] ${data.toString().trim()}`);
+    });
+    this.process.on("exit", (code) => {
+      console.error(`[LSP] Process exited with code ${code}`);
+      this.initialized = false;
+      this.process = null;
+      this.initPromise = null;
+      this.openDocuments.clear();
+      this.buffer = Buffer.alloc(0);
+      for (const [, pending] of this.pending) {
+        pending.reject(new Error(`LSP server exited (code ${code})`));
+      }
+      this.pending.clear();
+    });
+    this.process.on("error", (err) => {
+      console.error(`[LSP] Process error: ${err.message}. LSP features will fallback to regex.`);
+      this._isAvailable = false;
+      this.process = null;
+      this.initialized = false;
+      this.initPromise = null;
+      this.openDocuments.clear();
+      for (const [, pending] of this.pending) {
+        pending.reject(new Error(`LSP server error: ${err.message}`));
+      }
+      this.pending.clear();
     });
     const rootUri = this.toUri(root);
     const initResult = await this.sendRequestRaw("initialize", {
@@ -3680,19 +4148,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")
+      path13.join(projectRoot, "node_modules", ".bin", "typescript-language-server"),
+      path13.join(projectRoot, "..", "node_modules", ".bin", "typescript-language-server")
     ];
     for (const candidate of candidates) {
-      if (fs11.existsSync(candidate)) {
+      if (fs13.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(path13.delimiter)) {
+        const binPath = path13.join(dir, "typescript-language-server");
+        if (fs13.existsSync(binPath)) {
           return binPath;
         }
       }
@@ -3713,7 +4181,7 @@ var LSPClient = class {
     this.openDocuments.add(filePath);
     let content;
     try {
-      content = fs11.readFileSync(filePath, "utf-8");
+      content = fs13.readFileSync(filePath, "utf-8");
     } catch {
       content = "";
     }
@@ -3930,8 +4398,8 @@ var LSPClient = class {
 var lspClient = new LSPClient();
 
 // src/tools/lspTools.ts
-import fs12 from "fs";
-import path12 from "path";
+import fs14 from "fs";
+import path14 from "path";
 async function handleFindReferences(params) {
   const { filePath, line, character } = params;
   const validation = validateFilePath(filePath);
@@ -3939,7 +4407,7 @@ async function handleFindReferences(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs14.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -3961,7 +4429,7 @@ async function handleFindReferences(params) {
     const enrichedRefs = references.map((ref) => {
       let lineContent = "";
       try {
-        const content = fs12.readFileSync(ref.filePath, "utf-8");
+        const content = fs14.readFileSync(ref.filePath, "utf-8");
         const lines2 = content.split("\n");
         lineContent = lines2[ref.line]?.trim() ?? "";
       } catch {
@@ -3977,11 +4445,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: ${path14.relative(projectRoot, resolvedPath)}:${line + 1}:${character + 1}`,
       ""
     ];
     for (const [file, refs] of grouped) {
-      const relPath = path12.relative(projectRoot, file);
+      const relPath = path14.relative(projectRoot, file);
       lines.push(`**\u{1F4C4} ${relPath}:**`);
       for (const ref of refs) {
         const loc = `L${ref.line + 1}:${ref.character + 1}`;
@@ -4002,7 +4470,7 @@ async function handleGoToDefinition(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs14.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -4022,10 +4490,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 = path14.relative(projectRoot, definition.filePath);
     let lineContent = "";
     try {
-      const content = fs12.readFileSync(definition.filePath, "utf-8");
+      const content = fs14.readFileSync(definition.filePath, "utf-8");
       const lines2 = content.split("\n");
       lineContent = lines2[definition.line]?.trim() ?? "";
     } catch {
@@ -4057,7 +4525,7 @@ async function handleRenameSymbol(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs14.existsSync(resolvedPath)) {
     return `Error: File not found: "${filePath}".`;
   }
   if (!lspClient.isAvailable()) {
@@ -4086,7 +4554,7 @@ Make sure:
     const fileChanges = [];
     for (const change of result.changes) {
       try {
-        const content = fs12.readFileSync(change.filePath, "utf-8");
+        const content = fs14.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 +4568,10 @@ Make sure:
             lines2[edit.line] = before + edit.newText + after;
           }
         }
-        fs12.writeFileSync(change.filePath, lines2.join("\n"), "utf-8");
+        fs14.writeFileSync(change.filePath, lines2.join("\n"), "utf-8");
         totalEdits += change.edits.length;
         fileChanges.push({
-          filePath: path12.relative(projectRoot, change.filePath),
+          filePath: path14.relative(projectRoot, change.filePath),
           editCount: change.edits.length
         });
       } catch (err) {
@@ -4130,13 +4598,13 @@ async function handleGetTypeInfo(params) {
     return `Error: ${validation.error.message}`;
   }
   const resolvedPath = validation.resolvedPath;
-  if (!fs12.existsSync(resolvedPath)) {
+  if (!fs14.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 = fs14.readFileSync(resolvedPath, "utf-8");
       const fileLines = fileContent.split("\n");
       const targetLine = fileLines[line];
       if (!targetLine) {
@@ -4144,7 +4612,7 @@ async function handleGetTypeInfo(params) {
       }
       const symbolName = extractSymbolAtPosition(resolvedPath, line, character);
       const projectRoot = getProjectRoot();
-      const relPath = path12.relative(projectRoot, resolvedPath);
+      const relPath = path14.relative(projectRoot, resolvedPath);
       const contextStart = Math.max(0, line - 3);
       const contextEnd = Math.min(fileLines.length, line + 4);
       const contextLines = [];
@@ -4182,7 +4650,7 @@ async function handleGetTypeInfo(params) {
 \u26A0\uFE0F No type info for this position.`;
     }
     const projectRoot = getProjectRoot();
-    const relPath = path12.relative(projectRoot, resolvedPath);
+    const relPath = path14.relative(projectRoot, resolvedPath);
     const lines = [
       `\u{1F4CB} **Type Info** \u2014 \`${relPath}:${line + 1}:${character + 1}\``,
       "",
@@ -4223,7 +4691,7 @@ async function handleLspQuery(params) {
 }
 function extractSymbolAtPosition(filePath, line, character) {
   try {
-    const content = fs12.readFileSync(filePath, "utf-8");
+    const content = fs14.readFileSync(filePath, "utf-8");
     const lines = content.split("\n");
     const targetLine = lines[line];
     if (!targetLine) return null;
@@ -4254,7 +4722,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 = fs14.readFileSync(file, "utf-8");
         const lines2 = content.split("\n");
         for (let i = 0; i < lines2.length; i++) {
           if (regex.test(lines2[i])) {
@@ -4284,7 +4752,7 @@ async function fallbackGrepReferences(symbolName, _filePath, _line, _character)
       ""
     ];
     for (const [file, refs] of grouped) {
-      const relPath = path12.relative(projectRoot, file);
+      const relPath = path14.relative(projectRoot, file);
       lines.push(`**\u{1F4C4} ${relPath}:**`);
       for (const ref of refs) {
         lines.push(`  \u2514 L${ref.line} \u2014 ${ref.content}`);
@@ -4318,14 +4786,14 @@ async function fallbackGrepDefinition(symbolName) {
     ];
     for (const file of tsFiles) {
       try {
-        const content = fs12.readFileSync(file, "utf-8");
+        const content = fs14.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 = path14.relative(projectRoot, file);
               return [
                 `\u{1F4CD} **Go to Definition** (regex fallback)`,
                 `\u{1F4C4} File: \`${relPath}\``,
@@ -4356,7 +4824,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 +4860,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 +4890,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 {
@@ -4435,9 +4908,9 @@ function registerAllTools(server) {
     "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.",
     {
-      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)")
     },
     async (params) => {
       try {
@@ -4485,7 +4958,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 +4973,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 {
@@ -4616,6 +5089,22 @@ function registerAllTools(server) {
       }
     }
   );
+  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 };
+      }
+    }
+  );
   server.tool(
     "static_analysis",
     "Runs available linters/checkers (ESLint, TypeScript, Prettier, Ruff) and parses output into structured results. Auto-detects tools from project config.",
@@ -4634,7 +5123,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 fs15 from "fs";
+import path15 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 = path15.resolve(root, "CLAUDE.md");
+  if (!fs15.existsSync(claudePath)) {
+    try {
+      fs15.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 = path15.resolve(root, ".codex/config.toml");
+  if (results.some((r) => r.filePath === ".codex/config.toml")) return;
+  try {
+    const dir = path15.dirname(tomlPath);
+    if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+    if (fs15.existsSync(tomlPath)) {
+      const existingContent = fs15.readFileSync(tomlPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
+        return;
+      }
+      fs15.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
+    } else {
+      fs15.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 = path15.resolve(root, "settings.json");
+  if (results.some((r) => r.filePath === "settings.json")) return;
+  try {
+    if (fs15.existsSync(settingsPath)) {
+      const existingContent = fs15.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: {} };
+              fs15.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: {} };
+          fs15.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
+        }
+      } catch {
+      }
+    } else {
+      fs15.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 = path15.resolve(root, ".agents/mcp_config.json");
+  if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
+  try {
+    const mcpDir = path15.dirname(mcpPath);
+    if (fs15.existsSync(mcpPath)) {
+      const existingContent = fs15.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';
+            fs15.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: {} };
+      fs15.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
+    } else {
+      if (!fs15.existsSync(mcpDir)) fs15.mkdirSync(mcpDir, { recursive: true });
+      fs15.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 = path15.resolve(root, ".aider.conf.yml");
+  if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
+  try {
+    const conventionsRef = "read: CONVENTIONS.md";
+    if (fs15.existsSync(ymlPath)) {
+      const existingContent = fs15.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";
+      fs15.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");
+      fs15.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 = path15.resolve(root, ".github/skills/kuma/SKILL.md");
+  if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
+  try {
+    const dir = path15.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 (fs15.existsSync(skillPath)) {
+      const existingContent = fs15.readFileSync(skillPath, "utf-8");
+      if (existingContent.includes("kuma")) {
+        results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
+        return;
+      }
+      fs15.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
+    } else {
+      if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+      fs15.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 = path15.resolve(root, ".agents/mcp_config.json");
+  if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
+  try {
+    const dir = path15.dirname(mcpPath);
+    if (fs15.existsSync(mcpPath)) {
+      const existingContent = fs15.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: {} };
+      fs15.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
+    } else {
+      if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+      fs15.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 = path15.resolve(root, ".codewhale/mcp.json");
+  if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
+  try {
+    const dir = path15.dirname(mcpPath);
+    if (fs15.existsSync(mcpPath)) {
+      const existingContent = fs15.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: {} };
+      fs15.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
+    } else {
+      if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+      const config = {
+        mcpServers: {
+          kuma: {
+            command: "npx",
+            args: ["-y", "@plumpslabs/kuma"],
+            env: {}
+          }
+        }
+      };
+      fs15.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 = path15.resolve(root, relativePath);
+    const getTemplate = TEMPLATES[type];
+    try {
+      if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
+        agentsMdHandled = true;
+        const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
+        if (fs15.existsSync(fullPath)) {
+          const existingContent = fs15.readFileSync(fullPath, "utf-8");
+          if (existingContent.includes("_Generated by Kuma MCP_")) {
+            results.push({ type, filePath: relativePath, action: "skipped" });
+          } else {
+            fs15.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+            results.push({ type, filePath: relativePath, action: "appended" });
+          }
+        } else {
+          const dir = path15.dirname(fullPath);
+          if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+          fs15.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 (fs15.existsSync(fullPath)) {
+          const existingContent = fs15.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;
+          fs15.writeFileSync(fullPath, newContent, "utf-8");
+          results.push({ type, filePath: relativePath, action: "appended" });
+        } else {
+          const dir = path15.dirname(fullPath);
+          if (!fs15.existsSync(dir)) {
+            fs15.mkdirSync(dir, { recursive: true });
+          }
+          fs15.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 +5951,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 +6047,6 @@ async function main() {
       version: SERVER_VERSION
     },
     {
-      // Capabilities declaration
       capabilities: {
         tools: {},
         resources: {}
@@ -4672,6 +6065,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);