agentopology 0.1.1 → 0.2.1

package/dist/bindings/claude-code.js

@@ -48,6 +48,8 @@ function toTitle(id) {
  *     - item1
  *     - item2
  */
+/** Characters that require quoting in YAML scalar values. */
+const YAML_SPECIAL = /[:#\[\]{}&*!|>'"%@`]/;
 function frontmatter(fields) {
     const lines = ["---"];
     for (const [key, value] of Object.entries(fields)) {
@@ -65,7 +67,10 @@ function frontmatter(fields) {
             lines.push(`${key}: ${value}`);
         }
         else {
-            lines.push(`${key}: ${value}`);
+            // Auto-quote strings containing YAML-special characters
+            const str = String(value);
+            const needsQuotes = YAML_SPECIAL.test(str) || str.trim() !== str;
+            lines.push(`${key}: ${needsQuotes ? `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : str}`);
         }
     }
     lines.push("---");
@@ -93,10 +98,10 @@ function gitkeep(dirPath) {
  */
 function mapPermissionMode(perm) {
     // Claude Code native values — pass through
-    const nativeValues = ["plan", "auto", "confirm", "bypassPermissions"];
+    const nativeValues = ["plan", "default", "acceptEdits", "dontAsk", "bypassPermissions"];
     if (nativeValues.includes(perm)) {
-        // "auto" is the default, omit it
-        if (perm === "auto")
+        // "default" is the default, omit it
+        if (perm === "default")
             return undefined;
         return perm;
     }
@@ -106,8 +111,10 @@ function mapPermissionMode(perm) {
             return "plan";
         case "autonomous":
             return undefined; // default, omit
+        case "auto":
+            return undefined; // default, omit
         case "interactive":
-            return "default";
+            return "acceptEdits";
         case "unrestricted":
             return "bypassPermissions";
         default:
@@ -229,7 +236,7 @@ function generateAgents(ast) {
         if (agent.invocation !== "manual") {
             const desc = agent.description ?? ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
             if (desc) {
-                fm.description = `"${desc}"`;
+                fm.description = desc;
             }
         }
         if (agent.model)
@@ -237,9 +244,9 @@ function generateAgents(ast) {
         if (agent.maxTurns != null)
             fm.maxTurns = String(agent.maxTurns);
         if (agent.tools && agent.tools.length > 0)
-            fm.tools = agent.tools.map(convertMcpToolName);
+            fm.tools = agent.tools.map(convertMcpToolName).join(", ");
         if (agent.disallowedTools && agent.disallowedTools.length > 0)
-            fm.disallowedTools = agent.disallowedTools.map(convertMcpToolName);
+            fm.disallowedTools = agent.disallowedTools.map(convertMcpToolName).join(", ");
         if (agent.mcpServers && agent.mcpServers.length > 0)
             fm.mcpServers = agent.mcpServers;
         if (agent.background === true)
@@ -352,6 +359,103 @@ function generateAgents(ast) {
             }
             sections.push("");
         }
+        // Memory stores — rich instructions with store details and access methods
+        if (agent.memory && agent.memory.length > 0) {
+            const storeMap = new Map((ast.stores ?? []).map(s => [s.id, s]));
+            sections.push("## Memory Stores");
+            sections.push("");
+            sections.push("You have access to the following memory stores. Use them to persist and retrieve knowledge across conversations.");
+            sections.push("");
+            for (const storeId of agent.memory) {
+                const store = storeMap.get(storeId);
+                if (!store) {
+                    sections.push(`### ${storeId}`);
+                    sections.push(`- Store not found in topology`);
+                    sections.push("");
+                    continue;
+                }
+                sections.push(`### ${storeId}`);
+                if (store.description)
+                    sections.push(store.description);
+                sections.push("");
+                sections.push(`- **Type**: ${store.type}`);
+                sections.push(`- **Backend**: ${store.backend}`);
+                if (store.path)
+                    sections.push(`- **Path**: \`${store.path}\``);
+                if (store.scope)
+                    sections.push(`- **Scope**: ${store.scope}`);
+                // Access method — MCP or skill-based
+                const hasMcp = STORE_MCP_COMMANDS[store.backend] != null;
+                if (hasMcp) {
+                    sections.push(`- **Access**: MCP server \`${storeId}\` (auto-configured in .mcp.json)`);
+                }
+                else if (store.path) {
+                    sections.push(`- **Access**: Direct file access at \`${store.path}\``);
+                }
+                // Embedding config
+                if (store.embedding) {
+                    sections.push(`- **Embedding**: ${store.embedding.model} (${store.embedding.provider}, ${store.embedding.dimensions}d)`);
+                }
+                // Search strategy
+                if (store.search) {
+                    const parts = [`strategy: ${store.search.strategy}`];
+                    if (store.search.topK)
+                        parts.push(`top-k: ${store.search.topK}`);
+                    if (store.search.rerank)
+                        parts.push(`rerank: yes`);
+                    sections.push(`- **Search**: ${parts.join(", ")}`);
+                }
+                // Ingestion sources
+                if (store.ingestion?.sources) {
+                    sections.push(`- **Ingestion sources**: ${store.ingestion.sources.join(", ")}`);
+                }
+                // Lifecycle
+                if (store.lifecycle?.retention) {
+                    sections.push(`- **Retention**: ${store.lifecycle.retention}`);
+                }
+                sections.push("");
+            }
+        }
+        // Retrieval strategy — rich details
+        if (agent.retrieval) {
+            const retrieval = (ast.retrievals ?? []).find(r => r.id === agent.retrieval);
+            if (retrieval) {
+                sections.push("## Retrieval Strategy");
+                sections.push("");
+                sections.push(`**${retrieval.id}** — When you need to recall information, use this strategy:`);
+                sections.push("");
+                if (retrieval.sources)
+                    sections.push(`- **Sources**: ${retrieval.sources.join(", ")}`);
+                if (retrieval.budget)
+                    sections.push(`- **Token budget**: ${retrieval.budget} tokens max for retrieved context`);
+                if (retrieval.paths)
+                    sections.push(`- **Search paths**: ${retrieval.paths.join(", ")}`);
+                if (retrieval.rerank)
+                    sections.push(`- **Reranking**: enabled — results are cross-ranked for relevance`);
+                if (retrieval.diversity)
+                    sections.push(`- **Diversity**: enabled — results span different sources`);
+                if (retrieval.cacheHitThreshold != null) {
+                    sections.push(`- **Cache hit**: threshold ${retrieval.cacheHitThreshold} → ${retrieval.cacheHitAction ?? "short-circuit"}`);
+                }
+                if (retrieval.scoring) {
+                    const s = retrieval.scoring;
+                    const weights = [];
+                    if (s.recencyWeight != null)
+                        weights.push(`recency: ${s.recencyWeight}`);
+                    if (s.semanticWeight != null)
+                        weights.push(`semantic: ${s.semanticWeight}`);
+                    if (s.importanceWeight != null)
+                        weights.push(`importance: ${s.importanceWeight}`);
+                    if (weights.length)
+                        sections.push(`- **Scoring weights**: ${weights.join(", ")}`);
+                }
+                sections.push("");
+            }
+            else {
+                sections.push(`Retrieval strategy: ${agent.retrieval}`);
+                sections.push("");
+            }
+        }
         // Outputs section
         if (agent.outputs) {
             sections.push("## Outputs");
@@ -739,7 +843,7 @@ function generateGroupNodes(ast) {
         const skillFm = {};
         skillFm.name = group.id;
         if (group.description)
-            skillFm.description = `"${group.description}"`;
+            skillFm.description = group.description;
         skillFm["user-invocable"] = true;
         const skillSections = [];
         skillSections.push(frontmatter(skillFm));
@@ -756,7 +860,7 @@ function generateGroupNodes(ast) {
         const agentFm = {};
         agentFm.name = group.id;
         if (group.description)
-            agentFm.description = `"${group.description}"`;
+            agentFm.description = group.description;
         const agentSections = [];
         agentSections.push(frontmatter(agentFm));
         agentSections.push("");
@@ -782,9 +886,9 @@ function generateTopologySkill(ast) {
     const fm = {};
     fm.name = name;
     if (ast.topology.description) {
-        fm.description = `"${ast.topology.description}"`;
+        fm.description = ast.topology.description;
     }
-    fm.version = `"${ast.topology.version}"`;
+    fm.version = ast.topology.version;
     fm.topology = name;
     if (ast.topology.patterns.length > 0) {
         fm.patterns = ast.topology.patterns;
@@ -808,7 +912,7 @@ function generateTopologySkill(ast) {
         if (mainSkill.agent)
             fm.agent = mainSkill.agent;
         if (mainSkill.allowedTools && mainSkill.allowedTools.length > 0) {
-            fm["allowed-tools"] = mainSkill.allowedTools.map(convertMcpToolName);
+            fm["allowed-tools"] = mainSkill.allowedTools.map(convertMcpToolName).join(", ");
         }
     }
     const sections = [];
@@ -1085,6 +1189,30 @@ function generateTopologySkill(ast) {
             sections.push("");
         }
     }
+    // Memory Stores
+    const stores = ast.stores ?? [];
+    if (stores.length > 0) {
+        sections.push("## Memory Stores");
+        sections.push("");
+        for (const store of stores) {
+            sections.push(`### ${store.id}`);
+            sections.push(`- Type: ${store.type}`);
+            sections.push(`- Backend: ${store.backend}`);
+            if (store.path)
+                sections.push(`- Path: ${store.path}`);
+            if (store.connection)
+                sections.push(`- Connection: ${store.connection}`);
+            if (store.scope)
+                sections.push(`- Scope: ${store.scope}`);
+            if (store.search?.strategy)
+                sections.push(`- Search: ${store.search.strategy}`);
+            if (store.embedding?.model)
+                sections.push(`- Embedding: ${store.embedding.model}`);
+            if (store.lifecycle?.retention)
+                sections.push(`- Retention: ${store.lifecycle.retention}`);
+            sections.push("");
+        }
+    }
     files.push({
         path: `.claude/skills/${name}/SKILL.md`,
         content: sections.join("\n") + "\n",
@@ -1101,7 +1229,7 @@ function generateSkills(ast) {
         const sfm = {};
         sfm.name = skill.id;
         if (skill.description)
-            sfm.description = `"${skill.description}"`;
+            sfm.description = skill.description;
         if (skill.disableModelInvocation != null) {
             sfm["disable-model-invocation"] = skill.disableModelInvocation;
         }
@@ -1113,7 +1241,7 @@ function generateSkills(ast) {
         if (skill.agent)
             sfm.agent = skill.agent;
         if (skill.allowedTools && skill.allowedTools.length > 0) {
-            sfm["allowed-tools"] = skill.allowedTools.map(convertMcpToolName);
+            sfm["allowed-tools"] = skill.allowedTools.map(convertMcpToolName).join(", ");
         }
         // Only emit frontmatter if there are fields beyond just the name
         if (Object.keys(sfm).length > 1) {
@@ -1188,6 +1316,109 @@ function generateMemory(ast) {
     if (memory.workspace) {
         files.push(gitkeep(`.claude/skills/${name}/runs`));
     }
+    // Store directory markers
+    const stores = ast.stores ?? [];
+    for (const store of stores) {
+        files.push(gitkeep(`.claude/stores/${store.id}`));
+    }
+    return files;
+}
+/**
+ * Generate memory command files for each store.
+ *
+ * These are Claude Code slash-commands (`.claude/commands/`) that give agents
+ * a concrete way to interact with memory stores — search, ingest, and inspect.
+ * This works alongside (or instead of) MCP servers.
+ */
+function generateMemoryCommands(ast) {
+    const files = [];
+    const stores = ast.stores ?? [];
+    for (const store of stores) {
+        // Search command — for stores with search config or semantic/episodic type
+        if (store.search || store.type === "semantic" || store.type === "episodic") {
+            const hasMcp = STORE_MCP_COMMANDS[store.backend] != null;
+            const searchLines = [
+                "---",
+                `description: "Search the ${store.id} memory store"`,
+                "---",
+                "",
+                `# /memory-search-${store.id}`,
+                "",
+                `Search the **${store.id}** store for relevant information.`,
+                "",
+                `## Store Details`,
+                `- **Type**: ${store.type}`,
+                `- **Backend**: ${store.backend}`,
+            ];
+            if (store.path)
+                searchLines.push(`- **Path**: \`${store.path}\``);
+            if (store.search) {
+                searchLines.push(`- **Strategy**: ${store.search.strategy}`);
+                if (store.search.topK)
+                    searchLines.push(`- **Top-K**: ${store.search.topK}`);
+                if (store.search.rerank)
+                    searchLines.push(`- **Reranking**: enabled`);
+            }
+            if (store.embedding) {
+                searchLines.push(`- **Embedding**: ${store.embedding.model} (${store.embedding.provider}, ${store.embedding.dimensions}d)`);
+            }
+            searchLines.push("");
+            searchLines.push("## Instructions");
+            searchLines.push("");
+            if (hasMcp) {
+                searchLines.push(`Use the \`${store.id}\` MCP server to search this store.`);
+                searchLines.push(`The MCP server is configured in \`.mcp.json\` and provides tools for querying the ${store.backend} database.`);
+            }
+            else {
+                searchLines.push(`This store uses ${store.backend} at \`${store.path ?? ".claude/stores/" + store.id}\`.`);
+                searchLines.push(`Read the database directly or use an appropriate library to query it.`);
+            }
+            searchLines.push("");
+            searchLines.push("Search for: $ARGUMENTS");
+            searchLines.push("");
+            files.push({
+                path: `.claude/commands/memory-search-${store.id}.md`,
+                content: searchLines.join("\n"),
+                category: "machine",
+            });
+        }
+        // Ingest command — for stores with ingestion config
+        if (store.ingestion) {
+            const ingestLines = [
+                "---",
+                `description: "Ingest documents into the ${store.id} memory store"`,
+                "---",
+                "",
+                `# /memory-ingest-${store.id}`,
+                "",
+                `Ingest documents into the **${store.id}** store.`,
+                "",
+                "## Ingestion Config",
+                `- **Sources**: ${store.ingestion.sources?.join(", ") ?? "not specified"}`,
+                `- **Chunking**: ${store.ingestion.chunking ?? "recursive"}`,
+            ];
+            if (store.ingestion.chunkSize)
+                ingestLines.push(`- **Chunk size**: ${store.ingestion.chunkSize}`);
+            if (store.ingestion.overlap)
+                ingestLines.push(`- **Overlap**: ${store.ingestion.overlap}`);
+            if (store.embedding) {
+                ingestLines.push(`- **Embedding**: ${store.embedding.model} (${store.embedding.provider}, ${store.embedding.dimensions}d)`);
+            }
+            ingestLines.push("");
+            ingestLines.push("## Instructions");
+            ingestLines.push("");
+            ingestLines.push(`1. Read files from the configured sources: ${store.ingestion.sources?.join(", ") ?? "docs/"}`);
+            ingestLines.push(`2. Split content into chunks (${store.ingestion.chunking ?? "recursive"}, size: ${store.ingestion.chunkSize ?? 512})`);
+            ingestLines.push(`3. Generate embeddings using ${store.embedding?.model ?? "the configured model"}`);
+            ingestLines.push(`4. Insert into ${store.backend} at \`${store.path ?? ".claude/stores/" + store.id}\``);
+            ingestLines.push("");
+            files.push({
+                path: `.claude/commands/memory-ingest-${store.id}.md`,
+                content: ingestLines.join("\n"),
+                category: "machine",
+            });
+        }
+    }
     return files;
 }
 /** Generate gate script stubs. */
@@ -1210,7 +1441,7 @@ function generateGateScripts(ast) {
     }
     return files;
 }
-/** Generate gate wrapper scripts that filter Task calls to the correct agent. */
+/** Generate gate wrapper scripts that run validation when agents complete. */
 function generateGateWrapperScripts(ast) {
     const files = [];
     const name = ast.topology.name;
@@ -1223,11 +1454,13 @@ function generateGateWrapperScripts(ast) {
         if (gate.behavior === "advisory")
             continue;
         const gateScriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-        const onFailExit = gate.onFail === "halt" ? 'exit 1' : 'echo "Gate failed — bounce-back requested (advisory)"';
+        const onFailExit = gate.onFail === "halt"
+            ? `echo "Gate '${gate.id}' validation failed. Fix issues before proceeding." >&2\n  exit 2`
+            : `echo "Gate '${gate.id}' failed — bounce back and fix the issues." >&2\n  exit 2`;
         const contentLines = [
             "#!/usr/bin/env bash",
             `# Gate wrapper: ${gate.id}`,
-            `# Enforces gate "${gate.id}" on Task tool calls.`,
+            `# Enforces gate "${gate.id}" on SubagentStop (after: ${gate.after || "any"}).`,
             `# Auto-generated by agentopology scaffold — edit as needed.`,
             "set -euo pipefail",
             "",
@@ -1377,14 +1610,17 @@ function generateSettings(ast) {
     // Per-agent hooks are now rendered in AGENT.md frontmatter (not in settings.json).
     // This is the Claude Code native approach: hooks in the agent file are scoped
     // to that agent automatically.
-    // Gate enforcement — compile gates with run: to PreToolUse hooks
+    // Gate enforcement — compile gates with run: to SubagentStop hooks
+    // Gates fire AFTER an agent finishes (SubagentStop), not before a tool runs.
+    // The matcher is the gate's `after:` agent name so the hook fires when that
+    // specific agent completes.
     const gates = ast.nodes.filter((n) => n.type === "gate");
     for (const gate of gates) {
         if (!gate.run)
             continue;
         if (gate.behavior === "advisory")
             continue; // advisory gates stay in markdown only
-        const eventName = "PreToolUse";
+        const eventName = "SubagentStop";
         if (!hooksByEvent[eventName])
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
@@ -1396,8 +1632,12 @@ function generateSettings(ast) {
                     command,
                 },
             ],
-            matcher: "Task", // Gates fire on Task tool (agent spawning)
         };
+        // Use the gate's after: agent as matcher so the hook only fires
+        // when that specific agent completes. Without after:, match all agents.
+        if (gate.after) {
+            hookEntry.matcher = gate.after;
+        }
         hooksByEvent[eventName].push(hookEntry);
     }
     // Write hooksByEvent to settings if any hooks or gates were registered
@@ -1409,66 +1649,21 @@ function generateSettings(ast) {
     if (envSettings) {
         settings.env = envSettings;
     }
-    // Permissions section from settings block
+    // Permissions section from settings block — nested under "permissions" key
     const perms = ast.settings;
     if (perms) {
         const allow = perms.allow;
         const deny = perms.deny;
-        const ask = perms.ask;
+        const permObj = {};
         if (allow && allow.length > 0)
-            settings.allow = allow;
+            permObj.allow = allow;
         if (deny && deny.length > 0)
-            settings.deny = deny;
-        if (ask && ask.length > 0)
-            settings.ask = ask;
-    }
-    // Defaults documentation
-    if (ast.defaults) {
-        const d = ast.defaults;
-        const defaultsDoc = {};
-        if (d.temperature != null)
-            defaultsDoc.temperature = d.temperature;
-        if (d.maxTokens != null)
-            defaultsDoc.maxTokens = d.maxTokens;
-        if (d.topP != null)
-            defaultsDoc.topP = d.topP;
-        if (d.topK != null)
-            defaultsDoc.topK = d.topK;
-        if (d.stop)
-            defaultsDoc.stop = d.stop;
-        if (d.seed != null)
-            defaultsDoc.seed = d.seed;
-        if (d.thinking)
-            defaultsDoc.thinking = d.thinking;
-        if (d.thinkingBudget != null)
-            defaultsDoc.thinkingBudget = d.thinkingBudget;
-        if (d.outputFormat)
-            defaultsDoc.outputFormat = d.outputFormat;
-        if (d.timeout)
-            defaultsDoc.timeout = d.timeout;
-        if (d.logLevel)
-            defaultsDoc.logLevel = d.logLevel;
-        if (Object.keys(defaultsDoc).length > 0) {
-            settings._defaults = defaultsDoc;
-        }
-    }
-    // Observability documentation
-    if (ast.observability) {
-        const o = ast.observability;
-        const obsDoc = {
-            enabled: o.enabled,
-            level: o.level,
-            exporter: o.exporter,
-            sampleRate: o.sampleRate,
-        };
-        if (o.endpoint)
-            obsDoc.endpoint = o.endpoint;
-        if (o.service)
-            obsDoc.service = o.service;
-        obsDoc.capture = o.capture;
-        obsDoc.spans = o.spans;
-        settings._observability = obsDoc;
+            permObj.deny = deny;
+        if (Object.keys(permObj).length > 0)
+            settings.permissions = permObj;
     }
+    // Defaults and observability are documented in the CLAUDE.md context file,
+    // not in settings.json (Claude Code doesn't recognize these keys).
     // Top-level extensions for claude-code
     if (ast.extensions?.["claude-code"]) {
         for (const [k, v] of Object.entries(ast.extensions["claude-code"])) {
@@ -1483,9 +1678,34 @@ function generateSettings(ast) {
         category: "shared-config",
     };
 }
-/** Generate .mcp.json from mcp-servers block. Always includes env field. */
+/**
+ * Backend → MCP server mapping.
+ *
+ * Only packages verified to exist on npm or PyPI are included.
+ * npm packages use `npx -y`, Python packages use `uvx`.
+ * `pathFlag` controls how the DB path is passed (positional, --db, --db-path, etc.).
+ *
+ * Verified 2026-03-21:
+ *   npm:  kuzu-mcp-server@0.1.0, mongodb-mcp-server@1.8.1
+ *   pip:  mcp-server-sqlite@2025.4.25, mcp-server-qdrant@0.8.1,
+ *         mcp-server-neo4j@0.1.8, chroma-mcp@0.2.6
+ */
+const STORE_MCP_COMMANDS = {
+    // npm packages
+    "kuzu": { command: "npx", args: ["-y", "kuzu-mcp-server"] }, // positional
+    "mongodb": { command: "npx", args: ["-y", "mongodb-mcp-server"], pathFlag: "--uri" },
+    // Python MCP servers (via uvx)
+    "sqlite": { command: "uvx", args: ["mcp-server-sqlite"], pathFlag: "--db-path" },
+    "sqlite-vec": { command: "uvx", args: ["mcp-server-sqlite"], pathFlag: "--db-path" },
+    "qdrant": { command: "uvx", args: ["mcp-server-qdrant"], pathFlag: "--qdrant-url" },
+    "neo4j": { command: "uvx", args: ["mcp-server-neo4j"], pathFlag: "--db-uri" },
+    "chroma": { command: "uvx", args: ["chroma-mcp"], pathFlag: "--host" },
+    // No verified MCP servers: lancedb, pinecone, pgvector, falkordb
+    // These backends use skill-based access (slash commands) instead
+};
 function generateMcpJson(ast) {
-    if (Object.keys(ast.mcpServers).length === 0)
+    const stores = ast.stores ?? [];
+    if (Object.keys(ast.mcpServers).length === 0 && stores.length === 0)
         return null;
     const mcpConfig = { mcpServers: {} };
     const servers = mcpConfig.mcpServers;
@@ -1512,6 +1732,36 @@ function generateMcpJson(ast) {
         }
         servers[name] = entry;
     }
+    // Merge memory store MCP server entries
+    for (const store of stores) {
+        const mcpCmd = STORE_MCP_COMMANDS[store.backend];
+        if (!mcpCmd) {
+            // Backend not in the known MCP map — skip (skill-based access only)
+            continue;
+        }
+        const args = [...mcpCmd.args];
+        const storePath = store.path ?? `.claude/stores/${store.id}`;
+        // Each server has its own CLI convention for the DB path
+        if (mcpCmd.pathFlag) {
+            args.push(mcpCmd.pathFlag, storePath);
+        }
+        else {
+            // No pathFlag = positional argument (e.g., kuzu-mcp-server ./path)
+            args.push(storePath);
+        }
+        const env = {};
+        if (store.connection) {
+            env.CONNECTION_STRING = store.connection;
+        }
+        servers[store.id] = {
+            command: mcpCmd.command,
+            args,
+            env,
+        };
+    }
+    // If no servers were added (all stores had unsupported backends), return null
+    if (Object.keys(servers).length === 0)
+        return null;
     return {
         path: ".mcp.json",
         content: JSON.stringify(mcpConfig, null, 2) + "\n",
@@ -1676,21 +1926,23 @@ function generateCommandFiles(ast) {
         // Frontmatter
         const fm = {};
         if (ast.topology.description) {
-            fm.description = `"${ast.topology.description}"`;
+            fm.description = ast.topology.description;
+        }
+        if (trigger.argument) {
+            fm["argument-hint"] = `[${trigger.argument}]`;
         }
         sections.push(frontmatter(fm));
         sections.push("");
-        // Header
+        // Header — use $ARGUMENTS for Claude Code command argument substitution
         sections.push(`# /${trigger.name}`);
         sections.push("");
-        sections.push(trigger.pattern);
-        sections.push("");
-        // Arguments
         if (trigger.argument) {
-            sections.push("## Arguments");
-            sections.push(`- ${trigger.argument}: extracted from the command pattern`);
-            sections.push("");
+            sections.push(`/${trigger.name} $ARGUMENTS`);
         }
+        else {
+            sections.push(trigger.pattern);
+        }
+        sections.push("");
         // Pipeline (from edges, enhanced)
         if (ast.edges.length > 0) {
             sections.push("## Pipeline");
@@ -1797,7 +2049,7 @@ function generateWorkspaceProtocol(ast) {
  * destroy their content.
  */
 function generateContextFile(ast) {
-    const DEFAULT_PATH = ".claude/CONTEXT.md";
+    const DEFAULT_PATH = ".claude/CLAUDE.md";
     let fileName = ast.context.file ?? DEFAULT_PATH;
     // Safety: never overwrite the user's root-level CLAUDE.md
     if (fileName === "CLAUDE.md" || fileName === "./CLAUDE.md") {
@@ -2026,6 +2278,8 @@ export const claudeCodeBinding = {
         files.push(...generateSchemas(ast));
         // Memory directories
         files.push(...generateMemory(ast));
+        // Memory store command files (search/ingest per store)
+        files.push(...generateMemoryCommands(ast));
         // Gate scripts
         files.push(...generateGateScripts(ast));
         files.push(...generateGateWrapperScripts(ast));