@plumpslabs/kuma 2.3.23 → 2.3.25

package/README.md

@@ -142,6 +142,8 @@ Kuma consolidates everything into **3 coarse-grained tools**. Each action trigge
 | `arch_flow` | Layer 2 — Architecture flow mapping (Issue #17). |
 | `gotcha` | Layer 3 — Known gotchas & anti-regression shield (Issue #17/#21). |
 | `layers` | Show all 3 memory layers summary. |
+| `delete_node` | Delete specific node or record from disk & RAM immediately. |
+| `graph_health` | Monitor knowledge graph health, orphan nodes, and duplicate groups. |
 
 ### 🛡️ `kuma_safety` — Safety & Policy
 

package/dist/index.js

@@ -2558,7 +2558,7 @@ async function recordDomainFlow(params) {
       await addEdge({
         sourceId: fromId,
         targetId: toId,
-        type: "affects",
+        type: "depends_on",
         weight: 0.8,
         metadata: { reason: "arch_flow", domain: params.domain }
       });
@@ -8196,19 +8196,25 @@ function generateInitMdContent() {
     "- `status` \u2014 severity: `low` | `medium` | `high` | `critical` (default: `medium`)",
     "- `description` \u2014 optional workaround/fix description",
     "",
-    "### STEP 7: Record Arch Flow (RECORD INLINE \u2014 When Tracing Flow)",
+    "### STEP 7: Record Arch Flow (RECORD COMPLETE FLOW \u2014 Core Logic Only)",
     "```",
-    'kuma_memory({ action: "arch_flow", content: "domain: <name> | hops: <file1> \u2192 <file2> \u2192 <file3>" })',
+    'kuma_memory({ action: "arch_flow", content: "domain: <name> | hops: <core_file1> \u2192 <core_file2> \u2192 <core_file3>" })',
     "```",
-    "**When:** IMMEDIATELY after tracing EACH hop in a data/control flow. Record INLINE, then continue tracing the next hop.",
-    "**Why:** Architecture knowledge dissipates fast. Record each hop before moving to the next file/task.",
+    "**When:** AFTER tracing a COMPLETE architecture flow (not per hop).",
+    "**Why:** Record flow architecture for future sessions without cluttering the graph.",
+    "",
+    "**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`).",
     "",
     "**\u26A0\uFE0F CRITICAL FORMAT \u2014 Content MUST use this exact syntax:**",
     "```",
-    "domain: <DomainName> | hops: <file1.tsx> \u2192 <file2.js> \u2192 <file3.ts> | gotchas: <optional> | decisions: <optional>",
+    "domain: <DomainName> | hops: <core_file1.js> \u2192 <core_file2.js> \u2192 <core_file3.js> | gotchas: <optional> | decisions: <optional>",
     "```",
     "- `domain:` \u2014 short domain name (e.g. `InviteUserFlow`, `LeadManagementFlow`)",
-    "- `hops:` \u2014 file names separated by ` \u2192 ` (NOT newlines, NOT commas)",
+    "- `hops:` \u2014 max 5 core file names separated by ` \u2192 `",
     "- `gotchas:` \u2014 optional comma-separated gotchas",
     "- `decisions:` \u2014 optional comma-separated decisions",
     "",
@@ -8866,33 +8872,24 @@ function handleQuickrefGeneration(root, results) {
   const content = [
     "# Kuma Quick Reference",
     "",
-    "_(Auto-generated by `kuma init` \u2014 simplified workflow cheat sheet)_",
-    "",
-    "## Every Session (Mandatory \u2014 including research-only)",
+    "## Lean Mode (default \u2014 for speed)",
+    "1. `init` \u2192 edit \u2192 record (if needed)",
     "",
-    '  1. `kuma_context({ action: "init" })`                             \u2014 Load context',
-    '  2. `kuma_safety({ action: "guard" })`                             \u2014 Safety check',
-    '  3. `kuma_context({ action: "research", scope: "<area>" })`         \u2014 Research',
-    "  4. *(edit/read using native tools)*",
-    '  5. `kuma_memory({ action: "research_save", ... })`                \u2014 After exploring area (creates search cache)',
-    '  6. `kuma_memory({ action: "gotcha" })`                            \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-    '  7. `kuma_memory({ action: "arch_flow" })`                         \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
-    '  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',
+    "## Standard Mode (for safety)",
+    "1. `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
     "",
-    "\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.",
+    "## Full Mode (for complex changes)",
+    "1. `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
     "",
-    "\u26D4 Steps 5-10 are mandatory even for research-only sessions!",
+    "## Record Rules",
+    "- **MUST:** decision, gotcha",
+    "- **SKIP:** function, class, import, route",
     "",
     "## Platform Tool Names",
+    "- OpenCode / Antigravity: `kuma_kuma_*`",
+    "- Others: `kuma_*`",
     "",
-    "- **OpenCode:** Use `kuma_kuma_*` prefix (e.g. `kuma_kuma_context`)",
-    "- **Other platforms:** Use `kuma_*` directly (e.g. `kuma_context`)",
-    "",
-    "\u{1F4D6} Full rules: `.kuma/init.md`",
+    "\u{1F4D6} Full: `.kuma/init.md` | \u{1F4CA} Modes: `.kuma/MODE.md` | \u{1F7E2} Skip: `.kuma/SKIP_RULES.md`",
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
@@ -8904,11 +8901,9 @@ function handleQuickrefGeneration(root, results) {
         results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
         return;
       }
-      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
-    } else {
-      fs24.writeFileSync(quickrefPath, content, "utf-8");
-      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
     }
+    fs24.writeFileSync(quickrefPath, content, "utf-8");
+    results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
   } catch (err) {
     results.push({
       type: "claude",
@@ -8918,6 +8913,150 @@ function handleQuickrefGeneration(root, results) {
     });
   }
 }
+function handleModeMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/MODE.md");
+  const content = [
+    "# Adaptive Mode Selector",
+    "",
+    "## Mode Definitions",
+    "",
+    "| Mode | When to Use | Token Cost | Steps |",
+    "|------|-------------|------------|-------|",
+    "| **Lean** (default) | Small fixes, familiar code, hotfixes, < 3 files | ~100 | 3 |",
+    "| **Standard** | New features, unfamiliar modules, 3-10 files | ~300 | 5 |",
+    "| **Full** | Cross-module refactors, architecture changes, > 10 files | ~500 | 7 |",
+    "",
+    "## Auto-Detection Rules",
+    "",
+    "```",
+    "IF file_count < 3 AND area_familiar == true:",
+    '  mode = "lean"',
+    "ELSE IF file_count <= 10 OR area_familiar == false:",
+    '  mode = "standard"',
+    "ELSE IF file_count > 10 OR cross_module == true:",
+    '  mode = "full"',
+    "```",
+    "",
+    "## Mode Behaviors",
+    "",
+    "### Lean Mode (Default)",
+    "- Skip: guard, research, verify, changes",
+    "- Record: only if decision/gotcha explicit",
+    "- Focus: speed, minimal overhead",
+    "",
+    "### Standard Mode",
+    "- Include: guard (before unfamiliar), research (before edit)",
+    "- Record: decision, gotcha, arch_flow (if complex)",
+    "- Focus: safety + knowledge capture",
+    "",
+    "### Full Mode",
+    "- Include: all steps including impact, changes",
+    "- Record: everything valuable",
+    "- Focus: completeness, audit trail",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function handleSkipRulesMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/SKIP_RULES.md");
+  const content = [
+    "# Skip Rules \u2014 What NOT to Record",
+    "",
+    "## \u{1F7E2} NEVER Record (grep/glob is faster)",
+    "",
+    "| What | Why Skip | Better Tool |",
+    "|------|----------|-------------|",
+    "| Function definitions | `grep funcName(` | Grep |",
+    "| Class definitions | `grep class ClassName` | Grep |",
+    "| Import statements | Read import block | Read |",
+    "| Component definitions | `glob **/*Component*` | Glob |",
+    "| Route definitions | Check router file | Read |",
+    "| Type/interface definitions | `grep interface TypeName` | Grep |",
+    "| Variable/const declarations | `grep const varName` | Grep |",
+    "| Test file locations | `glob **/*.test.*` | Glob |",
+    "",
+    "## \u{1F534} ALWAYS Record (high value)",
+    "",
+    "| What | Why Record | Tool |",
+    "|------|------------|------|",
+    "| Architecture decisions with rationale | Preserves context | `decision` |",
+    "| Bugs/quirks found and fixed | Prevents re-discovery | `gotcha` |",
+    "| Cross-module flow paths | Saves 5-10 files next session | `arch_flow` |",
+    "| Business rules discovered | Domain knowledge | `domain_rules` |",
+    "",
+    "## \u{1F7E1} Record ONLY If Complex",
+    "",
+    "| What | Condition | Tool |",
+    "|------|-----------|------|",
+    "| Research findings | Multi-file exploration (> 3 files) | `research_save` |",
+    "| Architecture flow | Cross-service or > 3 hops | `arch_flow` |",
+    "| Feature definition | High-level feature with owns edges | `feature` |",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function handleStalenessMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/STALENESS.md");
+  const content = [
+    "# Auto-Staleness Detection",
+    "",
+    "## Staleness Signals",
+    "",
+    "| Signal | Detection | Action |",
+    "|--------|-----------|--------|",
+    "| File modified after save | Compare file mtime vs research_save timestamp | Mark STALE, skip cache |",
+    "| Git commit touches file | `git log --since` on researched files | Mark STALE, warn |",
+    '| Age > 7 days | Current time - research_save timestamp | Warn: "Cache may be stale" |',
+    "| Age > 30 days | Current time - research_save timestamp | Auto-invalidate, re-read |",
+    "",
+    "## Recovery Protocol",
+    "",
+    "```",
+    "ON stale_detected:",
+    "  1. Skip cached data",
+    "  2. Re-read file from disk",
+    "  3. Update research_save timestamp",
+    "  4. Continue with fresh data",
+    "",
+    "ON search_conflict:",
+    "  1. Prefer recent research (newer timestamp)",
+    "  2. If same age, prefer live file over cache",
+    "  3. Log conflict for review",
+    "```",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
 function handleInitMdGeneration(root, results) {
   const initMdPath = path24.resolve(root, ".kuma/init.md");
   try {
@@ -8944,6 +9083,9 @@ function handleInitMdGeneration(root, results) {
     });
   }
   handleQuickrefGeneration(root, results);
+  handleModeMdGeneration(root, results);
+  handleSkipRulesMdGeneration(root, results);
+  handleStalenessMdGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
   const mcpPath = path24.resolve(root, ".codewhale/mcp.json");
@@ -9681,30 +9823,18 @@ var init_skillGenerator = __esm({
     "use strict";
     BOOTSTRAP = [
       "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety).",
-      '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
+      '**Before coding, call `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 **ADAPTIVE WORKFLOW (Lean Mode by Default):**",
+      "  \u2022 **Lean Mode (Default, < 3 files):** `init` \u2192 edit/read \u2192 record (`decision`/`gotcha` 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`",
       "",
-      '  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 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
-      '  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{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
-      "   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.",
-      "",
-      "\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{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
       "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
     ].join("\n");
     BOOTSTRAP_OPENCODE = [
@@ -9712,27 +9842,15 @@ var init_skillGenerator = __esm({
       '**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):",
-      "",
-      '  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 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
-      '  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',
+      "\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`",
       "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
-      "   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{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
-      "\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{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`"
     ].join("\n");
   }
@@ -10265,6 +10383,11 @@ var MEMORY_ALIASES = {
   "read": "session",
   "fetch": "session",
   "current": "session",
+  // Graph health synonyms
+  "graph_health": "graph_health",
+  "graph-health": "graph_health",
+  "health-check": "graph_health",
+  "graph-status": "graph_health",
   // Decision synonyms
   "decision": "decision",
   "adr": "decision",
@@ -10296,7 +10419,6 @@ var MEMORY_ALIASES = {
   "task": "todo",
   "todos": "todo",
   "tasks": "todo",
-  // Context notes synonyms
   "context": "context",
   "notes": "context",
   "note": "context",
@@ -10401,6 +10523,8 @@ async function handleMemory(params) {
       return handleFeature(params);
     case "delete_node":
       return handleDeleteNode(params);
+    case "graph_health":
+      return handleGraphHealth(params);
     case "clear": {
       const { clearGraph: clearGraph2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
       await clearGraph2();
@@ -10452,14 +10576,26 @@ async function handleResearchSave(params) {
   });
   await saveResearchCache(scope, record, void 0, params.confidence);
   try {
-    const { upsertNode: upsertNode2, nodeId: nodeId2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-    await upsertNode2({ id: nodeId2("file", scope), type: "file", name: scope });
-    await upsertNode2({
-      id: `research::${scope}`,
-      type: "research",
-      name: `research:${scope}`,
-      metadata: { confidence: params.confidence || 0.8 }
-    });
+    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]);
+    db.run(`
+      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+      VALUES (?, 'research', ?, null, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        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]);
+    flushDb2(db);
   } catch {
   }
   try {
@@ -10675,12 +10811,20 @@ async function handleLayerAction(layer, params) {
 \u274C Wrong: hops: file1.js\\nfile2.js
 \u2705 Correct: domain: <name> | hops: file1.js \u2192 file2.js \u2192 file3.js`;
       }
-      const hops = hopsStr ? hopsStr.split("\u2192").map((h) => h.trim()).filter(Boolean).map((h, i, arr) => ({
+      const rawHops = hopsStr ? hopsStr.split("\u2192").map((h) => h.trim()).filter(Boolean) : [];
+      const coreHops = rawHops.filter((file) => {
+        if (file.endsWith(".tsx") || file.endsWith(".jsx")) return false;
+        if (file.includes("Controller")) return false;
+        if (file.includes("Schema") || file.includes("RequestSchema")) return false;
+        return true;
+      });
+      const limitedHopsList = coreHops.slice(0, 5);
+      const hops = limitedHopsList.map((h, i, arr) => ({
         from: i === 0 ? domain : arr[i - 1],
         to: h,
         relation: "flows",
         description: h
-      })) : [];
+      }));
       if (hops.length === 0) {
         return `\u274C **arch_flow format error:** no hops found after \u2192 separator.
 
@@ -10784,11 +10928,12 @@ async function handleDeleteNode(params) {
         return `\u26A0\uFE0F Unknown scope "${params.scope}". Supported: gotcha, todo, decision, checkpoint`;
     }
   }
-  if (params.target) {
+  if (params.target || params.scope) {
     const { flushDb: flushDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
-    if (params.target.includes("::") || params.target.includes(":") || params.target.includes("-")) {
+    const targetStr = params.target || "";
+    const targetId = params.scope && !targetStr.includes("::") ? `${targetStr}::${params.scope}` : targetStr;
+    if (targetId && (targetId.includes("::") || targetId.includes(":") || targetId.includes("-") || isNaN(parseInt(targetId, 10)))) {
       try {
-        const targetId = params.target;
         const domainName = targetId.startsWith("feature_domain::") ? targetId.replace("feature_domain::", "") : targetId;
         if (targetId.startsWith("feature_domain::")) {
           db.run("DELETE FROM nodes WHERE id LIKE ? OR id LIKE ? OR id LIKE ?", [
@@ -10802,16 +10947,18 @@ async function handleDeleteNode(params) {
           db.run("DELETE FROM nodes WHERE id = ?", [targetId]);
         }
         flushDb2(db);
-        return `\u{1F5D1}\uFE0F **Node & relations deleted instantly from RAM and Disk:** ${params.target}`;
+        return `\u{1F5D1}\uFE0F **Node & relations deleted instantly from RAM and Disk:** ${targetId}`;
       } catch (err) {
         return `\u274C Failed to delete node: ${err}`;
       }
     }
-    const id = parseInt(params.target, 10);
-    if (!isNaN(id)) {
-      db.run("DELETE FROM nodes WHERE rowid = ?", [id]);
-      flushDb2(db);
-      return `\u{1F5D1}\uFE0F **Node #${id} deleted.**`;
+    if (targetId) {
+      const id = parseInt(targetId, 10);
+      if (!isNaN(id)) {
+        db.run("DELETE FROM nodes WHERE rowid = ?", [id]);
+        flushDb2(db);
+        return `\u{1F5D1}\uFE0F **Node #${id} deleted.**`;
+      }
     }
   }
   return "\u26A0\uFE0F Provide `target` (node ID) to delete, or `scope` + `target` (numeric ID) for gotcha/todo/decision/checkpoint.\n\nExamples:\n- `delete_node`, target: 'function::sendMessage'\n- `delete_node`, scope: 'gotcha', target: '42'\n- `delete_node`, scope: 'todo', target: '7'\n- `delete_node`, scope: 'decision', target: '3'\n- `delete_node`, scope: 'checkpoint', target: '1'";
@@ -10872,6 +11019,68 @@ async function handleFeature(params) {
 \u{1F3F7}\uFE0F Tags: ${tags.length}
 \u26A0\uFE0F Risk: ${risk}`;
 }
+async function handleGraphHealth(_params) {
+  const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+  const db = await getDb2();
+  const getRows = (sql) => {
+    try {
+      const res = db.exec(sql);
+      if (!res.length) return [];
+      const cols = res[0].columns;
+      return res[0].values.map((val) => {
+        const obj = {};
+        cols.forEach((c, idx) => obj[c] = val[idx]);
+        return obj;
+      });
+    } catch {
+      return [];
+    }
+  };
+  const totalNodesRow = getRows("SELECT COUNT(*) as count FROM nodes")[0];
+  const totalNodes = totalNodesRow ? totalNodesRow.count : 0;
+  const totalEdgesRow = getRows("SELECT COUNT(*) as count FROM edges")[0];
+  const totalEdges = totalEdgesRow ? totalEdgesRow.count : 0;
+  const orphanRows = getRows(`
+    SELECT COUNT(*) as count FROM nodes
+    WHERE id NOT IN (SELECT DISTINCT source_id FROM edges UNION SELECT DISTINCT target_id FROM edges)
+  `);
+  const totalOrphans = orphanRows[0] ? orphanRows[0].count : 0;
+  const duplicateGroups = getRows(`
+    SELECT name, COUNT(*) as count FROM nodes GROUP BY name HAVING count > 1
+  `);
+  const typeStats = getRows(`
+    SELECT type, COUNT(*) as count FROM nodes GROUP BY type ORDER BY count DESC
+  `);
+  const lines = [
+    "\u{1F4CA} **Kuma Knowledge Graph Health 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\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    `\u2022 **Total Nodes:** ${totalNodes}`,
+    `\u2022 **Total Edges:** ${totalEdges}`,
+    `\u2022 **Orphan Nodes:** ${totalOrphans}`,
+    `\u2022 **Duplicate Groups:** ${duplicateGroups.length}`,
+    "",
+    "**Nodes by Type:**",
+    ...typeStats.map((s) => `  - \`${s.type}\`: ${s.count}`),
+    "",
+    "**Recommendations:**"
+  ];
+  const recs = [];
+  const crossLinks = typeStats.find((s) => s.type === "cross_service_link");
+  if (crossLinks && crossLinks.count > 50) {
+    recs.push("\u26A0\uFE0F Too many `cross_service_link` nodes. Run cleanup or delete obsolete feature domains.");
+  }
+  if (duplicateGroups.length > 0) {
+    recs.push(`\u26A0\uFE0F ${duplicateGroups.length} duplicate node groups detected. Delete duplicates using \`delete_node\`.`);
+  }
+  if (totalOrphans > 10) {
+    recs.push(`\u26A0\uFE0F ${totalOrphans} orphan nodes found (0 edges). Consider running \`heal\` or \`clear\`.`);
+  }
+  if (recs.length === 0) {
+    recs.push("\u2705 Graph health is optimal! Low noise, good signal-to-noise ratio.");
+  }
+  lines.push(...recs.map((r) => `  ${r}`));
+  return lines.join("\n");
+}
 async function handleLayersSummary(_params) {
   const { getLayersSummary: getLayersSummary2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
   return getLayersSummary2();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.23",
+  "version": "2.3.25",
   "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
   "type": "module",
   "main": "dist/index.js",

package/packages/ide/studio/public/index.html

@@ -234,8 +234,7 @@ header .status .dot.off { background: var(--red); }
     <div id="graph-container"></div>
     <div id="search-box"><input id="node-search" type="text" placeholder="Search nodes..." /></div>
     <div id="graph-controls">
-      <button onclick="resetGraphFocus()" title="Reset focus"><i data-lucide="x" style="width:12px;height:12px"></i></button>
-      <button onclick="if(network)network.fit()" title="Fit to viewport"><i data-lucide="maximize-2" style="width:12px;height:12px"></i></button>
+      <button onclick="if(network)network.fit()" title="Fit to viewport"><i data-lucide="maximize-2" style="width:12px;height:12px"></i> Fit</button>
       <div class="ctrl-sep"></div>
       <button class="depth-btn" data-depth="1" onclick="setDepth(1)">1</button>
       <button class="depth-btn active" data-depth="2" onclick="setDepth(2)">2</button>
@@ -482,7 +481,7 @@ function renderGraph(data) {
       stabilization: { iterations: 120, updateInterval: 50, onlyDynamicEdges: false, fit: false },
     },
     interaction: { hover: true, tooltipDelay: 300, zoomView: true, dragView: true, dragNodes: true, keyboard: true, multiselect: true, selectable: true, selectConnectedEdges: false },
-    nodes: { borderWidth: 0, font: { color: '#ffffff', size: 11, face: 'sans-serif', bold: true }, margin: { top: 6, bottom: 6, left: 10, right: 10 }, shapeProperties: { borderRadius: 6 } },
+    nodes: { borderWidth: 0, font: { color: '#ffffff', size: 11, face: 'sans-serif' }, margin: { top: 6, bottom: 6, left: 10, right: 10 }, shapeProperties: { borderRadius: 6 } },
     edges: { smooth: { type: 'continuous', roundness: 0.2 }, width: 1, color: { color: '#4a4a6a', highlight: '#7c3aed' } },
     configure: { enabled: false },
   });
@@ -780,7 +779,7 @@ function renderFeatures(data) {
   var items = data.features || [];
   var el = document.getElementById("panel-features");
   if(!el) return;
-  if(!items.length){el.innerHTML='<div class="empty">No features recorded yet.<br><br>Use:<br><code style="color:var(--accent)">kuma_memory({action:\'feature\', title:\'Auth\'})</code></div>';return;}
+  if(!items.length){el.innerHTML='<div class="empty">No features recorded yet.<br><br>Use:<br><code style="color:var(--accent)">kuma_memory</code></div>';return;}
   el.innerHTML = items.map(function(f){
     var feat = typeof f === 'string' ? JSON.parse(f) : f;
     var meta = {};
@@ -829,15 +828,56 @@ function renderHealth(data){
 }
 
 function setupSearch() {
+  var searchTimeout = null;
   document.getElementById("node-search").oninput = function() {
-    var query = this.value.toLowerCase().trim();
-    if (!network || !allNodes) return;
-    if (!query) { network.body.data.nodes.forEach(function(n){ network.body.data.nodes.update({id:n.id,opacity:1.0}); }); return; }
-    var matched = new Set();
-    allNodes.forEach(function(n){
-      if (n.name.toLowerCase().includes(query) || (n.file_path && n.file_path.toLowerCase().includes(query))) matched.add(n.id);
-    });
-    network.body.data.nodes.forEach(function(n){ network.body.data.nodes.update({ id: n.id, opacity: matched.has(n.id) ? 1.0 : 0.15 }); });
+    var self = this;
+    if (searchTimeout) clearTimeout(searchTimeout);
+    searchTimeout = setTimeout(function() {
+      var query = self.value.toLowerCase().trim();
+      if (!network || !allNodes) return;
+
+      if (!query) {
+        resetHighlight();
+        return;
+      }
+
+      var matched = new Set();
+      var firstMatchedId = null;
+      allNodes.forEach(function(n) {
+        if (n.name.toLowerCase().includes(query) || (n.file_path && n.file_path.toLowerCase().includes(query))) {
+          matched.add(n.id);
+          if (!firstMatchedId) firstMatchedId = n.id;
+        }
+      });
+
+      // Update Nodes
+      var nodeBatchUpdates = [];
+      network.body.data.nodes.forEach(function(n) {
+        var hit = matched.has(n.id);
+        nodeBatchUpdates.push({ id: n.id, opacity: hit ? 1.0 : 0.08, font: { color: hit ? '#ffffff' : 'rgba(255,255,255,0.04)', bold: hit } });
+      });
+      network.body.data.nodes.update(nodeBatchUpdates);
+
+      // Update Edges (Dim edges whose endpoints are both not in search results)
+      var edgeBatchUpdates = [];
+      network.body.data.edges.forEach(function(e) {
+        var hit = matched.has(e.from) || matched.has(e.to);
+        var def = edgeDefaults[e.id] || {};
+        var strokeColor = hit ? (def.color || '#64748b') : 'rgba(100,116,139,0.05)';
+        var fontColor = hit ? '#94a3b8' : 'rgba(148,163,184,0.03)';
+        edgeBatchUpdates.push({
+          id: e.id,
+          color: { color: strokeColor, highlight: '#c084fc', hover: '#38bdf8', opacity: hit ? 0.95 : 0.05 },
+          font: { color: fontColor, strokeWidth: 0, background: 'transparent' },
+          width: hit ? (def.width || 1.5) : 0.2
+        });
+      });
+      network.body.data.edges.update(edgeBatchUpdates);
+
+      if (firstMatchedId && matched.size < 10) {
+        network.focus(firstMatchedId, { scale: 1.2, animation: { duration: 300 } });
+      }
+    }, 150);
   };
 }
 </script>