@plumpslabs/kuma 2.4.5 → 2.4.7

package/dist/index.js

@@ -1329,25 +1329,31 @@ var init_sessionMemory = __esm({
             const parsed = JSON.parse(raw);
             const storedBranch = parsed.currentBranch;
             const branchSwitched = Boolean(storedBranch && currentGitBranch && storedBranch !== currentGitBranch);
+            const lastActive = parsed.lastActiveAt || parsed.startTime || 0;
+            const isIdle = lastActive > 0 && Date.now() - lastActive > 2 * 3600 * 1e3;
+            const startTime = isIdle ? Date.now() : parsed.startTime || config.startTime;
+            const metrics = isIdle ? { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 } : parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 };
+            const toolCalls = isIdle ? [] : parsed.toolCalls || [];
             this.state = {
               projectRoot: parsed.projectRoot || config.projectRoot,
-              startTime: parsed.startTime || config.startTime,
+              startTime,
+              lastActiveAt: Date.now(),
               currentGoal: parsed.currentGoal || "",
               currentBranch: currentGitBranch || storedBranch || void 0,
               previousBranch: branchSwitched ? storedBranch : parsed.previousBranch,
               branchSwitched,
-              completedSteps: parsed.completedSteps || [],
+              completedSteps: isIdle ? [] : parsed.completedSteps || [],
               modifiedFiles: new Map(parsed.modifiedFiles || []),
               failedFiles: new Map(parsed.failedFiles || []),
               searchResults: new Map(parsed.searchResults || []),
               dependencyGraph: new Map(parsed.dependencyGraph || []),
-              toolCalls: parsed.toolCalls || [],
+              toolCalls,
               conventions: parsed.conventions,
               recordings: parsed.recordings || { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, features: 0, total: 0 },
-              metrics: parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
+              metrics
             };
             this.initialized = true;
-            console.error(`[SessionMemory] Loaded persistent session memory.json`);
+            console.error(`[SessionMemory] Loaded persistent session memory.json${isIdle ? " (idle reset applied)" : ""}`);
             return;
           } catch (err) {
             console.error(`[SessionMemory] Failed to load persistent session: ${err}. Re-initializing.`);
@@ -1508,6 +1514,7 @@ No unresolved issues.`;
           const serialized = {
             projectRoot: this.state.projectRoot,
             startTime: this.state.startTime,
+            lastActiveAt: this.state.lastActiveAt || Date.now(),
             currentGoal: this.state.currentGoal,
             currentBranch: this.state.currentBranch,
             previousBranch: this.state.previousBranch,
@@ -1908,6 +1915,32 @@ No unresolved issues.`;
       }
       getModifiedFiles() {
         this.ensureInit();
+        try {
+          const root = this.state.projectRoot;
+          const gitOut = execSync("git status --porcelain", {
+            cwd: root,
+            encoding: "utf-8",
+            timeout: 3e3,
+            stdio: ["pipe", "pipe", "pipe"]
+          }).trim();
+          if (gitOut) {
+            for (const line of gitOut.split("\n")) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+              const rawPath = trimmed.slice(2).trim();
+              const cleanPath = rawPath.replace(/^["']|["']$/g, "").split(" -> ").pop();
+              if (cleanPath.startsWith(".kuma/") || cleanPath.startsWith(".git/")) continue;
+              if (!this.state.modifiedFiles.has(cleanPath)) {
+                this.state.modifiedFiles.set(cleanPath, {
+                  filePath: cleanPath,
+                  modifiedAt: Date.now(),
+                  status: trimmed.startsWith("??") || trimmed.startsWith("A") ? "created" : "modified"
+                });
+              }
+            }
+          }
+        } catch {
+        }
         return Array.from(this.state.modifiedFiles.values());
       }
       getFailedFiles() {
@@ -2130,6 +2163,14 @@ No unresolved issues.`;
             projectRoot: process.cwd(),
             startTime: Date.now()
           });
+        } else if (this.state) {
+          const lastActive = this.state.lastActiveAt || this.state.startTime || 0;
+          if (lastActive > 0 && Date.now() - lastActive > 2 * 3600 * 1e3) {
+            this.state.startTime = Date.now();
+            this.state.metrics = { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 };
+            this.state.toolCalls = [];
+          }
+          this.state.lastActiveAt = Date.now();
         }
       }
     };
@@ -3481,7 +3522,8 @@ async function recordDomainFlow(params) {
       type: "feature_domain",
       name: params.domain,
       metadata: {
-        hops: params.hops.length,
+        hops: params.hops,
+        hopsCount: params.hops.length,
         gotchas: params.gotchas?.length || 0,
         decisions: params.decisions?.length || 0,
         filePaths: params.filePaths || [],
@@ -4554,7 +4596,7 @@ function scoreMemoryRelevance(context, limit = 5) {
   const results = [];
   const kumaDir = path9.join(getProjectRoot(), MEMORY_DIR);
   if (!fs8.existsSync(kumaDir)) return [];
-  const terms = context.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+  const terms = Array.from(new Set(context.toLowerCase().split(/[\s/._-]+/).filter((w) => w.length > 2)));
   if (terms.length === 0) return [];
   try {
     const files = fs8.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
@@ -4781,21 +4823,21 @@ function getActiveGotchas() {
     let currentSeverity = "";
     let currentStatus = "active";
     for (const line of lines) {
-      const fileMatch = line.match(/^###\s+(.+?)\s*[—–-]+\s*(.+)/);
+      const fileMatch = line.match(/^###\s+\[?(.+?)\]?\s*(?:[—–-]+\s*(.+))?$/);
       if (fileMatch) {
         if (currentFilePath && currentStatus !== "resolved" && currentStatus !== "deprecated") {
           results.push({ filePath: currentFilePath, description: currentDesc, severity: currentSeverity, content: currentSection });
         }
         currentFilePath = fileMatch[1].trim();
-        currentDesc = fileMatch[2].trim();
+        currentDesc = (fileMatch[2] || fileMatch[1]).trim();
         currentSeverity = "medium";
         currentStatus = "active";
         currentSection = line + "\n";
         continue;
       }
-      const sevMatch = line.match(/- \*\*Severity\*\*:\s*(\w+)/);
+      const sevMatch = line.match(/[-*]\s*(?:⚡\s*)?\*\*Severity\*\*:\s*(\w+)/i);
       if (sevMatch) currentSeverity = sevMatch[1].toLowerCase();
-      const statusMatch = line.match(/- \*\*Status\*\*:\s*(\w+)/);
+      const statusMatch = line.match(/[-*]\s*(?:🏷️\s*)?\*\*Status\*\*:\s*(\w+)/i);
       if (statusMatch) currentStatus = statusMatch[1].toLowerCase();
       currentSection += line + "\n";
     }
@@ -4809,8 +4851,10 @@ function getActiveGotchas() {
 function checkFileGotchas(filePath) {
   const gotchas = getActiveGotchas();
   const warnings = [];
+  const base = path10.basename(filePath);
   for (const g of gotchas) {
-    if (filePath.includes(g.filePath) || g.filePath.includes(filePath)) {
+    const gBase = path10.basename(g.filePath);
+    if (filePath.includes(g.filePath) || g.filePath.includes(filePath) || base && gBase && base === gBase) {
       const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
       warnings.push(`${icon} **Gotcha**: ${g.description} (${g.severity})`);
     }
@@ -4919,8 +4963,9 @@ function isGotchaFresh(storedHash, currentHash) {
   if (!currentHash) return true;
   return storedHash === currentHash;
 }
-async function getFreshGotchasForFile(filePath, limit = 5) {
+async function getFreshGotchasForFile(filePath, limit = 5, includeStale = false) {
   const root = getProjectRoot();
+  const base = path11.basename(filePath);
   try {
     const dbFile = path11.join(root, ".kuma", "kuma.db");
     if (fs10.existsSync(dbFile)) {
@@ -4930,44 +4975,58 @@ async function getFreshGotchasForFile(filePath, limit = 5) {
         SELECT id, file_path, description, severity, workaround, content_hash
         FROM known_gotchas
         WHERE status IN ('active', 'verified')
-          AND (file_path = ? OR ? LIKE ('%' || file_path || '%'))
+          AND (
+            file_path = ?
+            OR file_path LIKE ?
+            OR ? LIKE ('%' || file_path || '%')
+            OR file_path LIKE ?
+          )
         ORDER BY
-          CASE WHEN file_path = ? THEN 0 ELSE 1 END, -- exact match first
+          CASE WHEN file_path = ? THEN 0 WHEN file_path LIKE ? THEN 1 ELSE 2 END,
           CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END,
           updated_at DESC
         LIMIT ?
       `);
-      stmt.bind([filePath, filePath, filePath, limit]);
+      stmt.bind([filePath, `%${filePath}%`, filePath, `%${base}%`, filePath, `%${filePath}%`, limit * 2]);
       const rows = [];
       while (stmt.step()) rows.push(stmt.getAsObject());
       stmt.free();
-      const currentHash = hashFileContent(filePath);
-      return rows.map((r) => ({
-        id: r.id,
-        filePath: r.file_path,
-        description: r.description,
-        severity: r.severity,
-        workaround: r.workaround ?? null,
-        stale: !isGotchaFresh(r.content_hash ?? null, currentHash)
-      })).filter((g) => !g.stale).slice(0, limit);
+      if (rows.length > 0) {
+        const currentHash = hashFileContent(filePath);
+        const mapped = rows.map((r) => ({
+          id: r.id,
+          filePath: r.file_path,
+          description: r.description,
+          severity: r.severity,
+          workaround: r.workaround ?? null,
+          stale: !isGotchaFresh(r.content_hash ?? null, currentHash)
+        }));
+        const filtered = includeStale ? mapped : mapped.filter((g) => !g.stale);
+        return filtered.slice(0, limit);
+      }
     }
   } catch {
   }
   try {
     if (!fs10.existsSync(path11.join(root, ".kuma"))) return [];
-    const { checkFileGotchas: checkFileGotchas2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
-    const warnings = checkFileGotchas2(filePath);
-    if (warnings.length === 0) return [];
-    return warnings.slice(0, limit).map((w) => ({
-      filePath,
-      description: w,
-      severity: "medium",
-      workaround: null,
-      stale: false
-    }));
+    const { getActiveGotchas: getActiveGotchas2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
+    const allGotchas = getActiveGotchas2();
+    const matched = allGotchas.filter(
+      (g) => g.filePath.includes(filePath) || filePath.includes(g.filePath) || base && path11.basename(g.filePath) === base
+    );
+    if (matched.length > 0) {
+      return matched.slice(0, limit).map((g) => ({
+        filePath: g.filePath,
+        description: g.description,
+        severity: g.severity,
+        workaround: null,
+        stale: false
+      }));
+    }
   } catch {
     return [];
   }
+  return [];
 }
 async function getFileTrace(filePath, limit = 8) {
   try {
@@ -5015,14 +5074,81 @@ function formatFileTrace(entries, filePath) {
   return lines.join("\n");
 }
 async function getDecisionsForFile(filePath, limit = 3) {
+  const decisions = [];
+  const root = getProjectRoot();
+  const base = path11.basename(filePath);
+  const baseWithoutExt = base.replace(/\.[^.]+$/, "");
+  try {
+    const decisionsMdPath = path11.join(root, ".kuma", "memories", "decisions.md");
+    if (fs10.existsSync(decisionsMdPath)) {
+      const content = fs10.readFileSync(decisionsMdPath, "utf-8");
+      const sections = content.split(/^##\s+/m);
+      for (const section of sections) {
+        if (!section.trim() || section.startsWith("# ")) continue;
+        const sectionLines = section.split("\n");
+        const title = sectionLines[0].trim();
+        const sectionText = section.toLowerCase();
+        const matches = sectionText.includes(filePath.toLowerCase()) || sectionText.includes(base.toLowerCase()) || baseWithoutExt.length > 3 && sectionText.includes(baseWithoutExt.toLowerCase());
+        if (matches) {
+          let rationale = "";
+          for (const line of sectionLines) {
+            const rMatch = line.match(/^[-*]\s*\*\*Rationale:\*\*\s*(.+)$/i);
+            if (rMatch) {
+              rationale = rMatch[1].trim();
+              break;
+            }
+            const oMatch = line.match(/^[-*]\s*\*\*Outcome:\*\*\s*(.+)$/i);
+            if (!rationale && oMatch) {
+              rationale = oMatch[1].trim();
+            }
+          }
+          decisions.push(`\u{1F4CC} ${title}${rationale ? ` \u2014 *${rationale}*` : ""}`);
+          if (decisions.length >= limit) return decisions;
+        }
+      }
+    }
+  } catch {
+  }
+  try {
+    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const stmt = db.prepare(`
+      SELECT name, metadata FROM nodes
+      WHERE type = 'decision'
+        AND (name LIKE ? OR metadata LIKE ? OR name LIKE ? OR metadata LIKE ?)
+      LIMIT ?
+    `);
+    stmt.bind([`%${base}%`, `%${base}%`, `%${baseWithoutExt}%`, `%${baseWithoutExt}%`, limit]);
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      try {
+        const meta = JSON.parse(row.metadata || "{}");
+        const title = row.name.replace(/^ADR:\s*/, "");
+        const reason = meta.rationale || meta.context || meta.outcome || "";
+        const formatted = `\u{1F4CC} ${title}${reason ? ` \u2014 *${reason.substring(0, 100)}*` : ""}`;
+        if (!decisions.includes(formatted)) {
+          decisions.push(formatted);
+        }
+      } catch {
+      }
+    }
+    stmt.free();
+    if (decisions.length >= limit) return decisions.slice(0, limit);
+  } catch {
+  }
   try {
     const { scoreMemoryRelevance: scoreMemoryRelevance2 } = await Promise.resolve().then(() => (init_kumaMemory(), kumaMemory_exports));
-    const base = path11.basename(filePath);
-    const scored = scoreMemoryRelevance2(`${filePath} ${base}`, limit);
-    return scored.map((m) => `\u{1F4CC} ${m.topic} \u2014 ${m.score}% match (${m.reason})`);
+    const searchTerms = `${filePath} ${base} ${baseWithoutExt}`.replace(/[\/._-]/g, " ");
+    const scored = scoreMemoryRelevance2(searchTerms, limit);
+    for (const m of scored) {
+      const formatted = `\u{1F4CC} ${m.topic} \u2014 ${m.content ? m.content.substring(0, 80) : `${m.score}% match`}`;
+      if (!decisions.includes(formatted)) {
+        decisions.push(formatted);
+      }
+    }
   } catch {
-    return [];
   }
+  return decisions.slice(0, limit);
 }
 async function getRelevantContext(filePath, goal) {
   const parts = [];
@@ -5253,6 +5379,7 @@ __export(kumaGotchas_exports, {
   resolveGotcha: () => resolveGotcha,
   resolveGotchasForScope: () => resolveGotchasForScope,
   setGotchaStatus: () => setGotchaStatus,
+  syncGotchaStatusToMarkdown: () => syncGotchaStatusToMarkdown,
   syncGotchasGraph: () => syncGotchasGraph,
   syncGotchasToDb: () => syncGotchasToDb
 });
@@ -5339,15 +5466,17 @@ async function addGotcha(entry) {
     const severity = entry.severity || "medium";
     const status = entry.status || "active";
     const contentHash = hashFileContent(entry.filePath);
+    const trap = entry.description;
+    const ruleFix = entry.workaround || "Review implementation carefully before modifying.";
     const formatted = [
-      `### ${entry.filePath} \u2014 ${entry.description}`,
-      `- **Issue**: ${entry.description}`,
-      `- **Severity**: ${severity}`,
-      entry.workaround ? `- **Workaround**: ${entry.workaround}` : "",
-      entry.triggerCommand ? `- **Trigger**: when running \`${entry.triggerCommand}\`` : "",
-      entry.status ? `- **Status**: ${entry.status}` : "",
-      entry.scopePackage ? `- **Scope Package**: ${entry.scopePackage}` : "",
-      `- **Added**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`
+      `### ${entry.filePath} \u2014 ${trap}`,
+      `- \u{1FAA4} **Trap**: ${trap}`,
+      `- \u{1F6E1}\uFE0F **Rule/Fix**: ${ruleFix}`,
+      `- \u26A1 **Severity**: ${severity}`,
+      entry.triggerCommand ? `- \u2328\uFE0F **Trigger**: when running \`${entry.triggerCommand}\`` : "",
+      entry.status ? `- \u{1F3F7}\uFE0F **Status**: ${status}` : "",
+      entry.scopePackage ? `- \u{1F4E6} **Scope Package**: ${entry.scopePackage}` : "",
+      `- \u{1F4C5} **Added**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`
     ].filter(Boolean).join("\n");
     const checkStmt = db.prepare(
       `SELECT id FROM known_gotchas WHERE file_path = ? AND description LIKE ?`
@@ -5533,13 +5662,14 @@ async function resolveGotchasForScope(scope) {
     const db = await getDb();
     const stmt = db.prepare(
       `SELECT id, file_path, content_hash FROM known_gotchas
-       WHERE status = 'active' AND file_path LIKE ? AND content_hash IS NOT NULL`
+       WHERE status = 'active' AND (file_path LIKE ? OR file_path = ?) AND content_hash IS NOT NULL`
     );
-    stmt.bind([`%${scope}%`]);
+    stmt.bind([`%${scope}%`, scope]);
     const rows = [];
     while (stmt.step()) rows.push(stmt.getAsObject());
     stmt.free();
     let resolved = 0;
+    const resolvedPaths = [];
     for (const r of rows) {
       const current = hashFileContent(r.file_path);
       if (current && current !== r.content_hash) {
@@ -5548,9 +5678,13 @@ async function resolveGotchasForScope(scope) {
           [r.id]
         );
         resolved++;
+        resolvedPaths.push(r.file_path);
       }
     }
-    if (resolved > 0) saveDb();
+    if (resolved > 0) {
+      saveDb();
+      syncGotchaStatusToMarkdown([scope, ...resolvedPaths], "resolved", "auto-verified");
+    }
     return { resolved };
   } catch {
     return { resolved: 0 };
@@ -5656,14 +5790,73 @@ async function getGotchasByStatus(status, limit = 20) {
     return [];
   }
 }
+function syncGotchaStatusToMarkdown(targetPaths, newStatus, reason) {
+  try {
+    const mdPath = path12.join(getProjectRoot(), ".kuma", "KNOWN_GOTCHAS.md");
+    if (!fs11.existsSync(mdPath)) return false;
+    const content = fs11.readFileSync(mdPath, "utf-8");
+    const lines = content.split("\n");
+    const normalizedTargets = targetPaths.map((p) => p.trim().toLowerCase()).filter(Boolean);
+    if (normalizedTargets.length === 0) return false;
+    let modified = false;
+    const outputLines = [];
+    let inMatchingSection = false;
+    let sectionHasStatus = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(/^###\s+\[?(.+?)\]?\s*(?:[—–-]+\s*(.+))?$/);
+      if (headingMatch) {
+        if (inMatchingSection && !sectionHasStatus) {
+          outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+          modified = true;
+        }
+        const headingFile = headingMatch[1].trim().toLowerCase();
+        const headingBase = path12.basename(headingFile);
+        inMatchingSection = normalizedTargets.some(
+          (t) => headingFile.includes(t) || t.includes(headingFile) || headingBase === t || headingBase === path12.basename(t)
+        );
+        sectionHasStatus = false;
+        outputLines.push(line);
+        continue;
+      }
+      if (inMatchingSection) {
+        const statusMatch = line.match(/^(\s*[-*]\s*(?:🏷️\s*)?\*\*Status\*\*:\s*)(.*)$/i);
+        if (statusMatch) {
+          outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+          sectionHasStatus = true;
+          modified = true;
+          continue;
+        }
+      }
+      outputLines.push(line);
+    }
+    if (inMatchingSection && !sectionHasStatus) {
+      outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+      modified = true;
+    }
+    if (modified) {
+      fs11.writeFileSync(mdPath, outputLines.join("\n"), "utf-8");
+    }
+    return modified;
+  } catch {
+    return false;
+  }
+}
 async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent") {
   try {
     await ensureGotchasSchema();
     const db = await getDb();
     let resolved = 0;
     const isId = typeof idOrScope === "number" || /^\d+$/.test(String(idOrScope).trim());
+    const targetPaths = [];
     if (isId) {
       const id = Number(idOrScope);
+      const findStmt = db.prepare(`SELECT file_path FROM known_gotchas WHERE id = ?`);
+      findStmt.bind([id]);
+      if (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'resolved', verified_by = ?, last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ? AND status != 'resolved'`,
         [verifiedBy, id]
@@ -5671,12 +5864,22 @@ async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent")
       resolved = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     } else {
       const scope = String(idOrScope).trim();
+      targetPaths.push(scope);
+      const findStmt = db.prepare(`SELECT DISTINCT file_path FROM known_gotchas WHERE (file_path = ? OR file_path LIKE ?)`);
+      findStmt.bind([scope, `%${scope}%`]);
+      while (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'resolved', verified_by = ?, last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE (file_path = ? OR file_path LIKE ?) AND status != 'resolved'`,
         [verifiedBy, scope, `%${scope}%`]
       );
       resolved = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     }
+    if (targetPaths.length > 0) {
+      syncGotchaStatusToMarkdown(targetPaths, "resolved", resolutionReason);
+    }
     if (resolved > 0) {
       saveDb();
       rebuildFtsIndex();
@@ -5685,6 +5888,13 @@ async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent")
         message: `\u2705 Resolved ${resolved} gotcha(s) for "${idOrScope}"${resolutionReason ? `: ${resolutionReason}` : ""}.`
       };
     }
+    const mdUpdated = syncGotchaStatusToMarkdown(targetPaths.length > 0 ? targetPaths : [String(idOrScope)], "resolved", resolutionReason);
+    if (mdUpdated) {
+      return {
+        resolved: 1,
+        message: `\u2705 Resolved gotcha in KNOWN_GOTCHAS.md for "${idOrScope}"${resolutionReason ? `: ${resolutionReason}` : ""}.`
+      };
+    }
     return { resolved: 0, message: `\u26A0\uFE0F No active gotchas found matching "${idOrScope}".` };
   } catch (err) {
     return { resolved: 0, message: `\u274C Failed to resolve gotcha: ${err}` };
@@ -5696,8 +5906,15 @@ async function deprecateGotcha(idOrScope, reason) {
     const db = await getDb();
     let deprecated = 0;
     const isId = typeof idOrScope === "number" || /^\d+$/.test(String(idOrScope).trim());
+    const targetPaths = [];
     if (isId) {
       const id = Number(idOrScope);
+      const findStmt = db.prepare(`SELECT file_path FROM known_gotchas WHERE id = ?`);
+      findStmt.bind([id]);
+      if (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'deprecated', verified_by = 'deprecation', last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ? AND status != 'deprecated'`,
         [id]
@@ -5705,12 +5922,22 @@ async function deprecateGotcha(idOrScope, reason) {
       deprecated = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     } else {
       const scope = String(idOrScope).trim();
+      targetPaths.push(scope);
+      const findStmt = db.prepare(`SELECT DISTINCT file_path FROM known_gotchas WHERE (file_path = ? OR file_path LIKE ?)`);
+      findStmt.bind([scope, `%${scope}%`]);
+      while (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'deprecated', verified_by = 'deprecation', last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE (file_path = ? OR file_path LIKE ?) AND status != 'deprecated'`,
         [scope, `%${scope}%`]
       );
       deprecated = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     }
+    if (targetPaths.length > 0) {
+      syncGotchaStatusToMarkdown(targetPaths, "deprecated", reason);
+    }
     if (deprecated > 0) {
       saveDb();
       rebuildFtsIndex();
@@ -5719,6 +5946,13 @@ async function deprecateGotcha(idOrScope, reason) {
         message: `\u{1F9F9} Deprecated ${deprecated} gotcha(s) for "${idOrScope}"${reason ? `: ${reason}` : ""}.`
       };
     }
+    const mdUpdated = syncGotchaStatusToMarkdown(targetPaths.length > 0 ? targetPaths : [String(idOrScope)], "deprecated", reason);
+    if (mdUpdated) {
+      return {
+        deprecated: 1,
+        message: `\u{1F9F9} Deprecated gotcha in KNOWN_GOTCHAS.md for "${idOrScope}"${reason ? `: ${reason}` : ""}.`
+      };
+    }
     return { deprecated: 0, message: `\u26A0\uFE0F No active gotchas found matching "${idOrScope}".` };
   } catch (err) {
     return { deprecated: 0, message: `\u274C Failed to deprecate gotcha: ${err}` };
@@ -6477,7 +6711,8 @@ var kumaFlowCache_exports = {};
 __export(kumaFlowCache_exports, {
   deriveHopsFromImports: () => deriveHopsFromImports,
   getFlowFreshness: () => getFlowFreshness,
-  getFreshDomainFlow: () => getFreshDomainFlow
+  getFreshDomainFlow: () => getFreshDomainFlow,
+  getHopsForDomain: () => getHopsForDomain
 });
 import fs15 from "fs";
 import path16 from "path";
@@ -6568,9 +6803,86 @@ function deriveHopsFromImports(entryFile, maxHops = 6) {
   }
   return hops;
 }
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function getHopsForDomain(domain) {
+  const hops = [];
+  try {
+    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const stmt = db.prepare(`SELECT metadata FROM nodes WHERE type = 'feature_domain' AND name = ? LIMIT 1`);
+    stmt.bind([domain]);
+    if (stmt.step()) {
+      const meta = JSON.parse(stmt.getAsObject().metadata || "{}");
+      if (Array.isArray(meta.hops) && meta.hops.length > 0 && typeof meta.hops[0] === "object") {
+        stmt.free();
+        return meta.hops;
+      }
+    }
+    stmt.free();
+    const nodeStmt = db.prepare(`
+      SELECT name, metadata FROM nodes
+      WHERE type = 'cross_service_link' AND (metadata LIKE ? OR id LIKE ?)
+      LIMIT 25
+    `);
+    nodeStmt.bind([`%"domain":"${domain}"%`, `%${domain}::%`]);
+    const rawNodes = [];
+    while (nodeStmt.step()) {
+      const row = nodeStmt.getAsObject();
+      try {
+        const meta = JSON.parse(row.metadata || "{}");
+        rawNodes.push({
+          name: row.name,
+          hopIndex: typeof meta.hopIndex === "number" ? meta.hopIndex : 999,
+          relation: meta.relation,
+          description: meta.description
+        });
+      } catch {
+      }
+    }
+    nodeStmt.free();
+    if (rawNodes.length >= 2) {
+      rawNodes.sort((a, b) => a.hopIndex - b.hopIndex);
+      const uniqueSteps = [];
+      for (const n of rawNodes) {
+        if (uniqueSteps.length === 0 || uniqueSteps[uniqueSteps.length - 1] !== n.name) {
+          uniqueSteps.push(n.name);
+        }
+      }
+      for (let i = 0; i < uniqueSteps.length - 1; i++) {
+        hops.push({ from: uniqueSteps[i], to: uniqueSteps[i + 1] });
+      }
+      if (hops.length > 0) return hops;
+    }
+  } catch {
+  }
+  try {
+    const root = getProjectRoot();
+    const archPath = path16.join(root, ".kuma", "ARCHITECTURE_FLOW.md");
+    if (fs15.existsSync(archPath)) {
+      const content = fs15.readFileSync(archPath, "utf-8");
+      const lines = content.split("\n");
+      for (const line of lines) {
+        const domMatch = line.match(new RegExp(`domain:\\s*${escapeRegex(domain)}\\s*\\|\\s*hops:\\s*(.+)`, "i"));
+        if (domMatch) {
+          const hopsPart = domMatch[1].trim();
+          const arrowSteps = hopsPart.split(/→|->/).map((s) => s.trim()).filter(Boolean);
+          for (let i = 0; i < arrowSteps.length - 1; i++) {
+            hops.push({ from: arrowSteps[i], to: arrowSteps[i + 1] });
+          }
+          if (hops.length > 0) return hops;
+        }
+      }
+    }
+  } catch {
+  }
+  return hops;
+}
 async function getFreshDomainFlow(domain) {
   const freshness = await getFlowFreshness(domain);
-  if (!freshness) {
+  const hops = await getHopsForDomain(domain);
+  if (!freshness && hops.length === 0) {
     return `\u2139\uFE0F No arch_flow recorded for domain "${domain}".
 Record one with kuma_memory({ action: 'arch_flow', content: 'domain: ${domain} | hops: a.ts \u2192 b.ts \u2192 c.ts' }).`;
   }
@@ -6579,33 +6891,55 @@ Record one with kuma_memory({ action: 'arch_flow', content: 'domain: ${domain} |
     `\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`,
     ""
   ];
-  if (freshness.fresh) {
-    lines.push(`\u2705 Cache FRESH \u2014 served as-is (${freshness.filePaths.length} file(s) tracked).`);
-  } else {
-    lines.push(`\u{1F501} Cache STALE (${freshness.staleFiles.length} file(s) changed) \u2014 re-deriving from imports...`);
-    try {
-      const entry = freshness.filePaths[0];
-      const hops = deriveHopsFromImports(entry);
-      if (hops.length > 0) {
-        const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-        await recordDomainFlow2({
-          domain,
-          hops,
-          filePaths: freshness.filePaths
-        });
-        lines.push(`\u2705 Re-derived ${hops.length} hop(s) from ${path16.basename(entry)} \u2014 cache refreshed.`);
-      } else {
-        lines.push("\u26A0\uFE0F No imports to follow \u2014 cache left as-is (record hops manually if needed).");
+  if (freshness) {
+    if (freshness.fresh) {
+      lines.push(`\u2705 Cache FRESH \u2014 served as-is (${freshness.filePaths.length} file(s) tracked).`);
+    } else {
+      lines.push(`\u{1F501} Cache STALE (${freshness.staleFiles.length} file(s) changed) \u2014 re-deriving from imports...`);
+      try {
+        const entry = freshness.filePaths[0];
+        const derivedHops = deriveHopsFromImports(entry);
+        if (derivedHops.length > 0) {
+          const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+          await recordDomainFlow2({
+            domain,
+            hops: derivedHops,
+            filePaths: freshness.filePaths
+          });
+          lines.push(`\u2705 Re-derived ${derivedHops.length} hop(s) from ${path16.basename(entry)} \u2014 cache refreshed.`);
+          hops.splice(0, hops.length, ...derivedHops);
+        } else {
+          lines.push("\u26A0\uFE0F No imports to follow \u2014 cache left as-is (record hops manually if needed).");
+        }
+      } catch (err) {
+        lines.push(`\u26A0\uFE0F Re-derivation failed: ${err}`);
       }
-    } catch (err) {
-      lines.push(`\u26A0\uFE0F Re-derivation failed: ${err}`);
     }
+  } else {
+    lines.push(`\u2139\uFE0F Serving flow from markdown definition.`);
   }
   lines.push("");
-  for (const fp of freshness.filePaths) {
-    lines.push(`  \u{1F4C4} ${fp}${freshness.staleFiles.includes(fp) ? " \u26A0\uFE0F changed" : ""}`);
+  if (hops.length > 0) {
+    lines.push("\u{1F504} **Flow Sequence (Hops):**");
+    for (let i = 0; i < hops.length; i++) {
+      const h = hops[i];
+      const detail = h.relation && h.relation !== "flows" ? ` (${h.relation})` : "";
+      if (i === 0) {
+        lines.push(`  1. ${h.from} \u2192`);
+      }
+      const isLast = i === hops.length - 1;
+      lines.push(`  ${i + 2}. ${h.to}${detail}${isLast ? "" : " \u2192"}`);
+    }
+    lines.push("");
   }
-  return lines.join("\n");
+  if (freshness && freshness.filePaths.length > 0) {
+    lines.push("\u{1F4C1} **Tracked Files:**");
+    for (const fp of freshness.filePaths) {
+      lines.push(`  \u{1F4C4} ${fp}${freshness.staleFiles.includes(fp) ? " \u26A0\uFE0F changed" : ""}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
 }
 var init_kumaFlowCache = __esm({
   "src/engine/kumaFlowCache.ts"() {
@@ -7168,25 +7502,66 @@ async function createCheckpoint(label, description) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
     fs22.mkdirSync(cpDir, { recursive: true });
-    const db = await getDb();
-    const filesStmt = db.prepare(
-      "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
-    );
+    const candidatePaths = /* @__PURE__ */ new Set();
+    try {
+      const { execSync: execSync6 } = await import("child_process");
+      const gitOut = execSync6("git status --porcelain", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 4e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      if (gitOut) {
+        for (const line of gitOut.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          const rawPath = trimmed.slice(2).trim();
+          const cleanPath = rawPath.replace(/^["']|["']$/g, "").split(" -> ").pop();
+          if (cleanPath.startsWith(".kuma/") || cleanPath.startsWith(".git/")) continue;
+          candidatePaths.add(cleanPath);
+        }
+      }
+    } catch {
+    }
+    try {
+      for (const m of sessionMemory.getModifiedFiles()) {
+        if (!m.filePath.startsWith(".kuma/") && !m.filePath.startsWith(".git/")) {
+          candidatePaths.add(m.filePath);
+        }
+      }
+    } catch {
+    }
+    try {
+      const db2 = await getDb();
+      const filesStmt = db2.prepare(
+        "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
+      );
+      while (filesStmt.step()) {
+        const row = filesStmt.getAsObject();
+        const fp = row.file_path;
+        if (fp && !fp.startsWith(".kuma/") && !fp.startsWith(".git/")) {
+          candidatePaths.add(fp);
+        }
+      }
+      filesStmt.free();
+    } catch {
+    }
     const files = [];
-    while (filesStmt.step()) {
-      const row = filesStmt.getAsObject();
-      const fp = row.file_path;
+    for (const fp of candidatePaths) {
       const fullPath = path23.resolve(root, fp);
-      if (fs22.existsSync(fullPath)) {
-        const content = fs22.readFileSync(fullPath, "utf-8");
-        const hash = simpleHash2(content);
-        const fileDir = path23.dirname(path23.join(cpDir, "files", fp));
-        if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
-        fs22.writeFileSync(path23.join(cpDir, "files", fp), content, "utf-8");
-        files.push({ path: fp, hash });
+      try {
+        if (fs22.existsSync(fullPath) && fs22.statSync(fullPath).isFile()) {
+          const content = fs22.readFileSync(fullPath, "utf-8");
+          const hash = simpleHash2(content);
+          const fileDir = path23.dirname(path23.join(cpDir, "files", fp));
+          if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
+          fs22.writeFileSync(path23.join(cpDir, "files", fp), content, "utf-8");
+          files.push({ path: fp, hash });
+        }
+      } catch {
       }
     }
-    filesStmt.free();
+    const db = await getDb();
     const dbData = db.export();
     fs22.writeFileSync(path23.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
@@ -10478,11 +10853,32 @@ async function handleHistory(params) {
   try {
     const { getFileTrace: getFileTrace2, formatFileTrace: formatFileTrace2, getFreshGotchasForFile: getFreshGotchasForFile2, getDecisionsForFile: getDecisionsForFile2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
     const trace = await getFileTrace2(target, 8);
-    lines.push(formatFileTrace2(trace, target) || "  (no changes recorded for this file yet)");
+    const traceFormatted = formatFileTrace2(trace, target);
+    if (traceFormatted) {
+      lines.push(traceFormatted);
+    } else {
+      try {
+        const { execSync: execSync6 } = await import("child_process");
+        const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+        const root = getProjectRoot2();
+        const gitHistory = execSync6(
+          `git log -n 5 --pretty=format:"  \u2022 %h (%ad) %s" --date=short -- "${target}"`,
+          { cwd: root, encoding: "utf-8", timeout: 3e3, stdio: ["pipe", "pipe", "pipe"] }
+        ).trim();
+        if (gitHistory) {
+          lines.push(`\u{1F570}\uFE0F **Git Commit History (latest):**
+${gitHistory}`);
+        } else {
+          lines.push("  (no changes recorded for this file yet)");
+        }
+      } catch {
+        lines.push("  (no changes recorded for this file yet)");
+      }
+    }
     lines.push("");
-    const gotchas = await getFreshGotchasForFile2(target, 5);
+    const gotchas = await getFreshGotchasForFile2(target, 5, true);
     if (gotchas.length > 0) {
-      lines.push("\u26A0\uFE0F **Active gotchas** (fresh):");
+      lines.push("\u26A0\uFE0F **Active gotchas:**");
       for (const g of gotchas) {
         const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
         lines.push(`  ${icon} [${g.severity}] ${g.description}`);
@@ -10497,11 +10893,34 @@ async function handleHistory(params) {
     try {
       const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
       const db = await getDb2();
-      const stmt = db.prepare(`SELECT description, last_verified_at FROM known_gotchas WHERE status = 'resolved' AND file_path LIKE ? ORDER BY last_verified_at DESC LIMIT 3`);
-      stmt.bind([`%${path17.basename(target)}%`]);
+      const base = path17.basename(target);
+      const stmt = db.prepare(`
+        SELECT description, last_verified_at FROM known_gotchas
+        WHERE status = 'resolved' AND (file_path LIKE ? OR file_path LIKE ?)
+        ORDER BY last_verified_at DESC LIMIT 5
+      `);
+      stmt.bind([`%${base}%`, `%${target}%`]);
       const resolved = [];
       while (stmt.step()) resolved.push(stmt.getAsObject());
       stmt.free();
+      if (resolved.length === 0) {
+        try {
+          const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+          const mdPath = path17.join(getProjectRoot2(), ".kuma", "KNOWN_GOTCHAS.md");
+          if (fs16.existsSync(mdPath)) {
+            const mdContent = fs16.readFileSync(mdPath, "utf-8");
+            const sections = mdContent.split(/^###\s+/m);
+            for (const sec of sections) {
+              const secLower = sec.toLowerCase();
+              if ((secLower.includes(base.toLowerCase()) || secLower.includes(target.toLowerCase())) && secLower.includes("status**: resolved")) {
+                const descLine = sec.split("\n")[0].trim();
+                resolved.push({ description: descLine, last_verified_at: null });
+              }
+            }
+          }
+        } catch {
+        }
+      }
       if (resolved.length > 0) {
         lines.push("\u2705 **Resolved gotchas** (fixed):");
         for (const r of resolved) {
@@ -10514,7 +10933,7 @@ async function handleHistory(params) {
     }
     const decisions = await getDecisionsForFile2(target, 3);
     if (decisions.length > 0) {
-      lines.push("\u{1F4CC} **Relevant decisions**");
+      lines.push("\u{1F4CC} **Relevant decisions:**");
       for (const d of decisions) lines.push(`  ${d}`);
       lines.push("");
     }
@@ -10589,6 +11008,8 @@ var MEMORY_ALIASES = {
   "resolve_gotcha": "gotcha",
   "resolve-gotcha": "gotcha",
   "resolve": "gotcha",
+  "gotcha_resolve": "gotcha",
+  "gotcha-resolve": "gotcha",
   "deprecate_gotcha": "gotcha",
   "deprecate-gotcha": "gotcha",
   "deprecate": "gotcha"
@@ -10784,7 +11205,7 @@ async function handleArchFlow(params) {
 async function handleGotchaAction(params) {
   const rawStatus = (params.status || "").toLowerCase().trim();
   const rawAction = (params.action || "").toLowerCase().trim();
-  const isResolution = rawStatus === "resolved" || rawStatus === "resolve" || rawAction === "resolve_gotcha" || rawAction === "resolve";
+  const isResolution = rawStatus === "resolved" || rawStatus === "resolve" || rawAction === "resolve_gotcha" || rawAction === "gotcha_resolve" || rawAction === "gotcha-resolve" || rawAction === "resolve";
   const isDeprecation = rawStatus === "deprecated" || rawStatus === "deprecate" || rawAction === "deprecate_gotcha" || rawAction === "deprecate";
   const target = params.target || params.id || params.scope;
   if (isResolution && target) {
@@ -11449,127 +11870,123 @@ async function doInit() {
 // src/manifest.ts
 var CORE_NOTE = "\n\nCORE ACTIONS (use these): ";
 function registerAllTools(server) {
-  server.tool(
-    "kuma_context",
-    "Context & memory recall. Call FIRST each session. Lean \u2014 each call returns only what you need." + CORE_NOTE + "`init` (start of session: project brief + session state), `research` (before editing unfamiliar code), `history` (why is this file written this way), `flow` (read a recorded architecture flow), `map` (repository topology), `impact` (blast radius analysis).",
-    {
-      action: z.enum(["init", "research", "history", "flow", "map", "impact"]).describe(
-        "init=project brief + session restore, research=research pipeline, history=file rationale + fresh gotchas, flow=read recorded domain flow, map=repo topology, impact=blast radius"
-      ),
-      scope: z.string().optional().describe("Research scope or target for impact"),
-      target: z.string().optional().describe("Target symbol/file for history/flow/impact"),
-      goal: z.string().optional().describe("Current goal (for init)")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleContext({
-          action: params.action,
-          scope: params.scope,
-          target: params.target,
-          goal: params.goal
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
-      }
+  const contextDesc = "Context & memory recall. Call FIRST each session. Lean \u2014 each call returns only what you need." + CORE_NOTE + "`init` (start of session: project brief + session state), `research` (before editing unfamiliar code), `history` (why is this file written this way), `flow` (read a recorded architecture flow), `map` (repository topology), `impact` (blast radius analysis).";
+  const contextSchema = {
+    action: z.enum(["init", "research", "history", "flow", "map", "impact"]).describe(
+      "init=project brief + session restore, research=research pipeline, history=file rationale + fresh gotchas, flow=read recorded domain flow, map=repo topology, impact=blast radius"
+    ),
+    scope: z.string().optional().describe("Research scope or target for impact"),
+    target: z.string().optional().describe("Target symbol/file for history/flow/impact"),
+    goal: z.string().optional().describe("Current goal (for init)")
+  };
+  const contextHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleContext({
+        action: params.action,
+        scope: params.scope,
+        target: params.target,
+        goal: params.goal
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
     }
-  );
-  server.tool(
-    "kuma_memory",
-    "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph).",
-    {
-      action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search"]).describe(
-        "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup"
-      ),
-      scope: z.string().optional().describe("File path for gotcha \u2014 or scope for research_save/search"),
-      target: z.string().optional().describe("Target file, gotcha ID, or component"),
-      trigger_command: z.string().optional().describe("Gotcha trigger: shell command that hits this gotcha"),
-      query: z.string().optional().describe("Search query for search action"),
-      content: z.string().optional().describe("Content/notes for research_save / gotcha description / arch_flow record"),
-      record: z.string().optional().describe("JSON record string for research_save"),
-      confidence: z.number().min(0).max(1).optional().describe("Confidence for research_save (0-1)"),
-      title: z.string().optional().describe("Decision title (optional if content/target provided)"),
-      context: z.string().optional().describe("Decision context"),
-      rationale: z.string().optional().describe("Decision rationale (optional if content provided)"),
-      outcome: z.string().optional().describe("Decision outcome (default: implemented)"),
-      status: z.string().optional().describe("Gotcha severity (low|medium|high|critical) or status (resolved|deprecated)"),
-      severity: z.string().optional().describe("Gotcha severity (low|medium|high|critical)"),
-      description: z.string().optional().describe("Gotcha workaround / rationale"),
-      id: z.union([z.number(), z.string()]).optional().describe("Gotcha ID for resolution or deprecation"),
-      limit: z.number().min(1).max(100).optional().describe("Result limit for search")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleMemory({
-          action: params.action,
-          scope: params.scope,
-          target: params.target,
-          query: params.query,
-          content: params.content,
-          record: params.record,
-          confidence: params.confidence,
-          title: params.title,
-          context: params.context,
-          rationale: params.rationale,
-          outcome: params.outcome,
-          limit: params.limit,
-          status: params.status,
-          severity: params.severity,
-          description: params.description,
-          trigger_command: params.trigger_command,
-          id: params.id
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_memory: ${err}` }], isError: true };
-      }
+  };
+  server.tool("kuma_context", contextDesc, contextSchema, contextHandler);
+  server.tool("kuma_kuma_context", contextDesc, contextSchema, contextHandler);
+  const memoryDesc = "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs).";
+  const memorySchema = {
+    action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search", "gotcha_resolve"]).describe(
+      "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup, gotcha_resolve=archive fixed bug"
+    ),
+    scope: z.string().optional().describe("File path for gotcha \u2014 or scope for research_save/search"),
+    target: z.string().optional().describe("Target file, gotcha ID, or component"),
+    trigger_command: z.string().optional().describe("Gotcha trigger: shell command that hits this gotcha"),
+    query: z.string().optional().describe("Search query for search action"),
+    content: z.string().optional().describe("Content/notes for research_save / gotcha description / arch_flow record"),
+    record: z.string().optional().describe("JSON record string for research_save"),
+    confidence: z.number().min(0).max(1).optional().describe("Confidence for research_save (0-1)"),
+    title: z.string().optional().describe("Decision title (optional if content/target provided)"),
+    context: z.string().optional().describe("Decision context"),
+    rationale: z.string().optional().describe("Decision rationale (optional if content provided)"),
+    outcome: z.string().optional().describe("Decision outcome (default: implemented)"),
+    status: z.string().optional().describe("Gotcha severity (low|medium|high|critical) or status (resolved|deprecated)"),
+    severity: z.string().optional().describe("Gotcha severity (low|medium|high|critical)"),
+    description: z.string().optional().describe("Gotcha workaround / rationale"),
+    id: z.union([z.number(), z.string()]).optional().describe("Gotcha ID for resolution or deprecation"),
+    limit: z.number().min(1).max(100).optional().describe("Result limit for search")
+  };
+  const memoryHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleMemory({
+        action: params.action,
+        scope: params.scope,
+        target: params.target,
+        query: params.query,
+        content: params.content,
+        record: params.record,
+        confidence: params.confidence,
+        title: params.title,
+        context: params.context,
+        rationale: params.rationale,
+        outcome: params.outcome,
+        limit: params.limit,
+        status: params.status,
+        severity: params.severity,
+        description: params.description,
+        trigger_command: params.trigger_command,
+        id: params.id
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_memory: ${err}` }], isError: true };
     }
-  );
-  server.tool(
-    "kuma_safety",
-    "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after).",
-    {
-      action: z.enum(["guard", "verify", "checkpoint", "rollback_label"]).describe(
-        "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
-      ),
-      scope: z.string().optional().describe("Scope for verify (e.g. 'auth', file path)"),
-      target: z.string().optional().describe("Target test file or scope for verify"),
-      command: z.string().optional().describe("Custom test command to run during verify"),
-      timeoutMs: z.number().optional().describe("Custom timeout in milliseconds for verify (default: 60000)"),
-      timeout: z.number().optional().describe("Custom timeout in seconds for verify"),
-      force: z.boolean().optional().describe("Force re-run even if cache is fresh or rate limited (verify)"),
-      guardGoal: z.string().optional().describe("Goal for guard check"),
-      guardCheck: z.enum(["all", "anti-pattern", "loop", "drift", "context"]).optional().describe("Guard check type"),
-      label: z.string().optional().describe("Checkpoint label for checkpoint/rollback_label"),
-      description: z.string().optional().describe("Description for checkpoint")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleSafety({
-          action: params.action,
-          guardGoal: params.guardGoal,
-          guardCheck: params.guardCheck,
-          scope: params.scope,
-          target: params.target,
-          command: params.command,
-          timeoutMs: params.timeoutMs,
-          timeout: params.timeout,
-          force: params.force,
-          label: params.label,
-          description: params.description
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_safety: ${err}` }], isError: true };
-      }
+  };
+  server.tool("kuma_memory", memoryDesc, memorySchema, memoryHandler);
+  server.tool("kuma_kuma_memory", memoryDesc, memorySchema, memoryHandler);
+  const safetyDesc = "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after).";
+  const safetySchema = {
+    action: z.enum(["guard", "verify", "checkpoint", "rollback_label"]).describe(
+      "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
+    ),
+    scope: z.string().optional().describe("Scope for verify (e.g. 'auth', file path)"),
+    target: z.string().optional().describe("Target test file or scope for verify"),
+    command: z.string().optional().describe("Custom test command to run during verify"),
+    timeoutMs: z.number().optional().describe("Custom timeout in milliseconds for verify (default: 60000)"),
+    timeout: z.number().optional().describe("Custom timeout in seconds for verify"),
+    force: z.boolean().optional().describe("Force re-run even if cache is fresh or rate limited (verify)"),
+    guardGoal: z.string().optional().describe("Goal for guard check"),
+    guardCheck: z.enum(["all", "anti-pattern", "loop", "drift", "context"]).optional().describe("Guard check type"),
+    label: z.string().optional().describe("Checkpoint label for checkpoint/rollback_label"),
+    description: z.string().optional().describe("Description for checkpoint")
+  };
+  const safetyHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleSafety({
+        action: params.action,
+        guardGoal: params.guardGoal,
+        guardCheck: params.guardCheck,
+        scope: params.scope,
+        target: params.target,
+        command: params.command,
+        timeoutMs: params.timeoutMs,
+        timeout: params.timeout,
+        force: params.force,
+        label: params.label,
+        description: params.description
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_safety: ${err}` }], isError: true };
     }
-  );
-  console.error("[Manifest] Registered 3 coarse-grained tools with 13 core actions (init/research/history/flow \xB7 gotcha/decision/arch_flow/research_save/search \xB7 guard/verify/checkpoint/rollback_label).");
+  };
+  server.tool("kuma_safety", safetyDesc, safetySchema, safetyHandler);
+  server.tool("kuma_kuma_safety", safetyDesc, safetySchema, safetyHandler);
+  console.error("[Manifest] Registered 3 core tools with universal dual-prefix aliases (kuma_* and kuma_kuma_*).");
   console.error("[Manifest] Auto-init hooks installed on all tools.");
-  console.error("[Manifest] Namespace aliases active (kuma_kuma_* \u2192 kuma_*, context \u2192 kuma_context).");
 }
 
 // src/index.ts
@@ -11624,6 +12041,64 @@ async function main() {
     printHelp();
     process.exit(0);
   }
+  if (args[0] === "status") {
+    console.log(`\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Health & Memory Status`);
+    console.log(`\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\u2501\u2501\u2501`);
+    try {
+      const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+      const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+      const root = getProjectRoot2();
+      console.log(`\u{1F4C1} Project Root: ${root}`);
+      const db = await getDb2();
+      let decisionsCount = 0;
+      try {
+        const dRes = db.exec("SELECT COUNT(*) FROM nodes WHERE type = 'decision'");
+        decisionsCount = dRes[0]?.values[0]?.[0] || 0;
+      } catch {
+      }
+      let activeGotchas = 0;
+      let resolvedGotchas = 0;
+      let candidateGotchas = 0;
+      try {
+        const gRes = db.exec("SELECT status, COUNT(*) FROM known_gotchas GROUP BY status");
+        for (const row of gRes[0]?.values || []) {
+          const status = String(row[0]);
+          const cnt = Number(row[1]);
+          if (status === "active" || status === "verified") activeGotchas += cnt;
+          else if (status === "resolved") resolvedGotchas += cnt;
+          else if (status === "candidate") candidateGotchas += cnt;
+        }
+      } catch {
+      }
+      let shadowInjections = 0;
+      let savedMinutes = 0;
+      try {
+        const { getInjectionStats: getInjectionStats2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+        const stats = getInjectionStats2(24);
+        shadowInjections = stats.count;
+        savedMinutes = Math.round(stats.savedMs / 6e4);
+      } catch {
+      }
+      let workspaceDesc = "Single project";
+      try {
+        const { getWorkspaceInfo: getWorkspaceInfo2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
+        const wsInfo = await getWorkspaceInfo2(root);
+        if (wsInfo.isWorkspace) {
+          workspaceDesc = `${wsInfo.packages.length} package(s) (${wsInfo.type.toUpperCase()})`;
+        }
+      } catch {
+      }
+      console.log(`\u{1F3DB}\uFE0F Decisions Recorded: ${decisionsCount}`);
+      console.log(`\u26A0\uFE0F Active Gotchas: ${activeGotchas} active \xB7 ${resolvedGotchas} resolved \xB7 ${candidateGotchas} candidate`);
+      console.log(`\u{1FA84} Shadow Memory: ${shadowInjections} prevention(s) in last 24h (~${savedMinutes} min saved)`);
+      console.log(`\u{1F4E6} Workspace: ${workspaceDesc}`);
+      console.log(`\u{1F6E1}\uFE0F Safety Hooks: Active`);
+      console.log(`\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\u2501\u2501\u2501`);
+    } catch (err) {
+      console.error(`\u274C Failed to retrieve status: ${err}`);
+    }
+    process.exit(0);
+  }
   if (args[0] === "stop" && (args[1] === "--force" || args[1] === "-f")) {
     console.error(`\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Kill Switch`);
     console.error("");