@plumpslabs/kuma 2.3.14 → 2.3.16

package/dist/{chunk-LRO3HWGC.js → chunk-S7BQGNHQ.js}

@@ -70,17 +70,23 @@ var BOOTSTRAP_LINES = [
   '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
   "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
   "",
-  "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
+  "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
   "",
-  '  1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-  '  2. `kuma_safety({ action: "guard" })` \u2014 Safety check before work',
+  '  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 using native tools)*",
-  '  5. `kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
-  '  6. `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
-  '  7. `kuma_context({ action: "changes" })` \u2014 Review changes',
+  "  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)',
+  '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
+  ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
   "",
-  "\u26D4 Skipping workflow = stale context, missed decisions, unverified code.",
+  "\u{1F504} Record findings INLINE as you work \u2014 not just at steps 5-8. Every read/grep = mini research_save.",
+  "\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{1F4D6} Full rules: `.kuma/init.md`",
   "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
 ].join("\n");
@@ -294,54 +300,71 @@ function generateInitMdContent() {
     "",
     "> \u26D4 DO NOT EDIT FILES BEFORE STEP 3 \u2014 Unless trivial/minor change",
     "",
-    "### STEP 4: EDIT \u2014 Implement (Use Agent Native Tools)",
+    "### STEP 4: EDIT/READ \u2014 Implement (Use Agent Native Tools)",
     "```",
     "# Use agent BUILT-IN tools to read, grep, edit, create files",
     "# Kuma does NOT manage files \u2014 that's your agent's job",
     "```",
     "",
+    "> \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.",
+    "> 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",
     "",
-    "**MANUAL \u2014 When to call these yourself:**",
-    '- `kuma_memory({ action: "research_save" })` \u2014 after exploring/learning something new',
-    '- `kuma_memory({ action: "decision" })` \u2014 after making an architecture/design choice',
-    '- `kuma_memory({ action: "context" })` \u2014 inject arbitrary context notes',
-    '- `kuma_memory({ action: "domain_rules" })` \u2014 record business rules',
-    '- `kuma_memory({ action: "arch_flow" })` \u2014 document architecture flow',
-    '- `kuma_memory({ action: "gotcha" })` \u2014 log known quirks/workarounds',
-    '- `kuma_memory({ action: "todo" })` \u2014 create persistent task',
-    '- `kuma_memory({ action: "mine" })` \u2014 extract historical decisions from git',
-    "",
-    "### STEP 5: Save Research (AFTER Editing)",
+    "**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)",
+    "",
+    "### STEP 5: Save Research (RECORD INLINE \u2014 After Every Read/Grep)",
+    "```",
+    'kuma_memory({ action: "research_save", scope: "<file or area>", confidence: 0.8 })',
+    "```",
+    "**When:** After EVERY read/grep that discovers new files, functions, imports, or patterns. Don't wait \u2014 record inline!",
+    "**Why:** Persist findings into knowledge graph + research cache. Graph grows richer across sessions.",
+    "",
+    "### STEP 6: Record Gotchas (RECORD INLINE \u2014 When Bug Found)",
+    "```",
+    'kuma_memory({ action: "gotcha", filePath: "<file>", description: "...", severity: "medium" })',
+    "```",
+    "**When:** IMMEDIATELY when you discover bugs, quirks, unexpected behavior, or workarounds. Record INLINE, don't save for later.",
+    "**Why:** Prevents future agents from hitting the same issues. Every bug = a gotcha. Skip now = lost forever.",
+    "",
+    "### STEP 7: Record Arch Flow (RECORD INLINE \u2014 When Tracing Flow)",
     "```",
-    'kuma_memory({ action: "research_save", scope: "<area>", confidence: 0.8 })',
+    'kuma_memory({ action: "arch_flow", content: "..." })',
     "```",
-    "**When:** After exploring a new area or finishing edits",
-    "**Why:** Persist findings into knowledge graph + research cache",
+    "**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.",
     "",
-    "### STEP 6: Record Decision (AFTER Significant Changes)",
+    "### STEP 8: Record Decision (RECORD INLINE \u2014 When Choosing)",
     "```",
     'kuma_memory({ action: "decision", decisionAction: "record", title: "...", outcome: "..." })',
     "```",
-    "**When:** After making architecture/design decisions",
-    "**Why:** Saves ADR (Architecture Decision Record) to the decision log",
+    "**When:** IMMEDIATELY when you choose between 2+ options, uncover an architecture pattern, or identify a root cause.",
+    "**Why:** Saves ADR (Architecture Decision Record). Bukan cuma code changes \u2014 temuan, tradeoffs, root causes juga.",
     "",
-    "### STEP 7: Verify (AFTER Editing)",
+    "### STEP 9: Verify (MANDATORY \u2014 After Research/Editing)",
     "```",
     'kuma_safety({ action: "verify", scope: "<area or file>" })',
     "```",
-    "**When:** After edits are done, before switching tasks",
-    "**Why:** Auto-run scoped tests + AST code validation",
+    "**When:** After research/edits are done, before switching tasks. Even for research-only \u2014 confirms nothing is broken.",
+    '**Why:** Auto-run scoped tests + AST code validation. If no test framework, at minimum report "No tests to run".',
     "",
-    "### STEP 8: Check Changes (BEFORE Commit / End of Session)",
+    "### STEP 10: Check Changes (MANDATORY \u2014 End of Session)",
     "```",
     'kuma_context({ action: "changes" })',
     "```",
-    "**When:** End of session or before git commit",
-    "**Why:** Review all modifications made in this session",
+    "**When:** End of session or before git commit. Even 0 changes = valid result to confirm.",
+    "**Why:** View session log of all modifications + tool calls made in this session.",
     "",
     "---",
     "",
@@ -355,7 +378,7 @@ function generateInitMdContent() {
     "| `research` | 5-step research pipeline | STEP 3 \u2014 Before edits |",
     "| `impact` | Analyze change effects on symbol | After research, before design |",
     "| `navigate` | Trace code flow | When need to understand call flow |",
-    "| `changes` | View session change log | STEP 8 \u2014 End of session |",
+    "| `changes` | View session change log | STEP 10 \u2014 End of session |",
     "| `health` | Project health score 0-100 | Periodic check |",
     "| `digest` | Ultra-compact project briefing | Session start (alt to init) |",
     "| `drift` | Detect memory staleness | When suspecting stale context |",
@@ -364,17 +387,17 @@ function generateInitMdContent() {
     "",
     "| Action | Description | When to Call |",
     "|--------|-------------|--------------|",
-    "| `research_save` | Save research results | STEP 5 \u2014 After exploring/editing |",
-    "| `decision` | ADR-style decision record | STEP 6 \u2014 After major decisions |",
+    "| `research_save` | Save research results | STEP 5 \u2014 IMMEDIATELY after every read/grep (inline) |",
+    "| `gotcha` | Record bugs/quirks/workarounds | STEP 6 \u2014 IMMEDIATELY when bug found (inline) |",
+    "| `arch_flow` | Document architecture flow | STEP 7 \u2014 IMMEDIATELY after each flow hop (inline) |",
+    "| `decision` | ADR-style decision record | STEP 8 \u2014 IMMEDIATELY when choosing (inline) |",
     "| `mine` | Mine decisions from git log | When need historical context |",
     "| `session` | Session summary | End of session |",
     "| `heal` | Self-heal knowledge graph | When graph has errors |",
     "| `search` | Search memories + graph | Find stored information |",
     "| `todo` | Persistent todo CRUD | When managing tasks |",
-    "| `context` | Inject context notes | Manual \u2014 additional notes |",
-    "| `domain_rules` | Layer 1: business rules | Manual \u2014 record business rules |",
-    "| `arch_flow` | Layer 2: architecture flow | Manual \u2014 document architecture |",
-    "| `gotcha` | Layer 3: known gotchas | Manual \u2014 log quirks/legacy |",
+    "| `context` | Inject context notes | Additional notes when needed |",
+    "| `domain_rules` | Layer 1: business rules | Record business rules when discovered |",
     "| `layers` | Show all 3 layers summary | Overview memory layers |",
     "",
     "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
@@ -382,7 +405,7 @@ function generateInitMdContent() {
     "| Action | Description | When to Call |",
     "|--------|-------------|--------------|",
     "| `guard` | Anti-pattern, drift, loop | STEP 2 \u2014 Before work |",
-    "| `verify` | Auto-run scoped tests | STEP 7 \u2014 After edits |",
+    "| `verify` | Auto-run scoped tests + validation | STEP 9 \u2014 After research/edits |",
     "| `check` | Pre-execution safety check | Before risky operations |",
     "| `audit` | Query safety audit trail | Security investigation |",
     "| `lock` | Multi-agent file lock | Multi-agent collaboration |",
@@ -429,20 +452,23 @@ function generateInitMdContent() {
     "## \u{1F4CC} Workflow Summary",
     "",
     "```",
-    "EVERY SESSION (Mandatory):",
-    "  1. kuma_context   \u2192 init             \u2014 Load project context",
-    "  2. kuma_safety    \u2192 guard            \u2014 Safety check",
-    "  3. kuma_context   \u2192 research         \u2014 Research target area",
-    "  --- EDIT (use native tools) ---",
-    "  5. kuma_memory    \u2192 research_save    \u2014 Save findings",
-    "  6. kuma_memory    \u2192 decision         \u2014 Record decisions",
-    "  7. kuma_safety    \u2192 verify           \u2014 Verify correctness",
-    "  8. kuma_context   \u2192 changes          \u2014 Review changes",
-    "",
-    "MANUAL (When needed):",
+    "EVERY SESSION (Mandatory \u2014 including research-only):",
+    "  1. kuma_context   \u2192 init                \u2014 Load project context",
+    "  2. kuma_safety    \u2192 guard               \u2014 Safety check",
+    "  3. kuma_context   \u2192 research            \u2014 Research target area",
+    "  --- EDIT/READ (use native tools) ---",
+    "  5. kuma_memory    \u2192 research_save       \u2014 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)",
+    "  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{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
+    "",
+    "ON DISCOVERY (When needed):",
     "  kuma_memory \u2192 domain_rules   \u2014 Business rules (Layer 1)",
-    "  kuma_memory \u2192 arch_flow      \u2014 Architecture flow (Layer 2)",
-    "  kuma_memory \u2192 gotcha         \u2014 Known quirks (Layer 3)",
     "  kuma_memory \u2192 context        \u2014 Additional notes",
     "  kuma_memory \u2192 todo           \u2014 Task management",
     "  kuma_memory \u2192 mine           \u2014 Historical context",
@@ -494,15 +520,21 @@ function handleOpencodeSecondary(root, results) {
       '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context and session memory.',
       "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
-      "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
+      "\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 using native tools)*",
-      '  5. `kuma_kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
-      '  6. `kuma_kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
-      '  7. `kuma_kuma_context({ action: "changes" })` \u2014 Review changes',
+      '  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 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)',
+      '  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{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
       "",
       "\u26A0\uFE0F **OpenCode platform note:** Tool names are prefixed with `kuma_kuma_*`",
       "   (server name `kuma` + already-prefixed tool name `kuma_context`).",
@@ -614,19 +646,28 @@ function getCombinedAgentsMd(selectedTypes) {
     "",
     "---",
     "",
+    '> \u26A0\uFE0F **WARNING:** Agent often skip steps due to "research-only" bias. Do NOT skip.',
+    "> Follow the full 10-step workflow even for read-only investigations.",
+    "",
     "## \u26A0\uFE0F MANDATORY WORKFLOW",
     "",
-    "Follow these steps in order every session (all platforms):",
+    "Follow these steps in order every session (including research-only):",
     "",
-    '  1. `[kuma_]context({ action: "init" })`                   \u2014 Load project context (START HERE)',
-    '  2. `[kuma_]safety({ action: "guard" })`                   \u2014 Safety check before editing',
+    '  1. `[kuma_]context({ action: "init" })`                     \u2014 Load project context (START HERE)',
+    '  2. `[kuma_]safety({ action: "guard" })`                     \u2014 Safety check before editing',
     '  3. `[kuma_]context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-    "  4. *(edit using native tools)*",
-    '  5. `[kuma_]memory({ action: "research_save", ... })`      \u2014 Save findings',
-    '  6. `[kuma_]safety({ action: "verify", ... })`             \u2014 Verify correctness',
-    '  7. `[kuma_]context({ action: "changes" })`                \u2014 Review changes',
+    "  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',
+    '  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{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
-    "\u26D4 Skipping workflow = stale context, missed decisions, unverified code.",
+    "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
     "",
     "Replace `[kuma_]` with the correct prefix for your platform (see below).",
     "",
@@ -820,6 +861,62 @@ function handleOpenclawSecondary(root, results) {
     });
   }
 }
+function handleQuickrefGeneration(root, results) {
+  const quickrefPath = path.resolve(root, ".kuma/quickref.md");
+  const content = [
+    "# Kuma Quick Reference",
+    "",
+    "_(Auto-generated by `kuma init` \u2014 simplified workflow cheat sheet)_",
+    "",
+    "## Every Session (Mandatory \u2014 including research-only)",
+    "",
+    '  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 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.",
+    "",
+    "\u26D4 Steps 5-10 are mandatory even for research-only sessions!",
+    "",
+    "## Platform Tool Names",
+    "",
+    "- **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`",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const kumaDir = path.dirname(quickrefPath);
+    if (!fs.existsSync(kumaDir)) fs.mkdirSync(kumaDir, { recursive: true });
+    if (fs.existsSync(quickrefPath)) {
+      const existing = fs.readFileSync(quickrefPath, "utf-8");
+      if (existing.includes("_Generated by Kuma MCP_")) {
+        results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
+        return;
+      }
+      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
+    } else {
+      fs.writeFileSync(quickrefPath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({
+      type: "claude",
+      filePath: ".kuma/quickref.md",
+      action: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
 function handleInitMdGeneration(root, results) {
   const initMdPath = path.resolve(root, ".kuma/init.md");
   try {
@@ -845,6 +942,7 @@ function handleInitMdGeneration(root, results) {
       error: err instanceof Error ? err.message : String(err)
     });
   }
+  handleQuickrefGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
   const mcpPath = path.resolve(root, ".codewhale/mcp.json");

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   ALL_CONFIG_TYPES,
   formatInitResults,
   runInit
-} from "./chunk-LRO3HWGC.js";
+} from "./chunk-S7BQGNHQ.js";
 import {
   formatDecisionTemplate,
   getProactiveMemories,
@@ -2190,7 +2190,7 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "**Call AFTER editing** to persist what you learned.\n\nAFTER EDITING (call these yourself):\n\u2022 STEP 5: `research_save` \u2014 save findings into knowledge graph\n\u2022 STEP 6: `decision` \u2014 record architecture decisions (ADR)\n\nMANUAL (call when you discover something):\n\u2022 `gotcha` \u2014 found a quirk/workaround/legacy issue? Log it!\n\u2022 `domain_rules` \u2014 uncovered business rules? Save them!\n\u2022 `arch_flow` \u2014 mapped out architecture flow? Document it!\n\u2022 `context` \u2014 need to inject extra notes? Use this!\n\u2022 `todo` \u2014 create persistent task items\n\u2022 `mine` \u2014 extract historical context from git log\n\nOther actions: session, heal, search, changes, benchmark, layers.",
+    "**Call AFTER research/editing every session** (including research-only). Record INLINE as you work.\n\nRECORD INLINE (call IMMEDIATELY during research):\n\u2022 STEP 5: `research_save` \u2014 every read/grep that finds new files/functions. Don't wait!\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. Record INLINE, not at the end.\n\u2022 STEP 7: `arch_flow` \u2014 IMMEDIATELY after EACH flow hop trace. Record before next task.\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options or finding architecture patterns.\n\nON DISCOVERY (when you encounter something):\n\u2022 `domain_rules` \u2014 uncovered business rules? Save them!\n\u2022 `context` \u2014 need to inject extra notes? Use this!\n\u2022 `todo` \u2014 create persistent task items\n\u2022 `mine` \u2014 extract historical context from git log\n\nOther actions: session, heal, search, changes, benchmark, layers.",
     {
       action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "federated", "gen_test", "trajectory", "skills"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save, session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules (Issue #17), arch_flow=Layer 2 architecture flow (Issue #17), gotcha=Layer 3 known gotchas (Issue #17/#21), layers=all 3 layers summary, federated=resolve federated kuma:// URI (Issue #27), gen_test=generate test from trajectory (Issue #28), trajectory=list trajectories, skills=list distilled skills"),
       scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
@@ -2257,7 +2257,7 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_safety",
-    "Safety checks, policy enforcement, and auto-verification.\n\nWORKFLOW:\n\u2022 STEP 2 (BEFORE work): `guard` \u2014 detect anti-patterns, drift, runaway loops\n\u2022 STEP 7 (AFTER edits): `verify` \u2014 auto-run scoped tests + AST validation\n\nOther actions: check (pre-exec safety), audit (query trail), lock (multi-agent), health (score 0-100), policy (evaluate commands), ast (code validation), checkpoint (snapshot before refactors), contract (pre/post-condition check).",
+    "Safety checks, policy enforcement, and auto-verification.\n\nWORKFLOW:\n\u2022 STEP 2 (BEFORE work): `guard` \u2014 detect anti-patterns, drift, runaway loops\n\u2022 STEP 9 (AFTER research/edits): `verify` \u2014 auto-run scoped tests + AST validation\n\nOther actions: check (pre-exec safety), audit (query trail), lock (multi-agent), health (score 0-100), policy (evaluate commands), ast (code validation), checkpoint (snapshot before refactors), contract (pre/post-condition check).",
     {
       action: z.enum(["guard", "verify", "check", "audit", "lock", "health", "override", "security", "gc", "doctor", "portability", "gitignore", "clean", "policy", "ast", "validate", "checkpoint", "rollback_label", "checkpoint_list", "contract"]).describe("Safety action: guard=anti-patterns, verify=auto-run scoped tests, check=pre-exec safety, audit=query trail, lock=multi-agent, health=score, security=scan leaks, gc=garbage collect, doctor=health check, portability=paths, gitignore=config, clean=purge scratch dir & drift, policy=Policy-as-Code engine (Issue #24), ast/validate=AST-based code validation (Issue #22), checkpoint=create atomic snapshot (Issue #29), rollback_label=restore from checkpoint (Issue #29), checkpoint_list=list checkpoints, contract=run contract checks (Issue #26), override=bypass"),
       // Verify params
@@ -2571,7 +2571,7 @@ async function main() {
   });
   (async () => {
     try {
-      const { generateInitMdContent } = await import("./init-7MWMONZL.js");
+      const { generateInitMdContent } = await import("./init-P3DAC23E.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const initMdPath = path7.resolve(process.cwd(), ".kuma/init.md");
@@ -2588,7 +2588,7 @@ async function main() {
   (async () => {
     try {
       const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-YOWQVJFR.js");
-      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-JIHFTNH6.js");
+      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-GYEDLFZP.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const detection = detectAgent();

package/dist/{init-7MWMONZL.js → init-P3DAC23E.js}

@@ -4,7 +4,7 @@ import {
   formatInitResults,
   generateInitMdContent,
   runInit
-} from "./chunk-LRO3HWGC.js";
+} from "./chunk-S7BQGNHQ.js";
 import "./chunk-E2KFPEBT.js";
 export {
   ALL_CONFIG_TYPES,

package/dist/{skillGenerator-JIHFTNH6.js → skillGenerator-GYEDLFZP.js}

@@ -4,17 +4,23 @@ var BOOTSTRAP = [
   '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
   "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
   "",
-  "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
+  "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
   "",
-  '  1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-  '  2. `kuma_safety({ action: "guard" })` \u2014 Safety check before work',
+  '  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 using native tools)*",
-  '  5. `kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
-  '  6. `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
-  '  7. `kuma_context({ action: "changes" })` \u2014 Review changes',
+  "  4. *(edit/read using native tools)*",
+  '  5. `kuma_memory({ action: "research_save", ... })`        \u2014 Save findings (inline after every read/grep)',
+  '  6. `kuma_memory({ action: "gotcha" })`                    \u2014 Record bugs/quirks (inline when found)',
+  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 Record data flow (inline after each hop)',
+  '  8. `kuma_memory({ action: "decision" })`                  \u2014 Record key decisions (inline when choosing)',
+  '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
+  ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
   "",
-  "\u26D4 Skipping workflow = stale context, missed decisions, unverified code.",
+  "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+  "\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{1F4D6} Full rules: `.kuma/init.md`",
   "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
 ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.14",
+  "version": "2.3.16",
   "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",