@plumpslabs/kuma 2.3.17 → 2.3.19

package/dist/{chunk-3TX6Q37T.js → chunk-3BRBJZ7P.js}

@@ -78,7 +78,7 @@ function createSchema(db) {
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     source_id TEXT NOT NULL REFERENCES nodes(id),
     target_id TEXT NOT NULL REFERENCES nodes(id),
-    type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes')),
+    type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with')),
     weight REAL DEFAULT 1.0,
     metadata TEXT DEFAULT '{}',
     created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
@@ -87,13 +87,13 @@ function createSchema(db) {
   try {
     const schema = db.exec(`SELECT sql FROM sqlite_master WHERE type='table' AND name='edges'`);
     const edgeSql = schema[0]?.values?.[0]?.[0] || "";
-    if (edgeSql.includes("contains") === false || edgeSql.includes("composes") === false) {
+    if (edgeSql.includes("flows_through") === false) {
       db.run(`ALTER TABLE edges RENAME TO edges_old`);
       db.run(`CREATE TABLE IF NOT EXISTS edges (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         source_id TEXT NOT NULL REFERENCES nodes(id),
         target_id TEXT NOT NULL REFERENCES nodes(id),
-        type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes')),
+        type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with')),
         weight REAL DEFAULT 1.0,
         metadata TEXT DEFAULT '{}',
         created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),

package/dist/{chunk-SPHI2BOO.js → chunk-3OHYYXYN.js}

@@ -1,6 +1,6 @@
 import {
   sessionMemory
-} from "./chunk-R6B3VUSB.js";
+} from "./chunk-LVKOGXLC.js";
 import {
   getProjectRoot
 } from "./chunk-E2KFPEBT.js";

package/dist/{chunk-AJ7HHUDW.js → chunk-ABKE45T4.js}

@@ -76,14 +76,16 @@ var BOOTSTRAP_LINES = [
   '  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 IMMEDIATELY after every read/grep (inline)',
-  '  6. `kuma_memory({ action: "gotcha" })`                    \u2014 IMMEDIATELY when bug/quirks found (inline)',
-  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 IMMEDIATELY after tracing each flow hop (inline)',
-  '  8. `kuma_memory({ action: "decision" })`                  \u2014 IMMEDIATELY when choosing between options (inline)',
+  '  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{1F504} Record findings INLINE as you work \u2014 not just at steps 5-8. Every read/grep = mini research_save.",
+  "\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.",
@@ -119,7 +121,7 @@ function windsurfRulesTemplate() {
     "",
     "Windsurf Cascade agent: Kuma MCP tools are installed.",
     "All behavioral rules are in `.kuma/init.md`.",
-    "**Before coding, load project context via `kuma_init()`.**",
+    '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
     "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
     "",
     "Also auto-detected as SKILL.md in `.windsurf/skills/` and `.agents/skills/`."
@@ -153,11 +155,37 @@ function aiderTemplate() {
   ].join("\n");
 }
 function opencodeAgentsMdTemplate() {
+  const opencodeLines = [
+    "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
+    '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
+    "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
+    "",
+    "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+    "",
+    '  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',
+    "",
+    "\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.",
+    "",
+    "\u26A0\uFE0F **OpenCode platform note:** Tool names use `kuma_kuma_*` prefix",
+    "   (server name `kuma` + already-prefixed tool name `kuma_context`).",
+    ""
+  ].join("\n");
   return [
     "## Kuma MCP \u2014 OpenCode",
     "",
-    KUMA_CORE_INSTRUCTIONS,
-    "",
+    opencodeLines,
     "\u{1F4D6} Rules: `.kuma/init.md`",
     "\u{1F9E0} Skill: `.agents/skills/kuma/SKILL.md`"
   ].join("\n");
@@ -275,6 +303,13 @@ function generateInitMdContent() {
     "",
     "---",
     "",
+    "> \u26A0\uFE0F **Platform Tool Names:**",
+    '> \u2022 **OpenCode / Antigravity:** Use `kuma_kuma_*` prefix (e.g. `kuma_kuma_context({ action: "init" })`)',
+    '> \u2022 **Other platforms (Claude, Cursor, Cline, etc.):** Use `kuma_*` directly (e.g. `kuma_context({ action: "init" })`)',
+    "> \u2022 **Replace `kuma_` with `kuma_kuma_` in all examples below if you're on OpenCode.**",
+    "",
+    "---",
+    "",
     "## \u26A0\uFE0F SESSION WORKFLOW \u2014 Follow Steps in Order",
     "",
     "### STEP 1: Init Session (ALWAYS \u2014 Start of Session)",
@@ -309,20 +344,43 @@ function generateInitMdContent() {
     "> \u26A0\uFE0F **Research-only sessions included.** Workflow ini wajib meskipun session hanya membaca/riset tanpa code changes.",
     "",
     "> \u{1F9E0} **Graph Philosophy:** Record findings INLINE as you work, not just at the end. Every time you read a",
-    "> file, grep a pattern, or trace a flow \u2014 call `research_save` immediately to persist file/func/import nodes.",
+    "> file, grep a pattern, or trace a flow \u2014 call `research_save` immediately to persist what you learned.",
     "> The knowledge graph accumulates across sessions. The more you use it, the richer it becomes.",
     "",
-    "**AUTO-RECORDED nodes/edges** (Kuma scanner detects these automatically):",
-    "- Files, Functions, Classes \u2192 created as graph nodes",
-    "- Imports, Calls, Extends \u2192 created as graph edges",
-    "- Variables, Components, Routes \u2192 created when detected",
-    "",
-    "**RECORD INLINE \u2014 Don't wait for steps 5-8:**",
-    "- After EVERY `read` that finds new files \u2192 call `research_save` mini (persist file nodes)",
-    "- After EVERY `grep` that discovers new functions \u2192 call `research_save` (persist function nodes)",
-    "- When you discover a bug/quirk \u2192 call `gotcha` IMMEDIATELY (not at step 6)",
-    "- When you trace a data flow hop \u2192 call `arch_flow` IMMEDIATELY (not at step 7)",
-    "- When you choose between options \u2192 call `decision` IMMEDIATELY (not at step 8)",
+    "> \u{1F52C} **Scanner vs Inline Recording:**",
+    "> \u2022 Scanner = cold start only. Auto-detects structure in TS/JS/TSX/JSX files during research step 3.",
+    "> \u2022 Inline Recording = primary method. You (the agent) record findings as you read/grep/edit.",
+    "> \u2022 Non-TS/JS projects (Go, Ruby, Python, Rust, PHP) rely ENTIRELY on inline recording.",
+    "",
+    "**AUTO-RECORDED (cold start scanner \u2014 TS/JS only):**",
+    "- Files, Functions, Classes \u2192 scanned during research step 3",
+    "- Imports, Calls, Extends \u2192 scanned edges",
+    "- Components, Routes \u2192 scanned when patterns match",
+    "",
+    "\u{1F534} **MUST RECORD \u2014 High Impact (use MCP):**",
+    "- `arch_flow` \u2014 IMMEDIATELY after each flow hop. Saves reading 5-10 files next session.",
+    "- `gotcha` \u2014 IMMEDIATELY when bug/quirk found. No re-research needed.",
+    "- `decision` \u2014 IMMEDIATELY when choosing. Preserves rationale context.",
+    "- `research_save` \u2014 After exploring area. Creates searchable cache + graph file node.",
+    "",
+    "\u{1F7E2} **SKIP \u2014 Low Impact (agent can grep faster):**",
+    "- Function/class nodes \u2192 grep `funcName(` / `class ClassName`",
+    "- Component nodes \u2192 glob `**/*ComponentName*`",
+    "- Import edges \u2192 check imports directly",
+    "- Route nodes \u2192 check router file directly",
+    "- Visual graph \u2192 for humans, not AI agents",
+    "",
+    "**RECORD INLINE \u2014 Focus on high-impact actions:**",
+    "- Finished tracing a flow? \u2192 `arch_flow` IMMEDIATELY (saves reading 5-10 files next session)",
+    "- Found a bug/quirk? \u2192 `gotcha` IMMEDIATELY (no re-research needed)",
+    "- Chose between options? \u2192 `decision` IMMEDIATELY (preserves rationale)",
+    "- Explored a new area? \u2192 `research_save` (creates searchable cache)",
+    "",
+    "**SKIP recording these \u2014 grep/glob is faster:**",
+    "- Function/class nodes \u2192 just `grep funcName(` or `grep class ClassName`",
+    "- Component/route nodes \u2192 glob directly",
+    "- Import edges \u2192 read import statements",
+    "- Visual graph \u2192 for humans, not AI",
     "",
     "### STEP 5: Save Research (RECORD INLINE \u2014 After Every Read/Grep)",
     "```",
@@ -398,6 +456,7 @@ function generateInitMdContent() {
     "| `todo` | Persistent todo CRUD | When managing tasks |",
     "| `context` | Inject context notes | Additional notes when needed |",
     "| `domain_rules` | Layer 1: business rules | Record business rules when discovered |",
+    "| `add_node` | Create structural nodes (low impact \u2014 grep is faster) | Rarely needed; only for visualize debugging |",
     "| `layers` | Show all 3 layers summary | Overview memory layers |",
     "",
     "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
@@ -431,6 +490,8 @@ function generateInitMdContent() {
     "| \u25B2 `triangle` | route | API routes | AUTO by scanner |",
     "| \u2B52 `star` | test | Test files/describes | AUTO by scanner |",
     "| \u{1F4C4} `note` | context | Manual context notes | MANUAL \u2014 kuma_memory context |",
+    "| \u{1F3DB}\uFE0F `feature_domain` | FeatureDomain | High-level feature domain anchor | MANUAL \u2014 kuma_memory arch_flow (domain:) |",
+    "| \u{1F517} `cross_service_link` | Workflow hop | Cross-service/inter-file flow step | MANUAL \u2014 kuma_memory arch_flow (hops:) |",
     "| \u{1F3F7}\uFE0F `tag` | domain_rule | Business rules (Layer 1) | MANUAL \u2014 kuma_memory domain_rules |",
     "| \u{1F500} `flow` | arch_flow | Architecture flows (Layer 2) | MANUAL \u2014 kuma_memory arch_flow |",
     "| \u26A0\uFE0F `warning` | gotcha | Known gotchas (Layer 3) | MANUAL \u2014 kuma_memory gotcha |",
@@ -457,14 +518,15 @@ function generateInitMdContent() {
     "  2. kuma_safety    \u2192 guard               \u2014 Safety check",
     "  3. kuma_context   \u2192 research            \u2014 Research target area",
     "  --- EDIT/READ (use native tools) ---",
-    "  5. kuma_memory    \u2192 research_save       \u2014 Save findings (inline after every read/grep)",
-    "  6. kuma_memory    \u2192 gotcha              \u2014 Record bugs/quirks (inline when found)",
-    "  7. kuma_memory    \u2192 arch_flow           \u2014 Record data flow (inline after each hop)",
-    "  8. kuma_memory    \u2192 decision            \u2014 Record key decisions (inline when choosing)",
+    "  5. kuma_memory    \u2192 research_save       \u2014 After exploring area (creates search cache)",
+    "  6. kuma_memory    \u2192 gotcha              \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)",
+    "  7. kuma_memory    \u2192 arch_flow           \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)",
+    "  8. kuma_memory    \u2192 decision            \u2014 When choosing (preserves rationale)",
     "  9. kuma_safety    \u2192 verify              \u2014 Run tests / confirm nothing broken",
     " 10. kuma_context   \u2192 changes             \u2014 Review session activity",
     "",
-    "\u{1F504} Record INLINE as you work \u2014 not just at steps 5-8. Every read/grep = mini research_save.",
+    "\u{1F525} `arch_flow` + `gotcha` are EXPONENTIAL \u2014 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.",
     "",
     "ON DISCOVERY (When needed):",
@@ -472,14 +534,19 @@ function generateInitMdContent() {
     "  kuma_memory \u2192 context        \u2014 Additional notes",
     "  kuma_memory \u2192 todo           \u2014 Task management",
     "  kuma_memory \u2192 mine           \u2014 Historical context",
+    "  kuma_memory \u2192 add_node       \u2014 Manual function/class/component node (for visualize)",
     "```",
     "",
     "## \u{1F9E0} How the Scanner Works",
     "",
-    "Kuma's code scanner (`kumaCodeScanner.ts`) uses **regex-based pattern matching**",
-    "to detect code structure. It is NOT a full AST parser (no Babel/TypeScript compiler dependency).",
+    "Kuma's code scanner (`kumaCodeScanner.ts`) uses **lightweight regex-based pattern matching**",
+    "for **cold start** \u2014 giving new agents basic project structure on first session.",
+    "It is NOT a full AST parser (no Babel/TypeScript compiler dependency).",
+    "",
+    "**Scope:** TS/JS/TSX/JSX only. Non-TypeScript projects (Go, Ruby, Python, Rust, PHP, etc.)",
+    "rely entirely on **AI inline recording** \u2014 the agent records what it discovers as it works.",
     "",
-    "**What it detects (line-by-line regex):**",
+    "**What auto-scanner detects (line-by-line regex, TS/JS only):**",
     "- `function` declarations (named + async + generator)",
     "- Arrow function assignments (`const foo = (...) => ...`)",
     "- Typed arrow functions (`const foo: Type = (...) => ...`)",
@@ -491,41 +558,41 @@ function generateInitMdContent() {
     "- Test files (`.test.`, `.spec.`, `__tests__/`)",
     "",
     "**Known limitations:**",
-    "- Regex-based = can miss multi-line constructs or non-standard patterns",
+    "- Regex-based: can miss multi-line constructs or non-standard patterns",
     "- Complex generics or deeply nested syntax may not match",
     "- TypeScript advanced types may be partially parsed",
-    "- Scanner runs automatically during `kuma_context research` step 3",
+    "- Scanner runs during `kuma_context research` step 3 (max 200 files)",
     "- If scanner returns 0 structural nodes, the regex patterns didn't match your code style",
     "",
-    "**For richer code analysis:**",
-    "- Record findings INLINE as you read/grep \u2014 this builds the graph manually",
-    "- Call `research_save` after exploring files to persist function/class/import nodes",
-    "- The more you use Kuma, the richer the graph becomes (persistent across sessions)",
+    "**Key principle: Scanner = cold start, Inline Recording = primary.**",
+    "The scanner populates initial graph structure. Every subsequent session, the agent's",
+    "inline recording (research_save, gotcha, arch_flow, decision) enriches the graph further.",
+    "The more you use Kuma, the richer the graph becomes \u2014 persistent across sessions.",
     "",
     "---",
     "",
-    "## \u{1F4BE} How to Read Memory & Search the Graph",
+    "## \u{1F4BE} How to Retrieve Past Research \u2014 research_save \u2192 search",
     "",
-    "Kuma stores knowledge in two places:",
+    "Kuma stores knowledge in two places. The primary retrieval method for AI agents",
+    "is **`search`**, not `visualize`. Visualize is for human debugging, not agent consumption.",
     "",
-    "**1. Knowledge Graph (SQLite - `.kuma/kuma.db`)**",
-    "- Nodes: files, functions, classes, components, routes, tests, gotchas, decisions",
-    "- Edges: imports, calls, extends, contains, composes, routes",
-    '- Query: `kuma_memory({ action: "search", query: "<term>" })`',
-    "- Falls back to codebase grep if graph is empty",
+    "**Flow: research_save \u2192 search (for agents)**",
+    '- Save: `kuma_memory({ action: "research_save", scope: "<file or area>", confidence: 0.8 })`',
+    '- Retrieve: `kuma_memory({ action: "search", query: "<term>" })`',
+    '- Auto-load: `kuma_context({ action: "research", scope: "<area>" })`',
+    '- List cache: `kuma_context({ action: "researches" })`',
     "",
-    "**2. Research Cache (SQLite - `.kuma/kuma.db`)**",
-    '- Saved via `kuma_memory({ action: "research_save", scope: "<area>", confidence: 0.8 })`',
-    '- List: `kuma_context({ action: "researches" })`',
-    '- Auto-loaded during `kuma_context({ action: "research", scope: "<area>" })`',
+    "**Key design:** `research_save` now creates BOTH research cache entries AND",
+    "knowledge graph nodes (file + research scope). This means `search` finds",
+    "past research even if the graph scanner didn't detect your code style.",
     "",
-    "**Quick memory reading tips:**",
+    "**Quick retrieval tips:**",
+    '- `kuma_memory({ action: "search", query: "<term>" })` \u2014 **primary method**. Finds past research + graph nodes + codebase',
+    '- `kuma_context({ action: "research", scope: "<area>" })` \u2014 deep 5-step research, auto-loads past cache',
     '- `kuma_context({ action: "init" })` \u2014 shows graph stats + recent research + health score',
-    '- `kuma_context({ action: "research", scope: "<area>" })` \u2014 deep research with graph query',
-    '- `kuma_memory({ action: "search", query: "<term>" })` \u2014 search all memories + graph',
-    '- `kuma_context({ action: "visualize" })` \u2014 Mermaid diagram of the graph',
     '- `kuma_context({ action: "drift" })` \u2014 check if memories are stale vs actual code',
     '- `kuma_context({ action: "changes" })` \u2014 view session activity log',
+    '- `kuma_context({ action: "visualize" })` \u2014 (human debugging) Mermaid diagram of the graph',
     "",
     "---",
     "",
@@ -598,14 +665,15 @@ function handleOpencodeSecondary(root, results) {
       '  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 Save findings (inline after every read/grep)',
-      '  6. `kuma_kuma_memory({ action: "gotcha" })`                           \u2014 Record bugs/quirks (inline when found)',
-      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 Record data flow (inline after each hop)',
-      '  8. `kuma_kuma_memory({ action: "decision" })`                         \u2014 Record key decisions (inline when choosing)',
+      '  5. `kuma_kuma_memory({ action: "research_save", ... })`               \u2014 After exploring area (creates search cache)',
+      '  6. `kuma_kuma_memory({ action: "gotcha" })`                           \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
+      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
+      '  8. `kuma_kuma_memory({ action: "decision" })`                         \u2014 When choosing (preserves rationale)',
       '  9. `kuma_kuma_safety({ action: "verify", ... })`                      \u2014 Run tests / confirm nothing broken',
       ' 10. `kuma_kuma_context({ action: "changes" })`                         \u2014 Review session activity',
       "",
-      "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+      "\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.",
       "",
       "\u26A0\uFE0F **OpenCode platform note:** Tool names are prefixed with `kuma_kuma_*`",
@@ -729,14 +797,15 @@ function getCombinedAgentsMd(selectedTypes) {
     '  2. `[kuma_]safety({ action: "guard" })`                     \u2014 Safety check before editing',
     '  3. `[kuma_]context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
     "  4. *(edit/read using native tools)*",
-    '  5. `[kuma_]memory({ action: "research_save", ... })`        \u2014 Save all findings',
-    '  6. `[kuma_]memory({ action: "gotcha" })`                    \u2014 Record bugs/quirks found',
-    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 Record data flow if mapped',
-    '  8. `[kuma_]memory({ action: "decision" })`                  \u2014 Record key findings/decisions',
+    '  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',
     "",
-    "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+    "\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.",
     "",
     "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
@@ -946,15 +1015,16 @@ function handleQuickrefGeneration(root, results) {
     '  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 Save findings (inline after every read)',
-    '  6. `kuma_memory({ action: "gotcha" })`                            \u2014 Gotchas (inline when found)',
-    '  7. `kuma_memory({ action: "arch_flow" })`                         \u2014 Arch flow (inline after each hop)',
-    '  8. `kuma_memory({ action: "decision" })`                          \u2014 Decision (inline when choosing)',
-    '  9. `kuma_safety({ action: "verify", ... })`                       \u2014 Verify',
-    ' 10. `kuma_context({ action: "changes" })`                          \u2014 Review changes',
-    "",
-    "\u{1F504} Record INLINE as you work \u2014 Every read/grep = mini research_save.",
-    "\u{1F9E0} Graph is persistent \u2014 accumulates across sessions.",
+    '  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',
+    "",
+    "\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.",
     "",
     "\u26D4 Steps 5-10 are mandatory even for research-only sessions!",
     "",

package/dist/{chunk-Q2444HWO.js → chunk-FKRSI5U5.js}

@@ -1,6 +1,6 @@
 import {
   sessionMemory
-} from "./chunk-R6B3VUSB.js";
+} from "./chunk-LVKOGXLC.js";
 import {
   getProjectRoot
 } from "./chunk-E2KFPEBT.js";

package/dist/{chunk-RI3DKY62.js → chunk-GFLSAXAH.js}

@@ -1,7 +1,7 @@
 import {
   getDb,
   saveDb
-} from "./chunk-3TX6Q37T.js";
+} from "./chunk-3BRBJZ7P.js";
 
 // src/engine/safetyAudit.ts
 var SCHEMA_SQL = `

package/dist/{chunk-OJALFQ4H.js → chunk-L7F67KUP.js}

@@ -1,6 +1,6 @@
 import {
   sessionMemory
-} from "./chunk-R6B3VUSB.js";
+} from "./chunk-LVKOGXLC.js";
 import {
   getProjectRoot
 } from "./chunk-E2KFPEBT.js";
@@ -82,7 +82,7 @@ function recordDecision(decision) {
 }
 async function recordDecisionToGraph(decision) {
   try {
-    const { upsertNode, addEdge } = await import("./kumaGraph-GUQM75WL.js");
+    const { upsertNode, addEdge } = await import("./kumaGraph-UMXZNGYF.js");
     const decisionId = `decision::${decision.title.replace(/[^a-zA-Z0-9_\-\s]/g, "").trim().replace(/\s+/g, "-")}`;
     await upsertNode({
       id: decisionId,

package/dist/{chunk-R6B3VUSB.js → chunk-LVKOGXLC.js}

@@ -320,7 +320,7 @@ No unresolved issues.`;
    */
   async autoTrackToDb(toolName, params, timestamp) {
     try {
-      const { getDb, saveDb } = await import("./kumaDb-IC7UX7PU.js");
+      const { getDb, saveDb } = await import("./kumaDb-4XZ5S2LH.js");
       const db = await getDb();
       db.run(
         `INSERT INTO tool_calls (tool_name, params, success, duration_ms, created_at) VALUES (?, ?, 1, 0, ?)`,
@@ -605,7 +605,7 @@ No unresolved issues.`;
       this.addModifiedFile(filePath);
     }
     try {
-      const { recordChange } = await import("./kumaDb-IC7UX7PU.js");
+      const { recordChange } = await import("./kumaDb-4XZ5S2LH.js");
       const gitHash = this.getGitHead();
       await recordChange({ filePath, changeType, symbol, gitCommitHash: gitHash || void 0 });
     } catch {

package/dist/{chunk-ZKDYTYMS.js → chunk-PRUTTZBS.js}

@@ -1,7 +1,7 @@
 import {
   getDb,
   saveDb
-} from "./chunk-3TX6Q37T.js";
+} from "./chunk-3BRBJZ7P.js";
 import {
   getProjectRoot
 } from "./chunk-E2KFPEBT.js";
@@ -319,6 +319,144 @@ async function recordApiRoute(route, handler) {
   await upsertNode({ id: handlerId, type: "function", name: handler });
   await addEdge({ sourceId: routeId, targetId: handlerId, type: "routes" });
 }
+async function recordDomainFlow(params) {
+  let nodeCount = 0;
+  let edgeCount = 0;
+  try {
+    const domainId = nodeId("feature_domain", params.domain);
+    await upsertNode({
+      id: domainId,
+      type: "feature_domain",
+      name: params.domain,
+      metadata: {
+        hops: params.hops.length,
+        gotchas: params.gotchas?.length || 0,
+        decisions: params.decisions?.length || 0,
+        filePaths: params.filePaths || []
+      }
+    });
+    nodeCount++;
+    for (let i = 0; i < params.hops.length; i++) {
+      const hop = params.hops[i];
+      const fromId = nodeId("cross_service_link", `${params.domain}::${hop.from}`);
+      await upsertNode({
+        id: fromId,
+        type: "cross_service_link",
+        name: hop.from,
+        metadata: {
+          domain: params.domain,
+          relation: hop.relation,
+          description: hop.description || "",
+          hopIndex: i
+        }
+      });
+      nodeCount++;
+      const toId = nodeId("cross_service_link", `${params.domain}::${hop.to}`);
+      await upsertNode({
+        id: toId,
+        type: "cross_service_link",
+        name: hop.to,
+        metadata: {
+          domain: params.domain,
+          relation: hop.relation,
+          description: hop.description || "",
+          hopIndex: i
+        }
+      });
+      nodeCount++;
+      await addEdge({
+        sourceId: fromId,
+        targetId: toId,
+        type: "flows_through",
+        metadata: { relation: hop.relation, description: hop.description }
+      });
+      edgeCount++;
+      await addEdge({
+        sourceId: domainId,
+        targetId: fromId,
+        type: "contains",
+        metadata: { hopIndex: i }
+      });
+      edgeCount++;
+      await addEdge({
+        sourceId: domainId,
+        targetId: toId,
+        type: "contains",
+        metadata: { hopIndex: i }
+      });
+      edgeCount++;
+    }
+    if (params.gotchas) {
+      for (const gotcha of params.gotchas) {
+        const gotchaId = `gotcha::${params.domain}::${gotcha.substring(0, 40)}`;
+        try {
+          await upsertNode({
+            id: gotchaId,
+            type: "variable",
+            name: `gotcha:${gotcha.substring(0, 60)}`,
+            metadata: { domain: params.domain, gotcha, source: "arch_flow" }
+          });
+          nodeCount++;
+          await addEdge({
+            sourceId: domainId,
+            targetId: gotchaId,
+            type: "depends_on",
+            metadata: { type: "gotcha" }
+          });
+          edgeCount++;
+        } catch {
+        }
+      }
+    }
+    if (params.decisions) {
+      for (const decision of params.decisions) {
+        const decisionId = `decision::${params.domain}::${decision.substring(0, 40)}`;
+        try {
+          await upsertNode({
+            id: decisionId,
+            type: "variable",
+            name: `decision:${decision.substring(0, 60)}`,
+            metadata: { domain: params.domain, decision, source: "arch_flow" }
+          });
+          nodeCount++;
+          await addEdge({
+            sourceId: domainId,
+            targetId: decisionId,
+            type: "depends_on",
+            metadata: { type: "decision" }
+          });
+          edgeCount++;
+        } catch {
+        }
+      }
+    }
+    if (params.filePaths) {
+      for (const fp of params.filePaths) {
+        const fileId = nodeId("file", fp);
+        try {
+          await upsertNode({
+            id: fileId,
+            type: "file",
+            name: fp
+          });
+          nodeCount++;
+          await addEdge({
+            sourceId: domainId,
+            targetId: fileId,
+            type: "owns",
+            metadata: { domain: params.domain }
+          });
+          edgeCount++;
+        } catch {
+        }
+      }
+    }
+    return { nodeCount, edgeCount };
+  } catch (err) {
+    console.error(`[KumaGraph] Failed to record domain flow: ${err}`);
+    return { nodeCount, edgeCount };
+  }
+}
 async function queryGraph(params) {
   try {
     const db = await getDb();
@@ -353,7 +491,7 @@ Try a different search term or check if the graph has been built by using tools
         ""
       ];
       for (const r of results) {
-        const typeEmoji = r.type === "function" ? "\u{1F527}" : r.type === "file" ? "\u{1F4C4}" : r.type === "test" ? "\u{1F9EA}" : r.type === "api_route" ? "\u{1F310}" : r.type === "db_table" ? "\u{1F5C4}\uFE0F" : r.type === "class" ? "\u{1F3D7}\uFE0F" : "\u{1F4CC}";
+        const typeEmoji = r.type === "function" ? "\u{1F527}" : r.type === "file" ? "\u{1F4C4}" : r.type === "test" ? "\u{1F9EA}" : r.type === "api_route" ? "\u{1F310}" : r.type === "db_table" ? "\u{1F5C4}\uFE0F" : r.type === "class" ? "\u{1F3D7}\uFE0F" : r.type === "feature_domain" ? "\u{1F3DB}\uFE0F" : r.type === "workflow" ? "\u{1F504}" : r.type === "cross_service_link" ? "\u{1F517}" : "\u{1F4CC}";
         lines.push(`${typeEmoji} **${r.name}** (${r.type})`);
         if (r.file_path) lines.push(`   \u{1F4CD} ${r.file_path}`);
       }
@@ -458,7 +596,7 @@ The two nodes may not be connected in the knowledge graph yet. Use more tools to
 }
 async function buildFromSessionMemory() {
   try {
-    const { sessionMemory } = await import("./sessionMemory-4UWA3E5J.js");
+    const { sessionMemory } = await import("./sessionMemory-YPKVIOMV.js");
     const toolCalls = sessionMemory.getToolCallHistory(50);
     let edgeCount = 0;
     for (const call of toolCalls) {
@@ -757,7 +895,7 @@ async function getGraphStats() {
     if (typeCounts.length > 0) {
       lines.push("**Node Types:**");
       for (const t of typeCounts) {
-        const emoji = t.type === "function" ? "\u{1F527}" : t.type === "file" ? "\u{1F4C4}" : t.type === "test" ? "\u{1F9EA}" : t.type === "api_route" ? "\u{1F310}" : t.type === "db_table" ? "\u{1F5C4}\uFE0F" : t.type === "class" ? "\u{1F3D7}\uFE0F" : "\u{1F4CC}";
+        const emoji = t.type === "function" ? "\u{1F527}" : t.type === "file" ? "\u{1F4C4}" : t.type === "test" ? "\u{1F9EA}" : t.type === "api_route" ? "\u{1F310}" : t.type === "db_table" ? "\u{1F5C4}\uFE0F" : t.type === "class" ? "\u{1F3D7}\uFE0F" : t.type === "feature_domain" ? "\u{1F3DB}\uFE0F" : t.type === "workflow" ? "\u{1F504}" : t.type === "cross_service_link" ? "\u{1F517}" : "\u{1F4CC}";
         lines.push(`  ${emoji} ${t.type}: ${t.cnt}`);
       }
     }
@@ -961,6 +1099,7 @@ export {
   recordImport,
   recordTestRelation,
   recordApiRoute,
+  recordDomainFlow,
   queryGraph,
   buildFromSessionMemory,
   searchGraph,