@plumpslabs/kuma 2.3.31 → 2.3.33

package/dist/index.js

@@ -1427,7 +1427,7 @@ var init_sessionMemory = __esm({
               dependencyGraph: new Map(parsed.dependencyGraph || []),
               toolCalls: parsed.toolCalls || [],
               conventions: parsed.conventions,
-              recordings: parsed.recordings || { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, total: 0 },
+              recordings: parsed.recordings || { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, features: 0, total: 0 },
               metrics: parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
             };
             this.initialized = true;
@@ -1447,7 +1447,7 @@ var init_sessionMemory = __esm({
           searchResults: /* @__PURE__ */ new Map(),
           dependencyGraph: /* @__PURE__ */ new Map(),
           toolCalls: [],
-          recordings: { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, total: 0 },
+          recordings: { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, features: 0, total: 0 },
           metrics: { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
         };
         this.initialized = true;
@@ -1610,6 +1610,18 @@ No unresolved issues.`;
         this.state.currentGoal = goal;
         this.save();
       }
+      setGoalProgress(percentage, milestone) {
+        this.ensureInit();
+        this.state.goalProgress = {
+          percentage: Math.min(100, Math.max(0, percentage)),
+          milestone,
+          updatedAt: Date.now()
+        };
+        this.save();
+      }
+      getGoalProgress() {
+        return this.state.goalProgress || null;
+      }
       addCompletedStep(step) {
         this.ensureInit();
         if (!this.state.completedSteps.includes(step)) {
@@ -2031,6 +2043,9 @@ No unresolved issues.`;
           case "research_save":
             this.state.recordings.researchSaves++;
             break;
+          case "feature":
+            this.state.recordings.features++;
+            break;
         }
         this.state.recordings.total++;
         this.save();
@@ -2047,6 +2062,7 @@ No unresolved issues.`;
         if (r.gotchas === 0) missing.push("gotcha");
         if (r.decisions === 0) missing.push("decision");
         if (r.researchSaves === 0) missing.push("research_save");
+        if (r.features === 0) missing.push("feature");
         return {
           ...r,
           hasAnyRecordings: r.total > 0,
@@ -2509,6 +2525,223 @@ var init_kumaSelfHeal = __esm({
   }
 });
 
+// src/engine/languageSupport.ts
+import path5 from "path";
+function grepIncludeFlags() {
+  return SOURCE_EXTENSIONS.map((e) => `--include="*${e}"`).join(" ");
+}
+function isTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  const base = path5.basename(filePath);
+  const ext = path5.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  const segments = lower.split(/[\\/]/);
+  for (const lang of LANGUAGES) {
+    if (!lang.extensions.includes(ext.toLowerCase())) continue;
+    for (const p of lang.testPrefixes) {
+      if (p && stem.startsWith(p)) return true;
+    }
+    for (const s of lang.testSuffixes) {
+      if (s && stem.endsWith(s)) return true;
+    }
+    for (const d of lang.testDirs) {
+      const dLower = d.toLowerCase();
+      if (dLower.includes("/")) {
+        if (lower.includes(`${dLower}/`) || lower.includes(`${dLower}\\`)) return true;
+      } else if (segments.includes(dLower)) {
+        return true;
+      }
+    }
+  }
+  return /(\.test\.|\.spec\.|_test\.|_spec\.)/.test(lower) || /(\/|^)(__tests__|tests?|specs?)(\/|$)/.test(lower);
+}
+function getTestCandidates(sourcePath) {
+  const ext = path5.extname(sourcePath).toLowerCase();
+  const dir = path5.dirname(sourcePath);
+  const base = path5.basename(sourcePath, ext);
+  const lang = LANGUAGES.find((l) => l.extensions.includes(ext));
+  const candidates = /* @__PURE__ */ new Set();
+  const push = (p) => {
+    if (p && !candidates.has(p)) candidates.add(p);
+  };
+  if (lang) {
+    for (const suffix of lang.testSuffixes) {
+      if (!suffix) continue;
+      push(path5.join(dir, `${base}${suffix}${ext}`));
+    }
+    for (const prefix of lang.testPrefixes) {
+      if (prefix) push(path5.join(dir, `${prefix}${base}${ext}`));
+    }
+    for (const td of lang.testDirs) {
+      if (!td.includes("/")) {
+        push(path5.join(dir, td, `${base}${ext}`));
+      }
+    }
+  }
+  push(path5.join(dir, `${base}.test${ext}`));
+  push(path5.join(dir, `${base}.spec${ext}`));
+  push(path5.join(dir, `${base}_test${ext}`));
+  push(path5.join(dir, `test_${base}${ext}`));
+  push(path5.join(dir, "__tests__", `${base}${ext}`));
+  push(path5.join(dir, "tests", `${base}${ext}`));
+  return [...candidates];
+}
+function matchImportPath(line) {
+  for (const re of IMPORT_PATTERNS) {
+    re.lastIndex = 0;
+    const m = re.exec(line);
+    if (m) return (m[1] || m[2] || "").trim();
+  }
+  return null;
+}
+var LANGUAGES, SOURCE_EXTENSIONS, SOURCE_EXT_GLOB, DEFAULT_SOURCE_INCLUDES, IMPORT_PATTERNS;
+var init_languageSupport = __esm({
+  "src/engine/languageSupport.ts"() {
+    "use strict";
+    LANGUAGES = [
+      {
+        name: "typescript",
+        extensions: [".ts", ".tsx", ".mts", ".cts"],
+        testPrefixes: [],
+        testSuffixes: [".test", ".spec"],
+        testDirs: ["__tests__", "tests", "test", "spec"]
+      },
+      {
+        name: "javascript",
+        extensions: [".js", ".jsx", ".mjs", ".cjs"],
+        testPrefixes: [],
+        testSuffixes: [".test", ".spec"],
+        testDirs: ["__tests__", "tests", "test", "spec"]
+      },
+      {
+        name: "python",
+        extensions: [".py", ".pyw"],
+        testPrefixes: ["test_"],
+        testSuffixes: ["_test"],
+        testDirs: ["tests", "test"]
+      },
+      {
+        name: "go",
+        extensions: [".go"],
+        testPrefixes: [],
+        testSuffixes: ["_test"],
+        testDirs: ["testdata"]
+      },
+      {
+        name: "rust",
+        extensions: [".rs"],
+        testPrefixes: [],
+        testSuffixes: ["_test"],
+        testDirs: ["tests"]
+      },
+      {
+        name: "java",
+        extensions: [".java"],
+        testPrefixes: ["Test"],
+        testSuffixes: ["Test", "Tests"],
+        testDirs: ["src/test", "test", "tests"]
+      },
+      {
+        name: "kotlin",
+        extensions: [".kt", ".kts"],
+        testPrefixes: ["Test"],
+        testSuffixes: ["Test", "Tests"],
+        testDirs: ["src/test"]
+      },
+      {
+        name: "csharp",
+        extensions: [".cs"],
+        testPrefixes: [],
+        testSuffixes: ["Tests", "Test"],
+        testDirs: ["Tests", "test", "tests"]
+      },
+      {
+        name: "ruby",
+        extensions: [".rb"],
+        testPrefixes: [],
+        testSuffixes: ["_spec", "_test"],
+        testDirs: ["spec", "test", "tests"]
+      },
+      {
+        name: "php",
+        extensions: [".php"],
+        testPrefixes: [],
+        testSuffixes: ["Test"],
+        testDirs: ["tests", "test"]
+      },
+      {
+        name: "cpp",
+        extensions: [".c", ".cc", ".cpp", ".h", ".hpp", ".hxx"],
+        testPrefixes: [],
+        testSuffixes: ["_test"],
+        testDirs: ["tests", "test"]
+      },
+      {
+        name: "swift",
+        extensions: [".swift"],
+        testPrefixes: [],
+        testSuffixes: ["Tests"],
+        testDirs: ["Tests", "test"]
+      },
+      {
+        name: "scala",
+        extensions: [".scala"],
+        testPrefixes: [],
+        testSuffixes: ["Spec", "Test", "Tests"],
+        testDirs: ["src/test"]
+      },
+      {
+        name: "dart",
+        extensions: [".dart"],
+        testPrefixes: [],
+        testSuffixes: ["_test"],
+        testDirs: ["test", "tests"]
+      },
+      {
+        name: "shell",
+        extensions: [".sh", ".bash", ".zsh"],
+        testPrefixes: [],
+        testSuffixes: [],
+        testDirs: ["test", "tests"]
+      }
+    ];
+    SOURCE_EXTENSIONS = [
+      ...new Set(LANGUAGES.flatMap((l) => l.extensions))
+    ];
+    SOURCE_EXT_GLOB = `{${SOURCE_EXTENSIONS.map((e) => e.slice(1)).join(",")}}`;
+    DEFAULT_SOURCE_INCLUDES = [
+      `src/**/*.${SOURCE_EXT_GLOB}`,
+      `app/**/*.${SOURCE_EXT_GLOB}`,
+      `lib/**/*.${SOURCE_EXT_GLOB}`,
+      `packages/**/*.${SOURCE_EXT_GLOB}`,
+      `server/**/*.${SOURCE_EXT_GLOB}`,
+      `api/**/*.${SOURCE_EXT_GLOB}`
+    ];
+    IMPORT_PATTERNS = [
+      // JS/TS: import x from 'y' | import {a} from 'y' | import * as x from 'y'
+      /import\s+(?:\{[^}]*\}\s+from\s+)?(?:[^'"\n]*\s+from\s+)?['"]([^'"]+)['"]/,
+      // JS/TS (CJS): const x = require('y')
+      /require\s*\(\s*['"]([^'"]+)['"]\s*\)/,
+      // Python: import y | import y.z | from y import x | from .y import x
+      /^\s*(?:from\s+([.\w]+)\s+import\s+\S+|import\s+([.\w]+))/m,
+      // Go: import "y" | import alias "y"
+      /^\s*import\s+(?:\w+\s+)?"([^"]+)"/m,
+      // Rust: use y::z | extern crate y
+      /^\s*use\s+([\w:]+)/m,
+      // C/C++: #include <y> | #include "y"
+      /^\s*#\s*include\s*[<"]([^>"]+)[>"]/m,
+      // Ruby: require 'y' | require_relative 'y'
+      /^\s*require(?:_relative)?\s+['"]([^'"]+)['"]/m,
+      // PHP: require 'y' | include 'y' | use y\z;
+      /^\s*(?:require(?:_once)?|include(?:_once)?)\s*\(?\s*['"]([^'"]+)['"]/m,
+      // Java: import y.z.w;
+      /^\s*import\s+([\w.]+)\s*;/m,
+      // C#: using y.z.w;
+      /^\s*using\s+([\w.]+)\s*;/m
+    ];
+  }
+});
+
 // src/engine/kumaGraph.ts
 var kumaGraph_exports = {};
 __export(kumaGraph_exports, {
@@ -3105,7 +3338,7 @@ async function queryGraph(params) {
       if (results.length === 0) {
         return `\u{1F50D} **Graph Query** \u2014 No nodes found for "${query}".
 
-Try a different search term or check if the graph has been built by using tools like smart_grep or lsp_query.`;
+Try a different search term or use kuma_context({ action: 'research', scope: '<term>' }) to build graph context.`;
       }
       const lines = [
         `\u{1F50D} **Graph Nodes** \u2014 ${results.length} result(s) for "${query}"`,
@@ -3139,7 +3372,7 @@ Try a different search term or check if the graph has been built by using tools
       if (results.length === 0) {
         return `\u{1F50D} **Graph Edges** \u2014 No connections found for node "${query}".
 
-Try kuma_graph_query({ type: 'nodes', query: '<search>' }) to find node IDs first.`;
+Try kuma_context({ action: 'research', scope: '<term>' }) to build related graph nodes first.`;
       }
       const lines = [
         `\u{1F517} **Graph Edges** \u2014 ${results.length} connection(s) for "${query}"`,
@@ -3156,7 +3389,7 @@ Try kuma_graph_query({ type: 'nodes', query: '<search>' }) to find node IDs firs
       const parts = query.split("\u2192").map((s) => s.trim());
       if (parts.length !== 2) {
         return `\u26A0\uFE0F For path queries, use format: "sourceNodeID \u2192 targetNodeID"
-Example: kuma_graph_query({ type: 'paths', query: 'function::login \u2192 function::validatePassword' })`;
+Example: kuma_context({ action: 'impact', target: 'login' }) \u2192 traces connections between nodes.`;
       }
       const [sourceId, targetId] = parts;
       const visited = /* @__PURE__ */ new Set();
@@ -3396,27 +3629,27 @@ async function codebaseSearchFallback(query, limit = 20) {
         if (results.length >= limit || depth > MAX_WALK_DEPTH) return;
         let entries = [];
         try {
-          entries = fs27.readdirSync(dir);
+          entries = fs30.readdirSync(dir);
         } catch {
           return;
         }
         for (const entry of entries) {
           if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === "build") continue;
-          const full = path27.join(dir, entry);
+          const full = path31.join(dir, entry);
           try {
-            const stat = fs27.statSync(full);
+            const stat = fs30.statSync(full);
             if (stat.isDirectory()) {
               walk2(full, depth + 1);
             } else if (entry.toLowerCase().includes(query.toLowerCase())) {
-              results.push(path27.relative(root, full));
+              results.push(path31.relative(root, full));
             }
           } catch {
           }
         }
       };
       var walk = walk2;
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs30 = await import("fs");
+      const path31 = await import("path");
       const root = process.cwd();
       const results = [];
       const MAX_WALK_DEPTH = 8;
@@ -3559,7 +3792,7 @@ async function codebaseImpactFallback(target) {
     const { execSync: execSync8 } = await import("child_process");
     const root = process.cwd();
     const grepResult = execSync8(
-      `grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.json" -l "${target.replace(/"/g, '\\"')}" . 2>/dev/null | grep -v node_modules | grep -v .git | grep -v dist | grep -v .kuma | head -50`,
+      `grep -rn ${grepIncludeFlags()} --include="*.json" --include="*.md" -l "${target.replace(/"/g, '\\"')}" . 2>/dev/null | grep -v node_modules | grep -v .git | grep -v dist | grep -v .kuma | head -50`,
       { cwd: root, encoding: "utf-8", timeout: 5e3, maxBuffer: 256 * 1024 }
     ).trim();
     const files = grepResult ? grepResult.split("\n").filter(Boolean).filter((f) => !f.startsWith("./")) : [];
@@ -3567,7 +3800,7 @@ async function codebaseImpactFallback(target) {
       return { symbol: target, references: 0, files: 0, testFiles: 0, entryPoints: [], risk: "low" };
     }
     const fileCount = files.length;
-    const testFiles = files.filter((f) => f.includes("test") || f.includes("spec") || f.includes("__tests__")).length;
+    const testFiles = files.filter((f) => isTestFile(f)).length;
     const risk = fileCount > 20 ? "high" : fileCount > 5 ? "medium" : "low";
     return {
       symbol: target,
@@ -3666,6 +3899,7 @@ var init_kumaGraph = __esm({
     "use strict";
     init_kumaDb();
     init_kumaSelfHeal();
+    init_languageSupport();
     GRAPH_LIMITS = {
       maxNodes: 5e3,
       // Max nodes before pruning
@@ -3689,10 +3923,10 @@ __export(kumaMemory_exports, {
   shouldRecordDecision: () => shouldRecordDecision
 });
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 function scoreMemoryRelevance(context, limit = 5) {
   const results = [];
-  const kumaDir = path5.join(getProjectRoot(), MEMORY_DIR);
+  const kumaDir = path6.join(getProjectRoot(), MEMORY_DIR);
   if (!fs5.existsSync(kumaDir)) return [];
   const terms = context.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
   if (terms.length === 0) return [];
@@ -3700,7 +3934,7 @@ function scoreMemoryRelevance(context, limit = 5) {
     const files = fs5.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
     for (const file of files) {
       try {
-        const content = fs5.readFileSync(path5.join(kumaDir, file), "utf-8");
+        const content = fs5.readFileSync(path6.join(kumaDir, file), "utf-8");
         const lower = content.toLowerCase();
         let matchCount = 0;
         for (const term of terms) {
@@ -4250,6 +4484,136 @@ var init_safetyScore = __esm({
   }
 });
 
+// src/engine/kumaPathRules.ts
+var kumaPathRules_exports = {};
+__export(kumaPathRules_exports, {
+  ensureRulesDir: () => ensureRulesDir,
+  formatPathRules: () => formatPathRules,
+  getRulesForScope: () => getRulesForScope,
+  hasPathRules: () => hasPathRules,
+  loadPathRules: () => loadPathRules,
+  matchRulePath: () => matchRulePath
+});
+import fs6 from "fs";
+import path7 from "path";
+function rulesDir() {
+  return path7.join(getProjectRoot(), RULES_DIR);
+}
+function ensureRulesDir() {
+  try {
+    const dir = rulesDir();
+    if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
+  } catch {
+  }
+}
+function parseRuleFile(filePath) {
+  try {
+    const raw = fs6.readFileSync(filePath, "utf-8");
+    const id = path7.basename(filePath, ".md");
+    const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fm) {
+      return { id, description: id, paths: ["*"], content: raw.trim(), filePath };
+    }
+    const meta = fm[1];
+    const body = fm[2].trim();
+    const description = meta.match(/description:\s*(.+)/)?.[1]?.trim() || id;
+    const paths = [];
+    const pathSection = meta.match(/paths:\s*\r?\n([\s\S]*?)(?=\r?\n\S|$)/);
+    if (pathSection) {
+      for (const line of pathSection[1].split("\n")) {
+        const m = line.match(/^\s*-\s*['"]?([^'"]+)['"]?\s*$/);
+        if (m) paths.push(m[1].trim());
+      }
+    }
+    return { id, description, paths: paths.length ? paths : ["*"], content: body, filePath };
+  } catch {
+    return null;
+  }
+}
+function loadPathRules() {
+  ensureRulesDir();
+  try {
+    const dir = rulesDir();
+    return fs6.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => parseRuleFile(path7.join(dir, f))).filter((r) => r !== null);
+  } catch {
+    return [];
+  }
+}
+function matchRulePath(pattern, target) {
+  if (pattern === "*" || pattern === "**") return true;
+  const p = pattern.replace(/\\/g, "/").toLowerCase();
+  const t = target.replace(/\\/g, "/").toLowerCase();
+  if (p.endsWith("/**")) {
+    const prefix = p.slice(0, -3);
+    return t === prefix || t.startsWith(prefix + "/");
+  }
+  if (!/[*?]/.test(p) && (t === p || t.startsWith(p + "/"))) return true;
+  let re = "";
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === "*") {
+      if (p[i + 1] === "*") {
+        re += i === 0 ? "(?:.*/)?" : ".*";
+        if (p[i + 2] === "/") i += 2;
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (/[.()*+?^${}()|[\]\\]/.test(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  try {
+    const rx = new RegExp(`^${re}$`);
+    return rx.test(t);
+  } catch {
+    return t === p;
+  }
+}
+function getRulesForScope(scope) {
+  const rules = loadPathRules();
+  if (rules.length === 0) return [];
+  const target = (scope || "").toLowerCase();
+  if (!target) return rules.filter((r) => r.paths.includes("*"));
+  return rules.filter((rule) => rule.paths.some((p) => matchRulePath(p, target)));
+}
+function formatPathRules(scope) {
+  const matches = getRulesForScope(scope);
+  if (matches.length === 0) return "";
+  const lines = [
+    `\u{1F4CC} **Path Rules** (${matches.length} rule(s) apply to "${scope || "project"}")`,
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    ""
+  ];
+  for (const rule of matches) {
+    lines.push(`**${rule.description}**`);
+    const bodyLines = rule.content.split("\n").filter((l) => l.trim()).slice(0, 6);
+    for (const bl of bodyLines) {
+      lines.push(`  ${bl.substring(0, 140)}`);
+    }
+    if (rule.content.split("\n").filter((l) => l.trim()).length > 6) {
+      lines.push(`  \u2026 (full rule in ${rule.filePath})`);
+    }
+    lines.push("");
+  }
+  lines.push(`\u{1F4A1} Path rules load on-demand from ${RULES_DIR}/ \u2014 add/remove .md files anytime.`);
+  return lines.join("\n");
+}
+function hasPathRules() {
+  return loadPathRules().length > 0;
+}
+var RULES_DIR;
+var init_kumaPathRules = __esm({
+  "src/engine/kumaPathRules.ts"() {
+    "use strict";
+    init_pathValidator();
+    RULES_DIR = ".kuma/rules";
+  }
+});
+
 // src/engine/kumaCodeScanner.ts
 var kumaCodeScanner_exports = {};
 __export(kumaCodeScanner_exports, {
@@ -4258,8 +4622,8 @@ __export(kumaCodeScanner_exports, {
   scanCodebase: () => scanCodebase
 });
 import fastGlob from "fast-glob";
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path8 from "path";
 function getRoot() {
   if (!_cachedRoot) _cachedRoot = getProjectRoot();
   return _cachedRoot;
@@ -4270,10 +4634,10 @@ function lineAt(content, index) {
 function getDirectoryDirs(filePaths) {
   const dirs = /* @__PURE__ */ new Set();
   for (const fp of filePaths) {
-    let dir = path6.dirname(fp);
+    let dir = path8.dirname(fp);
     while (dir && dir !== "." && dir !== "/") {
       dirs.add(dir);
-      dir = path6.dirname(dir);
+      dir = path8.dirname(dir);
     }
   }
   return [...dirs].sort();
@@ -4283,21 +4647,14 @@ async function scanCodebase(options = {}) {
   const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
   const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
   const result = { nodeCount: 0, edgeCount: 0, filesScanned: 0, errors: [] };
-  const includePatterns = options.include || [
-    "src/**/*.{ts,tsx,js,jsx}",
-    "app/**/*.{ts,tsx,js,jsx}",
-    "lib/**/*.{ts,tsx,js,jsx}",
-    "packages/**/*.{ts,tsx,js,jsx}",
-    "server/**/*.{ts,tsx,js,jsx}",
-    "api/**/*.{ts,tsx,js,jsx}"
-  ];
+  const includePatterns = options.include || [...DEFAULT_SOURCE_INCLUDES];
   if (options.scope) {
     includePatterns.length = 0;
     if (options.scope.includes("/") || options.scope.includes(".")) {
       includePatterns.push(options.scope);
     } else {
-      includePatterns.push(`**/*${options.scope}*/**/*.{ts,tsx,js,jsx}`);
-      includePatterns.push(`**/*${options.scope}*.{ts,tsx,js,jsx}`);
+      includePatterns.push(`**/*${options.scope}*/**/*.${SOURCE_EXT_GLOB}`);
+      includePatterns.push(`**/*${options.scope}*.${SOURCE_EXT_GLOB}`);
     }
   }
   const ignorePatterns = [
@@ -4330,16 +4687,16 @@ async function scanCodebase(options = {}) {
   const scannedFilePaths = [];
   for (let i = 0; i < scannedCount; i++) {
     const filePath = files[i];
-    const fullPath = path6.join(root, filePath);
-    if (!fs6.existsSync(fullPath)) continue;
-    const stat = fs6.statSync(fullPath);
+    const fullPath = path8.join(root, filePath);
+    if (!fs7.existsSync(fullPath)) continue;
+    const stat = fs7.statSync(fullPath);
     if (stat.size > maxFileSize) continue;
     const mtime = stat.mtimeMs;
     const cached = fileCache.get(filePath);
     if (cached === mtime && !options.force) continue;
     fileCache.set(filePath, mtime);
     try {
-      const content = fs6.readFileSync(fullPath, "utf-8");
+      const content = fs7.readFileSync(fullPath, "utf-8");
       const parsed = parseFile(filePath, content);
       allParsed.push({ filePath, parsed, content });
       scannedFilePaths.push(filePath);
@@ -4382,7 +4739,7 @@ async function scanCodebase(options = {}) {
         });
         result.nodeCount++;
         for (const fp of scannedFilePaths) {
-          if (path6.dirname(fp) === dir) {
+          if (path8.dirname(fp) === dir) {
             const fileId = nodeId("file", fp);
             try {
               await addEdge({ sourceId: moduleId, targetId: fileId, type: "owns" });
@@ -4407,7 +4764,7 @@ function parseFile(filePath, content) {
     routes: [],
     imports: [],
     exports: [],
-    isTest: TEST_PATTERNS.some((p) => filePath.includes(p))
+    isTest: isTestFile(filePath)
   };
   const lines = content.split("\n");
   const isTsx = /\.(tsx|jsx)$/.test(filePath);
@@ -4739,17 +5096,20 @@ async function recordParsedFile(filePath, parsed, content, result) {
 }
 function resolveImportPath(fromFile, importPath, root) {
   if (!importPath.startsWith(".") && !importPath.startsWith("/")) return null;
-  const fromDir = path6.dirname(path6.join(root, fromFile));
-  const exts = [".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.tsx", "/index.js", "/index.jsx"];
+  const fromDir = path8.dirname(path8.join(root, fromFile));
+  const exts = [
+    ...SOURCE_EXTENSIONS,
+    ...SOURCE_EXTENSIONS.map((e) => `/index${e}`)
+  ];
   for (const ext of exts) {
-    const resolved = path6.resolve(fromDir, importPath + ext);
-    if (fs6.existsSync(resolved)) return path6.relative(root, resolved);
+    const resolved = path8.resolve(fromDir, importPath + ext);
+    if (fs7.existsSync(resolved)) return path8.relative(root, resolved);
   }
-  const dirPath = path6.resolve(fromDir, importPath);
-  if (fs6.existsSync(dirPath) && fs6.statSync(dirPath).isDirectory()) {
-    for (const ext of [".ts", ".tsx", ".js", ".jsx"]) {
-      const indexPath = path6.join(dirPath, `index${ext}`);
-      if (fs6.existsSync(indexPath)) return path6.relative(root, indexPath);
+  const dirPath = path8.resolve(fromDir, importPath);
+  if (fs7.existsSync(dirPath) && fs7.statSync(dirPath).isDirectory()) {
+    for (const ext of SOURCE_EXTENSIONS) {
+      const indexPath = path8.join(dirPath, `index${ext}`);
+      if (fs7.existsSync(indexPath)) return path8.relative(root, indexPath);
     }
   }
   return null;
@@ -4784,12 +5144,13 @@ async function scanAndFormat(options = {}) {
   const result = await scanCodebase(options);
   return formatScanResult(result);
 }
-var DEFAULT_MAX_FILES, DEFAULT_MAX_FILE_SIZE, fileCache, _cachedRoot, FUNCTION_DECL_RE, ARROW_FN_RE, TYPED_ARROW_RE, CLASS_RE, IMPORT_RE, JSX_RETURN_RE, JSX_ELEMENT_RE, JSX_IMPLICIT_RE, EXPRESS_ROUTE_RE, HONO_ROUTE_RE, EXPORT_RE, CALL_RE, TEST_PATTERNS, knownComponents, knownFunctions, symbolLocations;
+var DEFAULT_MAX_FILES, DEFAULT_MAX_FILE_SIZE, fileCache, _cachedRoot, FUNCTION_DECL_RE, ARROW_FN_RE, TYPED_ARROW_RE, CLASS_RE, IMPORT_RE, JSX_RETURN_RE, JSX_ELEMENT_RE, JSX_IMPLICIT_RE, EXPRESS_ROUTE_RE, HONO_ROUTE_RE, EXPORT_RE, CALL_RE, knownComponents, knownFunctions, symbolLocations;
 var init_kumaCodeScanner = __esm({
   "src/engine/kumaCodeScanner.ts"() {
     "use strict";
     init_pathValidator();
     init_kumaGraph();
+    init_languageSupport();
     DEFAULT_MAX_FILES = 200;
     DEFAULT_MAX_FILE_SIZE = 100 * 1024;
     fileCache = /* @__PURE__ */ new Map();
@@ -4806,7 +5167,6 @@ var init_kumaCodeScanner = __esm({
     HONO_ROUTE_RE = /c\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/g;
     EXPORT_RE = /export\s+(?:default\s+)?(\w+)/g;
     CALL_RE = /(\w+)\s*\(/g;
-    TEST_PATTERNS = [".test.", ".spec.", "__tests__", "/test/"];
     knownComponents = /* @__PURE__ */ new Set();
     knownFunctions = /* @__PURE__ */ new Set();
     symbolLocations = /* @__PURE__ */ new Map();
@@ -5091,18 +5451,18 @@ __export(domainRules_exports, {
   readLayer: () => readLayer,
   writeLayer: () => writeLayer
 });
-import fs7 from "fs";
-import path7 from "path";
+import fs8 from "fs";
+import path9 from "path";
 function layerFilePath(layer) {
-  return path7.join(getProjectRoot(), ".kuma", LAYER_FILES[layer].filename);
+  return path9.join(getProjectRoot(), ".kuma", LAYER_FILES[layer].filename);
 }
 function ensureLayerFile(layer) {
   const fp = layerFilePath(layer);
-  if (!fs7.existsSync(fp)) {
+  if (!fs8.existsSync(fp)) {
     const template = layer === "domain_rules" ? DOMAIN_RULES_TEMPLATE : layer === "arch_flow" ? ARCH_FLOW_TEMPLATE : GOTCHAS_TEMPLATE;
-    const dir = path7.dirname(fp);
-    if (!fs7.existsSync(dir)) fs7.mkdirSync(dir, { recursive: true });
-    fs7.writeFileSync(fp, template, "utf-8");
+    const dir = path9.dirname(fp);
+    if (!fs8.existsSync(dir)) fs8.mkdirSync(dir, { recursive: true });
+    fs8.writeFileSync(fp, template, "utf-8");
     console.error(`[DomainRules] Auto-created ${LAYER_FILES[layer].filename}`);
   }
   return fp;
@@ -5110,7 +5470,7 @@ function ensureLayerFile(layer) {
 function readLayer(layer) {
   try {
     const fp = ensureLayerFile(layer);
-    return fs7.readFileSync(fp, "utf-8");
+    return fs8.readFileSync(fp, "utf-8");
   } catch (err) {
     return `Error reading ${layer}: ${err}`;
   }
@@ -5118,7 +5478,7 @@ function readLayer(layer) {
 function writeLayer(layer, content) {
   try {
     const fp = ensureLayerFile(layer);
-    fs7.writeFileSync(fp, content, "utf-8");
+    fs8.writeFileSync(fp, content, "utf-8");
     const label = LAYER_FILES[layer].label;
     sessionMemory.recordToolCall("kuma_memory", { action: `write_${layer}` });
     return `\u2705 **${label}** updated successfully.`;
@@ -5129,9 +5489,9 @@ function writeLayer(layer, content) {
 function appendToLayer(layer, entry) {
   try {
     const fp = ensureLayerFile(layer);
-    const existing = fs7.readFileSync(fp, "utf-8");
+    const existing = fs8.readFileSync(fp, "utf-8");
     const newContent = existing.trimEnd() + "\n\n" + entry.trim() + "\n";
-    fs7.writeFileSync(fp, newContent, "utf-8");
+    fs8.writeFileSync(fp, newContent, "utf-8");
     return `\u2705 Entry added to **${LAYER_FILES[layer].label}**.`;
   } catch (err) {
     return `\u274C Failed to append: ${err}`;
@@ -5141,11 +5501,11 @@ function getLayersSummary() {
   const lines = ["\u{1F4DA} **3-Layer Memory Engine**", "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501"];
   for (const layer of ["domain_rules", "arch_flow", "gotcha"]) {
     const fp = layerFilePath(layer);
-    const exists = fs7.existsSync(fp);
+    const exists = fs8.existsSync(fp);
     const label = LAYER_FILES[layer].label;
     if (exists) {
       try {
-        const content = fs7.readFileSync(fp, "utf-8");
+        const content = fs8.readFileSync(fp, "utf-8");
         const lineCount = content.split("\n").length;
         const sizeKB = Math.round(Buffer.byteLength(content) / 1024);
         lines.push(`  ${layer === "domain_rules" ? "\u{1F4CB}" : layer === "arch_flow" ? "\u{1F3D7}\uFE0F" : "\u26A0\uFE0F"} **${label}** \u2014 ${lineCount} lines, ${sizeKB}KB`);
@@ -5162,7 +5522,7 @@ function getActiveGotchas() {
   const results = [];
   try {
     const fp = ensureLayerFile("gotcha");
-    const content = fs7.readFileSync(fp, "utf-8");
+    const content = fs8.readFileSync(fp, "utf-8");
     const lines = content.split("\n");
     let currentSection = "";
     let currentFilePath = "";
@@ -5210,7 +5570,7 @@ function generateDigest() {
   ];
   try {
     const fp1 = ensureLayerFile("domain_rules");
-    const content = fs7.readFileSync(fp1, "utf-8");
+    const content = fs8.readFileSync(fp1, "utf-8");
     const rules = [];
     const workflows = [];
     for (const line of content.split("\n")) {
@@ -5226,7 +5586,7 @@ function generateDigest() {
   }
   try {
     const fp2 = ensureLayerFile("arch_flow");
-    const content = fs7.readFileSync(fp2, "utf-8");
+    const content = fs8.readFileSync(fp2, "utf-8");
     const chains = [];
     for (const line of content.split("\n")) {
       if (line.includes("->") && line.includes("[")) chains.push(line.trim());
@@ -5370,8 +5730,8 @@ __export(contextDigest_exports, {
   generateContextDigest: () => generateContextDigest,
   generateDigest: () => generateContextDigest
 });
-import fs8 from "fs";
-import path8 from "path";
+import fs9 from "fs";
+import path10 from "path";
 function detectTechStack() {
   const root = getProjectRoot();
   const stack = {
@@ -5383,12 +5743,12 @@ function detectTechStack() {
     monorepo: false
   };
   try {
-    const pkgPath = path8.join(root, "package.json");
-    if (fs8.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs8.readFileSync(pkgPath, "utf-8"));
+    const pkgPath = path10.join(root, "package.json");
+    if (fs9.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs9.readFileSync(pkgPath, "utf-8"));
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      if (fs8.existsSync(path8.join(root, "pnpm-lock.yaml"))) stack.packageManager = "pnpm";
-      else if (fs8.existsSync(path8.join(root, "yarn.lock"))) stack.packageManager = "yarn";
+      if (fs9.existsSync(path10.join(root, "pnpm-lock.yaml"))) stack.packageManager = "pnpm";
+      else if (fs9.existsSync(path10.join(root, "yarn.lock"))) stack.packageManager = "yarn";
       else stack.packageManager = "npm";
       stack.monorepo = !!pkg.workspaces;
       if (deps.next) stack.framework = "Next.js";
@@ -5411,13 +5771,13 @@ function detectTechStack() {
       else if (deps.mocha) stack.testRunner = "Mocha";
       else if (deps.playwright) stack.testRunner = "Playwright";
       else if (deps.cypress) stack.testRunner = "Cypress";
-      if (fs8.existsSync(path8.join(root, "tsconfig.json"))) stack.languages.push("TypeScript");
+      if (fs9.existsSync(path10.join(root, "tsconfig.json"))) stack.languages.push("TypeScript");
       if (deps.typescript) stack.languages.push("TypeScript");
-      if (fs8.existsSync(path8.join(root, "jsconfig.json"))) stack.languages.push("JavaScript");
-      if (fs8.existsSync(path8.join(root, "go.mod"))) stack.languages.push("Go");
-      if (fs8.existsSync(path8.join(root, "Cargo.toml"))) stack.languages.push("Rust");
-      if (fs8.existsSync(path8.join(root, "pyproject.toml"))) stack.languages.push("Python");
-      if (fs8.existsSync(path8.join(root, "Gemfile"))) stack.languages.push("Ruby");
+      if (fs9.existsSync(path10.join(root, "jsconfig.json"))) stack.languages.push("JavaScript");
+      if (fs9.existsSync(path10.join(root, "go.mod"))) stack.languages.push("Go");
+      if (fs9.existsSync(path10.join(root, "Cargo.toml"))) stack.languages.push("Rust");
+      if (fs9.existsSync(path10.join(root, "pyproject.toml"))) stack.languages.push("Python");
+      if (fs9.existsSync(path10.join(root, "Gemfile"))) stack.languages.push("Ruby");
       if (stack.languages.length === 0) stack.languages.push("JavaScript");
     }
   } catch {
@@ -5448,13 +5808,13 @@ function detectEntryPoints() {
     "lib/index.ts"
   ];
   for (const c of candidates) {
-    if (fs8.existsSync(path8.join(root, c))) {
+    if (fs9.existsSync(path10.join(root, c))) {
       entryPoints.push(c);
     }
   }
   try {
-    const pkg = JSON.parse(fs8.readFileSync(path8.join(root, "package.json"), "utf-8"));
-    if (pkg.main && fs8.existsSync(path8.join(root, pkg.main))) {
+    const pkg = JSON.parse(fs9.readFileSync(path10.join(root, "package.json"), "utf-8"));
+    if (pkg.main && fs9.existsSync(path10.join(root, pkg.main))) {
       if (!entryPoints.includes(pkg.main)) entryPoints.push(pkg.main);
     }
   } catch {
@@ -5500,9 +5860,9 @@ async function generateContextDigest() {
     lines.push(`\u{1F6AA} **Entry**: ${entryPoints.slice(0, 3).join(", ")}`);
   }
   try {
-    const ruleFile = path8.join(getProjectRoot(), ".kuma", "DOMAIN_RULES.md");
-    if (fs8.existsSync(ruleFile)) {
-      const content = fs8.readFileSync(ruleFile, "utf-8");
+    const ruleFile = path10.join(getProjectRoot(), ".kuma", "DOMAIN_RULES.md");
+    if (fs9.existsSync(ruleFile)) {
+      const content = fs9.readFileSync(ruleFile, "utf-8");
       const rules = content.split("\n").filter((l) => /^- Rule \d+:?\s*/i.test(l)).map((l) => l.replace(/^- Rule \d+:?\s*/i, "").trim()).filter(Boolean);
       if (rules.length > 0) {
         lines.push(`\u{1F4CB} **Rules**: ${rules.slice(0, 5).join(" | ")}`);
@@ -5548,15 +5908,15 @@ __export(kumaDriftDetector_exports, {
   getDriftSummary: () => getDriftSummary,
   hashFile: () => hashFile
 });
-import fs9 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path11 from "path";
 import crypto3 from "crypto";
 function hashFile(filePath) {
   try {
     const root = getProjectRoot();
-    const fullPath = path9.resolve(root, filePath);
-    if (!fs9.existsSync(fullPath)) return null;
-    const content = fs9.readFileSync(fullPath, "utf-8");
+    const fullPath = path11.resolve(root, filePath);
+    if (!fs10.existsSync(fullPath)) return null;
+    const content = fs10.readFileSync(fullPath, "utf-8");
     return crypto3.createHash("sha256").update(content).digest("hex");
   } catch {
     return null;
@@ -5636,8 +5996,8 @@ async function detectDrift() {
       let hasStaleFile = false;
       for (const fp of filePaths) {
         if (!fp) continue;
-        const fullPath = path9.resolve(getProjectRoot(), fp);
-        if (!fs9.existsSync(fullPath)) {
+        const fullPath = path11.resolve(getProjectRoot(), fp);
+        if (!fs10.existsSync(fullPath)) {
           hasStaleFile = true;
           break;
         }
@@ -5668,12 +6028,12 @@ function computeScopeHash(scope) {
     hash.update(scope);
     let found = false;
     try {
-      const files = fs9.readdirSync(root);
+      const files = fs10.readdirSync(root);
       for (const file of files) {
         if (file.toLowerCase().includes(scope.toLowerCase())) {
           try {
-            if (fs9.statSync(path9.join(root, file)).isFile()) {
-              const content = fs9.readFileSync(path9.join(root, file), "utf-8");
+            if (fs10.statSync(path11.join(root, file)).isFile()) {
+              const content = fs10.readFileSync(path11.join(root, file), "utf-8");
               hash.update(file);
               hash.update(content.substring(0, 1e4));
               found = true;
@@ -5684,11 +6044,11 @@ function computeScopeHash(scope) {
       }
     } catch {
     }
-    const researchDir = path9.join(root, ".kuma", "research");
-    if (fs9.existsSync(researchDir)) {
-      const scopeFile = path9.join(researchDir, `${scope}.json`);
-      if (fs9.existsSync(scopeFile)) {
-        const content = fs9.readFileSync(scopeFile, "utf-8");
+    const researchDir = path11.join(root, ".kuma", "research");
+    if (fs10.existsSync(researchDir)) {
+      const scopeFile = path11.join(researchDir, `${scope}.json`);
+      if (fs10.existsSync(scopeFile)) {
+        const content = fs10.readFileSync(scopeFile, "utf-8");
         hash.update(content);
         found = true;
       }
@@ -5786,26 +6146,26 @@ __export(kumaProgressiveContext_exports, {
   getSkillBoundary: () => getSkillBoundary,
   loadSection: () => loadSection
 });
-import fs10 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path12 from "path";
 async function getProjectMeta() {
   const root = getProjectRoot();
   const name = root.split("/").pop() || "unknown";
   const stack = [];
-  if (fs10.existsSync(path10.join(root, "package.json"))) {
+  if (fs11.existsSync(path12.join(root, "package.json"))) {
     try {
-      const pkg = JSON.parse(fs10.readFileSync(path10.join(root, "package.json"), "utf-8"));
+      const pkg = JSON.parse(fs11.readFileSync(path12.join(root, "package.json"), "utf-8"));
       if (pkg.dependencies?.next) stack.push("Next.js");
       else if (pkg.dependencies?.react) stack.push("React");
       if (pkg.devDependencies?.typescript) stack.push("TypeScript");
-      if (fs10.existsSync(path10.join(root, "pnpm-lock.yaml"))) stack.push("pnpm");
-      else if (fs10.existsSync(path10.join(root, "yarn.lock"))) stack.push("yarn");
+      if (fs11.existsSync(path12.join(root, "pnpm-lock.yaml"))) stack.push("pnpm");
+      else if (fs11.existsSync(path12.join(root, "yarn.lock"))) stack.push("yarn");
     } catch {
     }
   }
-  if (fs10.existsSync(path10.join(root, "go.mod"))) stack.push("Go");
-  if (fs10.existsSync(path10.join(root, "Cargo.toml"))) stack.push("Rust");
-  if (fs10.existsSync(path10.join(root, "pyproject.toml"))) stack.push("Python");
+  if (fs11.existsSync(path12.join(root, "go.mod"))) stack.push("Go");
+  if (fs11.existsSync(path12.join(root, "Cargo.toml"))) stack.push("Rust");
+  if (fs11.existsSync(path12.join(root, "pyproject.toml"))) stack.push("Python");
   let nodeCount = 0;
   let edgeCount = 0;
   try {
@@ -5816,10 +6176,10 @@ async function getProjectMeta() {
     edgeCount = edgeRes[0]?.values[0]?.[0] ?? 0;
   } catch {
   }
-  const kumaDir = path10.join(root, ".kuma");
+  const kumaDir = path12.join(root, ".kuma");
   const layerStatus = {
-    domainRules: fs10.existsSync(path10.join(kumaDir, "DOMAIN_RULES.md")),
-    archFlow: fs10.existsSync(path10.join(kumaDir, "ARCHITECTURE_FLOW.md")),
+    domainRules: fs11.existsSync(path12.join(kumaDir, "DOMAIN_RULES.md")),
+    archFlow: fs11.existsSync(path12.join(kumaDir, "ARCHITECTURE_FLOW.md")),
     gotchas: getActiveGotchas().length
   };
   let hasDecisions = false;
@@ -6018,8 +6378,8 @@ __export(kumaSearch_exports, {
   formatHybridResults: () => formatHybridResults,
   hybridSearch: () => hybridSearch
 });
-import fs12 from "fs";
-import path12 from "path";
+import fs13 from "fs";
+import path14 from "path";
 function expandQueryTerms(query) {
   const terms = query.toLowerCase().split(/[\s_-]+/).filter((t) => t.length > 2);
   const expanded = /* @__PURE__ */ new Map();
@@ -6040,6 +6400,11 @@ function expandQueryTerms(query) {
   }
   return expanded;
 }
+function recencyScore(epochSec) {
+  if (!epochSec) return 0.5;
+  const ageDays = Math.max(0, (Date.now() / 1e3 - epochSec) / 86400);
+  return Math.max(0, Math.min(1, 1 - ageDays / 90));
+}
 async function buildSearchVectors() {
   if (_vectorCache && Date.now() - _vectorCache.builtAt < VECTOR_CACHE_TTL) {
     return _vectorCache.vectors;
@@ -6047,7 +6412,7 @@ async function buildSearchVectors() {
   const vectors = [];
   try {
     const db = await getDb();
-    const stmt = db.prepare("SELECT id, name, metadata, file_path FROM nodes ORDER BY updated_at DESC LIMIT 500");
+    const stmt = db.prepare("SELECT id, name, metadata, file_path, updated_at FROM nodes ORDER BY updated_at DESC LIMIT " + SCALE_LIMITS.maxNodes);
     while (stmt.step()) {
       const row = stmt.getAsObject();
       const name = row.name || "";
@@ -6068,7 +6433,8 @@ async function buildSearchVectors() {
       vectors.push({
         terms: termCounts,
         source: name || row.id,
-        sourceType: "graph"
+        sourceType: "graph",
+        recency: recencyScore(row.updated_at)
       });
     }
     stmt.free();
@@ -6076,12 +6442,13 @@ async function buildSearchVectors() {
   }
   try {
     const root = getProjectRoot();
-    const memDir = path12.join(root, ".kuma", "memories");
-    if (fs12.existsSync(memDir)) {
-      const files = fs12.readdirSync(memDir).filter((f) => f.endsWith(".md")).slice(0, 10);
+    const memDir = path14.join(root, ".kuma", "memories");
+    if (fs13.existsSync(memDir)) {
+      const files = fs13.readdirSync(memDir).filter((f) => f.endsWith(".md")).slice(0, SCALE_LIMITS.maxMemoryFiles);
       for (const file of files) {
         try {
-          const content = fs12.readFileSync(path12.join(memDir, file), "utf-8");
+          const fullPath = path14.join(memDir, file);
+          const content = fs13.readFileSync(fullPath, "utf-8");
           const text = content.toLowerCase();
           const rawTerms = extractTerms(text);
           const termCounts = /* @__PURE__ */ new Map();
@@ -6091,7 +6458,8 @@ async function buildSearchVectors() {
           vectors.push({
             terms: termCounts,
             source: file.replace(/\.md$/, ""),
-            sourceType: "memory"
+            sourceType: "memory",
+            recency: recencyScore(Math.floor(fs13.statSync(fullPath).mtimeMs / 1e3))
           });
         } catch {
         }
@@ -6101,7 +6469,7 @@ async function buildSearchVectors() {
   }
   try {
     const db = await getDb();
-    const stmt = db.prepare("SELECT scope, record FROM research_cache ORDER BY updated_at DESC LIMIT 50");
+    const stmt = db.prepare("SELECT scope, record, updated_at FROM research_cache ORDER BY updated_at DESC LIMIT " + SCALE_LIMITS.maxResearch);
     while (stmt.step()) {
       const row = stmt.getAsObject();
       const scope = row.scope || "";
@@ -6115,7 +6483,8 @@ async function buildSearchVectors() {
       vectors.push({
         terms: termCounts,
         source: scope,
-        sourceType: "research"
+        sourceType: "research",
+        recency: recencyScore(row.updated_at)
       });
     }
     stmt.free();
@@ -6217,7 +6586,8 @@ async function hybridSearch(query, limit = 10) {
       const existing = results.find((r) => r.source === vec.source);
       if (existing) {
         existing.vectorScore = vectorScore;
-        existing.score = Math.min(100, Math.round(existing.keywordScore * 0.6 + vectorScore * 0.4));
+        const recencyBoost = Math.round((vec.recency ?? 0.5) * 10);
+        existing.score = Math.min(100, Math.round(existing.keywordScore * 0.6 + vectorScore * 0.4 + recencyBoost));
         for (const [term] of vec.terms) {
           if (queryVector.has(term) && !existing.matchedTerms.includes(term)) {
             existing.matchedTerms.push(term);
@@ -6228,10 +6598,11 @@ async function hybridSearch(query, limit = 10) {
         for (const [term] of vec.terms) {
           if (queryVector.has(term)) matchedTerms.push(term);
         }
+        const recencyBoost = Math.round((vec.recency ?? 0.5) * 10);
         results.push({
           source: vec.source,
           sourceType: vec.sourceType,
-          score: Math.round(vectorScore * 0.4),
+          score: Math.min(100, Math.round(vectorScore * 0.4 + recencyBoost)),
           keywordScore: 0,
           vectorScore,
           matchedTerms
@@ -6286,7 +6657,7 @@ async function buildGraphConnectivity() {
   let totalEdges = 0;
   try {
     const db = await getDb();
-    const stmt = db.prepare("SELECT source_id, target_id FROM edges LIMIT 2000");
+    const stmt = db.prepare("SELECT source_id, target_id FROM edges LIMIT " + SCALE_LIMITS.maxEdges);
     while (stmt.step()) {
       const row = stmt.getAsObject();
       const src = row.source_id || "";
@@ -6336,7 +6707,7 @@ function clearSearchCache() {
   _vectorCache = null;
   clearConnectivityCache();
 }
-var SYNONYM_MAP, _vectorCache, VECTOR_CACHE_TTL, _connectivityCache, CONNECTIVITY_CACHE_TTL;
+var SYNONYM_MAP, SCALE_LIMITS, _vectorCache, VECTOR_CACHE_TTL, _connectivityCache, CONNECTIVITY_CACHE_TTL;
 var init_kumaSearch = __esm({
   "src/engine/kumaSearch.ts"() {
     "use strict";
@@ -6381,6 +6752,16 @@ var init_kumaSearch = __esm({
       update: ["update", "modify", "change", "edit", "patch"],
       delete: ["delete", "remove", "drop", "clear", "purge"]
     };
+    SCALE_LIMITS = {
+      maxNodes: 5e3,
+      // was 500 — graphs grow with project size
+      maxMemoryFiles: 30,
+      // was 10
+      maxResearch: 300,
+      // was 50
+      maxEdges: 2e4
+      // was 2000 (graph connectivity)
+    };
     _vectorCache = null;
     VECTOR_CACHE_TTL = 3e5;
     _connectivityCache = null;
@@ -6393,8 +6774,8 @@ var kumaMiner_exports = {};
 __export(kumaMiner_exports, {
   mineHistoricalDecisions: () => mineHistoricalDecisions
 });
-import fs13 from "fs";
-import path13 from "path";
+import fs14 from "fs";
+import path15 from "path";
 import { execSync as execSync4 } from "child_process";
 import fastGlob2 from "fast-glob";
 async function mineHistoricalDecisions(options = {}) {
@@ -6469,7 +6850,7 @@ async function mineHistoricalDecisions(options = {}) {
   }
   if (candidates.length < limit) {
     try {
-      const scopePattern = options.scope ? `**/*${options.scope}*.*` : "**/*.{ts,js,py,go,rs,java,md}";
+      const scopePattern = options.scope ? `**/*${options.scope}*.*` : `**/*.{${SOURCE_EXT_GLOB.slice(1, -1)},md}`;
       const files = await fastGlob2(scopePattern, {
         cwd: root,
         ignore: ["node_modules/**", "dist/**", ".kuma/**", ".git/**", "coverage/**"],
@@ -6484,9 +6865,9 @@ async function mineHistoricalDecisions(options = {}) {
       ];
       for (const file of files.slice(0, 50)) {
         if (candidates.length >= limit) break;
-        const fullPath = path13.join(root, file);
-        if (!fs13.existsSync(fullPath)) continue;
-        const content = fs13.readFileSync(fullPath, "utf-8");
+        const fullPath = path15.join(root, file);
+        if (!fs14.existsSync(fullPath)) continue;
+        const content = fs14.readFileSync(fullPath, "utf-8");
         const lines = content.split("\n");
         for (let i = 0; i < lines.length; i++) {
           const l = lines[i];
@@ -6561,6 +6942,7 @@ var init_kumaMiner = __esm({
     "use strict";
     init_kumaDb();
     init_kumaMemory();
+    init_languageSupport();
   }
 });
 
@@ -6793,8 +7175,8 @@ __export(kumaGitHarvester_exports, {
   installGitHook: () => installGitHook
 });
 import { execSync as execSync5 } from "child_process";
-import fs14 from "fs";
-import path14 from "path";
+import fs15 from "fs";
+import path16 from "path";
 function getRecentCommits(count = 5) {
   const root = getProjectRoot();
   try {
@@ -6974,11 +7356,11 @@ async function harvestGitHistory(options) {
 }
 function installGitHook() {
   const root = getProjectRoot();
-  const hooksDir = path14.join(root, ".git", "hooks");
-  if (!fs14.existsSync(hooksDir)) {
+  const hooksDir = path16.join(root, ".git", "hooks");
+  if (!fs15.existsSync(hooksDir)) {
     return "\u26A0\uFE0F Not a git repository \u2014 no .git/hooks/ directory found.";
   }
-  const hookPath = path14.join(hooksDir, "post-commit");
+  const hookPath = path16.join(hooksDir, "post-commit");
   const hookContent = `#!/bin/bash
 # Kuma auto-harvester hook (post-commit)
 # Automatically extracts decisions and gotchas from commits
@@ -6986,23 +7368,23 @@ if command -v npx &> /dev/null; then
   npx -y @plumpslabs/kuma --hook post-commit 2>/dev/null || true
 fi
 `;
-  if (fs14.existsSync(hookPath)) {
-    const existing = fs14.readFileSync(hookPath, "utf-8");
+  if (fs15.existsSync(hookPath)) {
+    const existing = fs15.readFileSync(hookPath, "utf-8");
     if (existing.includes("kuma")) {
       return "\u2705 Kuma git hook already installed.";
     }
     const backupPath = hookPath + ".backup." + Date.now();
-    fs14.copyFileSync(hookPath, backupPath);
-    fs14.writeFileSync(hookPath, hookContent, "utf-8");
+    fs15.copyFileSync(hookPath, backupPath);
+    fs15.writeFileSync(hookPath, hookContent, "utf-8");
     try {
-      fs14.chmodSync(hookPath, 493);
+      fs15.chmodSync(hookPath, 493);
     } catch {
     }
-    return `\u2705 Installed kuma post-commit hook (existing hook backed up to ${path14.basename(backupPath)})`;
+    return `\u2705 Installed kuma post-commit hook (existing hook backed up to ${path16.basename(backupPath)})`;
   }
-  fs14.writeFileSync(hookPath, hookContent, "utf-8");
+  fs15.writeFileSync(hookPath, hookContent, "utf-8");
   try {
-    fs14.chmodSync(hookPath, 493);
+    fs15.chmodSync(hookPath, 493);
   } catch {
   }
   return "\u2705 Installed kuma post-commit hook.";
@@ -7099,6 +7481,102 @@ function mineSessionInsights() {
       }
     }
   }
+  const dirReads = {};
+  for (const call of toolCalls) {
+    if (call.toolName === "read" || call.toolName === "browser_read") {
+      const file = call.params.filePath || "";
+      if (file) {
+        const dir = file.split("/").slice(0, -1).join("/") || "root";
+        if (!dirReads[dir]) dirReads[dir] = [];
+        dirReads[dir].push(file.split("/").pop() || file);
+      }
+    }
+  }
+  for (const [dir, files] of Object.entries(dirReads)) {
+    if (files.length >= 3) {
+      const dirName = dir.split("/").pop() || dir;
+      insights.push({
+        type: "feature",
+        scope: dir,
+        content: `${dirName} \u2014 ${files.length} files explored: ${files.slice(0, 5).join(", ")}${files.length > 5 ? "..." : ""}`,
+        confidence: 0.6,
+        source: `directory_exploration:${files.length}_files`
+      });
+    }
+  }
+  for (let i = 0; i < toolCalls.length - 1; i++) {
+    const a = toolCalls[i];
+    const b = toolCalls[i + 1];
+    if (a.toolName === "test" && b.toolName === "edit") {
+      const file = b.params.filePath || "";
+      if (file) {
+        insights.push({
+          type: "gotcha",
+          scope: file,
+          content: `Test failed then ${file.split("/").pop()} was edited \u2014 likely a bug fix needed`,
+          confidence: 0.7,
+          source: `test_fail_fix`
+        });
+      }
+    }
+  }
+  const importChain = [];
+  for (const call of toolCalls) {
+    if (call.toolName === "read" || call.toolName === "browser_read") {
+      const file = call.params.filePath || "";
+      if (file && file.endsWith(".ts")) {
+        importChain.push(file);
+      }
+    }
+  }
+  if (importChain.length >= 4) {
+    const uniqueFiles = [...new Set(importChain)];
+    if (uniqueFiles.length >= 3) {
+      insights.push({
+        type: "arch_flow",
+        scope: uniqueFiles[0],
+        content: `Import chain traced: ${uniqueFiles.slice(0, 5).map((f) => f.split("/").pop() || f).join(" \u2192 ")}`,
+        confidence: 0.6,
+        source: `import_chain:${uniqueFiles.length}_files`
+      });
+    }
+  }
+  const routeFiles = [];
+  for (const call of toolCalls) {
+    if (call.toolName === "read" || call.toolName === "browser_read") {
+      const file = call.params.filePath || "";
+      if (file && (file.includes("route") || file.includes("api") || file.includes("controller"))) {
+        routeFiles.push(file.split("/").pop() || file);
+      }
+    }
+  }
+  if (routeFiles.length >= 2) {
+    insights.push({
+      type: "feature",
+      scope: "api",
+      content: `API routes explored: ${routeFiles.slice(0, 5).join(", ")}`,
+      confidence: 0.5,
+      source: `api_route_discovery`
+    });
+  }
+  const componentFiles = [];
+  for (const call of toolCalls) {
+    if (call.toolName === "read" || call.toolName === "browser_read") {
+      const file = call.params.filePath || "";
+      if (file && (file.includes("component") || file.includes(".tsx") || file.includes(".jsx"))) {
+        componentFiles.push(file.split("/").pop() || file);
+      }
+    }
+  }
+  if (componentFiles.length >= 3) {
+    insights.push({
+      type: "arch_flow",
+      scope: "ui",
+      content: `UI components explored: ${componentFiles.slice(0, 5).join(", ")}`,
+      confidence: 0.6,
+      source: `component_discovery:${componentFiles.length}_files`
+    });
+  }
   return insights;
 }
 function formatMinedInsights(insights) {
@@ -7114,12 +7592,12 @@ function formatMinedInsights(insights) {
   ];
   for (let i = 0; i < insights.length; i++) {
     const ins = insights[i];
-    const icon = ins.type === "gotcha" ? "\u26A0\uFE0F" : ins.type === "decision" ? "\u{1F4CC}" : "\u{1F500}";
+    const icon = ins.type === "gotcha" ? "\u26A0\uFE0F" : ins.type === "decision" ? "\u{1F4CC}" : ins.type === "feature" ? "\u2B50" : "\u{1F500}";
     const conf = Math.round(ins.confidence * 100);
     lines.push(`${i + 1}. ${icon} **${ins.type}** (${conf}% confidence)`);
     lines.push(`   Scope: ${ins.scope}`);
     lines.push(`   ${ins.content}`);
-    lines.push(`   \u2192 \`kuma_memory({ action: "${ins.type}", ${ins.type === "arch_flow" ? "content" : 'scope: \\"${ins.scope}\\", content'}: "${ins.content.substring(0, 60)}..." })\``);
+    lines.push(`   \u2192 \`kuma_memory({ action: "${ins.type}", ${ins.type === "arch_flow" ? "content" : ins.type === "feature" ? `title: "\${ins.scope.split('/').pop() || ins.scope}", content` : 'scope: \\"${ins.scope}\\", content'}: "${ins.content.substring(0, 60)}..." })\``);
     lines.push("");
   }
   lines.push("\u{1F4A1} Approve by recording the ones you agree with. Skip the rest.");
@@ -7301,19 +7779,19 @@ __export(kumaPolicyEngine_exports, {
   processOverride: () => processOverride,
   savePolicyConfig: () => savePolicyConfig
 });
-import fs20 from "fs";
-import path20 from "path";
+import fs21 from "fs";
+import path22 from "path";
 function loadPolicyConfig() {
   try {
     const root = getProjectRoot();
-    const policyPath = path20.join(root, ".kuma", "POLICY.json");
-    if (fs20.existsSync(policyPath)) {
-      const content = fs20.readFileSync(policyPath, "utf-8");
+    const policyPath = path22.join(root, ".kuma", "POLICY.json");
+    if (fs21.existsSync(policyPath)) {
+      const content = fs21.readFileSync(policyPath, "utf-8");
       const config = JSON.parse(content);
       return { ...DEFAULT_POLICY_CONFIG, ...config };
     }
-    const ymlPath = path20.join(root, ".kuma", "policy.yml");
-    if (fs20.existsSync(ymlPath)) {
+    const ymlPath = path22.join(root, ".kuma", "policy.yml");
+    if (fs21.existsSync(ymlPath)) {
       console.error("[PolicyEngine] Found legacy policy.yml \u2014 consider migrating to POLICY.json");
     }
   } catch (err) {
@@ -7324,10 +7802,10 @@ function loadPolicyConfig() {
 function savePolicyConfig(config) {
   try {
     const root = getProjectRoot();
-    const policyPath = path20.join(root, ".kuma", "POLICY.json");
-    const dir = path20.dirname(policyPath);
-    if (!fs20.existsSync(dir)) fs20.mkdirSync(dir, { recursive: true });
-    fs20.writeFileSync(policyPath, JSON.stringify(config, null, 2), "utf-8");
+    const policyPath = path22.join(root, ".kuma", "POLICY.json");
+    const dir = path22.dirname(policyPath);
+    if (!fs21.existsSync(dir)) fs21.mkdirSync(dir, { recursive: true });
+    fs21.writeFileSync(policyPath, JSON.stringify(config, null, 2), "utf-8");
     return `\u2705 Policy config saved to .kuma/POLICY.json (${config.rules.length} rules)`;
   } catch (err) {
     return `\u274C Failed to save policy: ${err}`;
@@ -7612,14 +8090,14 @@ __export(kumaAstValidator_exports, {
   validateDiff: () => validateDiff,
   validateFile: () => validateFile
 });
-import fs21 from "fs";
-import path21 from "path";
+import fs22 from "fs";
+import path23 from "path";
 function loadImportWhitelist() {
   try {
     const root = getProjectRoot();
-    const whitelistPath = path21.join(root, ".kuma", "import-whitelist.json");
-    if (fs21.existsSync(whitelistPath)) {
-      return JSON.parse(fs21.readFileSync(whitelistPath, "utf-8"));
+    const whitelistPath = path23.join(root, ".kuma", "import-whitelist.json");
+    if (fs22.existsSync(whitelistPath)) {
+      return JSON.parse(fs22.readFileSync(whitelistPath, "utf-8"));
     }
   } catch {
   }
@@ -7645,7 +8123,9 @@ function validateCodeContent(code, filePath) {
         suggestion: "Restore the assertion or write an equivalent test for the new behavior"
       });
     }
-    if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(line) || /catch\s*\([^)]*\)\s*\{/.test(line) && lines[i + 1]?.trim() === "}") {
+    const emptyCatch = /catch\s*\([^)]*\)\s*\{\s*\}/.test(line) || /catch\s*\([^)]*\)\s*\{/.test(line) && lines[i + 1]?.trim() === "}" || // Python: bare/empty except blocks (except:, except Exception: pass)
+    /except\s*([^:]*)\s*:\s*(pass|\.\.\.)\s*(#.*)?$/.test(line) || /except\s*([^:]*)\s*:\s*$/.test(line) && /^pass(\s*#.*)?$/.test(lines[i + 1]?.trim() ?? "");
+    if (emptyCatch) {
       findings.push({
         line: lineNum,
         severity: "error",
@@ -7654,8 +8134,8 @@ function validateCodeContent(code, filePath) {
         suggestion: "Handle the error: log it, throw a meaningful error, or add a comment explaining why it's safe to ignore"
       });
     }
-    if (filePath?.includes(".test.") || filePath?.includes(".spec.")) {
-      if (/\breturn\s+(true|false|null|undefined|0|""|'')\s*;/.test(line) || /\breturn\s+\d+\s*;/.test(line) || /\bPromise\.resolve\s*\(\s*(true|false|null|undefined|0|""|'')\s*\)/.test(line)) {
+    if (isTestFile(filePath || "")) {
+      if (/\breturn\s+(true|false|null|undefined|0|""|'')\s*;/.test(line) || /\breturn\s+\d+\s*;/.test(line) || /\breturn\s+(True|False|None)\b/.test(line) || /\breturn\s+0\b/.test(line) || /\bPromise\.resolve\s*\(\s*(true|false|null|undefined|0|""|'')\s*\)/.test(line)) {
         findings.push({
           line: lineNum,
           severity: "warning",
@@ -7665,7 +8145,7 @@ function validateCodeContent(code, filePath) {
         });
       }
     }
-    if (!filePath?.includes(".test.") && !filePath?.includes(".spec.") && /\breturn\s+(true|false|null)\s*;/.test(line) && ((lines[i - 1] || "").includes("TODO") || (lines[i - 1] || "").includes("FIXME") || (lines[i - 1] || "").includes("HACK"))) {
+    if (!isTestFile(filePath || "") && /\breturn\s+(true|false|null)\s*;/.test(line) && ((lines[i - 1] || "").includes("TODO") || (lines[i - 1] || "").includes("FIXME") || (lines[i - 1] || "").includes("HACK"))) {
       findings.push({
         line: lineNum,
         severity: "warning",
@@ -7674,18 +8154,15 @@ function validateCodeContent(code, filePath) {
         suggestion: "Implement proper logic or add a clear comment explaining why this is correct"
       });
     }
-    const importMatch = line.match(/import\s+(?:\{[^}]*\}\s+from\s+)?['"]([^'"]+)['"]/);
-    if (importMatch) {
-      const imported = importMatch[1];
-      if (whitelist.blocked.some((b) => imported.includes(b))) {
-        findings.push({
-          line: lineNum,
-          severity: "error",
-          category: "import-violation",
-          message: `Blocked import: "${imported}" is not allowed per security whitelist`,
-          suggestion: `Remove or replace the import. Allowed packages: ${whitelist.allowed.slice(0, 5).join(", ") || "(none specified)"}`
-        });
-      }
+    const imported = matchImportPath(line);
+    if (imported && whitelist.blocked.some((b) => imported.includes(b))) {
+      findings.push({
+        line: lineNum,
+        severity: "error",
+        category: "import-violation",
+        message: `Blocked import: "${imported}" is not allowed per security whitelist`,
+        suggestion: `Remove or replace the import. Allowed packages: ${whitelist.allowed.slice(0, 5).join(", ") || "(none specified)"}`
+      });
     }
   }
   return findings;
@@ -7693,9 +8170,9 @@ function validateCodeContent(code, filePath) {
 function validateFile(filePath) {
   try {
     const root = getProjectRoot();
-    const fullPath = path21.resolve(root, filePath);
-    if (!fs21.existsSync(fullPath)) return [];
-    const content = fs21.readFileSync(fullPath, "utf-8");
+    const fullPath = path23.resolve(root, filePath);
+    if (!fs22.existsSync(fullPath)) return [];
+    const content = fs22.readFileSync(fullPath, "utf-8");
     return validateCodeContent(content, filePath);
   } catch {
     return [];
@@ -7755,6 +8232,7 @@ var init_kumaAstValidator = __esm({
   "src/engine/kumaAstValidator.ts"() {
     "use strict";
     init_pathValidator();
+    init_languageSupport();
   }
 });
 
@@ -7766,16 +8244,16 @@ __export(kumaCheckpoint_exports, {
   pruneCheckpoints: () => pruneCheckpoints,
   rollbackToCheckpoint: () => rollbackToCheckpoint
 });
-import fs22 from "fs";
-import path22 from "path";
+import fs23 from "fs";
+import path24 from "path";
 async function createCheckpoint(label, description) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    if (fs22.existsSync(cpDir)) {
+    const cpDir = path24.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    if (fs23.existsSync(cpDir)) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
-    fs22.mkdirSync(cpDir, { recursive: true });
+    fs23.mkdirSync(cpDir, { recursive: true });
     const db = await getDb();
     const filesStmt = db.prepare(
       "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
@@ -7784,19 +8262,19 @@ async function createCheckpoint(label, description) {
     while (filesStmt.step()) {
       const row = filesStmt.getAsObject();
       const fp = row.file_path;
-      const fullPath = path22.resolve(root, fp);
-      if (fs22.existsSync(fullPath)) {
-        const content = fs22.readFileSync(fullPath, "utf-8");
+      const fullPath = path24.resolve(root, fp);
+      if (fs23.existsSync(fullPath)) {
+        const content = fs23.readFileSync(fullPath, "utf-8");
         const hash = simpleHash2(content);
-        const fileDir = path22.dirname(path22.join(cpDir, "files", fp));
-        if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
-        fs22.writeFileSync(path22.join(cpDir, "files", fp), content, "utf-8");
+        const fileDir = path24.dirname(path24.join(cpDir, "files", fp));
+        if (!fs23.existsSync(fileDir)) fs23.mkdirSync(fileDir, { recursive: true });
+        fs23.writeFileSync(path24.join(cpDir, "files", fp), content, "utf-8");
         files.push({ path: fp, hash });
       }
     }
     filesStmt.free();
     const dbData = db.export();
-    fs22.writeFileSync(path22.join(cpDir, "kuma.db"), Buffer.from(dbData));
+    fs23.writeFileSync(path24.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
       label,
       timestamp: Date.now(),
@@ -7804,8 +8282,8 @@ async function createCheckpoint(label, description) {
       dbSnapshot: true,
       description
     };
-    fs22.writeFileSync(
-      path22.join(cpDir, "manifest.json"),
+    fs23.writeFileSync(
+      path24.join(cpDir, "manifest.json"),
       JSON.stringify(manifest, null, 2),
       "utf-8"
     );
@@ -7831,37 +8309,37 @@ async function createCheckpoint(label, description) {
 async function rollbackToCheckpoint(label) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    const manifestPath = path22.join(cpDir, "manifest.json");
-    if (!fs22.existsSync(manifestPath)) {
+    const cpDir = path24.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    const manifestPath = path24.join(cpDir, "manifest.json");
+    if (!fs23.existsSync(manifestPath)) {
       return `\u274C Checkpoint "${label}" not found. Use kuma_safety({ action: 'checkpoint_list' }) to see available checkpoints.`;
     }
     const manifest = JSON.parse(
-      fs22.readFileSync(manifestPath, "utf-8")
+      fs23.readFileSync(manifestPath, "utf-8")
     );
     let restored = 0;
     let failed = 0;
     for (const f of manifest.files) {
-      const snapshotPath = path22.join(cpDir, "files", f.path);
-      if (fs22.existsSync(snapshotPath)) {
+      const snapshotPath = path24.join(cpDir, "files", f.path);
+      if (fs23.existsSync(snapshotPath)) {
         try {
-          const content = fs22.readFileSync(snapshotPath, "utf-8");
-          const targetPath = path22.resolve(root, f.path);
-          const targetDir = path22.dirname(targetPath);
-          if (!fs22.existsSync(targetDir)) fs22.mkdirSync(targetDir, { recursive: true });
-          fs22.writeFileSync(targetPath, content, "utf-8");
+          const content = fs23.readFileSync(snapshotPath, "utf-8");
+          const targetPath = path24.resolve(root, f.path);
+          const targetDir = path24.dirname(targetPath);
+          if (!fs23.existsSync(targetDir)) fs23.mkdirSync(targetDir, { recursive: true });
+          fs23.writeFileSync(targetPath, content, "utf-8");
           restored++;
         } catch {
           failed++;
         }
       }
     }
-    const dbSnapshotPath = path22.join(cpDir, "kuma.db");
-    if (fs22.existsSync(dbSnapshotPath)) {
-      const kumaDir = path22.join(root, ".kuma");
-      const dbPath = path22.join(kumaDir, "kuma.db");
-      const snapshotData = fs22.readFileSync(dbSnapshotPath);
-      fs22.writeFileSync(dbPath, snapshotData);
+    const dbSnapshotPath = path24.join(cpDir, "kuma.db");
+    if (fs23.existsSync(dbSnapshotPath)) {
+      const kumaDir = path24.join(root, ".kuma");
+      const dbPath = path24.join(kumaDir, "kuma.db");
+      const snapshotData = fs23.readFileSync(dbSnapshotPath);
+      fs23.writeFileSync(dbPath, snapshotData);
       resetDbInstance();
     }
     sessionMemory.recordToolCall("kuma_checkpoint_rollback", {
@@ -7886,18 +8364,18 @@ async function rollbackToCheckpoint(label) {
 function listCheckpoints() {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR);
-    if (!fs22.existsSync(cpDir)) {
+    const cpDir = path24.join(root, CHECKPOINT_DIR);
+    if (!fs23.existsSync(cpDir)) {
       return "\u{1F4ED} No checkpoints found. Use kuma_safety({ action: 'checkpoint', label: 'pre-feature-x' }) to create one.";
     }
-    const entries = fs22.readdirSync(cpDir);
+    const entries = fs23.readdirSync(cpDir);
     const checkpoints = [];
     for (const entry of entries) {
-      const manifestPath = path22.join(cpDir, entry, "manifest.json");
-      if (fs22.existsSync(manifestPath)) {
+      const manifestPath = path24.join(cpDir, entry, "manifest.json");
+      if (fs23.existsSync(manifestPath)) {
         try {
           const manifest = JSON.parse(
-            fs22.readFileSync(manifestPath, "utf-8")
+            fs23.readFileSync(manifestPath, "utf-8")
           );
           checkpoints.push({ label: entry, manifest });
         } catch {
@@ -7929,12 +8407,12 @@ function listCheckpoints() {
 function pruneCheckpoints(keep = 5) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR);
-    if (!fs22.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
-    const entries = fs22.readdirSync(cpDir).map((e) => ({ name: e, time: fs22.statSync(path22.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
+    const cpDir = path24.join(root, CHECKPOINT_DIR);
+    if (!fs23.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
+    const entries = fs23.readdirSync(cpDir).map((e) => ({ name: e, time: fs23.statSync(path24.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
     let removed = 0;
     for (let i = keep; i < entries.length; i++) {
-      fs22.rmSync(path22.join(cpDir, entries[i].name), { recursive: true, force: true });
+      fs23.rmSync(path24.join(cpDir, entries[i].name), { recursive: true, force: true });
       removed++;
     }
     return removed > 0 ? `\u{1F9F9} Pruned **${removed} old checkpoint(s)**. Kept ${Math.min(keep, entries.length)} most recent.` : "\u2705 No checkpoints needed pruning.";
@@ -7974,18 +8452,18 @@ __export(kumaContractEngine_exports, {
   loadContracts: () => loadContracts,
   runContractChecks: () => runContractChecks
 });
-import fs23 from "fs";
-import path23 from "path";
+import fs24 from "fs";
+import path25 from "path";
 function contractsDir() {
-  return path23.join(getProjectRoot(), ".kuma", "contracts");
+  return path25.join(getProjectRoot(), ".kuma", "contracts");
 }
 function ensureContractsDir() {
   const dir = contractsDir();
-  if (!fs23.existsSync(dir)) {
-    fs23.mkdirSync(dir, { recursive: true });
-    const defaultPath = path23.join(dir, "default.json");
-    if (!fs23.existsSync(defaultPath)) {
-      fs23.writeFileSync(
+  if (!fs24.existsSync(dir)) {
+    fs24.mkdirSync(dir, { recursive: true });
+    const defaultPath = path25.join(dir, "default.json");
+    if (!fs24.existsSync(defaultPath)) {
+      fs24.writeFileSync(
         defaultPath,
         JSON.stringify(DEFAULT_CONTRACTS, null, 2),
         "utf-8"
@@ -7998,10 +8476,10 @@ function loadContracts() {
   const dir = contractsDir();
   const contracts = [];
   try {
-    const files = fs23.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const files = fs24.readdirSync(dir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
       try {
-        const content = fs23.readFileSync(path23.join(dir, file), "utf-8");
+        const content = fs24.readFileSync(path25.join(dir, file), "utf-8");
         const config = JSON.parse(content);
         contracts.push(config);
       } catch (err) {
@@ -8074,7 +8552,7 @@ function evaluateCondition(condition, contextPath) {
   switch (condition.type) {
     case "file_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs23.existsSync(p));
+      const exists = targetPath.some((p) => fs24.existsSync(p));
       return {
         passed: exists,
         message: exists ? `\u2705 File exists: ${condition.target}` : `\u274C Required file not found: ${condition.target} (${condition.description})`
@@ -8082,7 +8560,7 @@ function evaluateCondition(condition, contextPath) {
     }
     case "file_not_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs23.existsSync(p));
+      const exists = targetPath.some((p) => fs24.existsSync(p));
       return {
         passed: !exists,
         message: !exists ? `\u2705 File does not exist: ${condition.target}` : `\u274C File should not exist: ${condition.target} (${condition.description})`
@@ -8090,9 +8568,9 @@ function evaluateCondition(condition, contextPath) {
     }
     case "contains": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const fullPath = path23.resolve(root, contextPath);
-      if (!fs23.existsSync(fullPath)) return { passed: true, message: "\u26A0\uFE0F File not found" };
-      const content = fs23.readFileSync(fullPath, "utf-8");
+      const fullPath = path25.resolve(root, contextPath);
+      if (!fs24.existsSync(fullPath)) return { passed: true, message: "\u26A0\uFE0F File not found" };
+      const content = fs24.readFileSync(fullPath, "utf-8");
       const hasContent = condition.value ? content.includes(condition.value) : false;
       return {
         passed: hasContent,
@@ -8104,12 +8582,12 @@ function evaluateCondition(condition, contextPath) {
       const root2 = getProjectRoot();
       const targets = resolveTarget(condition.target, contextPath, root2);
       for (const t of targets) {
-        if (fs23.existsSync(t)) {
-          const content = fs23.readFileSync(t, "utf-8");
+        if (fs24.existsSync(t)) {
+          const content = fs24.readFileSync(t, "utf-8");
           if (condition.value && content.includes(condition.value)) {
             return {
               passed: false,
-              message: `\u274C Found forbidden pattern "${condition.value}" in ${path23.relative(root2, t)} (${condition.description})`
+              message: `\u274C Found forbidden pattern "${condition.value}" in ${path25.relative(root2, t)} (${condition.description})`
             };
           }
         }
@@ -8118,15 +8596,11 @@ function evaluateCondition(condition, contextPath) {
     }
     case "has_test_file": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const basename = path23.basename(contextPath, path23.extname(contextPath));
-      const dir = path23.dirname(contextPath);
-      const possibleTests = [
-        path23.join(dir, `${basename}.test.ts`),
-        path23.join(dir, `${basename}.spec.ts`),
-        path23.join(dir, `__tests__/${basename}.test.ts`),
-        path23.join(dir, `__tests__/${basename}.spec.ts`)
-      ];
-      const hasTest = possibleTests.some((t) => fs23.existsSync(t));
+      const candidates = getTestCandidates(contextPath);
+      const hasTest = candidates.some((t) => {
+        const abs = path25.isAbsolute(t) ? t : path25.resolve(root, t);
+        return fs24.existsSync(abs);
+      });
       return {
         passed: hasTest,
         message: hasTest ? `\u2705 Test file exists` : `\u274C No test file found for ${contextPath} (${condition.description})`
@@ -8150,18 +8624,24 @@ function resolveTarget(pattern, contextPath, root) {
   const r = root || getProjectRoot();
   if (pattern.startsWith("*")) {
     if (contextPath) {
-      const dir = path23.dirname(path23.resolve(r, contextPath));
+      const dir = path25.dirname(path25.resolve(r, contextPath));
       const suffix = pattern.replace("*", "");
       try {
-        const files = fs23.readdirSync(dir);
-        return files.filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path23.join(dir, f));
+        const files = fs24.readdirSync(dir);
+        return files.filter((f) => {
+          try {
+            return fs24.statSync(path25.join(dir, f)).isFile();
+          } catch {
+            return false;
+          }
+        }).filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path25.join(dir, f));
       } catch {
-        return [path23.join(dir, pattern.replace("*", ""))];
+        return [path25.join(dir, pattern.replace("*", ""))];
       }
     }
     return [];
   }
-  return [path23.resolve(r, pattern)];
+  return [path25.resolve(r, pattern)];
 }
 async function runContractChecks(toolName, filePath, phase = "pre") {
   const verdicts = phase === "pre" ? evaluatePreConditions(toolName, filePath) : evaluatePostConditions(toolName, filePath);
@@ -8223,6 +8703,7 @@ var init_kumaContractEngine = __esm({
   "src/engine/kumaContractEngine.ts"() {
     "use strict";
     init_pathValidator();
+    init_languageSupport();
     DEFAULT_CONTRACTS = {
       version: 1,
       contracts: [
@@ -8249,15 +8730,21 @@ var init_kumaContractEngine = __esm({
           postConditions: [
             {
               type: "not_contains",
-              target: "*.ts",
+              target: "*",
               value: "catch {}",
               description: "Empty catch blocks suppress errors silently"
             },
             {
               type: "not_contains",
-              target: "*.ts",
+              target: "*",
               value: "catch (e) {}",
               description: "Empty catch (e) {} suppresses errors silently"
+            },
+            {
+              type: "not_contains",
+              target: "*",
+              value: "except:",
+              description: "Bare except blocks suppress errors silently (Python)"
             }
           ],
           severity: "error"
@@ -8275,6 +8762,116 @@ var init_kumaContractEngine = __esm({
   }
 });
 
+// src/engine/kumaAutoGotcha.ts
+var kumaAutoGotcha_exports = {};
+__export(kumaAutoGotcha_exports, {
+  AUTO_GOTCHA_ESCALATE_AT: () => AUTO_GOTCHA_ESCALATE_AT,
+  AUTO_GOTCHA_THRESHOLD: () => AUTO_GOTCHA_THRESHOLD,
+  loadAutoGotchaState: () => loadAutoGotchaState,
+  resetScopeFailures: () => resetScopeFailures,
+  saveAutoGotchaState: () => saveAutoGotchaState,
+  trackVerificationResult: () => trackVerificationResult
+});
+import fs25 from "fs";
+import path26 from "path";
+function statePath() {
+  return path26.join(getProjectRoot(), STATE_FILE);
+}
+function loadAutoGotchaState() {
+  try {
+    const fp = statePath();
+    if (fs25.existsSync(fp)) {
+      const parsed = JSON.parse(fs25.readFileSync(fp, "utf-8"));
+      return {
+        failures: parsed?.failures ?? {},
+        lastRecorded: parsed?.lastRecorded ?? {}
+      };
+    }
+  } catch {
+  }
+  return { failures: {}, lastRecorded: {} };
+}
+function saveAutoGotchaState(state) {
+  try {
+    const fp = statePath();
+    const dir = path26.dirname(fp);
+    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+    fs25.writeFileSync(fp, JSON.stringify(state, null, 2), "utf-8");
+  } catch {
+  }
+}
+function resetScopeFailures(scope) {
+  const state = loadAutoGotchaState();
+  if (state.failures[scope] !== void 0 || state.lastRecorded?.[scope] !== void 0) {
+    delete state.failures[scope];
+    if (state.lastRecorded) delete state.lastRecorded[scope];
+    saveAutoGotchaState(state);
+  }
+}
+async function trackVerificationResult(scope, passed) {
+  if (!scope || scope === "session-impact") return { recorded: false, failureCount: 0 };
+  const state = loadAutoGotchaState();
+  const prev = state.failures[scope] ?? 0;
+  state.lastRecorded = state.lastRecorded || {};
+  if (passed) {
+    if (prev > 0 || state.lastRecorded[scope] !== void 0) {
+      delete state.failures[scope];
+      delete state.lastRecorded[scope];
+      saveAutoGotchaState(state);
+    }
+    return { recorded: false, failureCount: 0 };
+  }
+  const failureCount = prev + 1;
+  state.failures[scope] = failureCount;
+  saveAutoGotchaState(state);
+  const lastRecordedAt = state.lastRecorded[scope] ?? 0;
+  const shouldRecord = failureCount === AUTO_GOTCHA_THRESHOLD || failureCount === AUTO_GOTCHA_ESCALATE_AT;
+  if (!shouldRecord || failureCount <= lastRecordedAt) {
+    return { recorded: false, failureCount };
+  }
+  try {
+    const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+    const severity = failureCount >= AUTO_GOTCHA_ESCALATE_AT ? "high" : "medium";
+    const result = await addGotcha2({
+      filePath: scope,
+      description: `Verification keeps failing for scope "${scope}"`,
+      severity,
+      workaround: `Run tests locally before touching this area. Failing scope: "${scope}" \u2014 ${failureCount} consecutive failures. Verify with kuma_safety({ action: "verify", scope: "${scope}" }) after fixes.`
+    });
+    state.lastRecorded[scope] = failureCount;
+    saveAutoGotchaState(state);
+    return {
+      recorded: true,
+      failureCount,
+      message: [
+        `\u{1F9E0} **Auto-Gotcha recorded** (self-learning loop)`,
+        `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+        ``,
+        `\u26A0\uFE0F Scope \`${scope}\` failed verification ${failureCount} consecutive times.`,
+        `A gotcha has been recorded automatically so future sessions avoid re-discovering this.`,
+        ``,
+        result
+      ].join("\n")
+    };
+  } catch (err) {
+    return {
+      recorded: false,
+      failureCount,
+      message: `\u26A0\uFE0F Auto-gotcha recording failed: ${err}`
+    };
+  }
+}
+var STATE_FILE, AUTO_GOTCHA_THRESHOLD, AUTO_GOTCHA_ESCALATE_AT;
+var init_kumaAutoGotcha = __esm({
+  "src/engine/kumaAutoGotcha.ts"() {
+    "use strict";
+    init_pathValidator();
+    STATE_FILE = ".kuma/auto-gotcha.json";
+    AUTO_GOTCHA_THRESHOLD = 2;
+    AUTO_GOTCHA_ESCALATE_AT = 4;
+  }
+});
+
 // src/engine/kumaVerifier.ts
 var kumaVerifier_exports = {};
 __export(kumaVerifier_exports, {
@@ -8282,37 +8879,37 @@ __export(kumaVerifier_exports, {
   getRunningVerificationPid: () => getRunningVerificationPid,
   runAutoVerification: () => runAutoVerification
 });
-import fs24 from "fs";
-import path24 from "path";
+import fs26 from "fs";
+import path27 from "path";
 import { exec } from "child_process";
 function getLockDir(root = process.cwd()) {
-  return path24.resolve(root, LOCK_DIR_NAME);
+  return path27.resolve(root, LOCK_DIR_NAME);
 }
 function getPidFile(root = process.cwd()) {
-  return path24.join(getLockDir(root), "pid");
+  return path27.join(getLockDir(root), "pid");
 }
 function acquireFileLock(root) {
   const lockDir = getLockDir(root);
   try {
-    fs24.mkdirSync(lockDir, { recursive: false });
-    fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+    fs26.mkdirSync(lockDir, { recursive: false });
+    fs26.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
     return true;
   } catch {
     try {
-      if (fs24.existsSync(getPidFile(root))) {
-        const pid = parseInt(fs24.readFileSync(getPidFile(root), "utf-8"), 10);
+      if (fs26.existsSync(getPidFile(root))) {
+        const pid = parseInt(fs26.readFileSync(getPidFile(root), "utf-8"), 10);
         try {
           process.kill(pid, 0);
           return false;
         } catch {
-          fs24.rmSync(lockDir, { recursive: true, force: true });
+          fs26.rmSync(lockDir, { recursive: true, force: true });
           return acquireFileLock(root);
         }
       }
     } catch {
     }
     try {
-      fs24.rmSync(lockDir, { recursive: true, force: true });
+      fs26.rmSync(lockDir, { recursive: true, force: true });
       return acquireFileLock(root);
     } catch {
       return false;
@@ -8321,7 +8918,7 @@ function acquireFileLock(root) {
 }
 function releaseFileLock(root) {
   try {
-    fs24.rmSync(getLockDir(root), { recursive: true, force: true });
+    fs26.rmSync(getLockDir(root), { recursive: true, force: true });
   } catch {
   }
 }
@@ -8344,36 +8941,36 @@ function getRunningVerificationPid() {
   return _currentProcess?.pid ?? null;
 }
 function detectTestRunner(root = process.cwd()) {
-  const pkgPath = path24.join(root, "package.json");
-  if (fs24.existsSync(pkgPath)) {
+  const pkgPath = path27.join(root, "package.json");
+  if (fs26.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs24.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs26.readFileSync(pkgPath, "utf-8"));
       if (pkg.scripts && pkg.scripts.test) {
-        if (fs24.existsSync(path24.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
-        if (fs24.existsSync(path24.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test" };
+        if (fs26.existsSync(path27.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
+        if (fs26.existsSync(path27.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test" };
         return { runner: "npm", baseCommand: "npm test" };
       }
     } catch {
     }
   }
-  if (fs24.existsSync(path24.join(root, "pytest.ini")) || fs24.existsSync(path24.join(root, "pyproject.toml"))) return { runner: "pytest", baseCommand: "pytest" };
-  if (fs24.existsSync(path24.join(root, "Cargo.toml"))) return { runner: "cargo", baseCommand: "cargo test" };
-  if (fs24.existsSync(path24.join(root, "go.mod"))) return { runner: "go", baseCommand: "go test ./..." };
-  if (fs24.existsSync(path24.join(root, "Makefile"))) {
+  if (fs26.existsSync(path27.join(root, "pytest.ini")) || fs26.existsSync(path27.join(root, "pyproject.toml"))) return { runner: "pytest", baseCommand: "pytest" };
+  if (fs26.existsSync(path27.join(root, "Cargo.toml"))) return { runner: "cargo", baseCommand: "cargo test" };
+  if (fs26.existsSync(path27.join(root, "go.mod"))) return { runner: "go", baseCommand: "go test ./..." };
+  if (fs26.existsSync(path27.join(root, "Makefile"))) {
     try {
-      const makefileContent = fs24.readFileSync(path24.join(root, "Makefile"), "utf-8");
+      const makefileContent = fs26.readFileSync(path27.join(root, "Makefile"), "utf-8");
       const hasTestTarget = /^test:/m.test(makefileContent) || /^\s+test:/.test(makefileContent);
       if (hasTestTarget) return { runner: "make", baseCommand: "make test" };
     } catch {
     }
   }
-  if (fs24.existsSync(path24.join(root, "package.json"))) {
+  if (fs26.existsSync(path27.join(root, "package.json"))) {
     try {
-      const pkg = JSON.parse(fs24.readFileSync(path24.join(root, "package.json"), "utf-8"));
+      const pkg = JSON.parse(fs26.readFileSync(path27.join(root, "package.json"), "utf-8"));
       if (pkg.dependencies || pkg.devDependencies) {
-        if (fs24.existsSync(path24.join(root, "tsconfig.json"))) return { runner: "tsc", baseCommand: "npx tsc --noEmit" };
-        const srcDir = path24.join(root, "src");
-        if (fs24.existsSync(srcDir)) return { runner: "node", baseCommand: `node -c "${srcDir}/**/*.js" 2>/dev/null || node --check $(find src -name '*.js' 2>/dev/null | head -5)` };
+        if (fs26.existsSync(path27.join(root, "tsconfig.json"))) return { runner: "tsc", baseCommand: "npx tsc --noEmit" };
+        const srcDir = path27.join(root, "src");
+        if (fs26.existsSync(srcDir)) return { runner: "node", baseCommand: `node -c "${srcDir}/**/*.js" 2>/dev/null || node --check $(find src -name '*.js' 2>/dev/null | head -5)` };
       }
     } catch {
     }
@@ -8492,7 +9089,7 @@ async function runAutoVerification(options = {}) {
       const heartbeatTimer = setInterval(() => {
         if (getLockDir(root)) {
           try {
-            fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+            fs26.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
           } catch {
           }
         }
@@ -8512,8 +9109,24 @@ async function runAutoVerification(options = {}) {
         if (passed && fakePassPatterns.some((p) => p.test(rawOutput))) {
           passed = false;
         }
+        const isNoTests = fakePassPatterns.some((p) => p.test(rawOutput));
         const truncatedOutput = rawOutput.length > 2e3 ? rawOutput.substring(rawOutput.length - 2e3) : rawOutput;
         await saveVerification(scope, runner, fullCommand, passed, truncatedOutput, durationMs);
+        let autoGotchaMessage = null;
+        if (scope !== "session-impact" && !isNoTests) {
+          try {
+            const { trackVerificationResult: trackVerificationResult2 } = await Promise.resolve().then(() => (init_kumaAutoGotcha(), kumaAutoGotcha_exports));
+            const autoResult = await trackVerificationResult2(scope, passed);
+            if (autoResult.message) autoGotchaMessage = autoResult.message;
+          } catch {
+          }
+        } else if (passed) {
+          try {
+            const { resetScopeFailures: resetScopeFailures2 } = await Promise.resolve().then(() => (init_kumaAutoGotcha(), kumaAutoGotcha_exports));
+            resetScopeFailures2(scope);
+          } catch {
+          }
+        }
         _localRunning = false;
         _currentProcess = null;
         releaseFileLock(root);
@@ -8530,7 +9143,6 @@ async function runAutoVerification(options = {}) {
           ""
         ];
         if (!passed) {
-          const isNoTests = fakePassPatterns.some((p) => p.test(rawOutput));
           if (isNoTests) {
             lines[0] = `\u26AA **Verification: NO TESTS**`;
             lines.push("\u2139\uFE0F No tests ran. Install Jest, Vitest, pytest, or similar to enable verification.");
@@ -8545,6 +9157,9 @@ async function runAutoVerification(options = {}) {
           lines.push("\u{1F389} All scoped tests passed!");
           if (rawOutput) lines.push("```text", rawOutput.substring(0, 800), "```");
         }
+        if (autoGotchaMessage) {
+          lines.push("", autoGotchaMessage);
+        }
         resolve(lines.join("\n"));
       });
       _currentProcess = child;
@@ -8586,8 +9201,8 @@ __export(init_exports, {
   generateInitMdContent: () => generateInitMdContent,
   runInit: () => runInit
 });
-import fs25 from "fs";
-import path25 from "path";
+import fs27 from "fs";
+import path28 from "path";
 function configFilePath(type) {
   switch (type) {
     case "claude":
@@ -8997,10 +9612,10 @@ function generateInitMdContent() {
   ].join("\n");
 }
 function handleOpencodeSecondary(root, results) {
-  const skillPath = path25.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
+  const skillPath = path28.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
   if (results.some((r) => r.filePath === ".agents/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path25.dirname(skillPath);
+    const dir = path28.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -9024,18 +9639,18 @@ function handleOpencodeSecondary(root, results) {
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
-    if (fs25.existsSync(skillPath)) {
-      const existing = fs25.readFileSync(skillPath, "utf-8");
+    if (fs27.existsSync(skillPath)) {
+      const existing = fs27.readFileSync(skillPath, "utf-8");
       if (existing.includes("kuma-mcp")) {
         results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
       const newContent = existing.trimEnd() + "\n\n---\n\n" + content;
-      fs25.writeFileSync(skillPath, newContent, "utf-8");
+      fs27.writeFileSync(skillPath, newContent, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(skillPath, content, "utf-8");
+      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+      fs27.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -9048,21 +9663,21 @@ function handleOpencodeSecondary(root, results) {
   }
 }
 function handleCodexSecondary(root, results) {
-  const tomlPath = path25.resolve(root, ".codex/config.toml");
+  const tomlPath = path28.resolve(root, ".codex/config.toml");
   if (results.some((r) => r.filePath === ".codex/config.toml")) return;
   try {
-    const dir = path25.dirname(tomlPath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (fs25.existsSync(tomlPath)) {
-      const existingContent = fs25.readFileSync(tomlPath, "utf-8");
+    const dir = path28.dirname(tomlPath);
+    if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+    if (fs27.existsSync(tomlPath)) {
+      const existingContent = fs27.readFileSync(tomlPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      fs27.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
     } else {
-      fs25.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
+      fs27.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "created" });
     }
   } catch (err) {
@@ -9075,11 +9690,11 @@ function handleCodexSecondary(root, results) {
   }
 }
 function handleQwenSecondary(root, results) {
-  const settingsPath = path25.resolve(root, "settings.json");
+  const settingsPath = path28.resolve(root, "settings.json");
   if (results.some((r) => r.filePath === "settings.json")) return;
   try {
-    if (fs25.existsSync(settingsPath)) {
-      const existingContent = fs25.readFileSync(settingsPath, "utf-8");
+    if (fs27.existsSync(settingsPath)) {
+      const existingContent = fs27.readFileSync(settingsPath, "utf-8");
       if (existingContent.includes("kuma")) {
         if (!existingContent.includes("_Generated by Kuma MCP_")) {
           try {
@@ -9087,7 +9702,7 @@ function handleQwenSecondary(root, results) {
             parsed.mcpServers = parsed.mcpServers || {};
             if (!parsed.mcpServers.kuma) {
               parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-              fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+              fs27.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
               results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
               return;
             }
@@ -9102,13 +9717,13 @@ function handleQwenSecondary(root, results) {
         parsed.mcpServers = parsed.mcpServers || {};
         if (!parsed.mcpServers.kuma) {
           parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-          fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          fs27.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
           results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
         }
       } catch {
       }
     } else {
-      fs25.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
+      fs27.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
       results.push({ type: "qwen", filePath: "settings.json", action: "created" });
     }
   } catch (err) {
@@ -9206,18 +9821,18 @@ function getCombinedAgentsMd(selectedTypes) {
   return lines.join("\n");
 }
 function handleAntigravityMcpConfig(root, results) {
-  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path28.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const mcpDir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const mcpDir = path28.dirname(mcpPath);
+    if (fs27.existsSync(mcpPath)) {
+      const existingContent = fs27.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';
-            fs25.writeFileSync(mcpPath, updated, "utf-8");
+            fs27.writeFileSync(mcpPath, updated, "utf-8");
             results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
           }
         }
@@ -9226,11 +9841,11 @@ function handleAntigravityMcpConfig(root, results) {
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs27.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(mcpDir)) fs25.mkdirSync(mcpDir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs27.existsSync(mcpDir)) fs27.mkdirSync(mcpDir, { recursive: true });
+      fs27.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -9243,18 +9858,18 @@ function handleAntigravityMcpConfig(root, results) {
   }
 }
 function handleAiderSecondary(root, results) {
-  const ymlPath = path25.resolve(root, ".aider.conf.yml");
+  const ymlPath = path28.resolve(root, ".aider.conf.yml");
   if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
   try {
     const conventionsRef = "read: CONVENTIONS.md";
-    if (fs25.existsSync(ymlPath)) {
-      const existingContent = fs25.readFileSync(ymlPath, "utf-8");
+    if (fs27.existsSync(ymlPath)) {
+      const existingContent = fs27.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";
-      fs25.writeFileSync(ymlPath, newContent, "utf-8");
+      fs27.writeFileSync(ymlPath, newContent, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "appended" });
     } else {
       const content = [
@@ -9264,7 +9879,7 @@ function handleAiderSecondary(root, results) {
         conventionsRef,
         ""
       ].join("\n");
-      fs25.writeFileSync(ymlPath, content, "utf-8");
+      fs27.writeFileSync(ymlPath, content, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "created" });
     }
   } catch (err) {
@@ -9277,10 +9892,10 @@ function handleAiderSecondary(root, results) {
   }
 }
 function handleCopilotSecondary(root, results) {
-  const skillPath = path25.resolve(root, ".github/skills/kuma/SKILL.md");
+  const skillPath = path28.resolve(root, ".github/skills/kuma/SKILL.md");
   if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path25.dirname(skillPath);
+    const dir = path28.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -9291,17 +9906,17 @@ function handleCopilotSecondary(root, results) {
       "",
       "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
     ].join("\n");
-    if (fs25.existsSync(skillPath)) {
-      const existingContent = fs25.readFileSync(skillPath, "utf-8");
+    if (fs27.existsSync(skillPath)) {
+      const existingContent = fs27.readFileSync(skillPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      fs27.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(skillPath, content, "utf-8");
+      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+      fs27.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -9314,21 +9929,21 @@ function handleCopilotSecondary(root, results) {
   }
 }
 function handleOpenclawSecondary(root, results) {
-  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path28.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const dir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path28.dirname(mcpPath);
+    if (fs27.existsSync(mcpPath)) {
+      const existingContent = fs27.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: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs27.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+      fs27.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -9341,7 +9956,7 @@ function handleOpenclawSecondary(root, results) {
   }
 }
 function handleQuickrefGeneration(root, results) {
-  const quickrefPath = path25.resolve(root, ".kuma/quickref.md");
+  const quickrefPath = path28.resolve(root, ".kuma/quickref.md");
   const content = [
     "# Kuma Quick Reference",
     "",
@@ -9355,8 +9970,9 @@ function handleQuickrefGeneration(root, results) {
     "1. `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
     "",
     "## Record Rules",
-    "- **MUST:** decision, gotcha",
+    "- **MUST:** decision, gotcha, arch_flow, research_save, feature",
     "- **SKIP:** function, class, import, route",
+    "- **RELATIONSHIPS:** Every node MUST have edges. No orphan nodes.",
     "",
     "## Platform Tool Names",
     "- OpenCode / Antigravity: `kuma_kuma_*`",
@@ -9366,16 +9982,16 @@ function handleQuickrefGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const kumaDir = path25.dirname(quickrefPath);
-    if (!fs25.existsSync(kumaDir)) fs25.mkdirSync(kumaDir, { recursive: true });
-    if (fs25.existsSync(quickrefPath)) {
-      const existing = fs25.readFileSync(quickrefPath, "utf-8");
+    const kumaDir = path28.dirname(quickrefPath);
+    if (!fs27.existsSync(kumaDir)) fs27.mkdirSync(kumaDir, { recursive: true });
+    if (fs27.existsSync(quickrefPath)) {
+      const existing = fs27.readFileSync(quickrefPath, "utf-8");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
         return;
       }
     }
-    fs25.writeFileSync(quickrefPath, content, "utf-8");
+    fs27.writeFileSync(quickrefPath, content, "utf-8");
     results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
   } catch (err) {
     results.push({
@@ -9387,7 +10003,7 @@ function handleQuickrefGeneration(root, results) {
   }
 }
 function handleModeMdGeneration(root, results) {
-  const filePath = path25.resolve(root, ".kuma/MODE.md");
+  const filePath = path28.resolve(root, ".kuma/MODE.md");
   const content = [
     "# Adaptive Mode Selector",
     "",
@@ -9430,10 +10046,10 @@ function handleModeMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path25.dirname(filePath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (!fs25.existsSync(filePath)) {
-      fs25.writeFileSync(filePath, content, "utf-8");
+    const dir = path28.dirname(filePath);
+    if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+    if (!fs27.existsSync(filePath)) {
+      fs27.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "created" });
     }
   } catch (err) {
@@ -9441,7 +10057,7 @@ function handleModeMdGeneration(root, results) {
   }
 }
 function handleSkipRulesMdGeneration(root, results) {
-  const filePath = path25.resolve(root, ".kuma/SKIP_RULES.md");
+  const filePath = path28.resolve(root, ".kuma/SKIP_RULES.md");
   const content = [
     "# Skip Rules \u2014 What NOT to Record",
     "",
@@ -9478,10 +10094,10 @@ function handleSkipRulesMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path25.dirname(filePath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (!fs25.existsSync(filePath)) {
-      fs25.writeFileSync(filePath, content, "utf-8");
+    const dir = path28.dirname(filePath);
+    if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+    if (!fs27.existsSync(filePath)) {
+      fs27.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "created" });
     }
   } catch (err) {
@@ -9489,7 +10105,7 @@ function handleSkipRulesMdGeneration(root, results) {
   }
 }
 function handleStalenessMdGeneration(root, results) {
-  const filePath = path25.resolve(root, ".kuma/STALENESS.md");
+  const filePath = path28.resolve(root, ".kuma/STALENESS.md");
   const content = [
     "# Auto-Staleness Detection",
     "",
@@ -9520,10 +10136,10 @@ function handleStalenessMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path25.dirname(filePath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (!fs25.existsSync(filePath)) {
-      fs25.writeFileSync(filePath, content, "utf-8");
+    const dir = path28.dirname(filePath);
+    if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+    if (!fs27.existsSync(filePath)) {
+      fs27.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "created" });
     }
   } catch (err) {
@@ -9531,20 +10147,20 @@ function handleStalenessMdGeneration(root, results) {
   }
 }
 function handleInitMdGeneration(root, results) {
-  const initMdPath = path25.resolve(root, ".kuma/init.md");
+  const initMdPath = path28.resolve(root, ".kuma/init.md");
   try {
-    const kumaDir = path25.dirname(initMdPath);
-    if (!fs25.existsSync(kumaDir)) fs25.mkdirSync(kumaDir, { recursive: true });
-    if (fs25.existsSync(initMdPath)) {
-      const existing = fs25.readFileSync(initMdPath, "utf-8");
+    const kumaDir = path28.dirname(initMdPath);
+    if (!fs27.existsSync(kumaDir)) fs27.mkdirSync(kumaDir, { recursive: true });
+    if (fs27.existsSync(initMdPath)) {
+      const existing = fs27.readFileSync(initMdPath, "utf-8");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/init.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
+      fs27.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "appended" });
     } else {
-      fs25.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
+      fs27.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "created" });
     }
   } catch (err) {
@@ -9561,20 +10177,20 @@ function handleInitMdGeneration(root, results) {
   handleStalenessMdGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
-  const mcpPath = path25.resolve(root, ".codewhale/mcp.json");
+  const mcpPath = path28.resolve(root, ".codewhale/mcp.json");
   if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
   try {
-    const dir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path28.dirname(mcpPath);
+    if (fs27.existsSync(mcpPath)) {
+      const existingContent = fs27.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: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs27.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
       const config = {
         mcpServers: {
           kuma: {
@@ -9584,7 +10200,7 @@ function handleCodewhaleSecondary(root, results) {
           }
         }
       };
-      fs25.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs27.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "created" });
     }
   } catch (err) {
@@ -9606,28 +10222,28 @@ function runInit(options) {
   let agentsMdHandled = false;
   for (const type of selected) {
     const relativePath = configFilePath(type);
-    const fullPath = path25.resolve(root, relativePath);
+    const fullPath = path28.resolve(root, relativePath);
     const getTemplate = TEMPLATES[type];
     try {
       if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
         agentsMdHandled = true;
         const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
-        if (fs25.existsSync(fullPath)) {
+        if (fs27.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
           } else {
-            const existingContent = fs25.readFileSync(fullPath, "utf-8");
+            const existingContent = fs27.readFileSync(fullPath, "utf-8");
             if (existingContent.includes("_Generated by Kuma MCP_")) {
               results.push({ type, filePath: relativePath, action: "skipped" });
             } else {
-              fs25.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+              fs27.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
               results.push({ type, filePath: relativePath, action: "appended" });
             }
           }
         } else {
-          const dir = path25.dirname(fullPath);
-          if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-          fs25.writeFileSync(fullPath, combinedContent, "utf-8");
+          const dir = path28.dirname(fullPath);
+          if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+          fs27.writeFileSync(fullPath, combinedContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
@@ -9639,12 +10255,12 @@ function runInit(options) {
         continue;
       } else {
         const template = getTemplate();
-        if (fs25.existsSync(fullPath)) {
+        if (fs27.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
             continue;
           }
-          const existingContent = fs25.readFileSync(fullPath, "utf-8");
+          const existingContent = fs27.readFileSync(fullPath, "utf-8");
           if (existingContent.includes("_Generated by Kuma MCP_")) {
             if (type === "antigravity") {
               handleAntigravityMcpConfig(root, results);
@@ -9657,14 +10273,14 @@ function runInit(options) {
             continue;
           }
           const newContent = existingContent.trimEnd() + APPEND_SEPARATOR + template;
-          fs25.writeFileSync(fullPath, newContent, "utf-8");
+          fs27.writeFileSync(fullPath, newContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "appended" });
         } else {
-          const dir = path25.dirname(fullPath);
-          if (!fs25.existsSync(dir)) {
-            fs25.mkdirSync(dir, { recursive: true });
+          const dir = path28.dirname(fullPath);
+          if (!fs27.existsSync(dir)) {
+            fs27.mkdirSync(dir, { recursive: true });
           }
-          fs25.writeFileSync(fullPath, template, "utf-8");
+          fs27.writeFileSync(fullPath, template, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (type === "antigravity") {
@@ -9806,6 +10422,209 @@ var init_init = __esm({
   }
 });
 
+// src/engine/kumaLegacyOnboard.ts
+var kumaLegacyOnboard_exports = {};
+__export(kumaLegacyOnboard_exports, {
+  runLegacyOnboarding: () => runLegacyOnboarding
+});
+import fs28 from "fs";
+import path29 from "path";
+async function harvestGit(commitCount) {
+  try {
+    const { harvestGitHistory: harvestGitHistory2 } = await Promise.resolve().then(() => (init_kumaGitHarvester(), kumaGitHarvester_exports));
+    return await harvestGitHistory2({ commitCount });
+  } catch (err) {
+    return `\u26A0\uFE0F Git harvest skipped: ${err}`;
+  }
+}
+async function mineInlineMarkers(root, maxFiles) {
+  const markers = [];
+  try {
+    const { default: fg } = await import("fast-glob");
+    const files = await fg(
+      ["**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,cs,rb,php,c,cpp,h,hpp}"],
+      {
+        cwd: root,
+        ignore: ["node_modules/**", "dist/**", "build/**", ".git/**", ".kuma/**", "coverage/**", "vendor/**"],
+        onlyFiles: true,
+        deep: 8
+      }
+    );
+    for (const file of files.slice(0, maxFiles)) {
+      try {
+        const fullPath = path29.join(root, file);
+        const content = fs28.readFileSync(fullPath, "utf-8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length && markers.length < 100; i++) {
+          const line = lines[i];
+          for (const { tag, regex } of MARKER_PATTERNS) {
+            const m = regex.exec(line);
+            if (m) {
+              const text = (m[1] || m[2] || m[3] || line.trim()).trim().substring(0, 160);
+              markers.push({ filePath: file, line: i + 1, tag, text });
+              break;
+            }
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return markers;
+}
+async function buildFeatureNodes(root) {
+  const names = [];
+  try {
+    const { recordFeature: recordFeature2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+    const pkgPath = path29.join(root, "package.json");
+    if (fs28.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs28.readFileSync(pkgPath, "utf-8"));
+        const candidates = [
+          pkg.main,
+          pkg.module,
+          pkg.bin ? Object.keys(pkg.bin)[0] : null,
+          ...Array.isArray(pkg.exports) ? pkg.exports : []
+        ].filter(Boolean);
+        for (const c of candidates.slice(0, 5)) {
+          const name = path29.basename(c, path29.extname(c)).replace(/[^a-zA-Z0-9]/g, " ").trim();
+          if (name && !names.includes(name)) {
+            await recordFeature2({ name, description: `Detected entry point during legacy onboarding (${c})`, files: [c] });
+            names.push(name);
+          }
+        }
+      } catch {
+      }
+    }
+    const srcDir = path29.join(root, "src");
+    if (fs28.existsSync(srcDir)) {
+      try {
+        const entries = fs28.readdirSync(srcDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).filter((n) => !n.startsWith(".") && !["node_modules", "dist", "build", "__tests__", "test", "tests", "assets", "styles", "types", "utils"].includes(n));
+        for (const dir of entries.slice(0, 15)) {
+          if (!names.includes(dir)) {
+            const files = [path29.join("src", dir)];
+            await recordFeature2({
+              name: dir,
+              description: `Detected top-level module during legacy onboarding`,
+              files,
+              risk: "medium"
+            });
+            names.push(dir);
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return { created: names.length, names };
+}
+function buildArchitectureDigest(root, featureNames) {
+  const lines = [];
+  try {
+    const pkgPath = path29.join(root, "package.json");
+    if (fs28.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs28.readFileSync(pkgPath, "utf-8"));
+      lines.push(`\u{1F3D7}\uFE0F **Stack**: ${[pkg.framework, pkg.orm, pkg.testFramework].filter(Boolean).join(" + ") || "detected"}`);
+    }
+    if (featureNames.length > 0) {
+      lines.push(`\u{1F9E9} **Detected Modules**: ${featureNames.slice(0, 8).join(", ")}`);
+    }
+    lines.push(`\u{1F4C4} **Entry Points**: check package.json main/bin or src/index.*`);
+  } catch {
+  }
+  return lines.join("\n");
+}
+async function runLegacyOnboarding(options = {}) {
+  const root = getProjectRoot();
+  const commitCount = options.commitCount ?? 25;
+  const maxFiles = options.maxFiles ?? 200;
+  const lines = [
+    "\u{1F680} **Kuma Legacy Onboarding**",
+    "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    "",
+    `\u{1F4C1} Project: ${root.split("/").pop() || "unknown"}`,
+    "",
+    "\u23F3 Running bulk analysis \u2014 this may take a few seconds...",
+    ""
+  ];
+  lines.push("### 1\uFE0F\u20E3 Git History Harvest");
+  try {
+    const harvest = await harvestGit(commitCount);
+    lines.push(harvest);
+  } catch (err) {
+    lines.push(`\u26A0\uFE0F ${err}`);
+  }
+  lines.push("");
+  lines.push("### 2\uFE0F\u20E3 Inline Marker Mining (HACK/FIXME/TODO \u2192 gotchas)");
+  try {
+    const markers = await mineInlineMarkers(root, maxFiles);
+    if (markers.length === 0) {
+      lines.push("\u2705 No HACK/FIXME/TODO markers found \u2014 clean codebase.");
+    } else {
+      const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+      let recorded = 0;
+      for (const m of markers.slice(0, 40)) {
+        try {
+          const severity = m.tag === "HACK" || m.tag === "WARNING" ? "high" : m.tag === "FIXME" ? "medium" : "low";
+          await addGotcha2({
+            filePath: m.filePath,
+            description: `[${m.tag}] ${m.text} (line ${m.line})`,
+            severity,
+            workaround: `Legacy marker ${m.tag} at ${m.filePath}:${m.line} \u2014 review before modifying this file.`
+          });
+          recorded++;
+        } catch {
+        }
+      }
+      lines.push(`\u26A0\uFE0F Found ${markers.length} marker(s); recorded ${recorded} as gotchas (capped at 40).`);
+      lines.push(`\u{1F4A1} Remaining ${Math.max(0, markers.length - 40)} \u2014 re-run or use kuma_memory({ action: 'gotcha' }) inline.`);
+    }
+  } catch (err) {
+    lines.push(`\u26A0\uFE0F Marker mining failed: ${err}`);
+  }
+  lines.push("");
+  lines.push("### 3\uFE0F\u20E3 Feature Graph Bootstrap");
+  let featureNames = [];
+  try {
+    const feat = await buildFeatureNodes(root);
+    featureNames = feat.names;
+    lines.push(feat.created > 0 ? `\u{1F9E9} Built ${feat.created} feature node(s): ${feat.names.slice(0, 8).join(", ")}` : "\u2139\uFE0F No obvious top-level features detected \u2014 record manually via kuma_memory({ action: 'feature' }).");
+  } catch (err) {
+    lines.push(`\u26A0\uFE0F Feature bootstrap failed: ${err}`);
+  }
+  lines.push("");
+  lines.push("### 4\uFE0F\u20E3 Architecture Digest");
+  try {
+    const digest = buildArchitectureDigest(root, featureNames);
+    lines.push(digest);
+  } catch {
+  }
+  lines.push("");
+  lines.push("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push("\u2705 **Onboarding complete.** Suggested next steps:");
+  lines.push("  \u2022 `kuma_context({ action: 'digest' })` \u2014 compact briefing");
+  lines.push("  \u2022 `kuma_context({ action: 'research', scope: '<area>' })` \u2014 deep-dive first area");
+  lines.push("  \u2022 `kuma_memory({ action: 'arch_flow', content: 'domain: X | hops: a \u2192 b \u2192 c' })` \u2014 map core flows");
+  lines.push("  \u2022 `kuma_safety({ action: 'heal' })` \u2014 repair any stale graph entries");
+  return lines.join("\n");
+}
+var MARKER_PATTERNS;
+var init_kumaLegacyOnboard = __esm({
+  "src/engine/kumaLegacyOnboard.ts"() {
+    "use strict";
+    init_pathValidator();
+    MARKER_PATTERNS = [
+      { tag: "HACK", regex: /\/\/\s*HACK:?\s*(.*)|#\s*HACK:?\s*(.*)|<!--\s*HACK:?\s*(.*)-->/i },
+      { tag: "FIXME", regex: /\/\/\s*FIXME:?\s*(.*)|#\s*FIXME:?\s*(.*)|<!--\s*FIXME:?\s*(.*)-->/i },
+      { tag: "TODO", regex: /\/\/\s*TODO:?\s*(.*)|#\s*TODO:?\s*(.*)|<!--\s*TODO:?\s*(.*)-->/i },
+      { tag: "WARNING", regex: /\/\/\s*WARNING:?\s*(.*)|#\s*WARNING:?\s*(.*)|<!--\s*WARNING:?\s*(.*)-->/i },
+      { tag: "XXX", regex: /\/\/\s*XXX:?\s*(.*)|#\s*XXX:?\s*(.*)|<!--\s*XXX:?\s*(.*)-->/i }
+    ];
+  }
+});
+
 // src/utils/agentDetector.ts
 var agentDetector_exports = {};
 __export(agentDetector_exports, {
@@ -9814,19 +10633,19 @@ __export(agentDetector_exports, {
   getSkillPath: () => getSkillPath,
   skillExists: () => skillExists
 });
-import fs26 from "fs";
-import path26 from "path";
+import fs29 from "fs";
+import path30 from "path";
 function checkFile(root, filePath) {
   try {
-    return fs26.existsSync(path26.join(root, filePath));
+    return fs29.existsSync(path30.join(root, filePath));
   } catch {
     return false;
   }
 }
 function checkDir(root, dirPath) {
   try {
-    const fullPath = path26.join(root, dirPath);
-    return fs26.existsSync(fullPath) && fs26.statSync(fullPath).isDirectory();
+    const fullPath = path30.join(root, dirPath);
+    return fs29.existsSync(fullPath) && fs29.statSync(fullPath).isDirectory();
   } catch {
     return false;
   }
@@ -9894,7 +10713,7 @@ function getAgentLabel(type) {
 function skillExists(type, projectRoot) {
   const root = projectRoot ?? getProjectRoot();
   const skillPath = getSkillPath(type);
-  return fs26.existsSync(path26.join(root, skillPath));
+  return fs29.existsSync(path30.join(root, skillPath));
 }
 var AGENT_DETECTORS;
 var init_agentDetector = __esm({
@@ -10338,8 +11157,8 @@ init_kumaDb();
 init_kumaGraph();
 init_kumaMemory();
 init_pathValidator();
-import fs11 from "fs";
-import path11 from "path";
+import fs12 from "fs";
+import path13 from "path";
 import crypto4 from "crypto";
 var CONTEXT_ALIASES = {
   // Research synonyms
@@ -10360,6 +11179,11 @@ var CONTEXT_ALIASES = {
   "init": "init",
   "start": "init",
   "load": "init",
+  // Resume synonyms
+  "resume": "resume",
+  "continue": "resume",
+  "restore": "resume",
+  "reload": "resume",
   "brief": "init",
   "project": "init",
   "summary": "init",
@@ -10441,9 +11265,77 @@ async function handleContext(params) {
       return handleDrift(params);
     case "progressive":
       return handleProgressive(params);
+    case "resume":
+      return handleResume(params);
     default:
-      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync, visualize, digest, drift, progressive`;
+      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync, visualize, digest, drift, progressive, resume`;
+  }
+}
+async function handleResume(_params) {
+  sessionMemory.recordToolCall("kuma_context_resume", {});
+  const lines = [
+    "\u{1F504} **Kuma \u2014 Session Resume**",
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    ""
+  ];
+  try {
+    const db = await getDb();
+    const res = db.exec(
+      "SELECT goal, tool_calls, edits, rollbacks, failures, safety_score, started_at FROM sessions ORDER BY started_at DESC LIMIT 1"
+    );
+    if (res[0]?.values.length) {
+      const row = res[0].values[0];
+      const goal = row[0] || "no goal";
+      const calls = row[1] || 0;
+      const edits = row[2] || 0;
+      const rollbacks = row[3] || 0;
+      const failures2 = row[4] || 0;
+      const safety = row[5] == null ? null : row[5];
+      const time = new Date(row[6] * 1e3).toLocaleString();
+      lines.push("**Last Session**");
+      lines.push(`  \u{1F3AF} Goal: ${goal.substring(0, 80)}`);
+      lines.push(`  \u{1F550} ${time}`);
+      lines.push(`  \u{1F527} ${calls} calls \xB7 \u{1F4DD} ${edits} edits \xB7 \u21A9 ${rollbacks} rollbacks \xB7 \u274C ${failures2} failures${safety != null ? ` \xB7 \u{1F6E1} safety ${safety}` : ""}`);
+      lines.push("");
+    }
+  } catch {
+  }
+  const summary = sessionMemory.getSummary();
+  lines.push("**Current State**");
+  lines.push(`  \u{1F3AF} Goal: ${summary.currentGoal || "not set"}`);
+  const progress = sessionMemory.getGoalProgress();
+  if (progress) {
+    lines.push(`  \u{1F4CA} Progress: ${progress.percentage}%${progress.milestone ? ` \u2014 ${progress.milestone}` : ""}`);
+  }
+  lines.push(`  \u{1F4DD} Modified: ${summary.modifiedFiles?.length || 0} file(s)`);
+  lines.push(`  \u2705 Completed steps: ${summary.completedSteps?.length || 0}`);
+  lines.push(`  \u{1F6E0}\uFE0F Tool calls: ${summary.toolCallCount}`);
+  lines.push(`  \u23F1\uFE0F Session duration: ${summary.sessionDuration}`);
+  const failures = summary.unresolvedFailures;
+  if (failures?.length) {
+    lines.push(`  \u26A0\uFE0F Unresolved failures: ${failures.length}`);
+  }
+  lines.push("");
+  try {
+    const changes = await getChanges({ limit: 5 });
+    if (changes && !changes.startsWith("No changes")) {
+      lines.push("**Recent Changes**");
+      lines.push(changes);
+      lines.push("");
+    }
+  } catch {
   }
+  const history = sessionMemory.getToolCallHistory(5);
+  if (history.length) {
+    lines.push("**Recent Tool Calls**");
+    for (const h of history) {
+      const action = h.params?.action || "";
+      lines.push(`  \u{1F6E0} ${h.toolName}${action ? ` (${action})` : ""}`);
+    }
+    lines.push("");
+  }
+  lines.push("\u{1F4A1} Continue: kuma_context({ action: 'research', scope: '<area>' }) to pick up where you left off.");
+  return lines.join("\n");
 }
 async function handleInit(_params) {
   sessionMemory.setGoal(_params.goal || "Exploring project");
@@ -10513,6 +11405,15 @@ async function handleInit(_params) {
     lines.push(formatSafetyScore2(score));
   } catch {
   }
+  try {
+    const { formatPathRules: formatPathRules2 } = await Promise.resolve().then(() => (init_kumaPathRules(), kumaPathRules_exports));
+    const rulesBlock = formatPathRules2(_params.goal);
+    if (rulesBlock) {
+      lines.push("");
+      lines.push(rulesBlock);
+    }
+  } catch {
+  }
   lines.push("", "\u{1F4A1} Call kuma_context({ action: 'research', scope: '<area>' }) to research a specific area.");
   return lines.join("\n");
 }
@@ -10635,6 +11536,15 @@ async function handleResearch(params) {
     lines.push("  \u26A0\uFE0F Memory lookup failed");
   }
   lines.push("");
+  try {
+    const { formatPathRules: formatPathRules2 } = await Promise.resolve().then(() => (init_kumaPathRules(), kumaPathRules_exports));
+    const rulesBlock = formatPathRules2(scope);
+    if (rulesBlock) {
+      lines.push(rulesBlock);
+      lines.push("");
+    }
+  } catch {
+  }
   const newRecord = {
     scope,
     confidence: record?.confidence || 0.7,
@@ -10817,12 +11727,12 @@ async function handleProgressive(params) {
 function computeProjectHash(scope) {
   try {
     const root = getProjectRoot();
-    const files = fs11.readdirSync(root).slice(0, 20);
+    const files = fs12.readdirSync(root).slice(0, 20);
     const hash = crypto4.createHash("md5");
     hash.update(scope);
     for (const f of files) {
       try {
-        const stat = fs11.statSync(path11.join(root, f));
+        const stat = fs12.statSync(path13.join(root, f));
         hash.update(`${f}:${stat.mtimeMs}`);
       } catch {
       }
@@ -10891,8 +11801,8 @@ function getNoiseFilterPolicy() {
 // src/tools/kumaMemoryTool.ts
 init_pathValidator();
 init_pathValidator();
-import fs15 from "fs";
-import path15 from "path";
+import fs16 from "fs";
+import path17 from "path";
 var MEMORY_ALIASES = {
   // Session synonyms
   "session": "session",
@@ -11057,6 +11967,8 @@ async function handleMemory(params) {
       return handleAddNode(params);
     case "feature":
       return handleFeature(params);
+    case "goal_progress":
+      return handleGoalProgress(params);
     case "delete_node":
       return handleDeleteNode(params);
     case "graph_health":
@@ -11068,8 +11980,6 @@ async function handleMemory(params) {
     }
     case "harvest":
       return handleHarvest(params);
-    case "mine":
-      return handleMine(params);
     case "session_mine":
       return handleSessionMine(params);
     case "noise_policy":
@@ -11157,9 +12067,9 @@ async function handleResearchSave(params) {
   } catch {
   }
   try {
-    const researchDir = path15.join(getProjectRoot(), ".kuma", "research");
-    if (!fs15.existsSync(researchDir)) fs15.mkdirSync(researchDir, { recursive: true });
-    fs15.writeFileSync(path15.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
+    const researchDir = path17.join(getProjectRoot(), ".kuma", "research");
+    if (!fs16.existsSync(researchDir)) fs16.mkdirSync(researchDir, { recursive: true });
+    fs16.writeFileSync(path17.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordMemoryAction("research_save");
@@ -11623,13 +12533,22 @@ async function handleFeature(params) {
     tags,
     risk
   });
-  sessionMemory.recordMemoryAction("research_save");
+  sessionMemory.recordMemoryAction("feature");
   return `\u2705 **Feature "${params.title}" recorded** \u2014 ${result.nodeCount} node(s), ${result.edgeCount} edge(s)
 \u2B50 Level: feature
 \u{1F4C1} Files: ${files.length}
 \u{1F3F7}\uFE0F Tags: ${tags.length}
 \u26A0\uFE0F Risk: ${risk}`;
 }
+async function handleGoalProgress(params) {
+  const pct = params.confidence ?? 0;
+  const ms = params.content || params.title;
+  sessionMemory.setGoalProgress(pct, ms);
+  const p = sessionMemory.getGoalProgress();
+  if (!p) return "Error";
+  const bar = "\u2588".repeat(Math.floor(p.percentage / 10)) + "\u2591".repeat(10 - Math.floor(p.percentage / 10));
+  return `\u{1F4CA} ${bar} ${p.percentage}%${p.milestone ? " \u2014 " + p.milestone : ""}`;
+}
 async function handleGraphHealth(_params) {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
   const db = await getDb2();
@@ -11760,72 +12679,72 @@ init_sessionMemory();
 
 // src/engine/kumaLock.ts
 init_pathValidator();
-import fs16 from "fs";
-import path16 from "path";
+import fs17 from "fs";
+import path18 from "path";
 var LOCKS_DIR = ".kuma/locks";
 function locksDir() {
-  return path16.join(getProjectRoot(), LOCKS_DIR);
+  return path18.join(getProjectRoot(), LOCKS_DIR);
 }
 function ensureLocksDir() {
   const dir = locksDir();
-  if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+  if (!fs17.existsSync(dir)) fs17.mkdirSync(dir, { recursive: true });
 }
 function lockPath(filePath) {
   const safeName = filePath.replace(/[^a-zA-Z0-9_./-]/g, "_");
-  return path16.join(locksDir(), `${safeName}.lock.json`);
+  return path18.join(locksDir(), `${safeName}.lock.json`);
 }
 function acquireLock(filePath, agentId) {
   ensureLocksDir();
   const lp = lockPath(filePath);
   const id = agentId || `agent-${process.pid}`;
-  if (fs16.existsSync(lp)) {
+  if (fs17.existsSync(lp)) {
     try {
-      const existing = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+      const existing = JSON.parse(fs17.readFileSync(lp, "utf-8"));
       if (existing.agentId === id) {
         return `\u{1F512} **Already locked** by you (${id}) on ${new Date(existing.acquiredAt).toISOString()}`;
       }
       const elapsed = Math.floor((Date.now() - existing.acquiredAt) / 1e3);
       if (elapsed > 300) {
-        fs16.unlinkSync(lp);
+        fs17.unlinkSync(lp);
       } else {
         return `\u{1F512} **Locked** by ${existing.agentId} since ${new Date(existing.acquiredAt).toISOString()} (${elapsed}s ago)`;
       }
     } catch {
-      fs16.unlinkSync(lp);
+      fs17.unlinkSync(lp);
     }
   }
   const entry = { filePath, agentId: id, acquiredAt: Date.now(), status: "locked" };
-  fs16.writeFileSync(lp, JSON.stringify(entry, null, 2), "utf-8");
+  fs17.writeFileSync(lp, JSON.stringify(entry, null, 2), "utf-8");
   return `\u{1F513} **Lock acquired** on \`${filePath}\` by ${id}`;
 }
 function releaseLock(filePath, agentId) {
   ensureLocksDir();
   const lp = lockPath(filePath);
   const id = agentId || `agent-${process.pid}`;
-  if (!fs16.existsSync(lp)) {
+  if (!fs17.existsSync(lp)) {
     return `\u26A0\uFE0F No lock found for \`${filePath}\``;
   }
   try {
-    const existing = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+    const existing = JSON.parse(fs17.readFileSync(lp, "utf-8"));
     if (existing.agentId !== id) {
       return `\u26A0\uFE0F Cannot release lock held by ${existing.agentId}. Use force:true to override.`;
     }
-    fs16.unlinkSync(lp);
+    fs17.unlinkSync(lp);
     return `\u{1F513} **Lock released** on \`${filePath}\``;
   } catch {
-    fs16.unlinkSync(lp);
+    fs17.unlinkSync(lp);
     return `\u{1F513} **Lock released** (force cleanup) on \`${filePath}\``;
   }
 }
 function listLocks() {
   ensureLocksDir();
   const dir = locksDir();
-  const files = fs16.readdirSync(dir).filter((f) => f.endsWith(".lock.json"));
+  const files = fs17.readdirSync(dir).filter((f) => f.endsWith(".lock.json"));
   if (files.length === 0) return "\u{1F513} No active locks.";
   const lines = ["\u{1F512} **Active Locks:**", ""];
   for (const f of files) {
     try {
-      const entry = JSON.parse(fs16.readFileSync(path16.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs17.readFileSync(path18.join(dir, f), "utf-8"));
       const elapsed = Math.floor((Date.now() - entry.acquiredAt) / 1e3);
       lines.push(`  \u2022 \`${entry.filePath}\` \u2014 locked by ${entry.agentId} (${elapsed}s ago)`);
     } catch {
@@ -11836,9 +12755,9 @@ function listLocks() {
 }
 function isLocked(filePath) {
   const lp = lockPath(filePath);
-  if (!fs16.existsSync(lp)) return { locked: false };
+  if (!fs17.existsSync(lp)) return { locked: false };
   try {
-    const entry = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+    const entry = JSON.parse(fs17.readFileSync(lp, "utf-8"));
     return { locked: true, by: entry.agentId, since: entry.acquiredAt };
   } catch {
     return { locked: false };
@@ -11848,16 +12767,16 @@ function cleanStaleLocks() {
   ensureLocksDir();
   const dir = locksDir();
   let count = 0;
-  for (const f of fs16.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
+  for (const f of fs17.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
     try {
-      const entry = JSON.parse(fs16.readFileSync(path16.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs17.readFileSync(path18.join(dir, f), "utf-8"));
       if (Date.now() - entry.acquiredAt > 3e5) {
-        fs16.unlinkSync(path16.join(dir, f));
+        fs17.unlinkSync(path18.join(dir, f));
         count++;
       }
     } catch {
       try {
-        fs16.unlinkSync(path16.join(dir, f));
+        fs17.unlinkSync(path18.join(dir, f));
         count++;
       } catch {
       }
@@ -11873,8 +12792,8 @@ init_safetyAudit();
 
 // src/tools/kumaPolicy.ts
 init_pathValidator();
-import fs17 from "fs";
-import path17 from "path";
+import fs18 from "fs";
+import path19 from "path";
 var DEFAULT_POLICY = {
   never_touch: [
     ".env",
@@ -11900,15 +12819,15 @@ var DEFAULT_POLICY = {
 };
 function loadPolicy() {
   const root = getProjectRoot();
-  const ymlPath = path17.join(root, ".kuma", "policy.yml");
-  const yamlPath = path17.join(root, ".kuma", "policy.yaml");
+  const ymlPath = path19.join(root, ".kuma", "policy.yml");
+  const yamlPath = path19.join(root, ".kuma", "policy.yaml");
   let policyContent = null;
   let policyPath = null;
-  if (fs17.existsSync(ymlPath)) {
-    policyContent = fs17.readFileSync(ymlPath, "utf-8");
+  if (fs18.existsSync(ymlPath)) {
+    policyContent = fs18.readFileSync(ymlPath, "utf-8");
     policyPath = ymlPath;
-  } else if (fs17.existsSync(yamlPath)) {
-    policyContent = fs17.readFileSync(yamlPath, "utf-8");
+  } else if (fs18.existsSync(yamlPath)) {
+    policyContent = fs18.readFileSync(yamlPath, "utf-8");
     policyPath = yamlPath;
   }
   if (!policyContent) {
@@ -12018,9 +12937,9 @@ function checkFilePathPolicy(filePath, policy) {
   if (policy.max_file_size && policy.max_file_size > 0) {
     try {
       const root = getProjectRoot();
-      const fullPath = path17.join(root, filePath);
-      if (fs17.existsSync(fullPath)) {
-        const sizeKB = fs17.statSync(fullPath).size / 1024;
+      const fullPath = path19.join(root, filePath);
+      if (fs18.existsSync(fullPath)) {
+        const sizeKB = fs18.statSync(fullPath).size / 1024;
         if (sizeKB > policy.max_file_size) {
           violations.push({
             rule: "max_file_size",
@@ -12187,12 +13106,12 @@ async function safetyCheck(action, filePath, command) {
     }
     if (filePath) {
       try {
-        const fs27 = await import("fs");
-        const path27 = await import("path");
+        const fs30 = await import("fs");
+        const path31 = await import("path");
         const root = process.cwd();
-        const fullPath = path27.resolve(root, filePath);
-        if (fs27.existsSync(fullPath)) {
-          const stat = fs27.statSync(fullPath);
+        const fullPath = path31.resolve(root, filePath);
+        if (fs30.existsSync(fullPath)) {
+          const stat = fs30.statSync(fullPath);
           const sizeKB = Math.round(stat.size / 1024);
           if (sizeKB > 500) {
             checks.push({
@@ -12202,12 +13121,12 @@ async function safetyCheck(action, filePath, command) {
             });
           }
           if (filePath.endsWith(".ts") || filePath.endsWith(".js")) {
-            const baseName = path27.basename(filePath, path27.extname(filePath));
+            const baseName = path31.basename(filePath, path31.extname(filePath));
             const testPatterns = [
               filePath.replace(/\.(ts|js)$/, ".test.$1"),
               filePath.replace(/\.(ts|js)$/, ".spec.$1"),
               filePath.replace(/^src\//, "tests/").replace(/\.(ts|js)$/, ".test.$1"),
-              `**/__tests__/**/${baseName}.test.${path27.extname(filePath).slice(1)}`
+              `**/__tests__/**/${baseName}.test.${path31.extname(filePath).slice(1)}`
             ];
             let hasTests = false;
             const fg = await import("fast-glob");
@@ -12223,7 +13142,7 @@ async function safetyCheck(action, filePath, command) {
                 name: "Tests Check",
                 passed: true,
                 // Not a blocker, just informative
-                detail: `\u{1F9EA} No test file found for "${path27.basename(filePath)}" \u2014 consider adding tests`
+                detail: `\u{1F9EA} No test file found for "${path31.basename(filePath)}" \u2014 consider adding tests`
               });
             } else {
               checks.push({
@@ -12312,8 +13231,8 @@ init_sessionMemory();
 // src/guards/antiPatternDetector.ts
 init_pathValidator();
 init_sessionMemory();
-import fs18 from "fs";
-import path18 from "path";
+import fs19 from "fs";
+import path20 from "path";
 import { execSync as execSync6 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
@@ -12340,20 +13259,20 @@ function findPatchScripts(projectRoot) {
   const warnings = [];
   const recentFiles = scanRecentFiles(projectRoot);
   for (const file of recentFiles) {
-    const ext = path18.extname(file).toLowerCase();
+    const ext = path20.extname(file).toLowerCase();
     if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
-    const relativePath = path18.relative(projectRoot, file);
+    const relativePath = path20.relative(projectRoot, file);
     if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".") || relativePath.startsWith(".kuma/scratch")) {
       continue;
     }
     try {
-      const content = fs18.readFileSync(file, "utf-8").toLowerCase();
+      const content = fs19.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: ${path18.basename(file)}`,
+          message: `Created script file that modifies other files: ${path20.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
@@ -12387,15 +13306,15 @@ function detectBashGrepUsage() {
 function scanRecentFiles(projectRoot) {
   const recent = [];
   try {
-    const entries = fs18.readdirSync(projectRoot, { withFileTypes: true });
+    const entries = fs19.readdirSync(projectRoot, { withFileTypes: true });
     const now = Date.now();
     const recentThreshold = 30 * 60 * 1e3;
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       try {
-        const stat = fs18.statSync(path18.join(projectRoot, entry.name));
+        const stat = fs19.statSync(path20.join(projectRoot, entry.name));
         if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
-          recent.push(path18.join(projectRoot, entry.name));
+          recent.push(path20.join(projectRoot, entry.name));
         }
       } catch {
         continue;
@@ -12419,14 +13338,14 @@ function detectGitPatchScripts(projectRoot) {
         const prefix = line.substring(0, 2);
         if (prefix !== "??" && prefix !== "A ") continue;
         const file = line.substring(3).trim();
-        const ext = path18.extname(file).toLowerCase();
+        const ext = path20.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 = path18.join(projectRoot, file);
-        if (fs18.existsSync(fullPath)) {
-          const content = fs18.readFileSync(fullPath, "utf-8").toLowerCase();
+        const fullPath = path20.join(projectRoot, file);
+        if (fs19.existsSync(fullPath)) {
+          const content = fs19.readFileSync(fullPath, "utf-8").toLowerCase();
           const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
           if (matchedPattern) {
             warnings.push({
@@ -12449,7 +13368,7 @@ function detectGitPatchScripts(projectRoot) {
     if (deletedStdout) {
       const deletedFiles = deletedStdout.split("\n").filter(Boolean);
       for (const file of deletedFiles) {
-        const ext = path18.extname(file).toLowerCase();
+        const ext = path20.extname(file).toLowerCase();
         if (SCRIPT_EXTENSIONS.includes(ext)) {
           warnings.push({
             severity: "high",
@@ -12511,21 +13430,21 @@ function detectAllAntiPatterns() {
 // src/engine/contextSnapshot.ts
 init_sessionMemory();
 init_pathValidator();
-import fs19 from "fs";
-import path19 from "path";
+import fs20 from "fs";
+import path21 from "path";
 import { execSync as execSync7 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
-  return path19.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+  return path21.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
 }
 function ensureSnapshotDir() {
   const dir = snapshotDir();
-  if (!fs19.existsSync(dir)) {
-    fs19.mkdirSync(dir, { recursive: true });
+  if (!fs20.existsSync(dir)) {
+    fs20.mkdirSync(dir, { recursive: true });
   }
 }
 function snapshotFilePath(timestamp) {
-  return path19.join(snapshotDir(), `${timestamp}.json`);
+  return path21.join(snapshotDir(), `${timestamp}.json`);
 }
 function saveSnapshot(goal) {
   try {
@@ -12546,7 +13465,7 @@ function saveSnapshot(goal) {
     hasConventions: !!summary.hasConventions
   };
   try {
-    fs19.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
+    fs20.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordToolCall("kuma_context", { action: "save", goal: snapshot.goal });
@@ -12693,6 +13612,14 @@ async function handleKumaGuard(params) {
         suggestion: "After tracing a flow, record it:\nkuma_memory({ action: 'arch_flow', content: 'domain: <Name> | hops: <file1> \u2192 <file2> \u2192 <file3>' })"
       });
     }
+    if (readCalls >= 5 && recordingSummary.features === 0) {
+      warnings.push({
+        severity: "low",
+        pattern: "explore-without-feature",
+        message: `${readCalls} file reads but 0 features recorded. High-level module understanding helps future sessions.`,
+        suggestion: "After exploring a module/feature, record it:\nkuma_memory({ action: 'feature', title: '<FeatureName>', content: 'description', scope: 'file1.ts,file2.ts' })"
+      });
+    }
   }
   if (check === "context") {
     const snapshot = saveSnapshot(stats.goal);
@@ -12859,12 +13786,12 @@ async function handleSecurity(params) {
   sessionMemory.recordToolCall("kuma_safety_security", {});
   if (params.filePath) {
     try {
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs30 = await import("fs");
+      const path31 = await import("path");
       const root = process.cwd();
-      const fullPath = path27.resolve(root, params.filePath);
-      if (fs27.existsSync(fullPath) && fs27.statSync(fullPath).isFile()) {
-        const content = fs27.readFileSync(fullPath, "utf-8");
+      const fullPath = path31.resolve(root, params.filePath);
+      if (fs30.existsSync(fullPath) && fs30.statSync(fullPath).isFile()) {
+        const content = fs30.readFileSync(fullPath, "utf-8");
         const lines = content.split("\n");
         const findings = [];
         for (let i = 0; i < lines.length; i++) {
@@ -12918,23 +13845,23 @@ async function handleGitignore(_params) {
 }
 async function handleClean(_params) {
   sessionMemory.recordToolCall("kuma_safety_clean", {});
-  const fs27 = await import("fs");
-  const path27 = await import("path");
+  const fs30 = await import("fs");
+  const path31 = await import("path");
   const root = process.cwd();
-  const scratchDir = path27.resolve(root, ".kuma", "scratch");
+  const scratchDir = path31.resolve(root, ".kuma", "scratch");
   let removed = 0;
-  if (fs27.existsSync(scratchDir)) {
+  if (fs30.existsSync(scratchDir)) {
     try {
-      const entries = fs27.readdirSync(scratchDir);
+      const entries = fs30.readdirSync(scratchDir);
       for (const entry of entries) {
-        const fullPath = path27.join(scratchDir, entry);
+        const fullPath = path31.join(scratchDir, entry);
         try {
-          const stat = fs27.statSync(fullPath);
+          const stat = fs30.statSync(fullPath);
           if (stat.isFile()) {
-            fs27.unlinkSync(fullPath);
+            fs30.unlinkSync(fullPath);
             removed++;
           } else if (stat.isDirectory()) {
-            fs27.rmSync(fullPath, { recursive: true, force: true });
+            fs30.rmSync(fullPath, { recursive: true, force: true });
             removed++;
           }
         } catch {
@@ -13050,7 +13977,7 @@ async function handleVerify(params) {
   } else if (recordingSummary.total > 0) {
     recordingWarning = `
 
-\u2705 **Recordings:** ${recordingSummary.total} total (${recordingSummary.archFlows} arch_flow, ${recordingSummary.gotchas} gotcha, ${recordingSummary.decisions} decision, ${recordingSummary.researchSaves} research_save)`;
+\u2705 **Recordings:** ${recordingSummary.total} total (${recordingSummary.archFlows} arch_flow, ${recordingSummary.gotchas} gotcha, ${recordingSummary.decisions} decision, ${recordingSummary.researchSaves} research_save, ${recordingSummary.features} feature)`;
   }
   sessionMemory.recordToolCall("kuma_safety_verify", { scope: params.scope || params.filePath });
   const { runAutoVerification: runAutoVerification2 } = await Promise.resolve().then(() => (init_kumaVerifier(), kumaVerifier_exports));
@@ -13131,7 +14058,7 @@ function registerAllTools(server) {
     "kuma_context",
     "**Call FIRST every session.** Understand your project before making changes.\n\nWORKFLOW:\n\u2022 STEP 1 (ALWAYS): `init` \u2014 load project brief, restore session\n\u2022 STEP 3 (BEFORE edits): `research` \u2014 5-step pipeline (cache\u2192staleness\u2192graph\u2192impact\u2192decision)\n\u2022 STEP 8 (END of session): `changes` \u2014 review what you modified\n\nOther actions: impact (analyze changes), navigate (trace flow), health (score 0-100), digest (compact briefing), drift (detect staleness).",
     {
-      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize", "digest", "drift", "progressive"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, digest=ultra-compact <500 token project briefing (Issue #18), drift=detect memory staleness & code drift (Issue #20), progressive=progressive context loading (Issue #25), health=project health score"),
+      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize", "digest", "drift", "progressive", "resume"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, digest=ultra-compact <500 token project briefing (Issue #18), drift=detect memory staleness & code drift (Issue #20), progressive=progressive context loading (Issue #25), health=project health score, resume=load previous session context (goal, progress, changes)"),
       scope: z.string().optional().describe("Research scope for research/progressive action"),
       target: z.string().optional().describe("Target symbol/file for impact/navigate/changes"),
       goal: z.string().optional().describe("Current goal (for init/health)"),
@@ -13159,9 +14086,9 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 AFTER tracing COMPLETE flow (max 5 core files).\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, heal, search, changes, benchmark, layers.",
+    "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 AFTER tracing COMPLETE flow (max 5 core files).\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\u2022 STEP 9: `feature` \u2014 WHEN identifying a high-level feature/module (e.g. Auth, Billing). Creates owns edges to files.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, heal, search, changes, benchmark, layers.",
     {
-      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "add_node", "delete_node", "clear", "feature"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), session=summary, heal=repair, search=search (now with task retrieval + impact analysis), changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules, arch_flow=Layer 2 architecture flow (now auto-creates affects edges), gotcha=Layer 3 known gotchas, layers=all 3 layers summary, add_node=manually create function/class/component structural nodes, delete_node=delete a specific node/gotcha/todo/decision by ID or scope+target, clear=wipe all nodes/edges/gotchas, feature=record high-level feature with owns edges to files"),
+      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "add_node", "delete_node", "clear", "feature", "goal_progress"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), session=summary, heal=repair, search=search (now with task retrieval + impact analysis), changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules, arch_flow=Layer 2 architecture flow (now auto-creates affects edges), gotcha=Layer 3 known gotchas, layers=all 3 layers summary, add_node=manually create function/class/component structural nodes, delete_node=delete a specific node/gotcha/todo/decision by ID or scope+target, clear=wipe all nodes/edges/gotchas, feature=record high-level feature with owns edges to files, goal_progress=update goal completion percentage"),
       scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine"),
       query: z.string().optional().describe("Search query for search action"),
       content: z.string().optional().describe("Content/notes for research_save / context"),
@@ -13309,6 +14236,7 @@ Usage:
   npx @plumpslabs/kuma init --skip-existing Skip generation if file exists
   npx @plumpslabs/kuma init --claude --cursor  Generate specific files
   npx @plumpslabs/kuma studio        Start Kuma Studio web dashboard (knowledge graph visualizer)
+  npx @plumpslabs/kuma init --legacy  Bulk-onboard an existing (legacy) codebase
   npx @plumpslabs/kuma init --help  Show this help
 
 Available config files:
@@ -13331,6 +14259,14 @@ If no flags specified, you'll be prompted to select files interactively.
 }
 async function main() {
   const args = process.argv.slice(2);
+  if (args[0] === "--version" || args[0] === "-v" || args[0] === "version") {
+    console.log(`\u{1F43B} Kuma v${SERVER_VERSION}`);
+    process.exit(0);
+  }
+  if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    printHelp();
+    process.exit(0);
+  }
   if (args[0] === "stop" && (args[1] === "--force" || args[1] === "-f")) {
     console.error(`\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Kill Switch`);
     console.error("");
@@ -13353,14 +14289,14 @@ async function main() {
     } catch {
     }
     try {
-      const path27 = await import("path");
-      const fs27 = await import("fs");
-      const lockDir = path27.resolve(process.cwd(), ".kuma/verifier.lock");
-      if (fs27.existsSync(lockDir)) {
-        const pidFile = path27.join(lockDir, "pid");
-        if (fs27.existsSync(pidFile)) {
+      const path31 = await import("path");
+      const fs30 = await import("fs");
+      const lockDir = path31.resolve(process.cwd(), ".kuma/verifier.lock");
+      if (fs30.existsSync(lockDir)) {
+        const pidFile = path31.join(lockDir, "pid");
+        if (fs30.existsSync(pidFile)) {
           try {
-            const pid = parseInt(fs27.readFileSync(pidFile, "utf-8"), 10);
+            const pid = parseInt(fs30.readFileSync(pidFile, "utf-8"), 10);
             if (pid && pid !== process.pid) {
               try {
                 process.kill(-pid, "SIGKILL");
@@ -13376,7 +14312,7 @@ async function main() {
           } catch {
           }
         }
-        fs27.rmSync(lockDir, { recursive: true, force: true });
+        fs30.rmSync(lockDir, { recursive: true, force: true });
       }
       if (killedCount === 0) {
         console.error("\u2705 No running verifications found to kill.");
@@ -13470,6 +14406,18 @@ async function main() {
       printHelp();
       process.exit(0);
     }
+    if (flags.includes("--legacy")) {
+      try {
+        const { runLegacyOnboarding: runLegacyOnboarding2 } = await Promise.resolve().then(() => (init_kumaLegacyOnboard(), kumaLegacyOnboard_exports));
+        console.error("\u{1F43B} Kuma Legacy Onboarding \u2014 making your existing codebase agent-ready...");
+        const report = await runLegacyOnboarding2();
+        console.log(report);
+      } catch (err) {
+        console.error(`\u274C Legacy onboarding failed: ${err}`);
+        process.exit(1);
+      }
+      process.exit(0);
+    }
     const requestedFlags = flags.filter((f) => f.startsWith("--"));
     let selectedTypes;
     if (requestedFlags.length === 0) {
@@ -13524,23 +14472,23 @@ async function main() {
     });
     const output = formatInitResults(results);
     console.log(output);
-    const fs27 = await import("fs");
-    const path27 = await import("path");
-    const matchaSkills = path27.resolve(process.cwd(), "skills/matcha/SKILL.md");
-    const matchaAgents = path27.resolve(
+    const fs30 = await import("fs");
+    const path31 = await import("path");
+    const matchaSkills = path31.resolve(process.cwd(), "skills/matcha/SKILL.md");
+    const matchaAgents = path31.resolve(
       process.cwd(),
       ".agents/skills/matcha/SKILL.md"
     );
-    const matchaRootSkills = path27.resolve(
+    const matchaRootSkills = path31.resolve(
       process.cwd(),
       "skills/matcha/SKILL.md"
     );
-    const matchaAgentsMd = path27.resolve(process.cwd(), "AGENTS.md");
-    const matchaWindsurfRules = path27.resolve(
+    const matchaAgentsMd = path31.resolve(process.cwd(), "AGENTS.md");
+    const matchaWindsurfRules = path31.resolve(
       process.cwd(),
       ".windsurf"
     );
-    if (fs27.existsSync(matchaSkills) || fs27.existsSync(matchaAgents) || fs27.existsSync(matchaRootSkills) || fs27.existsSync(matchaAgentsMd) || fs27.existsSync(matchaWindsurfRules)) {
+    if (fs30.existsSync(matchaSkills) || fs30.existsSync(matchaAgents) || fs30.existsSync(matchaRootSkills) || fs30.existsSync(matchaAgentsMd) || fs30.existsSync(matchaWindsurfRules)) {
       console.error(
         "\n\u{1F375} Hey, I see matcha is installed \u2014 they pair well together!"
       );
@@ -13554,13 +14502,13 @@ async function main() {
   (async () => {
     try {
       const { generateInitMdContent: generateInitMdContent2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      const fs27 = await import("fs");
-      const path27 = await import("path");
-      const initMdPath = path27.resolve(process.cwd(), ".kuma/init.md");
-      if (!fs27.existsSync(initMdPath)) {
-        const kumaDir = path27.dirname(initMdPath);
-        if (!fs27.existsSync(kumaDir)) fs27.mkdirSync(kumaDir, { recursive: true });
-        fs27.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
+      const fs30 = await import("fs");
+      const path31 = await import("path");
+      const initMdPath = path31.resolve(process.cwd(), ".kuma/init.md");
+      if (!fs30.existsSync(initMdPath)) {
+        const kumaDir = path31.dirname(initMdPath);
+        if (!fs30.existsSync(kumaDir)) fs30.mkdirSync(kumaDir, { recursive: true });
+        fs30.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
         console.error(`[${SERVER_NAME}] Auto-generated .kuma/init.md`);
       }
     } catch (err) {
@@ -13571,8 +14519,8 @@ async function main() {
     try {
       const { detectAgent: detectAgent2, getSkillPath: getSkillPath2, getAgentLabel: getAgentLabel2 } = await Promise.resolve().then(() => (init_agentDetector(), agentDetector_exports));
       const { generateSkill: generateSkill2, getSecondaryFiles: getSecondaryFiles2 } = await Promise.resolve().then(() => (init_skillGenerator(), skillGenerator_exports));
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs30 = await import("fs");
+      const path31 = await import("path");
       const detection = detectAgent2();
       if (!detection.primary) {
         console.error(`[${SERVER_NAME}] No AI agent detected \u2014 skipping auto-skill creation`);
@@ -13580,22 +14528,22 @@ async function main() {
       }
       const agentType = detection.primary;
       const skillPath = getSkillPath2(agentType);
-      const fullPath = path27.resolve(process.cwd(), skillPath);
-      if (fs27.existsSync(fullPath)) {
+      const fullPath = path31.resolve(process.cwd(), skillPath);
+      if (fs30.existsSync(fullPath)) {
         console.error(`[${SERVER_NAME}] Skill exists for ${getAgentLabel2(agentType)} \u2014 skipping`);
         return;
       }
-      const dir = path27.dirname(fullPath);
-      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
-      fs27.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
+      const dir = path31.dirname(fullPath);
+      if (!fs30.existsSync(dir)) fs30.mkdirSync(dir, { recursive: true });
+      fs30.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
       console.error(`[${SERVER_NAME}] Auto-created ${skillPath} for ${getAgentLabel2(agentType)}`);
       const secondaryFiles = getSecondaryFiles2(agentType);
       for (const sf of secondaryFiles) {
-        const sfPath = path27.resolve(process.cwd(), sf.path);
-        const sfDir = path27.dirname(sfPath);
-        if (!fs27.existsSync(sfPath)) {
-          if (!fs27.existsSync(sfDir)) fs27.mkdirSync(sfDir, { recursive: true });
-          fs27.writeFileSync(sfPath, sf.content, "utf-8");
+        const sfPath = path31.resolve(process.cwd(), sf.path);
+        const sfDir = path31.dirname(sfPath);
+        if (!fs30.existsSync(sfPath)) {
+          if (!fs30.existsSync(sfDir)) fs30.mkdirSync(sfDir, { recursive: true });
+          fs30.writeFileSync(sfPath, sf.content, "utf-8");
           console.error(`[${SERVER_NAME}] Auto-created ${sf.path}`);
         }
       }
@@ -13620,11 +14568,11 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Graph auto-population: ${err}`);
       }
       try {
-        const fs27 = await import("fs");
-        const path27 = await import("path");
-        const scratchDir = path27.resolve(process.cwd(), ".kuma", "scratch");
-        if (!fs27.existsSync(scratchDir)) {
-          fs27.mkdirSync(scratchDir, { recursive: true });
+        const fs30 = await import("fs");
+        const path31 = await import("path");
+        const scratchDir = path31.resolve(process.cwd(), ".kuma", "scratch");
+        if (!fs30.existsSync(scratchDir)) {
+          fs30.mkdirSync(scratchDir, { recursive: true });
           console.error(`[${SERVER_NAME}] \u2705 Created .kuma/scratch/ for temporary debug artifacts`);
         }
       } catch (err) {