@plumpslabs/kuma 2.3.29 → 2.3.31

package/dist/index.js

@@ -19,6 +19,8 @@ __export(pathValidator_exports, {
   getProjectRoot: () => getProjectRoot,
   isReadable: () => isReadable,
   isWritable: () => isWritable,
+  normalizeNodeId: () => normalizeNodeId,
+  normalizeScope: () => normalizeScope,
   validateFileExtension: () => validateFileExtension,
   validateFilePath: () => validateFilePath
 });
@@ -192,6 +194,23 @@ function getKumaDir() {
 function getKumaBackupsDir() {
   return path.join(getKumaDir(), "backups");
 }
+function normalizeScope(raw, projectRoot) {
+  if (!raw || !raw.trim()) return null;
+  const root = projectRoot ?? getProjectRoot();
+  let scope = raw.trim();
+  const lineMatch = scope.match(/^(.+):(\d+)$/);
+  if (lineMatch) scope = lineMatch[1];
+  scope = scope.replace(/\\/g, "/");
+  if (!scope.includes("/") && !scope.includes(".")) return scope;
+  const resolved = path.resolve(root, scope);
+  const relative = path.relative(root, resolved);
+  if (relative.startsWith("..")) return scope.replace(/^\.\//, "");
+  return relative.replace(/\\/g, "/");
+}
+function normalizeNodeId(type, rawName, projectRoot) {
+  const normalized = normalizeScope(rawName, projectRoot);
+  return normalized ? `${type}::${normalized}` : `${type}::${rawName}`;
+}
 var init_pathValidator = __esm({
   "src/utils/pathValidator.ts"() {
     "use strict";
@@ -207,6 +226,7 @@ __export(kumaDb_exports, {
   checkPortability: () => checkPortability,
   ensureGitignore: () => ensureGitignore,
   flushDb: () => flushDb,
+  generateNodeId: () => generateNodeId,
   getBenchmarkDiff: () => getBenchmarkDiff,
   getChanges: () => getChanges,
   getDb: () => getDb,
@@ -218,6 +238,7 @@ __export(kumaDb_exports, {
   listDecisionLog: () => listDecisionLog,
   listResearchCache: () => listResearchCache,
   listTodos: () => listTodos,
+  rebuildFtsIndex: () => rebuildFtsIndex,
   recordChange: () => recordChange,
   recordDecisionLog: () => recordDecisionLog,
   resetDbInstance: () => resetDbInstance,
@@ -236,6 +257,11 @@ __export(kumaDb_exports, {
 import initSqlJs from "sql.js";
 import fs2 from "fs";
 import path2 from "path";
+import crypto from "crypto";
+function generateNodeId(type, name) {
+  const uuid = crypto.randomUUID().slice(0, 8);
+  return `${type}::${uuid}::${name}`;
+}
 function resetDbInstance() {
   dbInstance = null;
   initPromise = null;
@@ -304,9 +330,26 @@ function createSchema(db) {
     name TEXT NOT NULL,
     file_path TEXT,
     metadata TEXT DEFAULT '{}',
+    severity TEXT DEFAULT 'medium',
+    confidence REAL DEFAULT 0.8,
+    last_verified_at INTEGER,
     created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
     updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
   )`);
+  try {
+    const schema = db.exec(`SELECT sql FROM sqlite_master WHERE type='table' AND name='nodes'`);
+    const nodesSql = schema[0]?.values?.[0]?.[0] || "";
+    if (!nodesSql.includes("severity")) {
+      db.run(`ALTER TABLE nodes ADD COLUMN severity TEXT DEFAULT 'medium'`);
+    }
+    if (!nodesSql.includes("confidence")) {
+      db.run(`ALTER TABLE nodes ADD COLUMN confidence REAL DEFAULT 0.8`);
+    }
+    if (!nodesSql.includes("last_verified_at")) {
+      db.run(`ALTER TABLE nodes ADD COLUMN last_verified_at INTEGER`);
+    }
+  } catch {
+  }
   db.run(`CREATE TABLE IF NOT EXISTS edges (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     source_id TEXT NOT NULL REFERENCES nodes(id),
@@ -1304,6 +1347,14 @@ async function getLatestVerifications(limit = 10) {
     return [];
   }
 }
+function rebuildFtsIndex() {
+  try {
+    const db = dbInstance;
+    if (!db) return;
+    db.run(`INSERT INTO nodes_fts(nodes_fts) VALUES('rebuild')`);
+  } catch {
+  }
+}
 var DB_FILENAME, dbInstance, initPromise, _saveTimeout, _pendingDb, SAVE_DEBOUNCE_MS;
 var init_kumaDb = __esm({
   "src/engine/kumaDb.ts"() {
@@ -1928,26 +1979,31 @@ No unresolved issues.`;
       }
       detectLoop() {
         this.ensureInit();
-        const recentCalls = this.state.toolCalls.slice(-10);
-        if (recentCalls.length < 6) return { isLooping: false };
+        const recentCalls = this.state.toolCalls.slice(-20);
+        if (recentCalls.length < 12) return { isLooping: false };
+        const CLEANUP_TOOLS = /* @__PURE__ */ new Set(["kuma_memory_delete", "kuma_memory", "delete_node"]);
         const toolCounts = /* @__PURE__ */ new Map();
         for (const call of recentCalls) {
           const existing = toolCounts.get(call.toolName);
           const action = call.params.action || "";
+          const paramKey = JSON.stringify({ action, scope: call.params.scope, target: call.params.target });
           if (existing) {
             existing.count++;
             existing.actions.add(action);
+            existing.params.add(paramKey);
           } else {
-            toolCounts.set(call.toolName, { count: 1, actions: /* @__PURE__ */ new Set([action]) });
+            toolCounts.set(call.toolName, { count: 1, actions: /* @__PURE__ */ new Set([action]), params: /* @__PURE__ */ new Set([paramKey]) });
           }
         }
-        for (const [toolName, { count, actions }] of toolCounts) {
-          if (count >= 4) {
+        for (const [toolName, { count, actions, params }] of toolCounts) {
+          if (count >= 10) {
+            if (CLEANUP_TOOLS.has(toolName)) continue;
+            if (params.size >= 5) continue;
             if (actions.size >= 3) continue;
             return {
               isLooping: true,
               toolName,
-              message: `Detected potential loop: "${toolName}" called ${count} times in last ${recentCalls.length} tool calls. Consider a different approach.`
+              message: `Detected potential runaway loop: "${toolName}" called ${count} times in last ${recentCalls.length} tool calls with no variation. Consider a different approach.`
             };
           }
         }
@@ -2097,10 +2153,19 @@ No unresolved issues.`;
 });
 
 // src/engine/kumaSelfHeal.ts
+var kumaSelfHeal_exports = {};
+__export(kumaSelfHeal_exports, {
+  autoHeal: () => autoHeal,
+  detectStaleNodes: () => detectStaleNodes,
+  formatGotchaStalenessReport: () => formatGotchaStalenessReport,
+  formatHealReport: () => formatHealReport,
+  healOnQuery: () => healOnQuery,
+  verifyGotchaStaleness: () => verifyGotchaStaleness
+});
 import { execSync as execSync2 } from "child_process";
 import fs4 from "fs";
 import path4 from "path";
-import crypto from "crypto";
+import crypto2 from "crypto";
 function contentFingerprint(filePath) {
   try {
     const fullPath = path4.join(getProjectRoot(), filePath);
@@ -2118,7 +2183,7 @@ function contentFingerprint(filePath) {
         tail = Buffer.alloc(1024);
         fs4.readSync(fd, tail, 0, 1024, size - 1024);
       }
-      const hash = crypto.createHash("md5");
+      const hash = crypto2.createHash("md5");
       hash.update(head);
       hash.update(tail);
       hash.update(String(size));
@@ -2191,6 +2256,11 @@ async function detectStaleNodes() {
             issue: contentMatch ? "path-changed" : "file-missing"
           });
         }
+      } else {
+        try {
+          db.run(`UPDATE nodes SET last_verified_at = strftime('%s','now') WHERE id = ?`, [row.id]);
+        } catch {
+        }
       }
     }
     stmt.free();
@@ -2200,8 +2270,9 @@ async function detectStaleNodes() {
   return stale;
 }
 function findRenamedPath(oldPath) {
+  const root = getProjectRoot();
+  const basename = path4.basename(oldPath);
   try {
-    const root = getProjectRoot();
     const output = execSync2(
       `git log --follow --diff-filter=R --name-only --format="" -1 -- "${oldPath}"`,
       { cwd: root, encoding: "utf-8", maxBuffer: 1024 * 1024, timeout: 5e3 }
@@ -2210,10 +2281,23 @@ function findRenamedPath(oldPath) {
       const lines = output.split("\n").filter(Boolean);
       return lines[lines.length - 1] || null;
     }
-    return null;
   } catch {
-    return null;
   }
+  try {
+    const result = execSync2(
+      `find . -name "${basename}" -type f -not -path "./node_modules/*" -not -path "./.git/*" -not -path "./dist/*" 2>/dev/null | head -5`,
+      { cwd: root, encoding: "utf-8", maxBuffer: 1024 * 1024, timeout: 5e3 }
+    ).trim();
+    if (result) {
+      const candidates = result.split("\n").filter(Boolean);
+      for (const c of candidates) {
+        const relative = c.startsWith("./") ? c.slice(2) : c;
+        if (relative !== oldPath) return relative;
+      }
+    }
+  } catch {
+  }
+  return null;
 }
 async function cascadeStaleEdges(nodeIds) {
   try {
@@ -2254,12 +2338,26 @@ async function healStaleNode(entry) {
       saveDb();
       return true;
     }
-    db.run(
-      `UPDATE nodes SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.stale', 1) WHERE id = ?`,
-      [entry.nodeId]
-    );
+    if (entry.type === "gotcha") {
+      db.run("DELETE FROM edges WHERE source_id = ? OR target_id = ?", [entry.nodeId, entry.nodeId]);
+      db.run("DELETE FROM nodes WHERE id = ?", [entry.nodeId]);
+      const parts = entry.nodeId.split("::");
+      if (parts.length >= 3) {
+        db.run("DELETE FROM known_gotchas WHERE file_path = ? AND description LIKE ?", [parts[1], `${parts.slice(2).join("::")}%`]);
+      }
+    } else if (entry.type === "research") {
+      db.run(
+        `UPDATE nodes SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.stale', 1, '$.stale_reason', 'file_missing') WHERE id = ?`,
+        [entry.nodeId]
+      );
+    } else {
+      db.run(
+        `UPDATE nodes SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.stale', 1, '$.stale_reason', 'file_missing') WHERE id = ?`,
+        [entry.nodeId]
+      );
+    }
     saveDb();
-    return false;
+    return entry.type === "gotcha";
   } catch (err) {
     console.error(`[KumaSelfHeal] Failed to heal node ${entry.nodeId}: ${err}`);
     return false;
@@ -2269,14 +2367,19 @@ async function autoHeal() {
   const stale = await detectStaleNodes();
   let healed = 0;
   let missing = 0;
+  let removed = 0;
   for (const entry of stale) {
     const success = await healStaleNode(entry);
-    if (success) healed++;
-    else missing++;
+    if (success) {
+      healed++;
+      removed++;
+    } else {
+      missing++;
+    }
   }
-  const staleNodeIds = stale.filter((e) => !e.newPath).map((e) => e.nodeId);
+  const staleNodeIds = stale.filter((e) => !e.newPath && e.type !== "gotcha").map((e) => e.nodeId);
   const cascadedEdges = await cascadeStaleEdges(staleNodeIds);
-  return { healed, missing, total: stale.length, cascadedEdges };
+  return { healed, missing, total: stale.length, cascadedEdges, removed };
 }
 async function healOnQuery(filePaths) {
   if (filePaths.length === 0) return { healed: 0 };
@@ -2315,6 +2418,7 @@ function formatHealReport(result) {
     "",
     `\u{1F4CA} ${result.total} stale entr${result.total > 1 ? "ies" : "y"} found`,
     `\u2705 ${result.healed} healed (file renamed \u2192 path updated)`,
+    result.removed > 0 ? `\u{1F5D1}\uFE0F ${result.removed} removed (obsolete gotcha referencing deleted file)` : "",
     `\u274C ${result.missing} missing (file deleted \u2014 marked as stale)`,
     result.cascadedEdges > 0 ? `\u{1F517} ${result.cascadedEdges} cascade edges updated` : "",
     ""
@@ -2322,12 +2426,81 @@ function formatHealReport(result) {
   if (result.healed > 0) {
     lines.push("\u{1F4A1} Healed entries had their file paths updated via git rename detection or content hash matching.");
   }
+  if (result.removed > 0) {
+    lines.push("\u{1F5D1}\uFE0F Obsolete gotchas (referencing deleted files) were removed from both graph and table.");
+  }
   if (result.missing > 0) {
     lines.push("\u26A0\uFE0F Missing entries were marked as stale. The Knowledge Graph will deprioritize them.");
-    lines.push("\u{1F4A1} Run incremental healing after making changes to keep the graph fresh.");
   }
   return lines.join("\n");
 }
+async function verifyGotchaStaleness() {
+  const db = await getDb();
+  const stale = [];
+  try {
+    const rows = db.exec(`
+      SELECT id, metadata FROM nodes WHERE type = 'gotcha'
+    `);
+    if (rows.length === 0) return stale;
+    const columns = rows[0].columns;
+    const filePathIdx = columns.indexOf("metadata");
+    for (const row of rows[0].values) {
+      const nodeId2 = row[0];
+      let metadata = {};
+      try {
+        metadata = JSON.parse(row[filePathIdx]);
+      } catch {
+      }
+      const filePath = metadata.file_path;
+      if (!filePath || filePath.startsWith("search::") || filePath.startsWith("api_route::")) continue;
+      const fullPath = path4.join(getProjectRoot(), filePath);
+      if (!fs4.existsSync(fullPath)) {
+        stale.push({ gotchaId: nodeId2, file_path: filePath, issue: "file_missing" });
+      } else {
+        const desc = metadata.description || "";
+        const symbolMatch = desc.match(/\b(function|class|method|const|let|var|export)\s+(\w+)/i);
+        if (symbolMatch) {
+          const symbolName = symbolMatch[2];
+          try {
+            const content = fs4.readFileSync(fullPath, "utf-8");
+            if (!content.includes(symbolName)) {
+              stale.push({ gotchaId: nodeId2, file_path: filePath, issue: "symbol_missing" });
+            }
+          } catch {
+          }
+        }
+      }
+    }
+  } catch {
+  }
+  return stale;
+}
+function formatGotchaStalenessReport(stale) {
+  if (stale.length === 0) {
+    return "\u2705 **Gotcha Staleness Check** \u2014 All gotcha references are valid.";
+  }
+  const fileMissing = stale.filter((s) => s.issue === "file_missing");
+  const symbolMissing = stale.filter((s) => s.issue === "symbol_missing");
+  const lines = [
+    `\u26A0\uFE0F **Gotcha Staleness Report**`,
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    "",
+    `\u{1F4CA} ${stale.length} stale gotcha${stale.length > 1 ? "s" : ""} found`,
+    fileMissing.length > 0 ? `  \u{1F5D1}\uFE0F ${fileMissing.length} reference${fileMissing.length > 1 ? "s" : ""} deleted file` : "",
+    symbolMissing.length > 0 ? `  \u{1F50D} ${symbolMissing.length} reference${symbolMissing.length > 1 ? "s" : ""} missing symbol` : "",
+    ""
+  ];
+  for (const s of fileMissing.slice(0, 5)) {
+    lines.push(`  \u{1F5D1}\uFE0F \`${s.gotchaId}\` \u2192 file missing: \`${s.file_path}\``);
+  }
+  for (const s of symbolMissing.slice(0, 5)) {
+    lines.push(`  \u{1F50D} \`${s.gotchaId}\` \u2192 symbol missing in \`${s.file_path}\``);
+  }
+  if (stale.length > 5) lines.push(`  ... and ${stale.length - 5} more`);
+  lines.push("");
+  lines.push("\u{1F4A1} Use `kuma_memory({ action: 'delete_node', target: '<gotchaId>' })` to remove obsolete gotchas.");
+  return lines.join("\n");
+}
 var init_kumaSelfHeal = __esm({
   "src/engine/kumaSelfHeal.ts"() {
     "use strict";
@@ -2363,7 +2536,10 @@ __export(kumaGraph_exports, {
   upsertNode: () => upsertNode
 });
 function nodeId(type, name) {
-  return `${type}::${name}`;
+  if (type === "file") {
+    return `file::${name}`;
+  }
+  return generateNodeId(type, name);
 }
 async function pruneGraphIfNeeded() {
   try {
@@ -2424,16 +2600,20 @@ async function upsertNode(node) {
     const db = await getDb();
     const id = node.id || nodeId(node.type, node.name);
     const metadata = JSON.stringify(node.metadata ?? {});
+    const severity = node.metadata?.severity || "medium";
+    const confidence = node.metadata?.confidence || 0.8;
     db.run(`
-      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
-      VALUES (?, ?, ?, ?, ?, strftime('%s','now'))
+      INSERT INTO nodes (id, type, name, file_path, metadata, severity, confidence, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, strftime('%s','now'))
       ON CONFLICT(id) DO UPDATE SET
         type = excluded.type,
         name = excluded.name,
         file_path = COALESCE(excluded.file_path, nodes.file_path),
         metadata = excluded.metadata,
+        severity = excluded.severity,
+        confidence = excluded.confidence,
         updated_at = strftime('%s','now')
-    `, [id, node.type, node.name, node.filePath || null, metadata]);
+    `, [id, node.type, node.name, node.filePath || null, metadata, severity, confidence]);
     try {
       db.run(`INSERT INTO nodes_fts (rowid, name, metadata) VALUES (last_insert_rowid(), ?, ?)`, [node.name, metadata]);
     } catch {
@@ -3087,14 +3267,7 @@ async function searchGraph(query, limit = 20) {
       }
       stmt2.free();
       if (results2.length > 0) {
-        const lines2 = [
-          `\u{1F50D} **Graph Search** \u2014 ${results2.length} result(s) for "${query}"`,
-          ""
-        ];
-        for (const r of results2) {
-          lines2.push(`  \u2022 **${r.name}** (${r.type})${r.file_path ? ` \u2014 ${r.file_path}` : ""}`);
-        }
-        return lines2.join("\n");
+        return formatSearchResults(results2, query, db);
       }
     } catch {
     }
@@ -3113,18 +3286,72 @@ async function searchGraph(query, limit = 20) {
     if (results.length === 0) {
       return await codebaseSearchFallback(query, limit);
     }
-    const lines = [
-      `\u{1F50D} **Graph Search** \u2014 ${results.length} result(s) for "${query}"`,
-      ""
-    ];
-    for (const r of results) {
-      lines.push(`  \u2022 **${r.name}** (${r.type})${r.file_path ? ` \u2014 ${r.file_path}` : ""}`);
-    }
-    return lines.join("\n");
+    return formatSearchResults(results, query, db);
   } catch (err) {
     return `Error searching graph: ${err}`;
   }
 }
+function formatSearchResults(results, query, db) {
+  const lines = [
+    `\u{1F50D} **Graph Search** \u2014 ${results.length} result(s) for "${query}"`,
+    ""
+  ];
+  const topResults = results.slice(0, 10);
+  for (const r of topResults) {
+    const nodeType = r.type;
+    const icon = nodeType === "gotcha" ? "\u26A0\uFE0F" : nodeType === "decision" ? "\u{1F4CC}" : nodeType === "arch_flow" ? "\u{1F3DB}\uFE0F" : nodeType === "flow_explanation" ? "\u{1F4DD}" : nodeType === "research" ? "\u{1F52C}" : "\u{1F4C4}";
+    lines.push(`${icon} **${r.name}** (${r.type})${r.file_path ? ` \u2014 ${r.file_path}` : ""}`);
+    try {
+      const stmtEdges = db.prepare(`
+        SELECT n2.id, n2.type, n2.name, e.type as edge_type
+        FROM edges e
+        JOIN nodes n2 ON n2.id = e.target_id
+        WHERE e.source_id = ?
+        LIMIT 5
+      `);
+      stmtEdges.bind([r.id]);
+      const connected = [];
+      while (stmtEdges.step()) {
+        connected.push(stmtEdges.getAsObject());
+      }
+      stmtEdges.free();
+      if (connected.length > 0) {
+        lines.push(`  \u21B3 connected to: ${connected.map((c) => `${c.name} (${c.type})`).join(", ")}`);
+      }
+    } catch {
+    }
+    if (nodeType === "feature_domain" || nodeType === "arch_flow") {
+      try {
+        const domainName = r.name.replace("feature_domain::", "").replace("arch_flow::", "");
+        const stmtProse = db.prepare(`
+          SELECT metadata FROM nodes WHERE type = 'flow_explanation' AND name LIKE ?
+          LIMIT 1
+        `);
+        stmtProse.bind([`%${domainName}%`]);
+        if (stmtProse.step()) {
+          const metaRow = stmtProse.getAsObject();
+          stmtProse.free();
+          let meta = {};
+          try {
+            meta = JSON.parse(metaRow.metadata);
+          } catch {
+          }
+          if (meta.prose) {
+            lines.push(`  \u{1F4DD} ${meta.prose}`);
+          }
+        } else {
+          stmtProse.free();
+        }
+      } catch {
+      }
+    }
+    lines.push("");
+  }
+  if (results.length > 10) {
+    lines.push(`... and ${results.length - 10} more results`);
+  }
+  return lines.join("\n");
+}
 async function codebaseSearchFallback(query, limit = 20) {
   try {
     const fg = (await import("fast-glob")).default;
@@ -5323,14 +5550,14 @@ __export(kumaDriftDetector_exports, {
 });
 import fs9 from "fs";
 import path9 from "path";
-import crypto2 from "crypto";
+import crypto3 from "crypto";
 function hashFile(filePath) {
   try {
     const root = getProjectRoot();
     const fullPath = path9.resolve(root, filePath);
     if (!fs9.existsSync(fullPath)) return null;
     const content = fs9.readFileSync(fullPath, "utf-8");
-    return crypto2.createHash("sha256").update(content).digest("hex");
+    return crypto3.createHash("sha256").update(content).digest("hex");
   } catch {
     return null;
   }
@@ -5436,7 +5663,7 @@ async function detectDrift() {
 }
 function computeScopeHash(scope) {
   try {
-    const hash = crypto2.createHash("sha256");
+    const hash = crypto3.createHash("sha256");
     const root = getProjectRoot();
     hash.update(scope);
     let found = false;
@@ -6343,6 +6570,7 @@ __export(kumaGotchas_exports, {
   addGotcha: () => addGotcha,
   checkGotchasForFile: () => checkGotchasForFile,
   listGotchas: () => listGotchas,
+  syncGotchasGraph: () => syncGotchasGraph,
   syncGotchasToDb: () => syncGotchasToDb
 });
 async function ensureGotchasSchema() {
@@ -6376,32 +6604,58 @@ async function addGotcha(entry) {
       entry.workaround ? `- **Workaround**: ${entry.workaround}` : "",
       `- **Added**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`
     ].filter(Boolean).join("\n");
-    db.run(
-      `INSERT INTO known_gotchas (file_path, description, severity, workaround) VALUES (?, ?, ?, ?)`,
-      [entry.filePath, entry.description, severity, entry.workaround || null]
+    const checkStmt = db.prepare(
+      `SELECT id FROM known_gotchas WHERE file_path = ? AND description LIKE ?`
     );
-    const mdResult = appendToLayer("gotcha", formatted);
-    try {
-      const { upsertNode: upsertNode2, addEdge: addEdge2, nodeId: nodeId2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-      const fileNodeId = nodeId2("file", entry.filePath);
-      const gotchaNodeId = `gotcha::${entry.filePath}::${entry.description.substring(0, 30)}`;
-      await upsertNode2({ id: fileNodeId, type: "file", name: entry.filePath });
-      await upsertNode2({
-        id: gotchaNodeId,
-        type: "gotcha",
-        name: `gotcha:${entry.description.substring(0, 40)}`,
-        filePath: entry.filePath,
-        metadata: { severity, workaround: entry.workaround }
-      });
-      await addEdge2({ sourceId: fileNodeId, targetId: gotchaNodeId, type: "depends_on" });
-    } catch {
+    checkStmt.bind([entry.filePath, `${entry.description.substring(0, 30)}%`]);
+    const existing = checkStmt.step();
+    let existingId = null;
+    if (existing) {
+      const row = checkStmt.getAsObject();
+      existingId = row.id;
+    }
+    checkStmt.free();
+    if (existingId !== null) {
+      db.run(
+        `UPDATE known_gotchas SET severity = ?, workaround = ?, updated_at = strftime('%s','now') WHERE id = ?`,
+        [severity, entry.workaround || null, existingId]
+      );
+    } else {
+      db.run(
+        `INSERT INTO known_gotchas (file_path, description, severity, workaround) VALUES (?, ?, ?, ?)`,
+        [entry.filePath, entry.description, severity, entry.workaround || null]
+      );
     }
+    const mdResult = appendToLayer("gotcha", formatted);
     saveDb();
+    rebuildFtsIndex();
     sessionMemory.recordToolCall("kuma_gotcha_add", {
       filePath: entry.filePath,
       severity
     });
-    return `\u2705 **Gotcha recorded**: ${entry.filePath} \u2014 ${entry.description}
+    let linkedCount = 0;
+    try {
+      const { addEdge: addEdge2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+      const stmt = db.prepare(`
+        SELECT id FROM nodes WHERE type = 'arch_flow'
+        AND (metadata LIKE ? OR file_path = ?)
+        LIMIT 5
+      `);
+      stmt.bind([`%${entry.filePath}%`, entry.filePath]);
+      while (stmt.step()) {
+        const row = stmt.getAsObject();
+        const gotchaNodeId = `gotcha::${entry.filePath}::${entry.description.substring(0, 30)}`;
+        try {
+          await addEdge2({ sourceId: gotchaNodeId, targetId: row.id, type: "triggers" });
+          linkedCount++;
+        } catch {
+        }
+      }
+      stmt.free();
+    } catch {
+    }
+    const action = existingId !== null ? "updated" : "recorded";
+    return `\u2705 **Gotcha ${action}**: ${entry.filePath} \u2014 ${entry.description}${linkedCount > 0 ? ` (linked to ${linkedCount} flow(s))` : ""}
 ${mdResult}`;
   } catch (err) {
     return `\u274C Failed to add gotcha: ${err}`;
@@ -6490,6 +6744,37 @@ async function syncGotchasToDb() {
     return { synced: 0 };
   }
 }
+async function syncGotchasGraph() {
+  try {
+    await ensureGotchasSchema();
+    const { upsertNode: upsertNode2, addEdge: addEdge2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+    const db = await getDb();
+    let created = 0;
+    const stmt = db.prepare(
+      `SELECT file_path, description, severity, workaround FROM known_gotchas`
+    );
+    const rows = [];
+    while (stmt.step()) rows.push(stmt.getAsObject());
+    stmt.free();
+    for (const g of rows) {
+      const fileNodeId = `file::${g.file_path}`;
+      const gotchaNodeId = `gotcha::${g.file_path}::${g.description.substring(0, 30)}`;
+      await upsertNode2({ id: fileNodeId, type: "file", name: g.file_path });
+      await upsertNode2({
+        id: gotchaNodeId,
+        type: "gotcha",
+        name: `gotcha:${g.description.substring(0, 40)}`,
+        filePath: g.file_path,
+        metadata: { severity: g.severity, workaround: g.workaround || void 0 }
+      });
+      await addEdge2({ sourceId: fileNodeId, targetId: gotchaNodeId, type: "depends_on" });
+      created++;
+    }
+    return { created };
+  } catch {
+    return { created: 0 };
+  }
+}
 var init_kumaGotchas = __esm({
   "src/engine/kumaGotchas.ts"() {
     "use strict";
@@ -6729,6 +7014,124 @@ var init_kumaGitHarvester = __esm({
   }
 });
 
+// src/engine/kumaSessionMiner.ts
+var kumaSessionMiner_exports = {};
+__export(kumaSessionMiner_exports, {
+  formatMinedInsights: () => formatMinedInsights,
+  mineSessionInsights: () => mineSessionInsights
+});
+function mineSessionInsights() {
+  const insights = [];
+  const toolCalls = sessionMemory.getToolCallHistory(50);
+  if (toolCalls.length < 3) return insights;
+  const editCounts = /* @__PURE__ */ new Map();
+  for (const call of toolCalls) {
+    if (call.toolName === "browser_edit" || call.toolName === "write" || call.toolName === "edit") {
+      const file = call.params.filePath || call.params.path || "";
+      if (file) editCounts.set(file, (editCounts.get(file) || 0) + 1);
+    }
+  }
+  for (const [file, count] of editCounts) {
+    if (count >= 3) {
+      insights.push({
+        type: "gotcha",
+        scope: file,
+        content: `File required ${count} edits in one session \u2014 may indicate underlying complexity or recurring issue`,
+        confidence: 0.6,
+        source: `edit_count:${count}:${file}`
+      });
+    }
+  }
+  for (let i = 0; i < toolCalls.length - 1; i++) {
+    const curr = toolCalls[i];
+    const next = toolCalls[i + 1];
+    if (curr.toolName === "bash" && next.toolName === "edit") {
+      const cmd = curr.params.command || "";
+      const file = next.params.filePath || "";
+      if ((cmd.includes("test") || cmd.includes("lint") || cmd.includes("typecheck")) && file) {
+        insights.push({
+          type: "gotcha",
+          scope: file,
+          content: `Test/lint failed then file was edited \u2014 likely a bug fix`,
+          confidence: 0.7,
+          source: `error_fix_sequence`
+        });
+      }
+    }
+  }
+  let pendingReads = [];
+  for (const call of toolCalls) {
+    if (call.toolName === "read" || call.toolName === "browser_read") {
+      const file = call.params.filePath || "";
+      if (file) pendingReads.push(file);
+    } else if (call.toolName === "edit" && pendingReads.length >= 2) {
+      const file = call.params.filePath || "";
+      if (file) {
+        insights.push({
+          type: "arch_flow",
+          scope: file,
+          content: `domain: ${file.split("/").pop()?.replace(/\.\w+$/, "") || "Unknown"} | hops: ${pendingReads.slice(0, 5).map((f) => f.split("/").pop() || f).join(" \u2192 ")}`,
+          confidence: 0.5,
+          source: `research_flow:${pendingReads.length}_reads`
+        });
+      }
+      pendingReads = [];
+    } else {
+      pendingReads = [];
+    }
+  }
+  for (let i = 0; i < toolCalls.length - 2; i++) {
+    const a = toolCalls[i];
+    const b = toolCalls[i + 1];
+    const c = toolCalls[i + 2];
+    if ((a.toolName === "read" || a.toolName === "browser_read") && (b.toolName === "read" || b.toolName === "browser_read") && c.toolName === "edit") {
+      const fileA = a.params.filePath || "";
+      const fileB = b.params.filePath || "";
+      const fileC = c.params.filePath || "";
+      if (fileA !== fileB && fileC) {
+        insights.push({
+          type: "decision",
+          scope: fileC,
+          content: `Read ${fileA.split("/").pop()} and ${fileB.split("/").pop()} before editing ${fileC.split("/").pop()} \u2014 compared options`,
+          confidence: 0.5,
+          source: `compare_then_choose`
+        });
+      }
+    }
+  }
+  return insights;
+}
+function formatMinedInsights(insights) {
+  if (insights.length === 0) {
+    return "\u{1F50D} **Session Mining** \u2014 No patterns detected. Session was clean.";
+  }
+  const lines = [
+    `\u{1F50D} **Session Mining** \u2014 ${insights.length} insight${insights.length > 1 ? "s" : ""} found`,
+    `\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\u2501\u2501\u2501\u2501\u2501`,
+    "",
+    "Review and approve/skip each suggestion:",
+    ""
+  ];
+  for (let i = 0; i < insights.length; i++) {
+    const ins = insights[i];
+    const icon = ins.type === "gotcha" ? "\u26A0\uFE0F" : ins.type === "decision" ? "\u{1F4CC}" : "\u{1F500}";
+    const conf = Math.round(ins.confidence * 100);
+    lines.push(`${i + 1}. ${icon} **${ins.type}** (${conf}% confidence)`);
+    lines.push(`   Scope: ${ins.scope}`);
+    lines.push(`   ${ins.content}`);
+    lines.push(`   \u2192 \`kuma_memory({ action: "${ins.type}", ${ins.type === "arch_flow" ? "content" : 'scope: \\"${ins.scope}\\", content'}: "${ins.content.substring(0, 60)}..." })\``);
+    lines.push("");
+  }
+  lines.push("\u{1F4A1} Approve by recording the ones you agree with. Skip the rest.");
+  return lines.join("\n");
+}
+var init_kumaSessionMiner = __esm({
+  "src/engine/kumaSessionMiner.ts"() {
+    "use strict";
+    init_sessionMemory();
+  }
+});
+
 // src/engine/safetyAudit.ts
 var safetyAudit_exports = {};
 __export(safetyAudit_exports, {
@@ -7975,7 +8378,7 @@ function detectTestRunner(root = process.cwd()) {
     } catch {
     }
   }
-  return { runner: "unknown", baseCommand: "npm test || echo 'No test runner configured'" };
+  return { runner: "unknown", baseCommand: "" };
 }
 function checkAllowed(root) {
   if (_localRunning) return "\u23F3 Verification already in progress (this instance).";
@@ -8029,6 +8432,25 @@ async function runAutoVerification(options = {}) {
     }
     _localRunning = true;
     const { runner, baseCommand } = detectTestRunner(root);
+    if (runner === "unknown" || !baseCommand) {
+      _localRunning = false;
+      releaseFileLock(root);
+      const durationMs = Date.now() - startTime;
+      const output = "\u2139\uFE0F No test framework detected. Install Jest, Vitest, pytest, or similar to enable verification.";
+      await saveVerification(scope, "none", "none", true, output, durationMs);
+      return [
+        `\u26AA **Verification: NO TESTS**`,
+        `\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`,
+        "",
+        `\u{1F6E0}\uFE0F **Runner**: \`none\` (no test framework detected)`,
+        `\u{1F3AF} **Scope**: \`${scope}\``,
+        `\u23F1\uFE0F **Duration**: ${durationMs}ms`,
+        "",
+        "\u2139\uFE0F No test framework detected. Install Jest, Vitest, pytest, or similar to enable verification.",
+        "",
+        "\u{1F4A1} **Tip:** This is NOT a pass \u2014 it means nothing was verified. Run your tests manually or install a test framework."
+      ].join("\n");
+    }
     let testFiles = [];
     const modified = sessionMemory.getModifiedFiles().map((f) => f.filePath);
     if (options.scope) {
@@ -8078,7 +8500,18 @@ async function runAutoVerification(options = {}) {
       const child = exec(fullCommand, { cwd: root, timeout: timeoutMs }, async (error, stdout, stderr) => {
         const durationMs = Date.now() - startTime;
         const rawOutput = (stdout + "\n" + stderr).trim();
-        const passed = !error;
+        let passed = !error;
+        const fakePassPatterns = [
+          /Missing script.*test/i,
+          /No test runner configured/i,
+          /No tests found/i,
+          /Cannot find.*test/i,
+          /0 passing/i,
+          /no test specified/i
+        ];
+        if (passed && fakePassPatterns.some((p) => p.test(rawOutput))) {
+          passed = false;
+        }
         const truncatedOutput = rawOutput.length > 2e3 ? rawOutput.substring(rawOutput.length - 2e3) : rawOutput;
         await saveVerification(scope, runner, fullCommand, passed, truncatedOutput, durationMs);
         _localRunning = false;
@@ -8097,11 +8530,17 @@ async function runAutoVerification(options = {}) {
           ""
         ];
         if (!passed) {
-          lines.push("\u26A0\uFE0F **Verification failed!** Please fix test failures before shipping.");
-          if (error && error.killed) {
-            lines.push(`\u23F0 **Process was killed after ${timeoutMs}ms timeout**`);
+          const isNoTests = fakePassPatterns.some((p) => p.test(rawOutput));
+          if (isNoTests) {
+            lines[0] = `\u26AA **Verification: NO TESTS**`;
+            lines.push("\u2139\uFE0F No tests ran. Install Jest, Vitest, pytest, or similar to enable verification.");
+          } else {
+            lines.push("\u26A0\uFE0F **Verification failed!** Please fix test failures before shipping.");
+            if (error && error.killed) {
+              lines.push(`\u23F0 **Process was killed after ${timeoutMs}ms timeout**`);
+            }
+            lines.push("```text", rawOutput.substring(0, 1500), "```");
           }
-          lines.push("```text", rawOutput.substring(0, 1500), "```");
         } else {
           lines.push("\u{1F389} All scoped tests passed!");
           if (rawOutput) lines.push("```text", rawOutput.substring(0, 800), "```");
@@ -8244,28 +8683,23 @@ function opencodeAgentsMdTemplate() {
   const opencodeLines = [
     "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
     '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-    "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
     "",
-    "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+    "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+    '  1. `kuma_kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
+    "  2. *(edit/read using native tools)*",
+    '  3. `kuma_kuma_context({ action: "changes" })` \u2014 Review session',
     "",
-    '  1. `kuma_kuma_context({ action: "init" })`                    \u2014 Load context (START HERE)',
-    '  2. `kuma_kuma_safety({ action: "guard" })`                    \u2014 Safety check before work',
-    '  3. `kuma_kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-    "  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 value)',
-    '  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 between options (preserves rationale)',
-    '  9. `kuma_kuma_safety({ action: "verify", ... })`              \u2014 Run tests / confirm nothing broken',
-    ' 10. `kuma_kuma_context({ action: "changes" })`                 \u2014 Review session activity',
+    "\u{1F4DD} **RECORD when needed (don't force it):**",
+    '  \u2022 Found a bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+    '  \u2022 Traced a flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
+    '  \u2022 Chose between options? \u2192 `kuma_kuma_memory({ action: "decision" })`',
     "",
-    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
-    "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
-    "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
-    "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
+    "\u{1F527} **ON-DEMAND (use when appropriate):**",
+    '  \u2022 `kuma_kuma_safety({ action: "guard" })` \u2014 before risky ops',
+    '  \u2022 `kuma_kuma_context({ action: "research" })` \u2014 before editing unfamiliar code',
+    '  \u2022 `kuma_kuma_safety({ action: "verify" })` \u2014 after edits',
     "",
-    "\u26A0\uFE0F **OpenCode platform note:** Tool names use `kuma_kuma_*` prefix",
-    "   (server name `kuma` + already-prefixed tool name `kuma_context`).",
+    "\u26A0\uFE0F **OpenCode note:** Tool names use `kuma_kuma_*` prefix.",
     ""
   ].join("\n");
   return [
@@ -8360,28 +8794,23 @@ function antigravitySkillTemplate() {
   const antigravityLines = [
     "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
     '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-    "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
     "",
-    "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+    "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+    '  1. `kuma_kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
+    "  2. *(edit/read using native tools)*",
+    '  3. `kuma_kuma_context({ action: "changes" })` \u2014 Review session',
     "",
-    '  1. `kuma_kuma_context({ action: "init" })`                    \u2014 Load context (START HERE)',
-    '  2. `kuma_kuma_safety({ action: "guard" })`                    \u2014 Safety check before work',
-    '  3. `kuma_kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-    "  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 value)',
-    '  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 between options (preserves rationale)',
-    '  9. `kuma_kuma_safety({ action: "verify", ... })`              \u2014 Run tests / confirm nothing broken',
-    ' 10. `kuma_kuma_context({ action: "changes" })`                 \u2014 Review session activity',
+    "\u{1F4DD} **RECORD when needed (don't force it):**",
+    '  \u2022 Found a bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+    '  \u2022 Traced a flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
+    '  \u2022 Chose between options? \u2192 `kuma_kuma_memory({ action: "decision" })`',
     "",
-    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
-    "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
-    "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
-    "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
+    "\u{1F527} **ON-DEMAND:**",
+    '  \u2022 `kuma_kuma_safety({ action: "guard" })` \u2014 before risky ops',
+    '  \u2022 `kuma_kuma_context({ action: "research" })` \u2014 before editing unfamiliar code',
+    '  \u2022 `kuma_kuma_safety({ action: "verify" })` \u2014 after edits',
     "",
-    "\u26A0\uFE0F **Antigravity platform note:** Tool names use `kuma_kuma_*` prefix",
-    "   (server name `kuma` + already-prefixed tool name `kuma_context`).",
+    "\u26A0\uFE0F **Antigravity note:** Tool names use `kuma_kuma_*` prefix.",
     ""
   ].join("\n");
   return [
@@ -8410,429 +8839,161 @@ function antigravityMcpConfigTemplate() {
 }
 function generateInitMdContent() {
   return [
-    "# Kuma Init \u2014 Mandatory Workflow",
+    "# Kuma Init \u2014 Workflow & Rules",
     "",
-    "_(Auto-generated by `kuma init` \u2014 edit this file directly to customize rules)_",
+    "_(Auto-generated by `kuma init` \u2014 edit this file to customize)_",
     "",
     "---",
     "",
-    "> \u26A0\uFE0F **Platform Tool Names:**",
+    "> **Platform Tool Names:**",
     '> \u2022 **OpenCode / Antigravity:** Use `kuma_kuma_*` prefix (e.g. `kuma_kuma_context({ action: "init" })`)',
-    '> \u2022 **Other platforms (Claude, Cursor, Cline, etc.):** Use `kuma_*` directly (e.g. `kuma_context({ action: "init" })`)',
-    "> \u2022 **Replace `kuma_` with `kuma_kuma_` in all examples below if you're on OpenCode.**",
+    '> \u2022 **Other platforms:** Use `kuma_*` directly (e.g. `kuma_context({ action: "init" })`)',
     "",
     "---",
     "",
-    "## \u26A0\uFE0F SESSION WORKFLOW \u2014 Follow Steps in Order",
-    "",
-    "### STEP 1: Init Session (ALWAYS \u2014 Start of Session)",
-    "```",
-    'kuma_context({ action: "init" })',
-    "```",
-    "**When:** Every session start or project switch",
-    "**Why:** Load project brief, restore session memory, populate knowledge graph",
+    "## SESSION WORKFLOW",
     "",
-    "### STEP 2: Safety Guard (ALWAYS \u2014 Before Work)",
-    "```",
-    'kuma_safety({ action: "guard", guardGoal: "describe your intent" })',
-    "```",
-    "**When:** After STEP 1, before research or editing",
-    "**Why:** Detect anti-patterns, code drift, runaway loops upfront",
+    "### DEFAULT: 3-Step Lean Workflow",
     "",
-    "### STEP 3: Research (MANDATORY \u2014 Before Editing Unfamiliar Code)",
-    "```",
-    'kuma_context({ action: "research", scope: "<target area>" })',
-    "```",
-    "**When:** Every time you plan to edit code in an unfamiliar area",
-    "**Why:** 5-step pipeline: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup",
+    "**For most tasks (edits, reads, simple changes):**",
     "",
-    "> \u26D4 DO NOT EDIT FILES BEFORE STEP 3 \u2014 Unless trivial/minor change",
+    '1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
+    "2. *(edit/read using native tools)*",
+    '3. `kuma_context({ action: "changes" })` \u2014 Review session',
     "",
-    "### STEP 4: EDIT/READ \u2014 Implement (Use Agent Native Tools)",
-    "```",
-    "# Use agent BUILT-IN tools to read, grep, edit, create files",
-    "# Kuma does NOT manage files \u2014 that's your agent's job",
-    "```",
+    "### ON-DEMAND: Extended Actions",
     "",
-    "> \u26A0\uFE0F **Research-only sessions included.** Workflow ini wajib meskipun session hanya membaca/riset tanpa code changes.",
-    "",
-    "> \u{1F9E0} **Graph Philosophy:** Record findings INLINE as you work, not just at the end. Every time you read a",
-    "> file, grep a pattern, or trace a flow \u2014 call `research_save` immediately to persist what you learned.",
-    "> The knowledge graph accumulates across sessions. The more you use it, the richer it becomes.",
-    "",
-    "> \u{1F52C} **Scanner vs Inline Recording:**",
-    "> \u2022 Scanner = cold start only. Auto-detects structure in TS/JS/TSX/JSX files during research step 3.",
-    "> \u2022 Inline Recording = primary method. You (the agent) record findings as you read/grep/edit.",
-    "> \u2022 Non-TS/JS projects (Go, Ruby, Python, Rust, PHP) rely ENTIRELY on inline recording.",
-    "",
-    "> \u{1F6E1}\uFE0F **Node Idempotency & Relational Integrity (Anti-Duplication & No Orphans):**",
-    "> \u2022 **Zero Duplicate Risk:** `research_save` and `add_node` are fully idempotent. Re-saving an existing scope/file updates metadata and timestamp without duplicating nodes.",
-    "> \u2022 **Zero Orphan Guarantee:** Every node created with a `filePath` or `scope` is automatically linked via a `contains` or `depends_on` edge to its parent file node.",
-    "> \u2022 **Always Connected:** Avoid recording standalone orphan entities; link findings to a core business domain or file path.",
-    "",
-    "**AUTO-RECORDED (cold start scanner \u2014 TS/JS only):**",
-    "- Files, Functions, Classes \u2192 scanned during research step 3",
-    "- Imports, Calls, Extends \u2192 scanned edges",
-    "- Components, Routes \u2192 scanned when patterns match",
-    "",
-    "\u{1F534} **MUST RECORD \u2014 High Impact (use MCP):**",
-    "- `arch_flow` \u2014 AFTER tracing COMPLETE flow (not per hop). Max 5 core files.",
-    "- `gotcha` \u2014 IMMEDIATELY when bug/quirk found. No re-research needed.",
-    "- `decision` \u2014 IMMEDIATELY when choosing. Preserves rationale context.",
-    "- `research_save` \u2014 After exploring area. Creates searchable cache + graph file node.",
-    "",
-    "\u{1F7E2} **SKIP \u2014 Low Impact (agent can grep faster):**",
-    "- Function/class nodes \u2192 grep `funcName(` / `class ClassName`",
-    "- Component nodes \u2192 glob `**/*ComponentName*`",
-    "- Import edges \u2192 check imports directly",
-    "- Route nodes \u2192 check router file directly",
-    "- Visual graph \u2192 for humans, not AI agents",
-    "",
-    "**RECORD INLINE \u2014 Focus on high-impact actions:**",
-    "- Finished tracing a flow? \u2192 `arch_flow` AFTER tracing COMPLETE flow (max 5 core files)",
-    "- Found a bug/quirk? \u2192 `gotcha` IMMEDIATELY (no re-research needed)",
-    "- Chose between options? \u2192 `decision` IMMEDIATELY (preserves rationale)",
-    "- Explored a new area? \u2192 `research_save` (creates searchable cache)",
-    "",
-    "**SKIP recording these \u2014 grep/glob is faster:**",
-    "- Function/class nodes \u2192 just `grep funcName(` or `grep class ClassName`",
-    "- Component/route nodes \u2192 glob directly",
-    "- Import edges \u2192 read import statements",
-    "- Visual graph \u2192 for humans, not AI",
-    "",
-    "### STEP 5: Save Research (RECORD INLINE \u2014 After Every Read/Grep)",
-    "```",
-    'kuma_memory({ action: "research_save", scope: "<file or area>", confidence: 0.8 })',
-    "```",
-    "**When:** After EVERY read/grep that discovers new files, functions, imports, or patterns. Don't wait \u2014 record inline!",
-    "**Why:** Persist findings into knowledge graph + research cache. Graph grows richer across sessions.",
+    "**Record only when something important happens:**",
+    '- Found a bug/quirk? \u2192 `kuma_memory({ action: "gotcha" })` IMMEDIATELY',
+    '- Traced a complete flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 core files)',
+    '- Chose between options? \u2192 `kuma_memory({ action: "decision" })` to preserve rationale',
+    '- Explored new area? \u2192 `kuma_memory({ action: "research_save", scope: "<file>" })`',
     "",
-    "### STEP 6: Record Gotchas (RECORD INLINE \u2014 When Bug Found)",
-    "```",
-    'kuma_memory({ action: "gotcha", scope: "<file>", content: "<description>", status: "medium" })',
-    "```",
-    "**When:** IMMEDIATELY when you discover bugs, quirks, unexpected behavior, or workarounds. Record INLINE, don't save for later.",
-    "**Why:** Prevents future agents from hitting the same issues. Every bug = a gotcha. Skip now = lost forever.",
+    "**Safety checks (use when appropriate):**",
+    '- Before risky edits: `kuma_safety({ action: "guard", guardGoal: "..." })`',
+    '- After edits: `kuma_safety({ action: "verify", scope: "<area>" })`',
+    '- Before research: `kuma_context({ action: "research", scope: "<area>" })`',
     "",
-    "**\u26A0\uFE0F Parameters:**",
-    "- `scope` \u2014 file path where the bug was found",
-    "- `content` \u2014 bug description",
-    "- `status` \u2014 severity: `low` | `medium` | `high` | `critical` (default: `medium`)",
-    "- `description` \u2014 optional workaround/fix description",
+    "### Recording Rules",
     "",
-    "### STEP 7: Record Arch Flow (RECORD COMPLETE FLOW \u2014 Core Logic Only)",
-    "```",
-    'kuma_memory({ action: "arch_flow", content: "domain: <name> | hops: <core_file1> \u2192 <core_file2> \u2192 <core_file3>" })',
-    "```",
-    "**When:** AFTER tracing a COMPLETE architecture flow (not per hop).",
-    "**Why:** Record flow architecture for future sessions without cluttering the graph.",
+    "**RECORD (high value):**",
+    "- `gotcha` \u2014 IMMEDIATELY when bug/quirk found (saves future agents from same issue)",
+    "- `arch_flow` \u2014 AFTER tracing COMPLETE flow (max 5 core files, skip UI/controllers/schemas)",
+    "- `decision` \u2014 IMMEDIATELY when choosing between options (preserves rationale)",
+    "- `research_save` \u2014 After exploring a new area (creates search cache)",
     "",
-    "**Rules:**",
-    "1. MAX 5 files per flow \u2014 record core business logic files only.",
-    "2. SKIP UI components (*.tsx, *.jsx), Controllers (*Controller.js), Schemas (*Schema.js), and simple CRUD services.",
-    "3. INCLUDE files with complex business logic, decision points, state mutations, or error handling.",
-    "4. Format hops separated by ` \u2192 ` (e.g. `domain: LeadDistributionFlow | hops: LeadRotationService.js \u2192 ProspectAssignmentService.js \u2192 ActivityLogService.js`).",
+    "**SKIP (low value):** function/class/component nodes \u2014 grep/glob is faster",
     "",
-    "**\u26A0\uFE0F CRITICAL FORMAT \u2014 Content MUST use this exact syntax:**",
+    "**\u26A0\uFE0F gotcha format:**",
     "```",
-    "domain: <DomainName> | hops: <core_file1.js> \u2192 <core_file2.js> \u2192 <core_file3.js> | gotchas: <optional> | decisions: <optional>",
+    'kuma_memory({ action: "gotcha", scope: "<file_path>", content: "<description>", status: "medium" })',
     "```",
-    "- `domain:` \u2014 short domain name (e.g. `InviteUserFlow`, `LeadManagementFlow`)",
-    "- `hops:` \u2014 max 5 core file names separated by ` \u2192 `",
-    "- `gotchas:` \u2014 optional comma-separated gotchas",
-    "- `decisions:` \u2014 optional comma-separated decisions",
+    "- `scope` \u2014 file path where the bug was found",
+    "- `content` \u2014 bug description",
+    "- `status` \u2014 severity: `low` | `medium` | `high` | `critical`",
     "",
-    "**Example:**",
+    "**\u26A0\uFE0F arch_flow format:**",
     "```",
-    "domain: InviteUserFlow | hops: invitationModal.tsx \u2192 useInviteMemberForm.ts \u2192 workspaceService.ts \u2192 workspaceController.js",
+    'kuma_memory({ action: "arch_flow", content: "domain: <Name> | hops: <file1> \u2192 <file2> \u2192 <file3>" })',
     "```",
+    "- MAX 5 files per flow \u2014 core business logic only",
+    "- SKIP UI components, Controllers, Schemas, simple CRUD",
+    "- INCLUDE files with complex logic, decision points, state mutations",
     "",
-    "### STEP 8: Record Decision (RECORD INLINE \u2014 When Choosing)",
+    "**\u26A0\uFE0F decision format:**",
     "```",
     'kuma_memory({ action: "decision", decisionAction: "record", title: "...", context: "...", rationale: "...", outcome: "..." })',
     "```",
-    "**When:** IMMEDIATELY when you choose between 2+ options, uncover an architecture pattern, or identify a root cause.",
-    "**Why:** Saves ADR (Architecture Decision Record). Bukan cuma code changes \u2014 temuan, tradeoffs, root causes juga.",
+    "- Required: `title` and `rationale`",
     "",
-    "**\u26A0\uFE0F Required:** `title` and `rationale`. Optional: `context`, `outcome`.",
+    "---",
     "",
-    "### STEP 9: Verify (MANDATORY \u2014 After Research/Editing)",
-    "```",
-    'kuma_safety({ action: "verify", scope: "<area or file>" })',
-    "```",
-    "**When:** After research/edits are done, before switching tasks. Even for research-only \u2014 confirms nothing is broken.",
-    '**Why:** Auto-run scoped tests + AST code validation. If no test framework, at minimum report "No tests to run".',
+    "## \u26A0\uFE0F HONEST LIMITATIONS",
     "",
-    "### STEP 10: Check Changes (MANDATORY \u2014 End of Session)",
-    "```",
-    'kuma_context({ action: "changes" })',
-    "```",
-    "**When:** End of session or before git commit. Even 0 changes = valid result to confirm.",
-    "**Why:** View session log of all modifications + tool calls made in this session.",
+    "- **Node IDs are text-based** \u2014 same file recorded with slightly different paths can create duplicates. Use `delete_node` to clean up.",
+    "- **Metadata is JSON** \u2014 format varies per node type. Studio displays all fields dynamically.",
+    "- **Gotchas have 2 stores** \u2014 `known_gotchas` table + `nodes` graph. `syncGotchasGraph()` keeps them in sync.",
+    "- **Edge weights are static** \u2014 `contains`=2.0, `flows_through`=1.0. Dynamic ranking not yet implemented.",
     "",
     "---",
     "",
     "## \u{1F4CB} Tool Reference",
     "",
-    "### \u{1F9E0} kuma_context \u2014 Context & Research",
-    "",
-    "| Action | Description | When to Call |",
-    "|--------|-------------|--------------|",
-    "| `init` | Load project brief, restore session | STEP 1 \u2014 Every session |",
-    "| `research` | 5-step research pipeline | STEP 3 \u2014 Before edits |",
-    "| `impact` | Analyze change effects on symbol | After research, before design |",
-    "| `navigate` | Trace code flow | When need to understand call flow |",
-    "| `changes` | View session change log | STEP 10 \u2014 End of session |",
-    "| `health` | Project health score 0-100 | Periodic check |",
-    "| `digest` | Ultra-compact project briefing | Session start (alt to init) |",
-    "| `drift` | Detect memory staleness | When suspecting stale context |",
-    "| `rollback` | Undo a change by change ID | After changes review |",
-    "| `researches` | List all cached research scopes | When need to find past research |",
-    "| `sync` | Unified batch state (init+health+memory) | Token-efficient session start |",
-    "| `visualize` | Mermaid knowledge graph diagram | Human debugging / overview |",
-    "",
-    "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
-    "",
-    "| Action | Description | When to Call |",
-    "|--------|-------------|--------------|",
-    "| `research_save` | Save research results | STEP 5 \u2014 After exploring area (creates search cache) |",
-    "| `gotcha` | Record bugs/quirks/workarounds | STEP 6 \u2014 \u{1F525} IMMEDIATELY when bug found (inline) |",
-    "| `arch_flow` | Document architecture flow | STEP 7 \u2014 After tracing COMPLETE flow, max 5 core files |",
-    "| `decision` | ADR-style decision record | STEP 8 \u2014 IMMEDIATELY when choosing (inline) |",
-    "| `mine` | Mine decisions from git log | When need historical context |",
-    "| `session` | Session summary | End of session |",
-    "| `heal` | Self-heal knowledge graph | When graph has errors |",
-    "| `search` | Search memories + graph | Find stored information |",
-    "| `todo` | Persistent todo CRUD | When managing tasks |",
-    "| `context` | Inject context notes | Additional notes when needed |",
-    "| `domain_rules` | Layer 1: business rules | Record business rules when discovered |",
-    "| `feature` | Record high-level feature with owns edges | Define features like 'Authentication', 'Billing' |",
-    "| `add_node` | Create structural nodes (low impact \u2014 grep faster) | Rarely; only for visualize debugging |",
-    "",
-    "| `delete_node` | Delete specific nodes, gotchas, todos, or decisions by ID | When you saved wrong data or need cleanup |",
-    "| `clear` | Wipe ALL graph nodes, edges, gotchas | Emergency reset \u2014 irreversible |",
-    "| `layers` | Show all 3 layers summary | Overview memory layers |",
-    "",
-    "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
-    "",
-    "| Action | Description | When to Call |",
-    "|--------|-------------|--------------|",
-    "| `guard` | Anti-pattern, drift, loop | STEP 2 \u2014 Before work |",
-    "| `verify` | Auto-run scoped tests + validation | STEP 9 \u2014 After research/edits |",
-    "| `check` | Pre-execution safety check | Before risky operations |",
-    "| `audit` | Query safety audit trail | Security investigation |",
-    "| `lock` | Multi-agent file lock | Multi-agent collaboration |",
-    "| `health` | Safety score 0-100 | Periodic check |",
-    "| `policy` | Policy-as-Code engine | Evaluate command/file paths |",
-    "| `ast` | AST-based code validation | Code correctness checks |",
-    "| `checkpoint` | Create atomic snapshot | Before major refactors |",
-    "| `rollback_label` | Restore from checkpoint | After checkpoint created |",
-    "| `checkpoint_list` | List all checkpoints | Review snapshots |",
-    "| `contract` | Pre/post-condition check | Contract verification |",
-    "| `override` | Logged safety bypass | When safe to bypass guard (with reason) |",
-    "| `security` | Security leak scanner | Periodic or pre-commit scan |",
-    "| `gc` | Garbage collection | Clean up old data |",
-    "| `doctor` | Health diagnostics | Troubleshoot issues |",
-    "| `portability` | Check path portability | Cross-platform validation |",
-    "| `gitignore` | Auto-configure .gitignore for .kuma/ | After project setup |",
-    "| `clean` | Purge scratch + drift warnings | After cleanup needed |",
-    "",
-    "### \u{1F4D0} Tool Format Quick Reference",
-    "",
-    "**add_node \u2014 Create manual structural nodes:**",
-    "```",
-    "kuma_memory({ action: 'add_node', title: '<type>', content: '<name>', scope: '<file_path>' })",
-    "```",
-    "- `title` \u2014 node type: `function` | `class` | `component` | `file` | `api_route` | `test`",
-    "- `content` \u2014 node name (e.g. function name, file path)",
-    "- `scope` \u2014 file where this node lives (creates `contains` edge automatically)",
-    "",
-    "**delete_node \u2014 Remove nodes/records:**",
-    "```",
-    "// Delete a graph node (by ID):",
-    "kuma_memory({ action: 'delete_node', target: 'function::sendMessage' })",
-    "",
-    "// Delete a record (by scope + numeric ID):",
-    "kuma_memory({ action: 'delete_node', scope: 'gotcha', target: '42' })",
-    "kuma_memory({ action: 'delete_node', scope: 'todo', target: '7' })",
-    "kuma_memory({ action: 'delete_node', scope: 'decision', target: '3' })",
-    "```",
-    "- Graph node IDs use `::` separator (e.g. `function::sendMessage`, `feature_domain::InviteUserFlow`)",
-    "- Record IDs are numeric (shown in list/search results)",
-    "- Deleting `feature_domain` cascade-deletes all `cross_service_link` and edges",
+    "### kuma_context \u2014 Context & Research",
+    "",
+    "| Action | Description |",
+    "|--------|-------------|",
+    "| `init` | Load project brief, restore session |",
+    "| `research` | 5-step research pipeline |",
+    "| `impact` | Analyze change effects |",
+    "| `navigate` | Trace code flow |",
+    "| `changes` | View session change log |",
+    "| `health` | Project health score 0-100 |",
+    "| `digest` | Ultra-compact project briefing |",
+    "| `drift` | Detect memory staleness |",
+    "| `rollback` | Undo a change by change ID |",
+    "",
+    "### kuma_memory \u2014 Knowledge Recording",
+    "",
+    "| Action | Description |",
+    "|--------|-------------|",
+    "| `gotcha` | Record bug/quirk (IMMEDIATELY when found) |",
+    "| `arch_flow` | Record architecture flow (max 5 core files) |",
+    "| `decision` | Record ADR / decision rationale |",
+    "| `research_save` | Cache research findings |",
+    "| `search` | Search knowledge graph |",
+    "| `session_mine` | Auto-extract insights from transcript |",
+    "| `delete_node` | Remove node + graph + table entries |",
+    "",
+    "### kuma_safety \u2014 Safety & Verification",
+    "",
+    "| Action | Description |",
+    "|--------|-------------|",
+    "| `guard` | Anti-pattern detection before edits |",
+    "| `verify` | Auto-run scoped tests after edits |",
+    "| `gotcha_staleness` | Verify gotcha file references |",
     "",
     "---",
     "",
-    "## \u{1F4CA} Knowledge Graph \u2014 Node Types & Shapes",
-    "",
-    "Kuma's knowledge graph visualizes your project structure. Each node type has a unique shape:",
-    "",
-    "| Shape | Node Type | Description | Auto/Manual |",
-    "|-------|-----------|-------------|-------------|",
-    "| \u25A2 `box` | function | Functions (named/arrow) | AUTO by scanner |",
-    "| \u2B21 `hexagon` | class | Classes (TS/JS) | AUTO by scanner |",
-    "| \u25C7 `diamond` | component | React/Vue components | AUTO by scanner |",
-    "| \u25A3 `square` | file | Source files | AUTO by scanner |",
-    "| \u25B2 `triangle` | api_route | API routes | AUTO by scanner |",
-    "| \u2B52 `star` | test | Test files/describes | AUTO by scanner |",
-    "| \u25CB `ellipse` | module | Directory modules | AUTO by scanner |",
-    "| \u{1F5C4}\uFE0F `cylinder` | db_table | Database tables | AUTO by scanner |",
-    "| \u{1F537} `diamond` | interface | TypeScript interfaces | AUTO by scanner |",
-    "| \u{1F538} `small_diamond` | type | Type aliases | AUTO by scanner |",
-    "| \u{1F539} `small_square` | variable | Variables/constants | AUTO by scanner |",
-    "| \u{1F504} `circle` | workflow | Workflow definitions | AUTO by scanner |",
-    "| \u{1F4C4} `note` | context | Manual context notes | MANUAL \u2014 kuma_memory context |",
-    "| \u2B50 `star` | feature | High-level feature (Authentication, Billing) | MANUAL \u2014 kuma_memory feature |",
-    "| \u{1F3DB}\uFE0F `pillar` | feature_domain | High-level feature domain anchor | MANUAL \u2014 kuma_memory arch_flow (domain:) |",
-    "| \u{1F517} `link` | cross_service_link | Cross-service/inter-file flow step | MANUAL \u2014 kuma_memory arch_flow (hops:) |",
-    "| \u{1F3F7}\uFE0F `tag` | domain_rule | Business rules (Layer 1) | MANUAL \u2014 kuma_memory domain_rules |",
-    "| \u{1F500} `flow` | arch_flow | Architecture flows (Layer 2) | MANUAL \u2014 kuma_memory arch_flow |",
-    "| \u26A0\uFE0F `warning` | gotcha | Known gotchas (Layer 3) | MANUAL \u2014 kuma_memory gotcha |",
-    "| \u{1F4CC} `milestone` | decision | Architecture decisions | MANUAL \u2014 kuma_memory decision |",
-    "| \u2705 `checklist` | todo | Persistent todos | MANUAL \u2014 kuma_memory todo |",
-    "",
-    "**Edges (connections between nodes):**",
-    "- `imports` \u2014 file imports another (AUTO)",
-    "- `calls` \u2014 function calls another (AUTO)",
-    "- `defines` \u2014 file defines function/class (AUTO)",
-    "- `depends_on` \u2014 logical dependency (AUTO + MANUAL)",
-    "- `extends` \u2014 class extends class (AUTO)",
-    "- `contains` \u2014 file contains function (AUTO)",
-    "- `composes` \u2014 component contains sub-component (AUTO)",
-    "- `owns` \u2014 domain/file owns file (MANUAL \u2014 arch_flow, feature)",
-    "- `affects` \u2014 impact propagation chain (MANUAL \u2014 arch_flow, feature)",
-    "- `flows_through` \u2014 flow step to next step (MANUAL \u2014 arch_flow)",
-    "- `triggers` \u2014 flow triggers action (MANUAL)",
-    "- `syncs_with` \u2014 cross-service sync (MANUAL)",
-    "- `modified_by` \u2014 file modified by action (AUTO)",
-    "- `references` \u2014 node references context note (MANUAL)",
+    "## \u{1F9E0} Session Memory",
     "",
-    "---",
-    "",
-    "## \u{1F4CC} Workflow Summary",
-    "",
-    "```",
-    "EVERY SESSION (Mandatory \u2014 including research-only):",
-    "  1. kuma_context   \u2192 init                \u2014 Load project context",
-    "  2. kuma_safety    \u2192 guard               \u2014 Safety check",
-    "  3. kuma_context   \u2192 research            \u2014 Research target area",
-    "  --- 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 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.",
-    "",
-    "ON DISCOVERY (When needed):",
-    "  kuma_memory \u2192 feature        \u2014 Record high-level feature (Authentication, Billing)",
-    "  kuma_memory \u2192 domain_rules   \u2014 Business rules (Layer 1)",
-    "  kuma_memory \u2192 context        \u2014 Additional notes",
-    "  kuma_memory \u2192 todo           \u2014 Task management",
-    "  kuma_memory \u2192 mine           \u2014 Historical context",
-    "  kuma_memory \u2192 add_node       \u2014 Manual function/class/component node (for visualize)",
-    "",
-    "GRAPH-AS-RETRIEVAL (search now includes):",
-    "  \u2022 Task-focused retrieval: top N relevant nodes for a task description",
-    "  \u2022 Impact analysis: which nodes are affected by a change",
-    "  \u2022 arch_flow now auto-creates affects edges for impact propagation",
-    "```",
+    "Session memory tracks tool calls, recordings, and tool health across the session.",
+    "It detects loops (10+ identical calls), suppresses cleanup noise, and provides context for guard checks.",
     "",
-    "## \u{1F9E0} How the Scanner Works",
-    "",
-    "Kuma's code scanner (`kumaCodeScanner.ts`) uses **lightweight regex-based pattern matching**",
-    "for **cold start** \u2014 giving new agents basic project structure on first session.",
-    "It is NOT a full AST parser (no Babel/TypeScript compiler dependency).",
-    "",
-    "**Scope:** TS/JS/TSX/JSX only. Non-TypeScript projects (Go, Ruby, Python, Rust, PHP, etc.)",
-    "rely entirely on **AI inline recording** \u2014 the agent records what it discovers as it works.",
-    "",
-    "**What auto-scanner detects (line-by-line regex, TS/JS only):**",
-    "- `function` declarations (named + async + generator)",
-    "- Arrow function assignments (`const foo = (...) => ...`)",
-    "- Typed arrow functions (`const foo: Type = (...) => ...`)",
-    "- Class declarations (includes extends/implements)",
-    "- React/Vue components (functions returning JSX)",
-    "- API route handlers (Express + Hono patterns)",
-    "- Import statements (local file imports only)",
-    "- Function calls cross-file (`calls` edges)",
-    "- Test files (`.test.`, `.spec.`, `__tests__/`)",
-    "",
-    "**Known limitations:**",
-    "- Regex-based: can miss multi-line constructs or non-standard patterns",
-    "- Complex generics or deeply nested syntax may not match",
-    "- TypeScript advanced types may be partially parsed",
-    "- Scanner runs during `kuma_context research` step 3 (max 200 files)",
-    "- If scanner returns 0 structural nodes, the regex patterns didn't match your code style",
-    "",
-    "**Key principle: Scanner = cold start, Inline Recording = primary.**",
-    "The scanner populates initial graph structure. Every subsequent session, the agent's",
-    "inline recording (research_save, gotcha, arch_flow, decision) enriches the graph further.",
-    "The more you use Kuma, the richer the graph becomes \u2014 persistent across sessions.",
+    "\u{1F4CA} **Metrics Tracked:**",
+    "- Tool call count & unique tools used",
+    "- Recording counts: arch_flows, gotchas, decisions, research_saves",
+    "- Error detection from bash/test output",
+    "- Loop detection: identical tool+params called 10+ times",
     "",
     "---",
     "",
-    "## \u{1F4BE} How to Retrieve Past Research \u2014 research_save \u2192 search",
+    "## \u{1F4CF} Guard Anti-Patterns",
     "",
-    "Kuma stores knowledge in two places. The primary retrieval method for AI agents",
-    "is **`search`**, not `visualize`. Visualize is for human debugging, not agent consumption.",
+    "The guard checks for common anti-patterns before editing:",
     "",
-    "**Flow: research_save \u2192 search (for agents)**",
-    '- Save: `kuma_memory({ action: "research_save", scope: "<file or area>", confidence: 0.8 })`',
-    '- Retrieve: `kuma_memory({ action: "search", query: "<term>" })`',
-    '- Auto-load: `kuma_context({ action: "research", scope: "<area>" })`',
-    '- List cache: `kuma_context({ action: "researches" })`',
-    "",
-    "**Key design:** `research_save` now creates BOTH research cache entries AND",
-    "knowledge graph nodes (file + research scope). This means `search` finds",
-    "past research even if the graph scanner didn't detect your code style.",
-    "",
-    "**Quick retrieval tips:**",
-    '- `kuma_memory({ action: "search", query: "<term>" })` \u2014 **primary method**. Finds past research + graph nodes + codebase',
-    '- `kuma_context({ action: "research", scope: "<area>" })` \u2014 deep 5-step research, auto-loads past cache',
-    '- `kuma_context({ action: "init" })` \u2014 shows graph stats + recent research + health score',
-    '- `kuma_context({ action: "drift" })` \u2014 check if memories are stale vs actual code',
-    '- `kuma_context({ action: "changes" })` \u2014 view session activity log',
-    '- `kuma_context({ action: "visualize" })` \u2014 (human debugging) Mermaid diagram of the graph',
+    "1. **Missing Research** \u2014 editing unfamiliar code without research",
+    "2. **Missing Recordings** \u2014 many tool calls with 0 recordings (knowledge loss)",
+    "3. **AST Anti-Patterns** \u2014 editing generated files, test snapshots, dist directories",
+    "4. **Scope Mismatch** \u2014 editing files outside declared scope",
+    "5. **Loop Detection** \u2014 same tool+params called 10+ times (param variation < 5)",
     "",
     "---",
     "",
-    "## \u{1F52C} How Verification Works",
+    "## \u{1F5D1}\uFE0F Graph Management",
     "",
-    '`kuma_safety({ action: "verify", scope: "<area>" })` \u2014 STEP 9',
+    '**Delete:** `kuma_memory({ action: "delete_node", target: "<node_id_or_type>" })`',
+    "- Deletes from graph nodes, edges, AND known_gotchas table (unified delete)",
     "",
-    "**Auto-detection logic:**",
-    "1. Checks `package.json` \u2192 `scripts.test` \u2192 uses npm/pnpm/yarn test",
-    "2. If no test script, checks for Makefile with `test:` target",
-    "3. Falls back to Python (pytest), Rust (cargo test), Go (go test)",
-    "4. Last resort: `npx tsc --noEmit` (TypeScript syntax check) or `node -c`",
-    "5. If nothing found: returns informative message instead of failing",
+    '**Clear entire graph:** `kuma_memory({ action: "clear" })`',
     "",
-    "**Important:** Verification is NEVER auto-triggered. You must call it explicitly.",
-    "The 5-layer safety guard (concurrency lock, rate limiting, staleness cache,",
-    "runaway detection, hard timeout) prevents resource exhaustion.",
+    '**Self-heal:** `kuma_safety({ action: "gotcha_staleness" })`',
+    "- Verifies gotcha file/symbol references still exist",
+    "- Removes obsolete gotchas (deleted files)",
     "",
     "---",
     "",
-    "## \u{1F6AB} What Kuma Does NOT Do (Use Agent Native Tools)",
-    "",
-    "| Function | Correct Tool |",
-    "|----------|-------------|",
-    "| Edit files | Agent native edit tools |",
-    "| Search code | Agent native grep/search |",
-    "| Run commands | Agent native terminal |",
-    "| Create files | Agent native file creation |",
-    "| Git operations | Agent native git tools |",
-    "| Lint/test | Agent native run commands |",
-    "",
-    "---",
-    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+    "_Generated by Kuma MCP_"
   ].join("\n");
 }
 function handleOpencodeSecondary(root, results) {
@@ -8847,28 +9008,19 @@ function handleOpencodeSecondary(root, results) {
       "---",
       "",
       "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
-      '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context and session memory.',
-      "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
+      '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
       "",
-      "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+      '  1. `kuma_kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
+      "  2. *(edit/read using native tools)*",
+      '  3. `kuma_kuma_context({ action: "changes" })` \u2014 Review session',
       "",
-      '  1. `kuma_kuma_context({ action: "init" })`                            \u2014 Load context (START HERE)',
-      '  2. `kuma_kuma_safety({ action: "guard" })`                            \u2014 Safety check before work',
-      '  3. `kuma_kuma_context({ action: "research", scope: "<area>" })`        \u2014 Research before editing',
-      "  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 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',
+      "\u{1F4DD} **RECORD when needed:**",
+      '  \u2022 Bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` | Flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` | Decision? \u2192 `kuma_kuma_memory({ action: "decision" })`',
       "",
-      "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
-      "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
-      "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
+      "\u{1F527} **ON-DEMAND:** guard (risky ops) | research (unfamiliar code) | verify (after edits)",
       "",
-      "\u26A0\uFE0F **OpenCode platform note:** Tool names are prefixed with `kuma_kuma_*`",
-      "   (server name `kuma` + already-prefixed tool name `kuma_context`).",
+      "\u26A0\uFE0F **OpenCode note:** Tool names use `kuma_kuma_*` prefix.",
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
@@ -8976,29 +9128,24 @@ function getCombinedAgentsMd(selectedTypes) {
     "",
     "---",
     "",
-    '> \u26A0\uFE0F **WARNING:** Agent often skip steps due to "research-only" bias. Do NOT skip.',
-    "> Follow the full 10-step workflow even for read-only investigations.",
+    "## SESSION WORKFLOW",
     "",
-    "## \u26A0\uFE0F MANDATORY WORKFLOW",
+    "**DEFAULT: 3-Step Lean Workflow** (for most tasks):",
     "",
-    "Follow these steps in order every session (including research-only):",
+    '  1. `[kuma_]context({ action: "init" })` \u2014 Load context (START HERE)',
+    "  2. *(edit/read using native tools)*",
+    '  3. `[kuma_]context({ action: "changes" })` \u2014 Review session',
     "",
-    '  1. `[kuma_]context({ action: "init" })`                     \u2014 Load project context (START HERE)',
-    '  2. `[kuma_]safety({ action: "guard" })`                     \u2014 Safety check before editing',
-    '  3. `[kuma_]context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-    "  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 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',
+    "**Record only when something important happens:**",
+    '- Found a bug/quirk? \u2192 `[kuma_]memory({ action: "gotcha" })` IMMEDIATELY',
+    '- Traced a complete flow? \u2192 `[kuma_]memory({ action: "arch_flow" })` (max 5 core files)',
+    '- Chose between options? \u2192 `[kuma_]memory({ action: "decision" })`',
     "",
-    "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
-    "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
-    "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
+    "**Safety checks (use when appropriate):**",
+    '- Before risky edits: `[kuma_]safety({ action: "guard", guardGoal: "..." })`',
+    '- After edits: `[kuma_]safety({ action: "verify", scope: "<area>" })`',
+    '- Before research: `[kuma_]context({ action: "research", scope: "<area>" })`',
     "",
-    "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
     "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` (delete node/gotcha/todo/decision) | `clear` (wipe entire graph)",
     "",
     "Replace `[kuma_]` with the correct prefix for your platform (see below).",
@@ -9618,31 +9765,25 @@ var init_init = __esm({
     };
     BOOTSTRAP_LINES = [
       "Kuma MCP tools are installed (kuma_context, kuma_memory, kuma_safety).",
-      '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
-      "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
+      '**Before coding, call `kuma_context({ action: "init" })`** to load project context.',
       "",
-      "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+      '  1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
+      "  2. *(edit/read using native tools)*",
+      '  3. `kuma_context({ action: "changes" })` \u2014 Review session',
       "",
-      '  1. `kuma_context({ action: "init" })`                     \u2014 Load context (START HERE)',
-      '  2. `kuma_safety({ action: "guard" })`                     \u2014 Safety check before work',
-      '  3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-      "  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 value)',
-      '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 After tracing COMPLETE flow (max 5 files)',
-      '  8. `kuma_memory({ action: "decision" })`                  \u2014 When choosing between options (preserves rationale)',
-      '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
-      ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
+      "\u{1F4DD} **RECORD when needed (don't force it):**",
+      '  \u2022 Found a bug? \u2192 `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '  \u2022 Traced a flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '  \u2022 Chose between options? \u2192 `kuma_memory({ action: "decision" })`',
       "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
-      "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
-      "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
-      "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
+      "\u{1F527} **ON-DEMAND (use when appropriate):**",
+      '  \u2022 `kuma_safety({ action: "guard" })` \u2014 before risky ops (deletions, refactors)',
+      '  \u2022 `kuma_context({ action: "research" })` \u2014 before editing unfamiliar code',
+      '  \u2022 `kuma_safety({ action: "verify" })` \u2014 after edits to confirm nothing broken',
       "",
-      "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
-      "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` (delete node/gotcha/todo/decision) | `clear` (wipe entire graph)",
-      "\u{1F4D6} Full rules: `.kuma/init.md`",
-      "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
+      "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` | `clear`",
+      "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
     KUMA_CORE_INSTRUCTIONS = BOOTSTRAP_LINES;
     TEMPLATES = {
@@ -10150,34 +10291,34 @@ var init_skillGenerator = __esm({
     BOOTSTRAP = [
       "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety).",
       '**Before coding, call `kuma_context({ action: "init" })`** to load project context.',
-      "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`/`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`",
+      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+      "  1. `init` \u2014 load context",
+      "  2. *(edit/read using native tools)*",
+      "  3. `changes` \u2014 review session",
       "",
-      "\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{1F4DD} **RECORD when needed (don't force it):**",
+      '  \u2022 Found a bug? \u2192 `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '  \u2022 Traced a flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '  \u2022 Chose between options? \u2192 `kuma_memory({ action: "decision" })`',
       "",
-      "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
-      "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
+      "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
     BOOTSTRAP_OPENCODE = [
       "Kuma MCP tools are available (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
       '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-      "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
-      "\u26A1 **ADAPTIVE WORKFLOW (Lean Mode by Default):**",
-      '  \u2022 **Lean Mode (Default, < 3 files):** `kuma_kuma_context({ action: "init" })` \u2192 edit/read \u2192 record (`decision`/`gotcha`)',
-      "  \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`",
+      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
+      "  1. `init` \u2014 load context",
+      "  2. *(edit/read using native tools)*",
+      "  3. `changes` \u2014 review session",
       "",
-      "\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{1F4DD} **RECORD when needed (don't force it):**",
+      '  \u2022 Found a bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '  \u2022 Traced a flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '  \u2022 Chose between options? \u2192 `kuma_kuma_memory({ action: "decision" })`',
       "",
-      "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
-      "\u{1F9E0} Tools: `kuma_kuma_context` | `kuma_kuma_memory` | `kuma_kuma_safety`"
+      "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
   }
 });
@@ -10199,7 +10340,7 @@ init_kumaMemory();
 init_pathValidator();
 import fs11 from "fs";
 import path11 from "path";
-import crypto3 from "crypto";
+import crypto4 from "crypto";
 var CONTEXT_ALIASES = {
   // Research synonyms
   "research": "research",
@@ -10677,7 +10818,7 @@ function computeProjectHash(scope) {
   try {
     const root = getProjectRoot();
     const files = fs11.readdirSync(root).slice(0, 20);
-    const hash = crypto3.createHash("md5");
+    const hash = crypto4.createHash("md5");
     hash.update(scope);
     for (const f of files) {
       try {
@@ -10712,8 +10853,10 @@ var ALLOWED_NODE_TYPES = /* @__PURE__ */ new Set([
   // High-level feature domains
   "file",
   // File references (needed for graph connectivity)
-  "research"
+  "research",
   // Research cache nodes (needed for search)
+  "flow_explanation"
+  // Prose explanation of arch_flow (semantic layer)
 ]);
 function isNodeTypeAllowed(type) {
   return ALLOWED_NODE_TYPES.has(type);
@@ -10747,6 +10890,7 @@ function getNoiseFilterPolicy() {
 
 // src/tools/kumaMemoryTool.ts
 init_pathValidator();
+init_pathValidator();
 import fs15 from "fs";
 import path15 from "path";
 var MEMORY_ALIASES = {
@@ -10798,6 +10942,13 @@ var MEMORY_ALIASES = {
   "notes": "context",
   "note": "context",
   "inject": "context",
+  // Harvest synonyms
+  "harvest": "harvest",
+  "session_mining": "harvest",
+  // Session mine synonyms
+  "session_mine": "session_mine",
+  "mine-session": "session_mine",
+  "extract-session": "session_mine",
   "context-note": "context",
   // Benchmark synonyms
   "benchmark": "benchmark",
@@ -10856,7 +11007,6 @@ var MEMORY_ALIASES = {
   "reset": "clear",
   "purge-all": "clear",
   // Harvest synonyms (Pilar 5)
-  "harvest": "harvest",
   "git-harvest": "harvest",
   "auto-harvest": "harvest",
   "git": "harvest",
@@ -10918,6 +11068,10 @@ async function handleMemory(params) {
     }
     case "harvest":
       return handleHarvest(params);
+    case "mine":
+      return handleMine(params);
+    case "session_mine":
+      return handleSessionMine(params);
     case "noise_policy":
       return getNoiseFilterPolicy();
     default:
@@ -10957,7 +11111,8 @@ Use kuma_memory({ action: 'decision', title: '...', context: '...', rationale: '
   }
 }
 async function handleResearchSave(params) {
-  const scope = params.scope || "project";
+  const rawScope = params.scope || "project";
+  const scope = normalizeScope(rawScope) || rawScope;
   const record = params.record || JSON.stringify({
     scope,
     confidence: params.confidence || 0.8,
@@ -10968,16 +11123,24 @@ async function handleResearchSave(params) {
   try {
     const { getDb: getDb2, flushDb: flushDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
     const db = await getDb2();
-    const fileId = `file::${scope}`;
     const researchId = `research::${scope}`;
     const now = Math.floor(Date.now() / 1e3);
-    db.run(`
-      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
-      VALUES (?, 'file', ?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
-        updated_at = excluded.updated_at
-    `, [fileId, scope, scope, JSON.stringify({ findings: [params.content || ""], confidence: params.confidence || 0.8 }), now]);
+    const looksLikeFile = scope.includes("/") || /\.\w{1,5}$/.test(scope);
+    if (looksLikeFile) {
+      const fileId = `file::${scope}`;
+      db.run(`
+        INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+        VALUES (?, 'file', ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
+          updated_at = excluded.updated_at
+      `, [fileId, scope, scope, JSON.stringify({ findings: [params.content || ""], confidence: params.confidence || 0.8 }), now]);
+      db.run(`
+        INSERT INTO edges (source_id, target_id, type, weight, metadata, created_at)
+        VALUES (?, ?, 'contains', 1.0, '{}', ?)
+        ON CONFLICT DO NOTHING
+      `, [fileId, researchId, now]);
+    }
     db.run(`
       INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
       VALUES (?, 'research', ?, null, ?, ?)
@@ -10985,12 +11148,12 @@ async function handleResearchSave(params) {
         metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
         updated_at = excluded.updated_at
     `, [researchId, `research:${scope}`, JSON.stringify({ confidence: params.confidence || 0.8, last_findings: params.content || "" }), now]);
-    db.run(`
-      INSERT INTO edges (source_id, target_id, type, weight, metadata, created_at)
-      VALUES (?, ?, 'contains', 1.0, '{}', ?)
-      ON CONFLICT DO NOTHING
-    `, [fileId, researchId, now]);
     flushDb2(db);
+    try {
+      const { rebuildFtsIndex: rebuildFtsIndex2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+      rebuildFtsIndex2();
+    } catch {
+    }
   } catch {
   }
   try {
@@ -11232,6 +11395,30 @@ async function handleLayerAction(layer, params) {
         const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
         const flow = await recordDomainFlow2({ domain, hops, gotchas, decisions, filePaths });
         await writeLayer2("arch_flow", content);
+        try {
+          const { upsertNode: upsertNode2, addEdge: addEdge2, nodeId: gNodeId } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+          const proseId = `flow_explanation::${domain}::prose`;
+          const prose = [
+            `This is the ${domain} flow.`,
+            `It starts at ${hops[0]?.from || "entry point"}.`,
+            ...hops.map((h, i) => `Step ${i + 1}: ${h.from} \u2192 ${h.to} (${h.description || h.relation})`),
+            gotchas.length > 0 ? `Watch out for: ${gotchas.join(", ")}` : "",
+            decisions.length > 0 ? `Decisions made: ${decisions.join(", ")}` : ""
+          ].filter(Boolean).join(" ");
+          await upsertNode2({
+            id: proseId,
+            type: "flow_explanation",
+            name: `prose:${domain}`,
+            metadata: { prose, hopsCount: hops.length, domain }
+          });
+          await addEdge2({
+            sourceId: proseId,
+            targetId: gNodeId("feature_domain", domain),
+            type: "explains",
+            metadata: { autoGenerated: true }
+          });
+        } catch {
+        }
         sessionMemory.recordMemoryAction("arch_flow");
         return `\u2705 Domain flow "${domain}" recorded \u2014 ${flow.nodeCount} nodes, ${flow.edgeCount} edges created.
 \u{1F3DB}\uFE0F **Domain Anchor:** ${domain}
@@ -11270,9 +11457,10 @@ async function handleGotchaAction(params) {
 
 \u2705 Correct: kuma_memory({ action: "gotcha", scope: "path/to/file.ts", content: "bug description", status: "high" })`;
     }
+    const normalizedScope = normalizeScope(params.scope) || params.scope;
     const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
     const result = await addGotcha2({
-      filePath: params.scope,
+      filePath: normalizedScope,
       description: params.content,
       severity: params.status || "medium",
       workaround: params.description
@@ -11297,9 +11485,24 @@ async function handleDeleteNode(params) {
     switch (params.scope) {
       case "gotcha":
       case "gotchas": {
+        const gotchaRow = db.prepare("SELECT file_path, description FROM known_gotchas WHERE id = ?");
+        gotchaRow.bind([id]);
+        let gotchaFilePath = "";
+        let gotchaDesc = "";
+        if (gotchaRow.step()) {
+          const row = gotchaRow.getAsObject();
+          gotchaFilePath = row.file_path;
+          gotchaDesc = row.description;
+        }
+        gotchaRow.free();
         db.run("DELETE FROM known_gotchas WHERE id = ?", [id]);
+        if (gotchaFilePath && gotchaDesc) {
+          const gotchaNodeId = `gotcha::${gotchaFilePath}::${gotchaDesc.substring(0, 30)}`;
+          db.run("DELETE FROM edges WHERE source_id = ? OR target_id = ?", [gotchaNodeId, gotchaNodeId]);
+          db.run("DELETE FROM nodes WHERE id = ?", [gotchaNodeId]);
+        }
         saveDb2(db);
-        return `\u{1F5D1}\uFE0F **Gotcha #${id} deleted.**`;
+        return `\u{1F5D1}\uFE0F **Gotcha #${id} deleted** (table + graph).`;
       }
       case "todo":
       case "todos": {
@@ -11337,6 +11540,15 @@ async function handleDeleteNode(params) {
             `gotcha::${domainName}::%`
           ]);
           db.run("DELETE FROM edges WHERE source_id LIKE ? OR target_id LIKE ?", [`%${domainName}%`, `%${domainName}%`]);
+        } else if (targetId.startsWith("gotcha::")) {
+          db.run("DELETE FROM edges WHERE source_id = ? OR target_id = ?", [targetId, targetId]);
+          db.run("DELETE FROM nodes WHERE id = ?", [targetId]);
+          const parts = targetId.split("::");
+          if (parts.length >= 3) {
+            const gotchaFilePath = parts[1];
+            const gotchaDesc = parts.slice(2).join("::");
+            db.run("DELETE FROM known_gotchas WHERE file_path = ? AND description LIKE ?", [gotchaFilePath, `${gotchaDesc}%`]);
+          }
         } else {
           db.run("DELETE FROM edges WHERE source_id = ? OR target_id = ?", [targetId, targetId]);
           db.run("DELETE FROM nodes WHERE id = ?", [targetId]);
@@ -11361,9 +11573,10 @@ async function handleDeleteNode(params) {
 async function handleAddNode(params) {
   const type = params.title;
   const name = params.content;
-  const filePath = params.scope;
+  const rawFilePath = params.scope;
+  const filePath = rawFilePath ? normalizeScope(rawFilePath) || rawFilePath : void 0;
   if (!type || !name) {
-    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' })";
+    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, flow_explanation\n\u274C Rejected: function, class, component, variable, method\n\nExample: kuma_memory({ action: 'arch_flow', content: 'domain: AuthFlow | hops: auth.ts \u2192 middleware.ts' })";
   }
   if (!isNodeTypeAllowed(type)) {
     return [
@@ -11493,6 +11706,54 @@ async function handleHarvest(params) {
   const dryRun = params.status === "dry-run" || params.status === "preview";
   return await harvestGitHistory2({ commitCount: count, dryRun });
 }
+async function handleSessionMine(_params) {
+  const { mineSessionInsights: mineSessionInsights2, formatMinedInsights: formatMinedInsights2 } = await Promise.resolve().then(() => (init_kumaSessionMiner(), kumaSessionMiner_exports));
+  const insights = mineSessionInsights2();
+  if (insights.length === 0) {
+    return formatMinedInsights2(insights);
+  }
+  if (_params.scope === "approve" || _params.limit === -1) {
+    let approved = 0;
+    for (const ins of insights) {
+      try {
+        if (ins.type === "gotcha") {
+          const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+          await addGotcha2({ filePath: ins.scope, description: ins.content, severity: ins.confidence > 0.7 ? "high" : "medium" });
+        } else if (ins.type === "decision") {
+          const { recordDecision: recordDecision2 } = await Promise.resolve().then(() => (init_kumaMemory(), kumaMemory_exports));
+          await recordDecision2({
+            title: ins.content.substring(0, 80),
+            context: ins.source,
+            options: [],
+            rationale: ins.content,
+            outcome: "session_mined",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } else if (ins.type === "arch_flow") {
+          const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+          const hops = ins.content.split("\u2192").map((h) => h.trim()).filter(Boolean);
+          if (hops.length >= 2) {
+            await recordDomainFlow2({
+              domain: ins.scope.split("/").pop()?.replace(/\.\w+$/, "") || "Unknown",
+              hops: hops.map((h, i) => ({
+                from: i === 0 ? "entry" : hops[i - 1],
+                to: h,
+                relation: "flows",
+                description: h
+              }))
+            });
+          }
+        }
+        approved++;
+      } catch {
+      }
+    }
+    sessionMemory.recordToolCall("kuma_memory_session_mine_approve", { count: approved });
+    return `\u2705 **Session Mining** \u2014 ${approved}/${insights.length} insights auto-recorded to Knowledge Graph.`;
+  }
+  sessionMemory.recordToolCall("kuma_memory_session_mine_preview", { count: insights.length });
+  return formatMinedInsights2(insights);
+}
 
 // src/tools/kumaSafetyTool.ts
 init_sessionMemory();
@@ -12538,6 +12799,8 @@ async function handleSafety(params) {
       return handleCheckpointList(params);
     case "contract":
       return handleContract(params);
+    case "gotcha_staleness":
+      return handleGotchaStaleness(params);
     default:
       return `Unknown action "${action}".`;
   }
@@ -12798,6 +13061,11 @@ async function handleVerify(params) {
   });
   return verifyResult + recordingWarning;
 }
+async function handleGotchaStaleness(_params) {
+  const { verifyGotchaStaleness: verifyGotchaStaleness2, formatGotchaStalenessReport: formatGotchaStalenessReport2 } = await Promise.resolve().then(() => (init_kumaSelfHeal(), kumaSelfHeal_exports));
+  const stale = await verifyGotchaStaleness2();
+  return formatGotchaStalenessReport2(stale);
+}
 
 // src/engine/kumaAutoInit.ts
 init_sessionMemory();