@plumpslabs/kuma 2.3.27 → 2.3.29

package/dist/index.js

@@ -1181,8 +1181,8 @@ async function runDoctor() {
     } catch {
     }
     try {
-      const { execSync: execSync7 } = await import("child_process");
-      const psOutput = execSync7(
+      const { execSync: execSync8 } = await import("child_process");
+      const psOutput = execSync8(
         `ps -eo pid,ppid,command | grep -E "(jest|pnpm test|npm test|yarn test)" | grep -v grep | head -10`,
         { encoding: "utf-8", timeout: 5e3 }
       ).trim();
@@ -3169,27 +3169,27 @@ async function codebaseSearchFallback(query, limit = 20) {
         if (results.length >= limit || depth > MAX_WALK_DEPTH) return;
         let entries = [];
         try {
-          entries = fs26.readdirSync(dir);
+          entries = fs27.readdirSync(dir);
         } catch {
           return;
         }
         for (const entry of entries) {
           if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === "build") continue;
-          const full = path26.join(dir, entry);
+          const full = path27.join(dir, entry);
           try {
-            const stat = fs26.statSync(full);
+            const stat = fs27.statSync(full);
             if (stat.isDirectory()) {
               walk2(full, depth + 1);
             } else if (entry.toLowerCase().includes(query.toLowerCase())) {
-              results.push(path26.relative(root, full));
+              results.push(path27.relative(root, full));
             }
           } catch {
           }
         }
       };
       var walk = walk2;
-      const fs26 = await import("fs");
-      const path26 = await import("path");
+      const fs27 = await import("fs");
+      const path27 = await import("path");
       const root = process.cwd();
       const results = [];
       const MAX_WALK_DEPTH = 8;
@@ -3329,9 +3329,9 @@ async function analyzeImpact(target) {
 }
 async function codebaseImpactFallback(target) {
   try {
-    const { execSync: execSync7 } = await import("child_process");
+    const { execSync: execSync8 } = await import("child_process");
     const root = process.cwd();
-    const grepResult = execSync7(
+    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`,
       { cwd: root, encoding: "utf-8", timeout: 5e3, maxBuffer: 256 * 1024 }
     ).trim();
@@ -5782,8 +5782,11 @@ var init_kumaProgressiveContext = __esm({
 // src/engine/kumaSearch.ts
 var kumaSearch_exports = {};
 __export(kumaSearch_exports, {
+  buildGraphConnectivity: () => buildGraphConnectivity,
   buildSearchVectors: () => buildSearchVectors,
+  clearConnectivityCache: () => clearConnectivityCache,
   clearSearchCache: () => clearSearchCache,
+  enhancedHybridSearch: () => enhancedHybridSearch,
   expandQueryTerms: () => expandQueryTerms,
   formatHybridResults: () => formatHybridResults,
   hybridSearch: () => hybridSearch
@@ -6050,10 +6053,63 @@ function formatHybridResults(query, results) {
   lines.push("Hybrid search combines keyword matching with semantic synonym expansion.");
   return lines.join("\n");
 }
+async function buildGraphConnectivity() {
+  if (_connectivityCache) return _connectivityCache;
+  const nodeEdges = /* @__PURE__ */ new Map();
+  let totalEdges = 0;
+  try {
+    const db = await getDb();
+    const stmt = db.prepare("SELECT source_id, target_id FROM edges LIMIT 2000");
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const src = row.source_id || "";
+      const tgt = row.target_id || "";
+      if (src) nodeEdges.set(src, (nodeEdges.get(src) || 0) + 1);
+      if (tgt) nodeEdges.set(tgt, (nodeEdges.get(tgt) || 0) + 1);
+      totalEdges++;
+    }
+    stmt.free();
+  } catch {
+  }
+  _connectivityCache = { nodeEdges, totalEdges };
+  setTimeout(() => {
+    _connectivityCache = null;
+  }, CONNECTIVITY_CACHE_TTL);
+  return _connectivityCache;
+}
+function connectivityScore(nodeId2, connectivity) {
+  if (connectivity.totalEdges === 0) return 0;
+  const edges = connectivity.nodeEdges.get(nodeId2) || 0;
+  return Math.min(1, Math.log(1 + edges) / Math.log(1 + 20));
+}
+function clearConnectivityCache() {
+  _connectivityCache = null;
+}
+async function enhancedHybridSearch(query, limit = 10) {
+  const basicResults = await hybridSearch(query, limit * 2);
+  const connectivity = await buildGraphConnectivity();
+  for (const result of basicResults) {
+    try {
+      const db = await getDb();
+      const stmt = db.prepare("SELECT id FROM nodes WHERE name LIKE ? LIMIT 1");
+      stmt.bind([`%${result.source}%`]);
+      if (stmt.step()) {
+        const row = stmt.getAsObject();
+        const nodeId2 = row.id || "";
+        const connScore = connectivityScore(nodeId2, connectivity);
+        result.score = Math.min(100, Math.round(result.score * 0.6 + connScore * 40));
+      }
+      stmt.free();
+    } catch {
+    }
+  }
+  return basicResults.sort((a, b) => b.score - a.score).slice(0, limit);
+}
 function clearSearchCache() {
   _vectorCache = null;
+  clearConnectivityCache();
 }
-var SYNONYM_MAP, _vectorCache, VECTOR_CACHE_TTL;
+var SYNONYM_MAP, _vectorCache, VECTOR_CACHE_TTL, _connectivityCache, CONNECTIVITY_CACHE_TTL;
 var init_kumaSearch = __esm({
   "src/engine/kumaSearch.ts"() {
     "use strict";
@@ -6100,6 +6156,8 @@ var init_kumaSearch = __esm({
     };
     _vectorCache = null;
     VECTOR_CACHE_TTL = 3e5;
+    _connectivityCache = null;
+    CONNECTIVITY_CACHE_TTL = 3e5;
   }
 });
 
@@ -6441,6 +6499,236 @@ var init_kumaGotchas = __esm({
   }
 });
 
+// src/engine/kumaGitHarvester.ts
+var kumaGitHarvester_exports = {};
+__export(kumaGitHarvester_exports, {
+  detectSignificantCommits: () => detectSignificantCommits,
+  getRecentCommits: () => getRecentCommits,
+  harvestGitHistory: () => harvestGitHistory,
+  installGitHook: () => installGitHook
+});
+import { execSync as execSync5 } from "child_process";
+import fs14 from "fs";
+import path14 from "path";
+function getRecentCommits(count = 5) {
+  const root = getProjectRoot();
+  try {
+    const format = JSON.stringify({
+      hash: "%H",
+      message: "%s",
+      author: "%an",
+      date: "%ai"
+    });
+    const log = execSync5(
+      `git log -n ${count} --pretty=format:'${format.replace(/'/g, "'\\''")}' --name-only`,
+      { cwd: root, encoding: "utf-8", timeout: 5e3 }
+    );
+    const commits = [];
+    const entries = log.split("\n\n").filter(Boolean);
+    for (const entry of entries) {
+      const lines = entry.split("\n");
+      if (lines.length < 1) continue;
+      try {
+        const meta = JSON.parse(lines[0]);
+        const files = lines.slice(1).filter((f) => f.trim() && !f.startsWith("commit "));
+        let insertions = 0;
+        let deletions = 0;
+        try {
+          const stats = execSync5(
+            `git diff --shortstat ${meta.hash}^..${meta.hash}`,
+            { cwd: root, encoding: "utf-8", timeout: 3e3 }
+          );
+          const insMatch = stats.match(/(\d+) insertion/);
+          const delMatch = stats.match(/(\d+) deletion/);
+          if (insMatch) insertions = parseInt(insMatch[1], 10);
+          if (delMatch) deletions = parseInt(delMatch[1], 10);
+        } catch {
+        }
+        commits.push({
+          hash: meta.hash?.substring(0, 8) || "",
+          message: meta.message || "",
+          author: meta.author || "",
+          date: meta.date || "",
+          files,
+          insertions,
+          deletions
+        });
+      } catch {
+      }
+    }
+    return commits;
+  } catch {
+    return [];
+  }
+}
+function detectSignificantCommits(commits) {
+  const decisionKeywords = [
+    "refactor",
+    "migrate",
+    "switch to",
+    "replace",
+    "use .* instead",
+    "remove",
+    "drop",
+    "deprecate",
+    "upgrade",
+    "update to",
+    "architect",
+    "design",
+    "implement",
+    "add feature"
+  ];
+  const gotchaKeywords = [
+    "fix",
+    "bug",
+    "hotfix",
+    "patch",
+    "workaround",
+    "revert",
+    "broken",
+    "issue",
+    "error",
+    "crash",
+    "race condition",
+    "memory leak",
+    "performance"
+  ];
+  const decisions = [];
+  const gotchas = [];
+  const regular = [];
+  for (const commit of commits) {
+    const msg = commit.message.toLowerCase();
+    const isLargeChange = commit.files.length > 3 || commit.insertions + commit.deletions > 100;
+    const isDecision = decisionKeywords.some((kw) => new RegExp(kw, "i").test(msg)) || isLargeChange;
+    const isGotcha = gotchaKeywords.some((kw) => new RegExp(kw, "i").test(msg));
+    if (isDecision && !isGotcha) {
+      decisions.push(commit);
+    } else if (isGotcha) {
+      gotchas.push(commit);
+    } else {
+      regular.push(commit);
+    }
+  }
+  return { decisions, gotchas, regular };
+}
+async function harvestGitHistory(options) {
+  const count = options?.commitCount || 10;
+  const dryRun = options?.dryRun || false;
+  const commits = getRecentCommits(count);
+  if (commits.length === 0) {
+    return "\u{1F4ED} No git commits found. Is this a git repository?";
+  }
+  const { decisions, gotchas } = detectSignificantCommits(commits);
+  const lines = [
+    "\u{1F419} **Git Auto-Harvester**",
+    "\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{1F4CA} Scanned ${commits.length} commit(s)`,
+    `\u2696\uFE0F ${decisions.length} significant change(s) \u2192 decisions`,
+    `\u26A0\uFE0F ${gotchas.length} fix/revert(s) \u2192 gotchas`,
+    ""
+  ];
+  if (dryRun) {
+    lines.push("**Dry Run \u2014 no nodes created:**");
+    lines.push("");
+    if (decisions.length > 0) {
+      lines.push("**Potential Decisions:**");
+      for (const c of decisions) {
+        lines.push(`  \u2696\uFE0F ${c.hash} \u2014 ${c.message}`);
+        lines.push(`     Files: ${c.files.length}, +${c.insertions}/-${c.deletions}`);
+      }
+      lines.push("");
+    }
+    if (gotchas.length > 0) {
+      lines.push("**Potential Gotchas:**");
+      for (const c of gotchas) {
+        lines.push(`  \u26A0\uFE0F ${c.hash} \u2014 ${c.message}`);
+        lines.push(`     Files: ${c.files.join(", ")}`);
+      }
+      lines.push("");
+    }
+    lines.push("\u{1F4A1} Run without dryRun to create nodes.");
+    return lines.join("\n");
+  }
+  let decisionCount = 0;
+  for (const commit of decisions) {
+    try {
+      const { recordDecision: recordDecision2 } = await Promise.resolve().then(() => (init_kumaMemory(), kumaMemory_exports));
+      await recordDecision2({
+        title: commit.message,
+        context: `Auto-harvested from git commit ${commit.hash}`,
+        options: [],
+        rationale: `Files changed: ${commit.files.slice(0, 5).join(", ")}${commit.files.length > 5 ? ` +${commit.files.length - 5} more` : ""}`,
+        outcome: "implemented",
+        timestamp: new Date(commit.date).toISOString()
+      });
+      decisionCount++;
+    } catch {
+    }
+  }
+  let gotchaCount = 0;
+  for (const commit of gotchas) {
+    try {
+      const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+      const primaryFile = commit.files[0] || "unknown";
+      await addGotcha2({
+        filePath: primaryFile,
+        description: `Git commit ${commit.hash}: ${commit.message}`,
+        severity: commit.message.toLowerCase().includes("revert") ? "high" : "medium",
+        workaround: `See commit ${commit.hash} for details`
+      });
+      gotchaCount++;
+    } catch {
+    }
+  }
+  lines.push(`\u2705 Harvested: ${decisionCount} decision(s), ${gotchaCount} gotcha(s)`);
+  if (decisionCount + gotchaCount === 0) {
+    lines.push("\u{1F4ED} No significant commits to harvest.");
+  }
+  return lines.join("\n");
+}
+function installGitHook() {
+  const root = getProjectRoot();
+  const hooksDir = path14.join(root, ".git", "hooks");
+  if (!fs14.existsSync(hooksDir)) {
+    return "\u26A0\uFE0F Not a git repository \u2014 no .git/hooks/ directory found.";
+  }
+  const hookPath = path14.join(hooksDir, "post-commit");
+  const hookContent = `#!/bin/bash
+# Kuma auto-harvester hook (post-commit)
+# Automatically extracts decisions and gotchas from commits
+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 (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");
+    try {
+      fs14.chmodSync(hookPath, 493);
+    } catch {
+    }
+    return `\u2705 Installed kuma post-commit hook (existing hook backed up to ${path14.basename(backupPath)})`;
+  }
+  fs14.writeFileSync(hookPath, hookContent, "utf-8");
+  try {
+    fs14.chmodSync(hookPath, 493);
+  } catch {
+  }
+  return "\u2705 Installed kuma post-commit hook.";
+}
+var init_kumaGitHarvester = __esm({
+  "src/engine/kumaGitHarvester.ts"() {
+    "use strict";
+    init_pathValidator();
+  }
+});
+
 // src/engine/safetyAudit.ts
 var safetyAudit_exports = {};
 __export(safetyAudit_exports, {
@@ -6610,19 +6898,19 @@ __export(kumaPolicyEngine_exports, {
   processOverride: () => processOverride,
   savePolicyConfig: () => savePolicyConfig
 });
-import fs19 from "fs";
-import path19 from "path";
+import fs20 from "fs";
+import path20 from "path";
 function loadPolicyConfig() {
   try {
     const root = getProjectRoot();
-    const policyPath = path19.join(root, ".kuma", "POLICY.json");
-    if (fs19.existsSync(policyPath)) {
-      const content = fs19.readFileSync(policyPath, "utf-8");
+    const policyPath = path20.join(root, ".kuma", "POLICY.json");
+    if (fs20.existsSync(policyPath)) {
+      const content = fs20.readFileSync(policyPath, "utf-8");
       const config = JSON.parse(content);
       return { ...DEFAULT_POLICY_CONFIG, ...config };
     }
-    const ymlPath = path19.join(root, ".kuma", "policy.yml");
-    if (fs19.existsSync(ymlPath)) {
+    const ymlPath = path20.join(root, ".kuma", "policy.yml");
+    if (fs20.existsSync(ymlPath)) {
       console.error("[PolicyEngine] Found legacy policy.yml \u2014 consider migrating to POLICY.json");
     }
   } catch (err) {
@@ -6633,10 +6921,10 @@ function loadPolicyConfig() {
 function savePolicyConfig(config) {
   try {
     const root = getProjectRoot();
-    const policyPath = path19.join(root, ".kuma", "POLICY.json");
-    const dir = path19.dirname(policyPath);
-    if (!fs19.existsSync(dir)) fs19.mkdirSync(dir, { recursive: true });
-    fs19.writeFileSync(policyPath, JSON.stringify(config, null, 2), "utf-8");
+    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");
     return `\u2705 Policy config saved to .kuma/POLICY.json (${config.rules.length} rules)`;
   } catch (err) {
     return `\u274C Failed to save policy: ${err}`;
@@ -6921,14 +7209,14 @@ __export(kumaAstValidator_exports, {
   validateDiff: () => validateDiff,
   validateFile: () => validateFile
 });
-import fs20 from "fs";
-import path20 from "path";
+import fs21 from "fs";
+import path21 from "path";
 function loadImportWhitelist() {
   try {
     const root = getProjectRoot();
-    const whitelistPath = path20.join(root, ".kuma", "import-whitelist.json");
-    if (fs20.existsSync(whitelistPath)) {
-      return JSON.parse(fs20.readFileSync(whitelistPath, "utf-8"));
+    const whitelistPath = path21.join(root, ".kuma", "import-whitelist.json");
+    if (fs21.existsSync(whitelistPath)) {
+      return JSON.parse(fs21.readFileSync(whitelistPath, "utf-8"));
     }
   } catch {
   }
@@ -7002,9 +7290,9 @@ function validateCodeContent(code, filePath) {
 function validateFile(filePath) {
   try {
     const root = getProjectRoot();
-    const fullPath = path20.resolve(root, filePath);
-    if (!fs20.existsSync(fullPath)) return [];
-    const content = fs20.readFileSync(fullPath, "utf-8");
+    const fullPath = path21.resolve(root, filePath);
+    if (!fs21.existsSync(fullPath)) return [];
+    const content = fs21.readFileSync(fullPath, "utf-8");
     return validateCodeContent(content, filePath);
   } catch {
     return [];
@@ -7075,16 +7363,16 @@ __export(kumaCheckpoint_exports, {
   pruneCheckpoints: () => pruneCheckpoints,
   rollbackToCheckpoint: () => rollbackToCheckpoint
 });
-import fs21 from "fs";
-import path21 from "path";
+import fs22 from "fs";
+import path22 from "path";
 async function createCheckpoint(label, description) {
   try {
     const root = getProjectRoot();
-    const cpDir = path21.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    if (fs21.existsSync(cpDir)) {
+    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    if (fs22.existsSync(cpDir)) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
-    fs21.mkdirSync(cpDir, { recursive: true });
+    fs22.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"
@@ -7093,19 +7381,19 @@ async function createCheckpoint(label, description) {
     while (filesStmt.step()) {
       const row = filesStmt.getAsObject();
       const fp = row.file_path;
-      const fullPath = path21.resolve(root, fp);
-      if (fs21.existsSync(fullPath)) {
-        const content = fs21.readFileSync(fullPath, "utf-8");
+      const fullPath = path22.resolve(root, fp);
+      if (fs22.existsSync(fullPath)) {
+        const content = fs22.readFileSync(fullPath, "utf-8");
         const hash = simpleHash2(content);
-        const fileDir = path21.dirname(path21.join(cpDir, "files", fp));
-        if (!fs21.existsSync(fileDir)) fs21.mkdirSync(fileDir, { recursive: true });
-        fs21.writeFileSync(path21.join(cpDir, "files", fp), content, "utf-8");
+        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");
         files.push({ path: fp, hash });
       }
     }
     filesStmt.free();
     const dbData = db.export();
-    fs21.writeFileSync(path21.join(cpDir, "kuma.db"), Buffer.from(dbData));
+    fs22.writeFileSync(path22.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
       label,
       timestamp: Date.now(),
@@ -7113,8 +7401,8 @@ async function createCheckpoint(label, description) {
       dbSnapshot: true,
       description
     };
-    fs21.writeFileSync(
-      path21.join(cpDir, "manifest.json"),
+    fs22.writeFileSync(
+      path22.join(cpDir, "manifest.json"),
       JSON.stringify(manifest, null, 2),
       "utf-8"
     );
@@ -7140,37 +7428,37 @@ async function createCheckpoint(label, description) {
 async function rollbackToCheckpoint(label) {
   try {
     const root = getProjectRoot();
-    const cpDir = path21.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    const manifestPath = path21.join(cpDir, "manifest.json");
-    if (!fs21.existsSync(manifestPath)) {
+    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    const manifestPath = path22.join(cpDir, "manifest.json");
+    if (!fs22.existsSync(manifestPath)) {
       return `\u274C Checkpoint "${label}" not found. Use kuma_safety({ action: 'checkpoint_list' }) to see available checkpoints.`;
     }
     const manifest = JSON.parse(
-      fs21.readFileSync(manifestPath, "utf-8")
+      fs22.readFileSync(manifestPath, "utf-8")
     );
     let restored = 0;
     let failed = 0;
     for (const f of manifest.files) {
-      const snapshotPath = path21.join(cpDir, "files", f.path);
-      if (fs21.existsSync(snapshotPath)) {
+      const snapshotPath = path22.join(cpDir, "files", f.path);
+      if (fs22.existsSync(snapshotPath)) {
         try {
-          const content = fs21.readFileSync(snapshotPath, "utf-8");
-          const targetPath = path21.resolve(root, f.path);
-          const targetDir = path21.dirname(targetPath);
-          if (!fs21.existsSync(targetDir)) fs21.mkdirSync(targetDir, { recursive: true });
-          fs21.writeFileSync(targetPath, content, "utf-8");
+          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");
           restored++;
         } catch {
           failed++;
         }
       }
     }
-    const dbSnapshotPath = path21.join(cpDir, "kuma.db");
-    if (fs21.existsSync(dbSnapshotPath)) {
-      const kumaDir = path21.join(root, ".kuma");
-      const dbPath = path21.join(kumaDir, "kuma.db");
-      const snapshotData = fs21.readFileSync(dbSnapshotPath);
-      fs21.writeFileSync(dbPath, snapshotData);
+    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);
       resetDbInstance();
     }
     sessionMemory.recordToolCall("kuma_checkpoint_rollback", {
@@ -7195,18 +7483,18 @@ async function rollbackToCheckpoint(label) {
 function listCheckpoints() {
   try {
     const root = getProjectRoot();
-    const cpDir = path21.join(root, CHECKPOINT_DIR);
-    if (!fs21.existsSync(cpDir)) {
+    const cpDir = path22.join(root, CHECKPOINT_DIR);
+    if (!fs22.existsSync(cpDir)) {
       return "\u{1F4ED} No checkpoints found. Use kuma_safety({ action: 'checkpoint', label: 'pre-feature-x' }) to create one.";
     }
-    const entries = fs21.readdirSync(cpDir);
+    const entries = fs22.readdirSync(cpDir);
     const checkpoints = [];
     for (const entry of entries) {
-      const manifestPath = path21.join(cpDir, entry, "manifest.json");
-      if (fs21.existsSync(manifestPath)) {
+      const manifestPath = path22.join(cpDir, entry, "manifest.json");
+      if (fs22.existsSync(manifestPath)) {
         try {
           const manifest = JSON.parse(
-            fs21.readFileSync(manifestPath, "utf-8")
+            fs22.readFileSync(manifestPath, "utf-8")
           );
           checkpoints.push({ label: entry, manifest });
         } catch {
@@ -7238,12 +7526,12 @@ function listCheckpoints() {
 function pruneCheckpoints(keep = 5) {
   try {
     const root = getProjectRoot();
-    const cpDir = path21.join(root, CHECKPOINT_DIR);
-    if (!fs21.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
-    const entries = fs21.readdirSync(cpDir).map((e) => ({ name: e, time: fs21.statSync(path21.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
+    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);
     let removed = 0;
     for (let i = keep; i < entries.length; i++) {
-      fs21.rmSync(path21.join(cpDir, entries[i].name), { recursive: true, force: true });
+      fs22.rmSync(path22.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.";
@@ -7283,18 +7571,18 @@ __export(kumaContractEngine_exports, {
   loadContracts: () => loadContracts,
   runContractChecks: () => runContractChecks
 });
-import fs22 from "fs";
-import path22 from "path";
+import fs23 from "fs";
+import path23 from "path";
 function contractsDir() {
-  return path22.join(getProjectRoot(), ".kuma", "contracts");
+  return path23.join(getProjectRoot(), ".kuma", "contracts");
 }
 function ensureContractsDir() {
   const dir = contractsDir();
-  if (!fs22.existsSync(dir)) {
-    fs22.mkdirSync(dir, { recursive: true });
-    const defaultPath = path22.join(dir, "default.json");
-    if (!fs22.existsSync(defaultPath)) {
-      fs22.writeFileSync(
+  if (!fs23.existsSync(dir)) {
+    fs23.mkdirSync(dir, { recursive: true });
+    const defaultPath = path23.join(dir, "default.json");
+    if (!fs23.existsSync(defaultPath)) {
+      fs23.writeFileSync(
         defaultPath,
         JSON.stringify(DEFAULT_CONTRACTS, null, 2),
         "utf-8"
@@ -7307,10 +7595,10 @@ function loadContracts() {
   const dir = contractsDir();
   const contracts = [];
   try {
-    const files = fs22.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const files = fs23.readdirSync(dir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
       try {
-        const content = fs22.readFileSync(path22.join(dir, file), "utf-8");
+        const content = fs23.readFileSync(path23.join(dir, file), "utf-8");
         const config = JSON.parse(content);
         contracts.push(config);
       } catch (err) {
@@ -7383,7 +7671,7 @@ function evaluateCondition(condition, contextPath) {
   switch (condition.type) {
     case "file_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs22.existsSync(p));
+      const exists = targetPath.some((p) => fs23.existsSync(p));
       return {
         passed: exists,
         message: exists ? `\u2705 File exists: ${condition.target}` : `\u274C Required file not found: ${condition.target} (${condition.description})`
@@ -7391,7 +7679,7 @@ function evaluateCondition(condition, contextPath) {
     }
     case "file_not_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs22.existsSync(p));
+      const exists = targetPath.some((p) => fs23.existsSync(p));
       return {
         passed: !exists,
         message: !exists ? `\u2705 File does not exist: ${condition.target}` : `\u274C File should not exist: ${condition.target} (${condition.description})`
@@ -7399,9 +7687,9 @@ function evaluateCondition(condition, contextPath) {
     }
     case "contains": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const fullPath = path22.resolve(root, contextPath);
-      if (!fs22.existsSync(fullPath)) return { passed: true, message: "\u26A0\uFE0F File not found" };
-      const content = fs22.readFileSync(fullPath, "utf-8");
+      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 hasContent = condition.value ? content.includes(condition.value) : false;
       return {
         passed: hasContent,
@@ -7413,12 +7701,12 @@ function evaluateCondition(condition, contextPath) {
       const root2 = getProjectRoot();
       const targets = resolveTarget(condition.target, contextPath, root2);
       for (const t of targets) {
-        if (fs22.existsSync(t)) {
-          const content = fs22.readFileSync(t, "utf-8");
+        if (fs23.existsSync(t)) {
+          const content = fs23.readFileSync(t, "utf-8");
           if (condition.value && content.includes(condition.value)) {
             return {
               passed: false,
-              message: `\u274C Found forbidden pattern "${condition.value}" in ${path22.relative(root2, t)} (${condition.description})`
+              message: `\u274C Found forbidden pattern "${condition.value}" in ${path23.relative(root2, t)} (${condition.description})`
             };
           }
         }
@@ -7427,15 +7715,15 @@ function evaluateCondition(condition, contextPath) {
     }
     case "has_test_file": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const basename = path22.basename(contextPath, path22.extname(contextPath));
-      const dir = path22.dirname(contextPath);
+      const basename = path23.basename(contextPath, path23.extname(contextPath));
+      const dir = path23.dirname(contextPath);
       const possibleTests = [
-        path22.join(dir, `${basename}.test.ts`),
-        path22.join(dir, `${basename}.spec.ts`),
-        path22.join(dir, `__tests__/${basename}.test.ts`),
-        path22.join(dir, `__tests__/${basename}.spec.ts`)
+        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) => fs22.existsSync(t));
+      const hasTest = possibleTests.some((t) => fs23.existsSync(t));
       return {
         passed: hasTest,
         message: hasTest ? `\u2705 Test file exists` : `\u274C No test file found for ${contextPath} (${condition.description})`
@@ -7459,18 +7747,18 @@ function resolveTarget(pattern, contextPath, root) {
   const r = root || getProjectRoot();
   if (pattern.startsWith("*")) {
     if (contextPath) {
-      const dir = path22.dirname(path22.resolve(r, contextPath));
+      const dir = path23.dirname(path23.resolve(r, contextPath));
       const suffix = pattern.replace("*", "");
       try {
-        const files = fs22.readdirSync(dir);
-        return files.filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path22.join(dir, f));
+        const files = fs23.readdirSync(dir);
+        return files.filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path23.join(dir, f));
       } catch {
-        return [path22.join(dir, pattern.replace("*", ""))];
+        return [path23.join(dir, pattern.replace("*", ""))];
       }
     }
     return [];
   }
-  return [path22.resolve(r, pattern)];
+  return [path23.resolve(r, pattern)];
 }
 async function runContractChecks(toolName, filePath, phase = "pre") {
   const verdicts = phase === "pre" ? evaluatePreConditions(toolName, filePath) : evaluatePostConditions(toolName, filePath);
@@ -7591,37 +7879,37 @@ __export(kumaVerifier_exports, {
   getRunningVerificationPid: () => getRunningVerificationPid,
   runAutoVerification: () => runAutoVerification
 });
-import fs23 from "fs";
-import path23 from "path";
+import fs24 from "fs";
+import path24 from "path";
 import { exec } from "child_process";
 function getLockDir(root = process.cwd()) {
-  return path23.resolve(root, LOCK_DIR_NAME);
+  return path24.resolve(root, LOCK_DIR_NAME);
 }
 function getPidFile(root = process.cwd()) {
-  return path23.join(getLockDir(root), "pid");
+  return path24.join(getLockDir(root), "pid");
 }
 function acquireFileLock(root) {
   const lockDir = getLockDir(root);
   try {
-    fs23.mkdirSync(lockDir, { recursive: false });
-    fs23.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+    fs24.mkdirSync(lockDir, { recursive: false });
+    fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
     return true;
   } catch {
     try {
-      if (fs23.existsSync(getPidFile(root))) {
-        const pid = parseInt(fs23.readFileSync(getPidFile(root), "utf-8"), 10);
+      if (fs24.existsSync(getPidFile(root))) {
+        const pid = parseInt(fs24.readFileSync(getPidFile(root), "utf-8"), 10);
         try {
           process.kill(pid, 0);
           return false;
         } catch {
-          fs23.rmSync(lockDir, { recursive: true, force: true });
+          fs24.rmSync(lockDir, { recursive: true, force: true });
           return acquireFileLock(root);
         }
       }
     } catch {
     }
     try {
-      fs23.rmSync(lockDir, { recursive: true, force: true });
+      fs24.rmSync(lockDir, { recursive: true, force: true });
       return acquireFileLock(root);
     } catch {
       return false;
@@ -7630,7 +7918,7 @@ function acquireFileLock(root) {
 }
 function releaseFileLock(root) {
   try {
-    fs23.rmSync(getLockDir(root), { recursive: true, force: true });
+    fs24.rmSync(getLockDir(root), { recursive: true, force: true });
   } catch {
   }
 }
@@ -7653,36 +7941,36 @@ function getRunningVerificationPid() {
   return _currentProcess?.pid ?? null;
 }
 function detectTestRunner(root = process.cwd()) {
-  const pkgPath = path23.join(root, "package.json");
-  if (fs23.existsSync(pkgPath)) {
+  const pkgPath = path24.join(root, "package.json");
+  if (fs24.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs23.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs24.readFileSync(pkgPath, "utf-8"));
       if (pkg.scripts && pkg.scripts.test) {
-        if (fs23.existsSync(path23.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
-        if (fs23.existsSync(path23.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn 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" };
         return { runner: "npm", baseCommand: "npm test" };
       }
     } catch {
     }
   }
-  if (fs23.existsSync(path23.join(root, "pytest.ini")) || fs23.existsSync(path23.join(root, "pyproject.toml"))) return { runner: "pytest", baseCommand: "pytest" };
-  if (fs23.existsSync(path23.join(root, "Cargo.toml"))) return { runner: "cargo", baseCommand: "cargo test" };
-  if (fs23.existsSync(path23.join(root, "go.mod"))) return { runner: "go", baseCommand: "go test ./..." };
-  if (fs23.existsSync(path23.join(root, "Makefile"))) {
+  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"))) {
     try {
-      const makefileContent = fs23.readFileSync(path23.join(root, "Makefile"), "utf-8");
+      const makefileContent = fs24.readFileSync(path24.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 (fs23.existsSync(path23.join(root, "package.json"))) {
+  if (fs24.existsSync(path24.join(root, "package.json"))) {
     try {
-      const pkg = JSON.parse(fs23.readFileSync(path23.join(root, "package.json"), "utf-8"));
+      const pkg = JSON.parse(fs24.readFileSync(path24.join(root, "package.json"), "utf-8"));
       if (pkg.dependencies || pkg.devDependencies) {
-        if (fs23.existsSync(path23.join(root, "tsconfig.json"))) return { runner: "tsc", baseCommand: "npx tsc --noEmit" };
-        const srcDir = path23.join(root, "src");
-        if (fs23.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 (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)` };
       }
     } catch {
     }
@@ -7782,7 +8070,7 @@ async function runAutoVerification(options = {}) {
       const heartbeatTimer = setInterval(() => {
         if (getLockDir(root)) {
           try {
-            fs23.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+            fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
           } catch {
           }
         }
@@ -7859,8 +8147,8 @@ __export(init_exports, {
   generateInitMdContent: () => generateInitMdContent,
   runInit: () => runInit
 });
-import fs24 from "fs";
-import path24 from "path";
+import fs25 from "fs";
+import path25 from "path";
 function configFilePath(type) {
   switch (type) {
     case "claude":
@@ -8431,12 +8719,14 @@ function generateInitMdContent() {
     "  --- EDIT/READ (use native tools) ---",
     "  5. kuma_memory    \u2192 research_save       \u2014 After exploring area (creates search cache)",
     "  6. kuma_memory    \u2192 gotcha              \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)",
-    "  7. kuma_memory    \u2192 arch_flow           \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)",
-    "  8. kuma_memory    \u2192 decision            \u2014 When choosing (preserves rationale)",
-    "  9. kuma_safety    \u2192 verify              \u2014 Run tests / confirm nothing broken",
-    " 10. kuma_context   \u2192 changes             \u2014 Review session activity",
+    "  7. kuma_memory    \u2192 arch_flow           \u2014 After tracing COMPLETE flow (max 5 core files)",
+    "  8. kuma_memory    \u2192 feature             \u2014 \u2B50 When discovering a module/feature boundary (Authentication, Billing)",
+    "  9. kuma_memory    \u2192 decision            \u2014 When choosing (preserves rationale)",
+    " 10. kuma_safety    \u2192 verify              \u2014 Run tests / confirm nothing broken",
+    " 11. kuma_context   \u2192 changes             \u2014 Review session activity",
     "",
     "\u{1F525} `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+    "\u2B50 `feature` captures module ownership \u2014 use when you identify a cohesive feature boundary.",
     "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
     "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
@@ -8546,10 +8836,10 @@ function generateInitMdContent() {
   ].join("\n");
 }
 function handleOpencodeSecondary(root, results) {
-  const skillPath = path24.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
+  const skillPath = path25.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
   if (results.some((r) => r.filePath === ".agents/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path24.dirname(skillPath);
+    const dir = path25.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -8568,7 +8858,7 @@ function handleOpencodeSecondary(root, results) {
       "  4. *(edit/read using native tools)*",
       '  5. `kuma_kuma_memory({ action: "research_save", ... })`               \u2014 After exploring area (creates search cache)',
       '  6. `kuma_kuma_memory({ action: "gotcha" })`                           \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
+      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 After tracing COMPLETE flow, max 5 core files',
       '  8. `kuma_kuma_memory({ action: "decision" })`                         \u2014 When choosing (preserves rationale)',
       '  9. `kuma_kuma_safety({ action: "verify", ... })`                      \u2014 Run tests / confirm nothing broken',
       ' 10. `kuma_kuma_context({ action: "changes" })`                         \u2014 Review session activity',
@@ -8582,18 +8872,18 @@ function handleOpencodeSecondary(root, results) {
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
-    if (fs24.existsSync(skillPath)) {
-      const existing = fs24.readFileSync(skillPath, "utf-8");
+    if (fs25.existsSync(skillPath)) {
+      const existing = fs25.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;
-      fs24.writeFileSync(skillPath, newContent, "utf-8");
+      fs25.writeFileSync(skillPath, newContent, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-      fs24.writeFileSync(skillPath, content, "utf-8");
+      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      fs25.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -8606,21 +8896,21 @@ function handleOpencodeSecondary(root, results) {
   }
 }
 function handleCodexSecondary(root, results) {
-  const tomlPath = path24.resolve(root, ".codex/config.toml");
+  const tomlPath = path25.resolve(root, ".codex/config.toml");
   if (results.some((r) => r.filePath === ".codex/config.toml")) return;
   try {
-    const dir = path24.dirname(tomlPath);
-    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-    if (fs24.existsSync(tomlPath)) {
-      const existingContent = fs24.readFileSync(tomlPath, "utf-8");
+    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");
       if (existingContent.includes("kuma")) {
         results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
         return;
       }
-      fs24.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      fs25.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
     } else {
-      fs24.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
+      fs25.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "created" });
     }
   } catch (err) {
@@ -8633,11 +8923,11 @@ function handleCodexSecondary(root, results) {
   }
 }
 function handleQwenSecondary(root, results) {
-  const settingsPath = path24.resolve(root, "settings.json");
+  const settingsPath = path25.resolve(root, "settings.json");
   if (results.some((r) => r.filePath === "settings.json")) return;
   try {
-    if (fs24.existsSync(settingsPath)) {
-      const existingContent = fs24.readFileSync(settingsPath, "utf-8");
+    if (fs25.existsSync(settingsPath)) {
+      const existingContent = fs25.readFileSync(settingsPath, "utf-8");
       if (existingContent.includes("kuma")) {
         if (!existingContent.includes("_Generated by Kuma MCP_")) {
           try {
@@ -8645,7 +8935,7 @@ function handleQwenSecondary(root, results) {
             parsed.mcpServers = parsed.mcpServers || {};
             if (!parsed.mcpServers.kuma) {
               parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-              fs24.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+              fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
               results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
               return;
             }
@@ -8660,13 +8950,13 @@ function handleQwenSecondary(root, results) {
         parsed.mcpServers = parsed.mcpServers || {};
         if (!parsed.mcpServers.kuma) {
           parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-          fs24.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
           results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
         }
       } catch {
       }
     } else {
-      fs24.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
+      fs25.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
       results.push({ type: "qwen", filePath: "settings.json", action: "created" });
     }
   } catch (err) {
@@ -8699,7 +8989,7 @@ function getCombinedAgentsMd(selectedTypes) {
     "  4. *(edit/read using native tools)*",
     '  5. `[kuma_]memory({ action: "research_save", ... })`        \u2014 After exploring area (creates search cache)',
     '  6. `[kuma_]memory({ action: "gotcha" })`                    \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
+    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 After tracing COMPLETE flow (max 5 core files)',
     '  8. `[kuma_]memory({ action: "decision" })`                  \u2014 When choosing (preserves rationale)',
     '  9. `[kuma_]safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
     ' 10. `[kuma_]context({ action: "changes" })`                  \u2014 Review session activity',
@@ -8769,18 +9059,18 @@ function getCombinedAgentsMd(selectedTypes) {
   return lines.join("\n");
 }
 function handleAntigravityMcpConfig(root, results) {
-  const mcpPath = path24.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const mcpDir = path24.dirname(mcpPath);
-    if (fs24.existsSync(mcpPath)) {
-      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
+    const mcpDir = path25.dirname(mcpPath);
+    if (fs25.existsSync(mcpPath)) {
+      const existingContent = fs25.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';
-            fs24.writeFileSync(mcpPath, updated, "utf-8");
+            fs25.writeFileSync(mcpPath, updated, "utf-8");
             results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
           }
         }
@@ -8789,11 +9079,11 @@ function handleAntigravityMcpConfig(root, results) {
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs24.existsSync(mcpDir)) fs24.mkdirSync(mcpDir, { recursive: true });
-      fs24.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs25.existsSync(mcpDir)) fs25.mkdirSync(mcpDir, { recursive: true });
+      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -8806,18 +9096,18 @@ function handleAntigravityMcpConfig(root, results) {
   }
 }
 function handleAiderSecondary(root, results) {
-  const ymlPath = path24.resolve(root, ".aider.conf.yml");
+  const ymlPath = path25.resolve(root, ".aider.conf.yml");
   if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
   try {
     const conventionsRef = "read: CONVENTIONS.md";
-    if (fs24.existsSync(ymlPath)) {
-      const existingContent = fs24.readFileSync(ymlPath, "utf-8");
+    if (fs25.existsSync(ymlPath)) {
+      const existingContent = fs25.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";
-      fs24.writeFileSync(ymlPath, newContent, "utf-8");
+      fs25.writeFileSync(ymlPath, newContent, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "appended" });
     } else {
       const content = [
@@ -8827,7 +9117,7 @@ function handleAiderSecondary(root, results) {
         conventionsRef,
         ""
       ].join("\n");
-      fs24.writeFileSync(ymlPath, content, "utf-8");
+      fs25.writeFileSync(ymlPath, content, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "created" });
     }
   } catch (err) {
@@ -8840,10 +9130,10 @@ function handleAiderSecondary(root, results) {
   }
 }
 function handleCopilotSecondary(root, results) {
-  const skillPath = path24.resolve(root, ".github/skills/kuma/SKILL.md");
+  const skillPath = path25.resolve(root, ".github/skills/kuma/SKILL.md");
   if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path24.dirname(skillPath);
+    const dir = path25.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -8854,17 +9144,17 @@ function handleCopilotSecondary(root, results) {
       "",
       "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
     ].join("\n");
-    if (fs24.existsSync(skillPath)) {
-      const existingContent = fs24.readFileSync(skillPath, "utf-8");
+    if (fs25.existsSync(skillPath)) {
+      const existingContent = fs25.readFileSync(skillPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
-      fs24.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      fs25.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-      fs24.writeFileSync(skillPath, content, "utf-8");
+      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      fs25.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -8877,21 +9167,21 @@ function handleCopilotSecondary(root, results) {
   }
 }
 function handleOpenclawSecondary(root, results) {
-  const mcpPath = path24.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const dir = path24.dirname(mcpPath);
-    if (fs24.existsSync(mcpPath)) {
-      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
+    const dir = path25.dirname(mcpPath);
+    if (fs25.existsSync(mcpPath)) {
+      const existingContent = fs25.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: {} };
-      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-      fs24.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -8904,7 +9194,7 @@ function handleOpenclawSecondary(root, results) {
   }
 }
 function handleQuickrefGeneration(root, results) {
-  const quickrefPath = path24.resolve(root, ".kuma/quickref.md");
+  const quickrefPath = path25.resolve(root, ".kuma/quickref.md");
   const content = [
     "# Kuma Quick Reference",
     "",
@@ -8929,16 +9219,16 @@ function handleQuickrefGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const kumaDir = path24.dirname(quickrefPath);
-    if (!fs24.existsSync(kumaDir)) fs24.mkdirSync(kumaDir, { recursive: true });
-    if (fs24.existsSync(quickrefPath)) {
-      const existing = fs24.readFileSync(quickrefPath, "utf-8");
+    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");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
         return;
       }
     }
-    fs24.writeFileSync(quickrefPath, content, "utf-8");
+    fs25.writeFileSync(quickrefPath, content, "utf-8");
     results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
   } catch (err) {
     results.push({
@@ -8950,7 +9240,7 @@ function handleQuickrefGeneration(root, results) {
   }
 }
 function handleModeMdGeneration(root, results) {
-  const filePath = path24.resolve(root, ".kuma/MODE.md");
+  const filePath = path25.resolve(root, ".kuma/MODE.md");
   const content = [
     "# Adaptive Mode Selector",
     "",
@@ -8993,10 +9283,10 @@ function handleModeMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path24.dirname(filePath);
-    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-    if (!fs24.existsSync(filePath)) {
-      fs24.writeFileSync(filePath, content, "utf-8");
+    const dir = path25.dirname(filePath);
+    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+    if (!fs25.existsSync(filePath)) {
+      fs25.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "created" });
     }
   } catch (err) {
@@ -9004,7 +9294,7 @@ function handleModeMdGeneration(root, results) {
   }
 }
 function handleSkipRulesMdGeneration(root, results) {
-  const filePath = path24.resolve(root, ".kuma/SKIP_RULES.md");
+  const filePath = path25.resolve(root, ".kuma/SKIP_RULES.md");
   const content = [
     "# Skip Rules \u2014 What NOT to Record",
     "",
@@ -9041,10 +9331,10 @@ function handleSkipRulesMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path24.dirname(filePath);
-    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-    if (!fs24.existsSync(filePath)) {
-      fs24.writeFileSync(filePath, content, "utf-8");
+    const dir = path25.dirname(filePath);
+    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+    if (!fs25.existsSync(filePath)) {
+      fs25.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "created" });
     }
   } catch (err) {
@@ -9052,7 +9342,7 @@ function handleSkipRulesMdGeneration(root, results) {
   }
 }
 function handleStalenessMdGeneration(root, results) {
-  const filePath = path24.resolve(root, ".kuma/STALENESS.md");
+  const filePath = path25.resolve(root, ".kuma/STALENESS.md");
   const content = [
     "# Auto-Staleness Detection",
     "",
@@ -9083,10 +9373,10 @@ function handleStalenessMdGeneration(root, results) {
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
-    const dir = path24.dirname(filePath);
-    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-    if (!fs24.existsSync(filePath)) {
-      fs24.writeFileSync(filePath, content, "utf-8");
+    const dir = path25.dirname(filePath);
+    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+    if (!fs25.existsSync(filePath)) {
+      fs25.writeFileSync(filePath, content, "utf-8");
       results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "created" });
     }
   } catch (err) {
@@ -9094,20 +9384,20 @@ function handleStalenessMdGeneration(root, results) {
   }
 }
 function handleInitMdGeneration(root, results) {
-  const initMdPath = path24.resolve(root, ".kuma/init.md");
+  const initMdPath = path25.resolve(root, ".kuma/init.md");
   try {
-    const kumaDir = path24.dirname(initMdPath);
-    if (!fs24.existsSync(kumaDir)) fs24.mkdirSync(kumaDir, { recursive: true });
-    if (fs24.existsSync(initMdPath)) {
-      const existing = fs24.readFileSync(initMdPath, "utf-8");
+    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");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/init.md", action: "skipped" });
         return;
       }
-      fs24.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
+      fs25.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "appended" });
     } else {
-      fs24.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
+      fs25.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "created" });
     }
   } catch (err) {
@@ -9124,20 +9414,20 @@ function handleInitMdGeneration(root, results) {
   handleStalenessMdGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
-  const mcpPath = path24.resolve(root, ".codewhale/mcp.json");
+  const mcpPath = path25.resolve(root, ".codewhale/mcp.json");
   if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
   try {
-    const dir = path24.dirname(mcpPath);
-    if (fs24.existsSync(mcpPath)) {
-      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
+    const dir = path25.dirname(mcpPath);
+    if (fs25.existsSync(mcpPath)) {
+      const existingContent = fs25.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: {} };
-      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
     } else {
-      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
       const config = {
         mcpServers: {
           kuma: {
@@ -9147,7 +9437,7 @@ function handleCodewhaleSecondary(root, results) {
           }
         }
       };
-      fs24.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs25.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "created" });
     }
   } catch (err) {
@@ -9169,28 +9459,28 @@ function runInit(options) {
   let agentsMdHandled = false;
   for (const type of selected) {
     const relativePath = configFilePath(type);
-    const fullPath = path24.resolve(root, relativePath);
+    const fullPath = path25.resolve(root, relativePath);
     const getTemplate = TEMPLATES[type];
     try {
       if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
         agentsMdHandled = true;
         const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
-        if (fs24.existsSync(fullPath)) {
+        if (fs25.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
           } else {
-            const existingContent = fs24.readFileSync(fullPath, "utf-8");
+            const existingContent = fs25.readFileSync(fullPath, "utf-8");
             if (existingContent.includes("_Generated by Kuma MCP_")) {
               results.push({ type, filePath: relativePath, action: "skipped" });
             } else {
-              fs24.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+              fs25.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
               results.push({ type, filePath: relativePath, action: "appended" });
             }
           }
         } else {
-          const dir = path24.dirname(fullPath);
-          if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
-          fs24.writeFileSync(fullPath, combinedContent, "utf-8");
+          const dir = path25.dirname(fullPath);
+          if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+          fs25.writeFileSync(fullPath, combinedContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
@@ -9202,12 +9492,12 @@ function runInit(options) {
         continue;
       } else {
         const template = getTemplate();
-        if (fs24.existsSync(fullPath)) {
+        if (fs25.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
             continue;
           }
-          const existingContent = fs24.readFileSync(fullPath, "utf-8");
+          const existingContent = fs25.readFileSync(fullPath, "utf-8");
           if (existingContent.includes("_Generated by Kuma MCP_")) {
             if (type === "antigravity") {
               handleAntigravityMcpConfig(root, results);
@@ -9220,14 +9510,14 @@ function runInit(options) {
             continue;
           }
           const newContent = existingContent.trimEnd() + APPEND_SEPARATOR + template;
-          fs24.writeFileSync(fullPath, newContent, "utf-8");
+          fs25.writeFileSync(fullPath, newContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "appended" });
         } else {
-          const dir = path24.dirname(fullPath);
-          if (!fs24.existsSync(dir)) {
-            fs24.mkdirSync(dir, { recursive: true });
+          const dir = path25.dirname(fullPath);
+          if (!fs25.existsSync(dir)) {
+            fs25.mkdirSync(dir, { recursive: true });
           }
-          fs24.writeFileSync(fullPath, template, "utf-8");
+          fs25.writeFileSync(fullPath, template, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (type === "antigravity") {
@@ -9383,19 +9673,19 @@ __export(agentDetector_exports, {
   getSkillPath: () => getSkillPath,
   skillExists: () => skillExists
 });
-import fs25 from "fs";
-import path25 from "path";
+import fs26 from "fs";
+import path26 from "path";
 function checkFile(root, filePath) {
   try {
-    return fs25.existsSync(path25.join(root, filePath));
+    return fs26.existsSync(path26.join(root, filePath));
   } catch {
     return false;
   }
 }
 function checkDir(root, dirPath) {
   try {
-    const fullPath = path25.join(root, dirPath);
-    return fs25.existsSync(fullPath) && fs25.statSync(fullPath).isDirectory();
+    const fullPath = path26.join(root, dirPath);
+    return fs26.existsSync(fullPath) && fs26.statSync(fullPath).isDirectory();
   } catch {
     return false;
   }
@@ -9463,7 +9753,7 @@ function getAgentLabel(type) {
 function skillExists(type, projectRoot) {
   const root = projectRoot ?? getProjectRoot();
   const skillPath = getSkillPath(type);
-  return fs25.existsSync(path25.join(root, skillPath));
+  return fs26.existsSync(path26.join(root, skillPath));
 }
 var AGENT_DETECTORS;
 var init_agentDetector = __esm({
@@ -9863,11 +10153,11 @@ var init_skillGenerator = __esm({
       "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
       "\u26A1 **ADAPTIVE WORKFLOW (Lean Mode by Default):**",
-      "  \u2022 **Lean Mode (Default, < 3 files):** `init` \u2192 edit/read \u2192 record (`decision`/`gotcha` if needed)",
+      "  \u2022 **Lean Mode (Default, < 3 files):** `init` \u2192 edit/read \u2192 record (`decision`/`gotcha`/`feature` if needed)",
       "  \u2022 **Standard Mode (3-10 files/unfamiliar):** `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
       "  \u2022 **Full Mode (> 10 files/refactor):** `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
       "",
-      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow), `feature` (high-level module ownership)",
       "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
       "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
@@ -9883,7 +10173,7 @@ var init_skillGenerator = __esm({
       "  \u2022 **Standard Mode (3-10 files/unfamiliar):** `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
       "  \u2022 **Full Mode (> 10 files/refactor):** `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
       "",
-      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow), `feature` (high-level module ownership)",
       "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
       "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
@@ -10407,9 +10697,58 @@ init_sessionMemory();
 init_kumaDb();
 init_kumaSelfHeal();
 init_kumaMemory();
+
+// src/engine/kumaNoiseFilter.ts
+var ALLOWED_NODE_TYPES = /* @__PURE__ */ new Set([
+  "arch_flow",
+  // Architecture flow (Layer 2)
+  "gotcha",
+  // Known gotchas / edge cases (Layer 3)
+  "decision",
+  // Architecture decisions / ADRs
+  "cross_service_link",
+  // Backend ↔ Frontend integration links
+  "feature_domain",
+  // High-level feature domains
+  "file",
+  // File references (needed for graph connectivity)
+  "research"
+  // Research cache nodes (needed for search)
+]);
+function isNodeTypeAllowed(type) {
+  return ALLOWED_NODE_TYPES.has(type);
+}
+function getNoiseFilterPolicy() {
+  return [
+    "\u{1F9F9} **Kuma Noise Filter \u2014 Anti-AST Guard**",
+    "\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",
+    "",
+    "**Allowed High-Value Node Types:**",
+    "  \u{1F3DB}\uFE0F `arch_flow` \u2014 Architecture flow (max 5 core files per flow)",
+    "  \u{1F4CC} `gotcha` \u2014 Known bugs, edge cases, gotchas",
+    "  \u2696\uFE0F `decision` \u2014 Architecture decisions / ADRs",
+    "  \u{1F517} `cross_service_link` \u2014 Backend \u2194 Frontend integration links",
+    "  \u{1F3D7}\uFE0F `feature_domain` \u2014 High-level feature domains",
+    "  \u{1F4C4} `file` \u2014 File references (graph connectivity)",
+    "  \u{1F52C} `research` \u2014 Research cache nodes",
+    "",
+    "**Rejected Noise Types:**",
+    "  \u274C `function`, `class`, `component`, `variable`, `method`",
+    "  \u274C `interface`, `type`, `enum`, `const`, `hook`",
+    "  \u274C `route`, `api_route`, `test`",
+    "",
+    "**Why?** AST-level nodes create graph junk that slows retrieval.",
+    "Use `arch_flow` to describe HOW files connect, not individual functions.",
+    "",
+    "**Tip:** Instead of adding function nodes, record an `arch_flow`:",
+    "  kuma_memory({ action: 'arch_flow', content: 'domain: AuthFlow | hops: auth.ts \u2192 middleware.ts \u2192 session.ts' })"
+  ].join("\n");
+}
+
+// src/tools/kumaMemoryTool.ts
 init_pathValidator();
-import fs14 from "fs";
-import path14 from "path";
+import fs15 from "fs";
+import path15 from "path";
 var MEMORY_ALIASES = {
   // Session synonyms
   "session": "session",
@@ -10515,7 +10854,18 @@ var MEMORY_ALIASES = {
   "clear-graph": "clear",
   "wipe": "clear",
   "reset": "clear",
-  "purge-all": "clear"
+  "purge-all": "clear",
+  // Harvest synonyms (Pilar 5)
+  "harvest": "harvest",
+  "git-harvest": "harvest",
+  "auto-harvest": "harvest",
+  "git": "harvest",
+  // Noise policy synonyms (Pilar 4)
+  "noise_policy": "noise_policy",
+  "noise-policy": "noise_policy",
+  "noise": "noise_policy",
+  "anti-ast": "noise_policy",
+  "filter": "noise_policy"
 };
 async function handleMemory(params) {
   const rawAction = params.action || "session";
@@ -10566,6 +10916,10 @@ async function handleMemory(params) {
       await clearGraph2();
       return "\u{1F5D1}\uFE0F **Knowledge Graph Cleared** \u2014 All nodes, edges, and gotchas have been wiped from disk and memory.";
     }
+    case "harvest":
+      return handleHarvest(params);
+    case "noise_policy":
+      return getNoiseFilterPolicy();
     default:
       return `Unknown action "${action}".`;
   }
@@ -10640,9 +10994,9 @@ async function handleResearchSave(params) {
   } catch {
   }
   try {
-    const researchDir = path14.join(getProjectRoot(), ".kuma", "research");
-    if (!fs14.existsSync(researchDir)) fs14.mkdirSync(researchDir, { recursive: true });
-    fs14.writeFileSync(path14.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
+    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");
   } catch {
   }
   sessionMemory.recordMemoryAction("research_save");
@@ -10731,8 +11085,8 @@ ${impactLines.join("\n")}`;
   }
   let hybridResults = "";
   try {
-    const { hybridSearch: hybridSearch2, formatHybridResults: formatHybridResults2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
-    const semanticResults = await hybridSearch2(query, 8);
+    const { enhancedHybridSearch: enhancedHybridSearch2, formatHybridResults: formatHybridResults2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
+    const semanticResults = await enhancedHybridSearch2(query, 8);
     if (semanticResults.length > 0) {
       hybridResults = "\n" + formatHybridResults2(query, semanticResults);
     }
@@ -11009,11 +11363,14 @@ async function handleAddNode(params) {
   const name = params.content;
   const filePath = params.scope;
   if (!type || !name) {
-    return "\u26A0\uFE0F `title` (node type: function/class/component/file/api_route/test) and `content` (node name) required.\nExample: kuma_memory({ action: 'add_node', title: 'function', content: 'sendMessage', scope: 'ChatService.ts' })";
+    return "\u26A0\uFE0F `title` (node type) and `content` (node name) required.\n\n\u2705 Allowed types: arch_flow, gotcha, decision, cross_service_link, feature_domain, file, research\n\u274C Rejected: function, class, component, variable, method\n\nExample: kuma_memory({ action: 'arch_flow', content: 'domain: AuthFlow | hops: auth.ts \u2192 middleware.ts' })";
   }
-  const validTypes = ["function", "class", "component", "file", "api_route", "test"];
-  if (!validTypes.includes(type)) {
-    return `\u26A0\uFE0F Invalid type "${type}". Valid types: ${validTypes.join(", ")}`;
+  if (!isNodeTypeAllowed(type)) {
+    return [
+      `\u274C **Noise Filter:** Type "${type}" is not allowed.`,
+      "",
+      getNoiseFilterPolicy()
+    ].join("\n");
   }
   try {
     const { upsertNode: upsertNode2, nodeId: nodeId2, addEdge: addEdge2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
@@ -11126,78 +11483,88 @@ async function handleLayersSummary(_params) {
   const { getLayersSummary: getLayersSummary2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
   return getLayersSummary2();
 }
+async function handleHarvest(params) {
+  sessionMemory.recordToolCall("kuma_memory_harvest", { scope: params.scope });
+  const { harvestGitHistory: harvestGitHistory2, installGitHook: installGitHook2 } = await Promise.resolve().then(() => (init_kumaGitHarvester(), kumaGitHarvester_exports));
+  if (params.scope === "install") {
+    return installGitHook2();
+  }
+  const count = params.limit || 10;
+  const dryRun = params.status === "dry-run" || params.status === "preview";
+  return await harvestGitHistory2({ commitCount: count, dryRun });
+}
 
 // src/tools/kumaSafetyTool.ts
 init_sessionMemory();
 
 // src/engine/kumaLock.ts
 init_pathValidator();
-import fs15 from "fs";
-import path15 from "path";
+import fs16 from "fs";
+import path16 from "path";
 var LOCKS_DIR = ".kuma/locks";
 function locksDir() {
-  return path15.join(getProjectRoot(), LOCKS_DIR);
+  return path16.join(getProjectRoot(), LOCKS_DIR);
 }
 function ensureLocksDir() {
   const dir = locksDir();
-  if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+  if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
 }
 function lockPath(filePath) {
   const safeName = filePath.replace(/[^a-zA-Z0-9_./-]/g, "_");
-  return path15.join(locksDir(), `${safeName}.lock.json`);
+  return path16.join(locksDir(), `${safeName}.lock.json`);
 }
 function acquireLock(filePath, agentId) {
   ensureLocksDir();
   const lp = lockPath(filePath);
   const id = agentId || `agent-${process.pid}`;
-  if (fs15.existsSync(lp)) {
+  if (fs16.existsSync(lp)) {
     try {
-      const existing = JSON.parse(fs15.readFileSync(lp, "utf-8"));
+      const existing = JSON.parse(fs16.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) {
-        fs15.unlinkSync(lp);
+        fs16.unlinkSync(lp);
       } else {
         return `\u{1F512} **Locked** by ${existing.agentId} since ${new Date(existing.acquiredAt).toISOString()} (${elapsed}s ago)`;
       }
     } catch {
-      fs15.unlinkSync(lp);
+      fs16.unlinkSync(lp);
     }
   }
   const entry = { filePath, agentId: id, acquiredAt: Date.now(), status: "locked" };
-  fs15.writeFileSync(lp, JSON.stringify(entry, null, 2), "utf-8");
+  fs16.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 (!fs15.existsSync(lp)) {
+  if (!fs16.existsSync(lp)) {
     return `\u26A0\uFE0F No lock found for \`${filePath}\``;
   }
   try {
-    const existing = JSON.parse(fs15.readFileSync(lp, "utf-8"));
+    const existing = JSON.parse(fs16.readFileSync(lp, "utf-8"));
     if (existing.agentId !== id) {
       return `\u26A0\uFE0F Cannot release lock held by ${existing.agentId}. Use force:true to override.`;
     }
-    fs15.unlinkSync(lp);
+    fs16.unlinkSync(lp);
     return `\u{1F513} **Lock released** on \`${filePath}\``;
   } catch {
-    fs15.unlinkSync(lp);
+    fs16.unlinkSync(lp);
     return `\u{1F513} **Lock released** (force cleanup) on \`${filePath}\``;
   }
 }
 function listLocks() {
   ensureLocksDir();
   const dir = locksDir();
-  const files = fs15.readdirSync(dir).filter((f) => f.endsWith(".lock.json"));
+  const files = fs16.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(fs15.readFileSync(path15.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs16.readFileSync(path16.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 {
@@ -11208,9 +11575,9 @@ function listLocks() {
 }
 function isLocked(filePath) {
   const lp = lockPath(filePath);
-  if (!fs15.existsSync(lp)) return { locked: false };
+  if (!fs16.existsSync(lp)) return { locked: false };
   try {
-    const entry = JSON.parse(fs15.readFileSync(lp, "utf-8"));
+    const entry = JSON.parse(fs16.readFileSync(lp, "utf-8"));
     return { locked: true, by: entry.agentId, since: entry.acquiredAt };
   } catch {
     return { locked: false };
@@ -11220,16 +11587,16 @@ function cleanStaleLocks() {
   ensureLocksDir();
   const dir = locksDir();
   let count = 0;
-  for (const f of fs15.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
+  for (const f of fs16.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
     try {
-      const entry = JSON.parse(fs15.readFileSync(path15.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs16.readFileSync(path16.join(dir, f), "utf-8"));
       if (Date.now() - entry.acquiredAt > 3e5) {
-        fs15.unlinkSync(path15.join(dir, f));
+        fs16.unlinkSync(path16.join(dir, f));
         count++;
       }
     } catch {
       try {
-        fs15.unlinkSync(path15.join(dir, f));
+        fs16.unlinkSync(path16.join(dir, f));
         count++;
       } catch {
       }
@@ -11245,8 +11612,8 @@ init_safetyAudit();
 
 // src/tools/kumaPolicy.ts
 init_pathValidator();
-import fs16 from "fs";
-import path16 from "path";
+import fs17 from "fs";
+import path17 from "path";
 var DEFAULT_POLICY = {
   never_touch: [
     ".env",
@@ -11272,15 +11639,15 @@ var DEFAULT_POLICY = {
 };
 function loadPolicy() {
   const root = getProjectRoot();
-  const ymlPath = path16.join(root, ".kuma", "policy.yml");
-  const yamlPath = path16.join(root, ".kuma", "policy.yaml");
+  const ymlPath = path17.join(root, ".kuma", "policy.yml");
+  const yamlPath = path17.join(root, ".kuma", "policy.yaml");
   let policyContent = null;
   let policyPath = null;
-  if (fs16.existsSync(ymlPath)) {
-    policyContent = fs16.readFileSync(ymlPath, "utf-8");
+  if (fs17.existsSync(ymlPath)) {
+    policyContent = fs17.readFileSync(ymlPath, "utf-8");
     policyPath = ymlPath;
-  } else if (fs16.existsSync(yamlPath)) {
-    policyContent = fs16.readFileSync(yamlPath, "utf-8");
+  } else if (fs17.existsSync(yamlPath)) {
+    policyContent = fs17.readFileSync(yamlPath, "utf-8");
     policyPath = yamlPath;
   }
   if (!policyContent) {
@@ -11390,9 +11757,9 @@ function checkFilePathPolicy(filePath, policy) {
   if (policy.max_file_size && policy.max_file_size > 0) {
     try {
       const root = getProjectRoot();
-      const fullPath = path16.join(root, filePath);
-      if (fs16.existsSync(fullPath)) {
-        const sizeKB = fs16.statSync(fullPath).size / 1024;
+      const fullPath = path17.join(root, filePath);
+      if (fs17.existsSync(fullPath)) {
+        const sizeKB = fs17.statSync(fullPath).size / 1024;
         if (sizeKB > policy.max_file_size) {
           violations.push({
             rule: "max_file_size",
@@ -11559,12 +11926,12 @@ async function safetyCheck(action, filePath, command) {
     }
     if (filePath) {
       try {
-        const fs26 = await import("fs");
-        const path26 = await import("path");
+        const fs27 = await import("fs");
+        const path27 = await import("path");
         const root = process.cwd();
-        const fullPath = path26.resolve(root, filePath);
-        if (fs26.existsSync(fullPath)) {
-          const stat = fs26.statSync(fullPath);
+        const fullPath = path27.resolve(root, filePath);
+        if (fs27.existsSync(fullPath)) {
+          const stat = fs27.statSync(fullPath);
           const sizeKB = Math.round(stat.size / 1024);
           if (sizeKB > 500) {
             checks.push({
@@ -11574,12 +11941,12 @@ async function safetyCheck(action, filePath, command) {
             });
           }
           if (filePath.endsWith(".ts") || filePath.endsWith(".js")) {
-            const baseName = path26.basename(filePath, path26.extname(filePath));
+            const baseName = path27.basename(filePath, path27.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.${path26.extname(filePath).slice(1)}`
+              `**/__tests__/**/${baseName}.test.${path27.extname(filePath).slice(1)}`
             ];
             let hasTests = false;
             const fg = await import("fast-glob");
@@ -11595,7 +11962,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 "${path26.basename(filePath)}" \u2014 consider adding tests`
+                detail: `\u{1F9EA} No test file found for "${path27.basename(filePath)}" \u2014 consider adding tests`
               });
             } else {
               checks.push({
@@ -11684,9 +12051,9 @@ init_sessionMemory();
 // src/guards/antiPatternDetector.ts
 init_pathValidator();
 init_sessionMemory();
-import fs17 from "fs";
-import path17 from "path";
-import { execSync as execSync5 } from "child_process";
+import fs18 from "fs";
+import path18 from "path";
+import { execSync as execSync6 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
   "writeFile",
@@ -11712,20 +12079,20 @@ function findPatchScripts(projectRoot) {
   const warnings = [];
   const recentFiles = scanRecentFiles(projectRoot);
   for (const file of recentFiles) {
-    const ext = path17.extname(file).toLowerCase();
+    const ext = path18.extname(file).toLowerCase();
     if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
-    const relativePath = path17.relative(projectRoot, file);
+    const relativePath = path18.relative(projectRoot, file);
     if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".") || relativePath.startsWith(".kuma/scratch")) {
       continue;
     }
     try {
-      const content = fs17.readFileSync(file, "utf-8").toLowerCase();
+      const content = fs18.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: ${path17.basename(file)}`,
+          message: `Created script file that modifies other files: ${path18.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
@@ -11759,15 +12126,15 @@ function detectBashGrepUsage() {
 function scanRecentFiles(projectRoot) {
   const recent = [];
   try {
-    const entries = fs17.readdirSync(projectRoot, { withFileTypes: true });
+    const entries = fs18.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 = fs17.statSync(path17.join(projectRoot, entry.name));
+        const stat = fs18.statSync(path18.join(projectRoot, entry.name));
         if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
-          recent.push(path17.join(projectRoot, entry.name));
+          recent.push(path18.join(projectRoot, entry.name));
         }
       } catch {
         continue;
@@ -11780,7 +12147,7 @@ function scanRecentFiles(projectRoot) {
 function detectGitPatchScripts(projectRoot) {
   const warnings = [];
   try {
-    const statusStdout = execSync5("git status --porcelain", {
+    const statusStdout = execSync6("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -11791,14 +12158,14 @@ function detectGitPatchScripts(projectRoot) {
         const prefix = line.substring(0, 2);
         if (prefix !== "??" && prefix !== "A ") continue;
         const file = line.substring(3).trim();
-        const ext = path17.extname(file).toLowerCase();
+        const ext = path18.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 = path17.join(projectRoot, file);
-        if (fs17.existsSync(fullPath)) {
-          const content = fs17.readFileSync(fullPath, "utf-8").toLowerCase();
+        const fullPath = path18.join(projectRoot, file);
+        if (fs18.existsSync(fullPath)) {
+          const content = fs18.readFileSync(fullPath, "utf-8").toLowerCase();
           const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
           if (matchedPattern) {
             warnings.push({
@@ -11813,7 +12180,7 @@ function detectGitPatchScripts(projectRoot) {
         }
       }
     }
-    const deletedStdout = execSync5("git diff --name-only --diff-filter=D HEAD", {
+    const deletedStdout = execSync6("git diff --name-only --diff-filter=D HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -11821,7 +12188,7 @@ function detectGitPatchScripts(projectRoot) {
     if (deletedStdout) {
       const deletedFiles = deletedStdout.split("\n").filter(Boolean);
       for (const file of deletedFiles) {
-        const ext = path17.extname(file).toLowerCase();
+        const ext = path18.extname(file).toLowerCase();
         if (SCRIPT_EXTENSIONS.includes(ext)) {
           warnings.push({
             severity: "high",
@@ -11883,21 +12250,21 @@ function detectAllAntiPatterns() {
 // src/engine/contextSnapshot.ts
 init_sessionMemory();
 init_pathValidator();
-import fs18 from "fs";
-import path18 from "path";
-import { execSync as execSync6 } from "child_process";
+import fs19 from "fs";
+import path19 from "path";
+import { execSync as execSync7 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
-  return path18.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+  return path19.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
 }
 function ensureSnapshotDir() {
   const dir = snapshotDir();
-  if (!fs18.existsSync(dir)) {
-    fs18.mkdirSync(dir, { recursive: true });
+  if (!fs19.existsSync(dir)) {
+    fs19.mkdirSync(dir, { recursive: true });
   }
 }
 function snapshotFilePath(timestamp) {
-  return path18.join(snapshotDir(), `${timestamp}.json`);
+  return path19.join(snapshotDir(), `${timestamp}.json`);
 }
 function saveSnapshot(goal) {
   try {
@@ -11918,7 +12285,7 @@ function saveSnapshot(goal) {
     hasConventions: !!summary.hasConventions
   };
   try {
-    fs18.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
+    fs19.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordToolCall("kuma_context", { action: "save", goal: snapshot.goal });
@@ -11957,7 +12324,7 @@ function formatSnapshot(snapshot) {
 function getGitDiffStat2() {
   try {
     const root = getProjectRoot();
-    const stdout = execSync6("git diff --stat", {
+    const stdout = execSync7("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout: 3e3
@@ -12229,12 +12596,12 @@ async function handleSecurity(params) {
   sessionMemory.recordToolCall("kuma_safety_security", {});
   if (params.filePath) {
     try {
-      const fs26 = await import("fs");
-      const path26 = await import("path");
+      const fs27 = await import("fs");
+      const path27 = await import("path");
       const root = process.cwd();
-      const fullPath = path26.resolve(root, params.filePath);
-      if (fs26.existsSync(fullPath) && fs26.statSync(fullPath).isFile()) {
-        const content = fs26.readFileSync(fullPath, "utf-8");
+      const fullPath = path27.resolve(root, params.filePath);
+      if (fs27.existsSync(fullPath) && fs27.statSync(fullPath).isFile()) {
+        const content = fs27.readFileSync(fullPath, "utf-8");
         const lines = content.split("\n");
         const findings = [];
         for (let i = 0; i < lines.length; i++) {
@@ -12288,23 +12655,23 @@ async function handleGitignore(_params) {
 }
 async function handleClean(_params) {
   sessionMemory.recordToolCall("kuma_safety_clean", {});
-  const fs26 = await import("fs");
-  const path26 = await import("path");
+  const fs27 = await import("fs");
+  const path27 = await import("path");
   const root = process.cwd();
-  const scratchDir = path26.resolve(root, ".kuma", "scratch");
+  const scratchDir = path27.resolve(root, ".kuma", "scratch");
   let removed = 0;
-  if (fs26.existsSync(scratchDir)) {
+  if (fs27.existsSync(scratchDir)) {
     try {
-      const entries = fs26.readdirSync(scratchDir);
+      const entries = fs27.readdirSync(scratchDir);
       for (const entry of entries) {
-        const fullPath = path26.join(scratchDir, entry);
+        const fullPath = path27.join(scratchDir, entry);
         try {
-          const stat = fs26.statSync(fullPath);
+          const stat = fs27.statSync(fullPath);
           if (stat.isFile()) {
-            fs26.unlinkSync(fullPath);
+            fs27.unlinkSync(fullPath);
             removed++;
           } else if (stat.isDirectory()) {
-            fs26.rmSync(fullPath, { recursive: true, force: true });
+            fs27.rmSync(fullPath, { recursive: true, force: true });
             removed++;
           }
         } catch {
@@ -12432,6 +12799,64 @@ async function handleVerify(params) {
   return verifyResult + recordingWarning;
 }
 
+// src/engine/kumaAutoInit.ts
+init_sessionMemory();
+var _initialized = false;
+var _initPromise = null;
+async function ensureInitialized() {
+  if (_initialized) return false;
+  if (_initPromise) {
+    await _initPromise;
+    return false;
+  }
+  _initPromise = doInit();
+  await _initPromise;
+  return true;
+}
+async function doInit() {
+  try {
+    sessionMemory.init({
+      projectRoot: process.cwd(),
+      startTime: Date.now()
+    });
+    try {
+      const sessionInfo = sessionMemory.loadSession();
+      if (sessionInfo.hasPrevSession) {
+        console.error(`[kuma:auto-init] \u2705 Restored session (${sessionInfo.toolCallCount} previous tool calls)`);
+      }
+    } catch {
+    }
+    try {
+      const { buildFromSessionMemory: buildFromSessionMemory2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+      const edgeCount = await buildFromSessionMemory2();
+      if (edgeCount > 0) {
+        console.error(`[kuma:auto-init] \u2705 Graph auto-populated with ${edgeCount} entries`);
+      }
+    } catch {
+    }
+    try {
+      const { buildSearchVectors: buildSearchVectors2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
+      await buildSearchVectors2();
+    } catch {
+    }
+    try {
+      const { getDb: getDb2, saveDb: saveDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+      const db = await getDb2();
+      db.run(
+        `INSERT INTO sessions (started_at, goal, tool_calls) VALUES (?, ?, ?)`,
+        [Math.floor(Date.now() / 1e3), "Auto-initialized", 0]
+      );
+      saveDb2(db);
+    } catch {
+    }
+    _initialized = true;
+    console.error(`[kuma:auto-init] \u2705 Zero-call auto-init complete`);
+  } catch (err) {
+    console.error(`[kuma:auto-init] \u26A0\uFE0F Auto-init error: ${err}`);
+    _initialized = true;
+  }
+}
+
 // src/manifest.ts
 function registerAllTools(server) {
   server.tool(
@@ -12448,6 +12873,7 @@ function registerAllTools(server) {
     },
     async (params) => {
       try {
+        await ensureInitialized();
         const text = await handleContext({
           action: params.action,
           scope: params.scope,
@@ -12504,6 +12930,7 @@ function registerAllTools(server) {
     },
     async (params) => {
       try {
+        await ensureInitialized();
         const text = await handleMemory({
           action: params.action,
           scope: params.scope,
@@ -12563,6 +12990,7 @@ function registerAllTools(server) {
     },
     async (params) => {
       try {
+        await ensureInitialized();
         const text = await handleSafety({
           action: params.action,
           guardGoal: params.guardGoal,
@@ -12590,6 +13018,8 @@ function registerAllTools(server) {
     }
   );
   console.error("[Manifest] Registered 3 V3 coarse-grained tools (kuma_context, kuma_memory, kuma_safety).");
+  console.error("[Manifest] Pilar 1: Auto-init hooks installed on all tools.");
+  console.error("[Manifest] Pilar 2: Namespace aliases active (kuma_kuma_* \u2192 kuma_*, context \u2192 kuma_context).");
 }
 
 // src/index.ts
@@ -12655,14 +13085,14 @@ async function main() {
     } catch {
     }
     try {
-      const path26 = await import("path");
-      const fs26 = await import("fs");
-      const lockDir = path26.resolve(process.cwd(), ".kuma/verifier.lock");
-      if (fs26.existsSync(lockDir)) {
-        const pidFile = path26.join(lockDir, "pid");
-        if (fs26.existsSync(pidFile)) {
+      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)) {
           try {
-            const pid = parseInt(fs26.readFileSync(pidFile, "utf-8"), 10);
+            const pid = parseInt(fs27.readFileSync(pidFile, "utf-8"), 10);
             if (pid && pid !== process.pid) {
               try {
                 process.kill(-pid, "SIGKILL");
@@ -12678,7 +13108,7 @@ async function main() {
           } catch {
           }
         }
-        fs26.rmSync(lockDir, { recursive: true, force: true });
+        fs27.rmSync(lockDir, { recursive: true, force: true });
       }
       if (killedCount === 0) {
         console.error("\u2705 No running verifications found to kill.");
@@ -12686,25 +13116,25 @@ async function main() {
     } catch {
     }
     try {
-      const { execSync: execSync7 } = await import("child_process");
+      const { execSync: execSync8 } = await import("child_process");
       try {
-        execSync7("pkill -f 'jest' 2>/dev/null || true");
+        execSync8("pkill -f 'jest' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'jest-worker' 2>/dev/null || true");
+        execSync8("pkill -f 'jest-worker' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'pnpm test' 2>/dev/null || true");
+        execSync8("pkill -f 'pnpm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'npm test' 2>/dev/null || true");
+        execSync8("pkill -f 'npm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'yarn test' 2>/dev/null || true");
+        execSync8("pkill -f 'yarn test' 2>/dev/null || true");
       } catch {
       }
       console.error("\u2705 Killed orphaned test processes");
@@ -12756,6 +13186,14 @@ async function main() {
     return;
   }
   if (args[0] === "--hook") {
+    const hookType = args[1] || "post-commit";
+    if (hookType === "post-commit") {
+      try {
+        const { harvestGitHistory: harvestGitHistory2 } = await Promise.resolve().then(() => (init_kumaGitHarvester(), kumaGitHarvester_exports));
+        await harvestGitHistory2({ commitCount: 1 });
+      } catch {
+      }
+    }
     process.exit(0);
   }
   if (args[0] === "init") {
@@ -12818,23 +13256,23 @@ async function main() {
     });
     const output = formatInitResults(results);
     console.log(output);
-    const fs26 = await import("fs");
-    const path26 = await import("path");
-    const matchaSkills = path26.resolve(process.cwd(), "skills/matcha/SKILL.md");
-    const matchaAgents = path26.resolve(
+    const fs27 = await import("fs");
+    const path27 = await import("path");
+    const matchaSkills = path27.resolve(process.cwd(), "skills/matcha/SKILL.md");
+    const matchaAgents = path27.resolve(
       process.cwd(),
       ".agents/skills/matcha/SKILL.md"
     );
-    const matchaRootSkills = path26.resolve(
+    const matchaRootSkills = path27.resolve(
       process.cwd(),
       "skills/matcha/SKILL.md"
     );
-    const matchaAgentsMd = path26.resolve(process.cwd(), "AGENTS.md");
-    const matchaWindsurfRules = path26.resolve(
+    const matchaAgentsMd = path27.resolve(process.cwd(), "AGENTS.md");
+    const matchaWindsurfRules = path27.resolve(
       process.cwd(),
       ".windsurf"
     );
-    if (fs26.existsSync(matchaSkills) || fs26.existsSync(matchaAgents) || fs26.existsSync(matchaRootSkills) || fs26.existsSync(matchaAgentsMd) || fs26.existsSync(matchaWindsurfRules)) {
+    if (fs27.existsSync(matchaSkills) || fs27.existsSync(matchaAgents) || fs27.existsSync(matchaRootSkills) || fs27.existsSync(matchaAgentsMd) || fs27.existsSync(matchaWindsurfRules)) {
       console.error(
         "\n\u{1F375} Hey, I see matcha is installed \u2014 they pair well together!"
       );
@@ -12848,13 +13286,13 @@ async function main() {
   (async () => {
     try {
       const { generateInitMdContent: generateInitMdContent2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      const fs26 = await import("fs");
-      const path26 = await import("path");
-      const initMdPath = path26.resolve(process.cwd(), ".kuma/init.md");
-      if (!fs26.existsSync(initMdPath)) {
-        const kumaDir = path26.dirname(initMdPath);
-        if (!fs26.existsSync(kumaDir)) fs26.mkdirSync(kumaDir, { recursive: true });
-        fs26.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
+      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");
         console.error(`[${SERVER_NAME}] Auto-generated .kuma/init.md`);
       }
     } catch (err) {
@@ -12865,8 +13303,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 fs26 = await import("fs");
-      const path26 = await import("path");
+      const fs27 = await import("fs");
+      const path27 = await import("path");
       const detection = detectAgent2();
       if (!detection.primary) {
         console.error(`[${SERVER_NAME}] No AI agent detected \u2014 skipping auto-skill creation`);
@@ -12874,22 +13312,22 @@ async function main() {
       }
       const agentType = detection.primary;
       const skillPath = getSkillPath2(agentType);
-      const fullPath = path26.resolve(process.cwd(), skillPath);
-      if (fs26.existsSync(fullPath)) {
+      const fullPath = path27.resolve(process.cwd(), skillPath);
+      if (fs27.existsSync(fullPath)) {
         console.error(`[${SERVER_NAME}] Skill exists for ${getAgentLabel2(agentType)} \u2014 skipping`);
         return;
       }
-      const dir = path26.dirname(fullPath);
-      if (!fs26.existsSync(dir)) fs26.mkdirSync(dir, { recursive: true });
-      fs26.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
+      const dir = path27.dirname(fullPath);
+      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
+      fs27.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 = path26.resolve(process.cwd(), sf.path);
-        const sfDir = path26.dirname(sfPath);
-        if (!fs26.existsSync(sfPath)) {
-          if (!fs26.existsSync(sfDir)) fs26.mkdirSync(sfDir, { recursive: true });
-          fs26.writeFileSync(sfPath, sf.content, "utf-8");
+        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");
           console.error(`[${SERVER_NAME}] Auto-created ${sf.path}`);
         }
       }
@@ -12914,11 +13352,11 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Graph auto-population: ${err}`);
       }
       try {
-        const fs26 = await import("fs");
-        const path26 = await import("path");
-        const scratchDir = path26.resolve(process.cwd(), ".kuma", "scratch");
-        if (!fs26.existsSync(scratchDir)) {
-          fs26.mkdirSync(scratchDir, { recursive: true });
+        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 });
           console.error(`[${SERVER_NAME}] \u2705 Created .kuma/scratch/ for temporary debug artifacts`);
         }
       } catch (err) {
@@ -12936,33 +13374,11 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Session DB record: ${err}`);
       }
       try {
-        const fs26 = await import("fs");
-        const path26 = await import("path");
-        const hooksDir = path26.resolve(process.cwd(), ".kuma", "hooks");
-        if (!fs26.existsSync(hooksDir)) {
-          fs26.mkdirSync(hooksDir, { recursive: true });
-          const hookContent = `#!/bin/bash
-# Kuma auto-capture hook (post-commit)
-# Auto-updates knowledge graph after git commits
-if command -v npx &> /dev/null; then
-  npx -y @plumpslabs/kuma --hook post-commit 2>/dev/null || true
-fi
-`;
-          const gitHooksDir = path26.resolve(process.cwd(), ".git", "hooks");
-          if (fs26.existsSync(gitHooksDir)) {
-            const postCommitPath = path26.join(gitHooksDir, "post-commit");
-            if (!fs26.existsSync(postCommitPath)) {
-              fs26.writeFileSync(postCommitPath, hookContent, "utf-8");
-              try {
-                fs26.chmodSync(postCommitPath, 493);
-              } catch {
-              }
-              console.error(`[${SERVER_NAME}] \u2705 Created .git/hooks/post-commit for auto-capture`);
-            }
-          }
-        }
+        const { installGitHook: installGitHook2 } = await Promise.resolve().then(() => (init_kumaGitHarvester(), kumaGitHarvester_exports));
+        const hookResult = installGitHook2();
+        console.error(`[${SERVER_NAME}] ${hookResult}`);
       } catch (err) {
-        console.error(`[${SERVER_NAME}] \u26A0\uFE0F Auto-capture hook setup: ${err}`);
+        console.error(`[${SERVER_NAME}] \u26A0\uFE0F Git hook setup: ${err}`);
       }
       try {
         const { buildSearchVectors: buildSearchVectors2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
@@ -12973,6 +13389,13 @@ fi
       } catch (err) {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Search vector cache: ${err}`);
       }
+      try {
+        const { buildGraphConnectivity: buildGraphConnectivity2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
+        await buildGraphConnectivity2();
+        console.error(`[${SERVER_NAME}] \u2705 Graph connectivity index built`);
+      } catch (err) {
+        console.error(`[${SERVER_NAME}] \u26A0\uFE0F Graph connectivity: ${err}`);
+      }
       console.error(`[${SERVER_NAME}] \u2705 Cold start bootstrap complete`);
     } catch (err) {
       console.error(`[${SERVER_NAME}] \u26A0\uFE0F Cold start bootstrap error: ${err}`);
@@ -12998,13 +13421,19 @@ fi
     `[${SERVER_NAME}] Session started: ${(/* @__PURE__ */ new Date()).toISOString()}`
   );
   console.error(
-    `[${SERVER_NAME}] Kuma V3 \u2014 Safety-first context & orchestration engine`
+    `[${SERVER_NAME}] Kuma v2.0 \u2014 Zero-Overhead Autonomous Brain Engine`
+  );
+  console.error(
+    `[${SERVER_NAME}] \u26A1 Auto-init: no manual init needed (Pilar 1)`
+  );
+  console.error(
+    `[${SERVER_NAME}] \u{1F4DB} Namespace normalized: kuma_kuma_* \u2192 kuma_* (Pilar 2)`
   );
   console.error(
-    `[${SERVER_NAME}] \u{1F9E0} Call kuma_context({ action: "init" }) at session start`
+    `[${SERVER_NAME}] \u{1F9F9} Noise filter: AST node types rejected (Pilar 4)`
   );
   console.error(
-    `[${SERVER_NAME}] \u{1F52C} Call kuma_context({ action: "research", scope: "..." }) before editing`
+    `[${SERVER_NAME}] \u{1F419} Git auto-harvester installed (Pilar 5)`
   );
   console.error(
     `[${SERVER_NAME}] \u{1F6E1}\uFE0F 3 coarse-grained tools: kuma_context, kuma_memory, kuma_safety`