@infinitedusky/indusk-mcp 1.9.2 → 1.10.0

package/dist/bin/commands/extensions.js

@@ -3,7 +3,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, write
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
-import { disableExtension, disabledDir, enableExtension, ensureExtensionsDirs, extensionConfigDir, extensionsDir, getEnabledExtensions, isEnabled, loadExtension, loadExtensions, resolveManifestPath, } from "../../lib/extension-loader.js";
+import { disabledDir, disableExtension, enableExtension, ensureExtensionsDirs, extensionConfigDir, extensionsDir, getEnabledExtensions, isEnabled, loadExtension, loadExtensions, resolveManifestPath, } from "../../lib/extension-loader.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "../../..");
 const builtinDir = join(packageRoot, "extensions");
@@ -635,20 +635,31 @@ function printMcpInstructions(name, manifest) {
             }
             if (allResolved) {
                 const args = [
-                    "mcp", "add", "-t", "http",
-                    ...headerArgs.flatMap(h => {
+                    "mcp",
+                    "add",
+                    "-t",
+                    "http",
+                    ...headerArgs.flatMap((h) => {
                         const match = h.match(/--header "(.+): (.+)"/);
                         if (match)
                             return ["--header", `${match[1]}: ${match[2]}`];
                         return [];
                     }),
-                    "-s", "project", "--", name, url,
+                    "-s",
+                    "project",
+                    "--",
+                    name,
+                    url,
                 ];
-                const cmd = `claude ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`;
+                const cmd = `claude ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`;
                 console.info(`\n  ${name}: adding MCP server with credentials from .env...`);
                 // Remove existing entry first so we always write fresh credentials
                 try {
-                    execSync(`claude mcp remove -s project ${name}`, { cwd: process.cwd(), timeout: 10000, stdio: ["ignore", "pipe", "pipe"] });
+                    execSync(`claude mcp remove -s project ${name}`, {
+                        cwd: process.cwd(),
+                        timeout: 10000,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
                 }
                 catch {
                     // Ignore — may not exist

package/dist/bin/commands/init.js

@@ -46,6 +46,9 @@ function createCgcIgnore(projectRoot) {
         "dist/",
         "build/",
         ".git/",
+        ".jj/",
+        ".indusk/",
+        ".claude/",
         "*.png",
         "*.jpg",
         "*.svg",
@@ -296,6 +299,21 @@ export async function init(projectRoot, options = {}) {
     else {
         console.info("  skip: codegraphcontext MCP server (already exists)");
     }
+    // Add graphiti MCP server (Phase 5.5 — Streamable HTTP, runs in indusk-infra container)
+    const graphitiAddCommand = "claude mcp add -t http -s project graphiti http://localhost:8100/mcp";
+    if (!existingServers.has("graphiti") || force) {
+        try {
+            execSync(graphitiAddCommand, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+            console.info("  added: graphiti MCP server (http://localhost:8100/mcp)");
+        }
+        catch {
+            console.info("  failed: could not add graphiti MCP server — run manually:");
+            console.info(`    ${graphitiAddCommand}`);
+        }
+    }
+    else {
+        console.info("  skip: graphiti MCP server (already exists)");
+    }
     // 4b. Check infrastructure container
     console.info("\n[Infrastructure]");
     try {
@@ -755,12 +773,52 @@ export async function init(projectRoot, options = {}) {
     writeConfig(projectRoot, config);
     console.info(`\n[Config]`);
     console.info(`  create: .indusk/config.json (mode: ${config.mode})`);
+    // Create initial handoff so /catchup runs full orientation on first session
+    const handoffPath = join(projectRoot, ".claude/handoff.md");
+    if (!existsSync(handoffPath) || force) {
+        const today = new Date().toISOString().split("T")[0];
+        const handoffContent = [
+            "# Handoff",
+            "",
+            `**Date:** ${today}`,
+            "**Session:** Fresh init — first session orientation needed",
+            "",
+            "## Catchup Status",
+            "- [ ] mcp-ready",
+            "- [ ] handoff",
+            "- [ ] lessons",
+            "- [ ] health",
+            "- [ ] context",
+            "- [ ] plans",
+            "- [ ] skills",
+            "- [ ] extensions",
+            "- [ ] graph",
+            "",
+            "## What Was Being Worked On",
+            "`indusk init` just set up this project. No prior session.",
+            "",
+            "## Where It Stopped",
+            "Init complete. Agent needs full orientation (lessons, context, skills, extensions, graph).",
+            "",
+            "## What's Next",
+            "1. Run `/catchup` to orient the agent (reads lessons, context, skills, extensions, graph)",
+            "2. Edit CLAUDE.md with project details",
+            "3. Start planning: `/planner your-first-feature`",
+            "",
+            "## Open Issues",
+            "None — fresh project.",
+            "",
+        ].join("\n");
+        writeFileSync(handoffPath, handoffContent);
+        console.info("\n[Handoff]");
+        console.info("  create: .claude/handoff.md (first-session orientation)");
+    }
     // Summary
     console.info("\nDone!");
     console.info("\n⚠  Restart Claude Code to load the updated MCP server and skills.");
     console.info("\nNext steps:");
     console.info("  1. Set up infrastructure (if not done): indusk infra start");
-    console.info("  2. Restart Claude Code");
+    console.info("  2. Restart Claude Code — /catchup will auto-orient the agent");
     console.info("  3. Edit CLAUDE.md with your project details");
-    console.info("  4. Start planning: /plan your-first-feature");
+    console.info("  4. Start planning: /planner your-first-feature");
 }

package/dist/bin/commands/update.js

@@ -274,7 +274,38 @@ export async function update(projectRoot) {
                     console.info(`  ${name}: update hook failed`);
                 }
             }
-            if (manifest?.mcp_server?.setup_instructions) {
+            // Phase 5.5: ensure declared MCP server is registered in .mcp.json.
+            // If the manifest's top-level mcp_server.add_command is set and the server
+            // is missing from .mcp.json, run the command. Idempotent — skips if present.
+            // The MCP server's name in .mcp.json is the extension name (matches init's
+            // `claude mcp add ... <extName> ...` convention).
+            const mcpServer = manifest?.mcp_server;
+            if (mcpServer?.add_command) {
+                const mcpJsonPath = join(projectRoot, ".mcp.json");
+                let alreadyRegistered = false;
+                if (existsSync(mcpJsonPath)) {
+                    try {
+                        const mcpJson = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+                        alreadyRegistered = !!mcpJson.mcpServers?.[name];
+                    }
+                    catch { }
+                }
+                if (!alreadyRegistered) {
+                    try {
+                        execSync(mcpServer.add_command, {
+                            cwd: projectRoot,
+                            stdio: "pipe",
+                            timeout: 10000,
+                        });
+                        console.info(`  ${name}: registered MCP server`);
+                    }
+                    catch {
+                        console.info(`  ${name}: failed to register MCP server — run manually:`);
+                        console.info(`    ${mcpServer.add_command}`);
+                    }
+                }
+            }
+            else if (mcpServer?.setup_instructions) {
                 console.info(`  ${name}: MCP server setup — see .claude/skills/${name}/SKILL.md`);
             }
         }

package/dist/lib/config.d.ts

@@ -14,8 +14,27 @@ export interface InduskConfig {
         testRunner?: string;
         linter?: string;
     };
+    graphiti?: {
+        /**
+         * Group id used for project-specific Graphiti episodes. Defaults to the
+         * project directory basename. Override here if the directory name differs
+         * from the desired group id (e.g. shared monorepo, renamed project).
+         */
+        groupId?: string;
+    };
 }
 export declare function getConfigPath(projectRoot: string): string;
 export declare function readConfig(projectRoot: string): InduskConfig | null;
 export declare function writeConfig(projectRoot: string, config: InduskConfig): void;
 export declare function getPlanningDir(projectRoot: string): string;
+/**
+ * Get the Graphiti group id for project-specific episodes.
+ *
+ * Resolution order:
+ *   1. .indusk/config.json `graphiti.groupId` if set
+ *   2. Project directory basename
+ *
+ * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
+ * searching Graphiti — this gives both project-scoped and cross-project knowledge.
+ */
+export declare function getProjectGroupId(projectRoot: string): string;

package/dist/lib/config.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 const CONFIG_PATH = ".indusk/config.json";
 export function getConfigPath(projectRoot) {
     return join(projectRoot, CONFIG_PATH);
@@ -26,3 +26,19 @@ export function getPlanningDir(projectRoot) {
     // Default to new path (will be created by init)
     return newPath;
 }
+/**
+ * Get the Graphiti group id for project-specific episodes.
+ *
+ * Resolution order:
+ *   1. .indusk/config.json `graphiti.groupId` if set
+ *   2. Project directory basename
+ *
+ * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
+ * searching Graphiti — this gives both project-scoped and cross-project knowledge.
+ */
+export function getProjectGroupId(projectRoot) {
+    const config = readConfig(projectRoot);
+    if (config?.graphiti?.groupId)
+        return config.graphiti.groupId;
+    return basename(projectRoot);
+}

package/dist/lib/extension-loader.d.ts

@@ -53,6 +53,7 @@ export interface ExtensionManifest {
         headers?: Record<string, string>;
         env?: Record<string, string>;
         env_from_shell?: string[];
+        add_command?: string;
         setup_instructions?: string[];
     };
 }

package/dist/lib/extension-loader.js

@@ -100,10 +100,7 @@ function loadFromDir(baseDir, enabled) {
 export function loadExtensions(projectRoot) {
     const dir = extensionsDir(projectRoot);
     const disDir = disabledDir(projectRoot);
-    return [
-        ...loadFromDir(dir, true),
-        ...loadFromDir(disDir, false),
-    ];
+    return [...loadFromDir(dir, true), ...loadFromDir(disDir, false)];
 }
 export function getEnabledExtensions(projectRoot) {
     return loadExtensions(projectRoot).filter((e) => e.enabled);

package/extensions/excalidraw/manifest.json

@@ -7,8 +7,6 @@
 	"mcp_server": {
 		"type": "http",
 		"url": "https://mcp.excalidraw.com",
-		"setup_instructions": [
-			"claude mcp add -t http -- excalidraw https://mcp.excalidraw.com"
-		]
+		"setup_instructions": ["claude mcp add -t http -- excalidraw https://mcp.excalidraw.com"]
 	}
 }

package/extensions/excalidraw/skill.md

@@ -41,7 +41,7 @@ That's it. No tokens, no config files, no environment variables.
 
 ## When to Create Diagrams
 
-- **During `/plan` research or brief**: sketch the proposed architecture to make it concrete
+- **During `/planner` research or brief**: sketch the proposed architecture to make it concrete
 - **During `/work` teach mode**: visualize what a phase is building before and after
 - **During debugging**: draw the request flow to identify where things break
 - **During retrospective**: before/after architecture comparison

package/extensions/graphiti/manifest.json

@@ -18,6 +18,16 @@
 			}
 		]
 	},
+	"mcp_server": {
+		"type": "http",
+		"url": "http://localhost:8100/mcp",
+		"add_command": "claude mcp add -t http -s project graphiti http://localhost:8100/mcp",
+		"setup_instructions": [
+			"Registered automatically by `indusk init` and re-added by `indusk update` if missing.",
+			"The Graphiti MCP server runs inside the `indusk-infra` container on port 8100.",
+			"Exposes 9 tools: add_memory, search_nodes, search_memory_facts, get_episodes, get_entity_edge, delete_episode, delete_entity_edge, clear_graph, get_status."
+		]
+	},
 	"detect": {
 		"command": "docker inspect --format='{{.State.Running}}' indusk-infra 2>/dev/null | grep true"
 	}

package/extensions/graphiti/skill.md

@@ -2,16 +2,32 @@
 
 Graphiti is an episodic memory system backed by FalkorDB. It extracts entities and facts from text, detects contradictions, and supports semantic search across project-specific and shared knowledge.
 
+The Graphiti MCP server runs inside the `indusk-infra` container on `http://localhost:8100/mcp` and is registered automatically by `indusk init`. The agent has direct access via `mcp__graphiti__*` tools — there is no wrapping layer.
+
 ## When to Use
 
-- **Episode capture**: After a decision, retro finding, or correction — anything worth remembering across sessions
+- **Capture**: After a decision, retro finding, or correction — anything worth remembering across sessions
 - **Search**: Before making assumptions — check what's already known about a topic
-- **Context retrieval**: At session start or when working in an unfamiliar area
+- **Recall**: At session start (`/catchup` does this automatically) or when working in an unfamiliar area
+
+## Tools
+
+The agent has nine `mcp__graphiti__*` tools. The five you'll use most:
+
+| Tool | Purpose |
+|------|---------|
+| `add_memory` | Capture an episode (text/JSON/message) — entities and facts are extracted asynchronously |
+| `search_nodes` | Find entities by natural-language query |
+| `search_memory_facts` | Find facts (relationships between entities) by query |
+| `get_episodes` | List recent episodes by group |
+| `get_status` | Check that Graphiti is reachable and the database is healthy |
+
+The other four (`delete_episode`, `delete_entity_edge`, `get_entity_edge`, `clear_graph`) are for cleanup — use sparingly, never in normal flow.
 
 ## Core Concepts
 
 ### Episodes
-An episode is a chunk of text that Graphiti processes into entities and facts. Think of it as "something that happened" — a decision was made, a bug was found, a convention was established.
+An episode is a chunk of text that Graphiti processes into entities and facts. Think of it as "something that happened" — a decision was made, a bug was found, a convention was established. Episodes are processed in the background; entities appear in search results once extraction completes (a few seconds).
 
 ### Group IDs
 Every episode belongs to a group. Groups isolate knowledge:
@@ -21,54 +37,123 @@ Every episode belongs to a group. Groups isolate knowledge:
 | `{project-name}` | Project-specific knowledge | `infinitedusky`, `numero` |
 | `shared` | Cross-project conventions | Developer preferences, universal patterns |
 
-When searching, always include both the project group and `shared` to get the full picture. The `GraphitiClient` does this automatically.
+When searching, always include both the project group and `shared` to get the full picture. Use `getProjectGroupId(projectRoot)` (from `apps/indusk-mcp/src/lib/config.ts`) to get the project group consistently — it reads `.indusk/config.json` `graphiti.groupId` if set, otherwise falls back to the project directory basename.
 
 ### Entities and Facts
 Graphiti extracts:
 - **Entities**: Named things (tools, patterns, files, concepts)
 - **Facts**: Relationships between entities with temporal validity
 
-Facts can be contradicted — if you add "the parser handles three gate types" and later "the parser handles four gate types", Graphiti invalidates the old fact.
+Facts can be contradicted — if you add "the parser handles three gate types" and later "the parser handles four gate types", Graphiti invalidates the old fact. The contradicted fact gets `invalid_at` set; the new one gets `valid_at` set. Search results respect this — invalid facts are excluded by default.
 
 ## Patterns
 
 ### Capturing a Decision
-After an ADR is accepted or a significant choice is made:
+
+After an ADR is accepted or a significant choice is made, the planner skill calls this automatically. To do it manually:
+
 ```
-addEpisode("auth-approach-decision", 
-  "We chose JWT with refresh tokens over session cookies because the API serves both web and mobile clients. Session cookies don't work well with React Native.",
-  { groupId: "myproject" })
+mcp__graphiti__add_memory({
+  name: "auth-approach-decision",
+  episode_body: "We chose JWT with refresh tokens over session cookies because the API serves both web and mobile clients. Session cookies don't work well with React Native.",
+  group_id: "myproject",
+  source: "text",
+  source_description: "ADR"
+})
 ```
 
+The `name` should be short and topical — the agent uses it as a handle when re-discussing the decision. The `episode_body` should be detailed enough that someone reading it cold understands the decision and the reasoning.
+
 ### Capturing a Correction
-When someone corrects the agent or a mistake is found:
+
+When the user corrects the agent, the work skill prompts `context learn` AND captures the correction as an episode:
+
 ```
-addEpisode("correction-test-database",
-  "Integration tests must use a real database, not mocks. We got burned when mocked tests passed but the production migration failed.",
-  { groupId: "shared" })
+mcp__graphiti__add_memory({
+  name: "correction-pnpm-ce",
+  episode_body: "Always use `pnpm ce`, never `npx ce`. The composable.env skill specifies pnpm and the project's package.json maps `ce` to the binary. npx invokes a different code path.",
+  group_id: "shared",
+  source: "text",
+  source_description: "user correction"
+})
 ```
 
+Choosing `shared` vs project group:
+- **`shared`**: tools, conventions, patterns that apply across projects ("always use pnpm ce", "never mock the database in integration tests")
+- **`{project-name}`**: facts specific to one project's code, data, or domain ("the impl-parser handles four gate types per phase", "the bet matching engine is order-book based")
+
+When in doubt, ask: "Would this correction make sense to a different project?" Yes → `shared`. No → project group.
+
 ### Searching Before Acting
+
 Before making assumptions about how something works:
+
 ```
-searchNodes("authentication middleware")
-searchFacts("how does auth work in this project")
+mcp__graphiti__search_nodes({
+  query: "authentication middleware",
+  group_ids: ["myproject", "shared"],
+  max_nodes: 10
+})
+
+mcp__graphiti__search_memory_facts({
+  query: "how does auth work in this project",
+  group_ids: ["myproject", "shared"],
+  max_facts: 10
+})
 ```
 
+Always search both the project group and `shared` — knowledge is split across them. The wrapper class `GraphitiClient` in `apps/indusk-mcp/src/lib/graphiti-client.ts` does this automatically when called internally; agents calling `mcp__graphiti__*` tools directly need to pass both group ids in the request.
+
 ### Capturing a Retrospective Finding
-After a plan retrospective surfaces a useful insight:
+
+After a plan retrospective surfaces a useful insight, the retrospective skill captures it as an episode:
+
+```
+mcp__graphiti__add_memory({
+  name: "retro-gate-enforcement-1",
+  episode_body: "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
+  group_id: "infinitedusky",
+  source: "text",
+  source_description: "retrospective insight"
+})
+```
+
+One episode per insight, named `retro-{plan}-{n}`. If the retro surfaces a contradiction (we thought X, found Y), capture both framings as separate episodes — Graphiti's contradiction detection invalidates the older one.
+
+### Recall at Session Start
+
+The `/catchup` skill calls this automatically after reading project context, but you can also trigger it manually:
+
 ```
-addEpisode("retro-gate-enforcement",
-  "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
-  { groupId: "myproject" })
+mcp__graphiti__search_nodes({
+  query: "recent decisions",
+  group_ids: ["myproject", "shared"],
+  max_nodes: 5
+})
 ```
 
+Surface anything notable to the user. Pay extra attention to facts where `invalid_at` is recent — those are areas where prior decisions changed and active plans may be working from stale assumptions.
+
+## Capture Triggers (Where Episodes Come From)
+
+In normal workflow, episodes are written automatically by other skills. The agent rarely calls `add_memory` directly:
+
+| Trigger | Skill | Episode |
+|---------|-------|---------|
+| Brief accepted | `planner` | `brief-accepted-{plan}` — Problem + Proposed Direction in project group |
+| ADR accepted | `planner` | `adr-{plan}` — Y-statement in project group |
+| User correction (`context learn`) | `work` | `correction-{slug}` — lesson body in `shared` or project group |
+| Retrospective lesson | `retrospective` | `retro-{plan}-{n}` — one per insight in project group |
+| Retrospective "would do differently" | `retrospective` | `retro-{plan}-wdid-{n}` — one per item in project group |
+
+The agent should call `add_memory` directly **only** when something worth remembering happens outside these trigger points. Most of the time, just trust the skills to capture and let `/catchup` recall.
+
 ## What NOT to Capture
 
-- Code structure (CGC handles this)
-- Git history (git log handles this)
-- Ephemeral state (current task, in-progress work)
-- Things already in CLAUDE.md or lessons
+- **Code structure** — CGC handles this. `function X calls function Y` is a graph relationship, not an episode.
+- **Git history** — `git log` is authoritative.
+- **Ephemeral state** — current task, in-progress work, todo lists. Use the TodoWrite tool, not Graphiti.
+- **Things already in CLAUDE.md or lessons** — those layers exist for stable, project-wide truths. Graphiti is for things that have temporal context and might be contradicted.
 
 Graphiti is for knowledge that has temporal context — decisions that might change, facts that might be contradicted, insights that accumulate over time.
 
@@ -86,6 +171,13 @@ Global config (API keys, OTel): `~/.indusk/config.env`
 
 ### Graceful Degradation
 If the `indusk-infra` container is down:
-- CGC graph tools still check FalkorDB directly
-- Graphiti client methods return null/empty (never throw)
-- The agent continues working with flat-file context (CLAUDE.md, lessons, skills)
+- `mcp__graphiti__*` tools will report a clean error (the MCP transport fails to connect)
+- The agent should fall back to flat-file context (CLAUDE.md, lessons, skills) and continue working
+- The `GraphitiClient` wrapper class (used internally by indusk-mcp) returns null/empty instead of throwing
+- Don't pretend the call succeeded — if Graphiti is down, capture is lost. Tell the user to `indusk infra start`.
+
+### Health Check
+```
+mcp__graphiti__get_status({})
+```
+Returns `{ status: "healthy", message: "..." }` when Graphiti is reachable and the database is connected.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.9.2",
+	"version": "1.10.0",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/catchup.md

@@ -64,6 +64,29 @@ Read it fully. Don't skim.
 
 **After reading, edit the handoff to check off:** `- [x] context`
 
+### 4.5. Recall from Graphiti
+
+CLAUDE.md is the stable, slow-changing layer of project memory. Graphiti is the fast, temporal layer — it captures decisions, corrections, and retrospective insights as they happen. Catchup pulls both layers so the agent starts the session with full context.
+
+**Recall recent decisions and lessons:**
+```
+mcp__graphiti__search_nodes({
+  query: "recent decisions and lessons",
+  group_ids: ["{project-group}", "shared"],
+  max_nodes: 8
+})
+```
+
+The project group comes from the `getProjectGroupId(projectRoot)` helper (in `apps/indusk-mcp/src/lib/config.ts`). Always include both the project group and `shared` so cross-project conventions surface alongside project-specific knowledge.
+
+**Surface contradictions:** look at the returned nodes for any whose `attributes` reference recently invalidated facts (Graphiti marks superseded facts with `invalid_at`). If a recently invalidated fact relates to an active plan or current code area, flag it to the user — those are places where assumptions changed.
+
+**Output format:** include a "Graphiti recall" section in the catchup summary with the most relevant 3-5 nodes by name + summary. Don't dump everything — surface what's actionable.
+
+**Graceful degradation:** If `mcp__graphiti__search_nodes` is unavailable (Graphiti container down, transport error), skip this step silently and add a note to the catchup summary: `Graphiti: unavailable (run \`indusk infra start\` to recall episodic memory)`. Catchup should not fail if Graphiti is down — the rest of the layers are still valid.
+
+**After completing recall, edit the handoff to check off:** `- [x] graphiti` (added to the catchup status box section)
+
 ### 5. Check Active Plans
 Call `list_plans`. This shows every plan and its status. Pay attention to:
 - Plans with status `in-progress` — these are actively being worked on
@@ -78,7 +101,7 @@ Call `extensions_status` to see what extensions are enabled and their capabiliti
 Call `get_skill_summaries` to load the name, description, and type of every installed skill. This returns a compact summary — you do NOT need to read each skill file individually. The full skill content loads automatically when the user invokes a slash command.
 
 Skill types:
-- **process** — workflow skills with slash commands (plan, work, verify, context, document, retrospective)
+- **process** — workflow skills with slash commands (planner, work, verify, context, document, retrospective)
 - **extension** — tool integrations (cgc, composable-env, excalidraw, etc.)
 - **domain** — technology-specific best practices (typescript, testing, etc.)
 
@@ -104,6 +127,7 @@ After completing all steps, present a brief summary to the user:
 - Extensions: N enabled [list names]
 - Active plans: [list with current phase]
 - Codebase: [N files indexed]
+- Graphiti recall: [3-5 most relevant nodes by name + summary, or "unavailable" if Graphiti is down]
 
 Ready to pick up. What would you like to do?
 ```

package/skills/{plan.md → planner.md}

@@ -1,5 +1,5 @@
 ---
-name: plan
+name: planner
 description: Create and advance plans. Every plan follows the same document lifecycle — research, brief, ADR, impl, retrospective. Knows how to write each one, what order they go in, and how to pick up where things left off.
 argument-hint: "[workflow] [plan name] — workflow: feature (default), bugfix, refactor, spike"
 ---
@@ -29,15 +29,15 @@ General-purpose research (insights useful across plans) also lives in `research/
 
 ## Workflow Types
 
-The first argument to `/plan` can optionally be a workflow type that controls which documents are created:
+The first argument to `/planner` can optionally be a workflow type that controls which documents are created:
 
 | Command | Workflow | Documents |
 |---------|----------|-----------|
-| `/plan bugfix auth-expiry` | bugfix | brief + impl only |
-| `/plan refactor extract-auth` | refactor | brief + impl (with boundary map) |
-| `/plan spike redis-options` | spike | research only |
-| `/plan feature payment-flow` | feature | full lifecycle (default) |
-| `/plan payment-flow` | feature | same — no type defaults to feature |
+| `/planner bugfix auth-expiry` | bugfix | brief + impl only |
+| `/planner refactor extract-auth` | refactor | brief + impl (with boundary map) |
+| `/planner spike redis-options` | spike | research only |
+| `/planner feature payment-flow` | feature | full lifecycle (default) |
+| `/planner payment-flow` | feature | same — no type defaults to feature |
 
 Parse the input: if the first word is `bugfix`, `refactor`, `spike`, or `feature`, use that workflow. Otherwise, default to `feature`. The remaining words become the plan name (kebab-cased).
 
@@ -74,8 +74,32 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. **Consider creating a visual sketch** of the proposed architecture with Excalidraw (if the extension is enabled) — a hand-drawn diagram makes the proposal concrete and easier to discuss. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
+   **When the brief moves from `draft` to `accepted`**, capture the decision in Graphiti:
+   ```
+   mcp__graphiti__add_memory({
+     name: "brief-accepted-{plan-name}",
+     episode_body: "{Problem}\n\n{Proposed Direction}\n\n{Scope summary if helpful}",
+     group_id: "{project-group}",
+     source: "text",
+     source_description: "brief acceptance"
+   })
+   ```
+   The `group_id` is the project group (use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` — defaults to project directory basename, override via `.indusk/config.json` `graphiti.groupId`). Skip silently if `mcp__graphiti__add_memory` is unavailable (Graphiti may be down — degrade gracefully, do not fail the brief acceptance).
+
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see .indusk/planning/{plan}/adr.md`
 
+   **When the ADR moves from `proposed` to `accepted`**, capture the Y-statement in Graphiti:
+   ```
+   mcp__graphiti__add_memory({
+     name: "adr-{plan-name}",
+     episode_body: "In the context of {use case}, facing {constraint}, we decided for {chosen option} and against {rejected alternatives}, to achieve {desired outcome}, accepting {tradeoff}, because {rationale}.",
+     group_id: "{project-group}",
+     source: "text",
+     source_description: "ADR acceptance"
+   })
+   ```
+   The Y-statement is rich enough that Graphiti will extract entities for the chosen option, rejected alternatives, constraint, and rationale — and will detect contradictions if a later ADR overrides this one. Skip silently on Graphiti unavailability.
+
 6. **If ADR is accepted** (or brief is accepted for bugfix/refactor), write the impl. Break into phased checklists with concrete tasks. For refactor workflows, include a `## Boundary Map` section. For multi-phase impls of any type, consider adding a boundary map.
 
    **Gate policy applies when writing impls.** Set `gate_policy` in the impl frontmatter (`strict`, `ask`, or `auto`). The `validate-impl-structure` hook enforces this at write time:

package/skills/retrospective.md

@@ -21,7 +21,7 @@ The retrospective skill replaces the freeform "write a retrospective" step with
 ## When to Use
 
 - After `/work` completes all impl phases and the status is `completed`
-- When `/plan {name}` detects the impl is completed and the next step is retrospective
+- When `/planner {name}` detects the impl is completed and the next step is retrospective
 - Directly via `/retrospective {plan-name}`
 
 ## The Audit Checklist
@@ -91,6 +91,36 @@ If yes, call `add_lesson` for each one. These become personal lessons in `.claud
 
 If no lessons emerged, that's fine — not every plan produces new knowledge. Move on.
 
+**Also capture each retrospective insight in Graphiti** so it becomes part of the temporal knowledge graph and can surface in future searches and contradictions.
+
+For each item in the retrospective's **What We Learned** section:
+```
+mcp__graphiti__add_memory({
+  name: "retro-{plan-name}-{n}",
+  episode_body: "{the full insight, including context — not just a one-line summary}",
+  group_id: "{project-group}",
+  source: "text",
+  source_description: "retrospective lesson"
+})
+```
+
+For each item in the retrospective's **What We'd Do Differently** section:
+```
+mcp__graphiti__add_memory({
+  name: "retro-{plan-name}-wdid-{n}",
+  episode_body: "{the hindsight item, with reasoning}",
+  group_id: "{project-group}",
+  source: "text",
+  source_description: "retrospective hindsight"
+})
+```
+
+Use the project group (from `getProjectGroupId(projectRoot)`) — most retrospective insights are project-specific. Promote to `shared` only if the insight is clearly cross-project (those should also become a personal lesson via `add_lesson`).
+
+**Contradictions:** If the retrospective surfaces a moment where "we thought X but found Y", capture both as separate episodes. Graphiti's contradiction detection will invalidate the older fact when it sees the conflicting one. This is one of Graphiti's most useful features — it remembers that a previous assumption was overturned, so the agent doesn't accidentally re-introduce it later.
+
+Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, and lesson recording via `add_lesson` is the canonical path. Graphiti capture is supplementary.
+
 ### Step 7: Context Audit
 
 Re-read CLAUDE.md in full. After the entire impl is done, verify:

package/skills/toolbelt.md

@@ -17,7 +17,7 @@ To see which MCP servers and extensions are active, call `extensions_status`.
 ## How the Skills Work Together
 
 ```
-/plan → creates planning docs (research, brief, ADR, impl)
+/planner → creates planning docs (research, brief, ADR, impl)
                 ↓
 /work → executes impl checklist, phase by phase
          each phase has four gates:
@@ -139,7 +139,7 @@ While executing impl items:
 
 Gates prevent skipping important work. Three enforcement levels, set via `gate_policy` in impl frontmatter or `.claude/settings.json`:
 
-| Mode | Writing the impl (`/plan`) | Executing the impl (`/work`) |
+| Mode | Writing the impl (`/planner`) | Executing the impl (`/work`) |
 |------|---------------------------|------------------------------|
 | **`strict`** | Every gate must have a real item. No `(none needed)`. | Every item must be completed. No skipping. |
 | **`ask`** (default) | Every gate must have a real item. No `(none needed)`. | Skip only with conversation proof: `(none needed — asked: "..." — user: "...")` |

package/skills/work.md

@@ -70,7 +70,7 @@ Three modes, configured via `gate_policy` in the impl frontmatter or `.claude/se
 
 | Mode | Behavior |
 |------|----------|
-| **`strict`** | No overrides at any stage. Every gate must have a real item when the impl is written (`/plan`), and every item must be completed during `/work`. No `(none needed)`, no `skip-reason:`, no conversation proof. |
+| **`strict`** | No overrides at any stage. Every gate must have a real item when the impl is written (`/planner`), and every item must be completed during `/work`. No `(none needed)`, no `skip-reason:`, no conversation proof. |
 | **`ask`** (default) | Every gate must have a real item when the impl is written. During `/work`, the agent must ask the user before skipping, and include proof of the conversation in the skip format. Hooks enforce both stages. |
 | **`auto`** | Gates can be pre-filled with `(none needed)` or `skip-reason:` at write time. During `/work`, the agent can skip without asking. Use when running autonomously. |
 
@@ -118,7 +118,7 @@ In `ask` mode, skipped gates MUST include proof that the conversation happened:
 
 The hook validates that both `asked:` and `user:` are present with non-empty quoted content. Bare `(none needed)` or `skip-reason:` without conversation proof will be **blocked by the hook**.
 
-| Mode | At write time (`/plan`) | At execution time (`/work`) |
+| Mode | At write time (`/planner`) | At execution time (`/work`) |
 |------|------------------------|---------------------------|
 | `strict` | No opt-outs — real items required | No skipping — everything completed |
 | `ask` | No opt-outs — real items required | Skip only with conversation proof |
@@ -148,7 +148,7 @@ The hook validates that both `asked:` and `user:` are present with non-empty quo
     - Update impl status to `completed`
     - Summarize what was done
     - If this plan included an ADR, confirm CLAUDE.md's Key Decisions was updated
-    - Let the user know the plan is ready for a retrospective if they want one (`/plan {name}` will pick up at the retrospective stage)
+    - Let the user know the plan is ready for a retrospective if they want one (`/planner {name}` will pick up at the retrospective stage)
 
 ## Teach Mode
 
@@ -202,6 +202,27 @@ When you are corrected mid-work — the user says "no, not that way" or "don't d
 
 Don't wait to be told. Corrections are the most valuable source of project knowledge.
 
+**When the user confirms `context learn`, ALSO capture the correction in Graphiti:**
+```
+mcp__graphiti__add_memory({
+  name: "correction-{slug}",
+  episode_body: "{lesson text}",
+  group_id: "{shared OR project-group}",
+  source: "text",
+  source_description: "user correction"
+})
+```
+
+Where `{slug}` is a short kebab-case label for the topic (e.g. `correction-pnpm-ce`, `correction-graphiti-error-handling`).
+
+**Choosing `shared` vs project group:**
+- **`shared`**: tools, conventions, patterns that apply across projects. Examples: "always use pnpm ce", "never mock the database in integration tests", "use jj describe-then-do for commits". The lesson is generally true and a different project would benefit from it.
+- **`{project-group}`**: facts specific to this project's code, data, or domain. Examples: "the impl-parser handles four gate types per phase", "graph_ensure auto-repairs the indusk-infra container". The lesson only makes sense in the context of this project.
+
+When in doubt, ask: "Would this correction make sense to a different project?" Yes → `shared`. No → project group.
+
+Use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` to get the project group consistently. Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, do not fail the work item.
+
 ## Commits (jj)
 
 Use the **describe-then-do** workflow from the jj skill: