create-merlin-brain 3.23.0 → 4.2.0

package/README.md

@@ -115,9 +115,25 @@ On Codex, Merlin now installs beyond basic MCP connectivity:
 - Project `.codex/agents/` with Merlin specialist agents
 - Project `.agents/skills/` with Merlin workflow skills
 - Project `AGENTS.md` and `.codex/config.toml` for repo-local guidance
+- Merlin capability discovery via `merlin_help`
+- Automatic steering toward `merlin_smart_route`, `merlin_recommend_for_task`, and `merlin_find_skill` when Codex sees feature, bug, or resume-style prompts
 
 Codex does not currently expose a documented extension point for replacing app-shell chrome or adding a custom sidebar icon, so Merlin parity is implemented on the supported surfaces Codex actually provides.
 
+Typical Codex prompts:
+
+```text
+Use Merlin to map this codebase before changing anything.
+```
+
+```text
+Use Merlin to find the best skill, agent, and workflow for this task: add OAuth login.
+```
+
+```text
+Call merlin_help for this task: debug the failing Stripe webhook tests.
+```
+
 ## Documentation
 
 Visit [merlin.build/docs](https://merlin.build/docs) for full documentation.

package/bin/install.cjs

@@ -136,6 +136,8 @@ const AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
 const COMMANDS_DIR = path.join(CLAUDE_DIR, 'commands', 'merlin');
 const LOOP_DIR = path.join(CLAUDE_DIR, 'loop');
 const RULES_DIR = path.join(CLAUDE_DIR, 'rules');
+const SCRIPTS_DIR = path.join(CLAUDE_DIR, 'scripts');
+const MERLIN_STATE_DIR = path.join(CLAUDE_DIR, 'merlin-state');
 
 const colors = {
   reset: '\x1b[0m',
@@ -1356,6 +1358,48 @@ async function install() {
     logWarn('Hooks not found in package');
   }
 
+  // Step 11b: Install Codex integration scripts
+  logStep('11b/13', 'Installing Codex integration scripts...');
+  const scriptsSrc = path.join(filesDir, 'scripts');
+  if (fs.existsSync(scriptsSrc)) {
+    ensureDir(SCRIPTS_DIR);
+    const count = copyDirRecursive(scriptsSrc, SCRIPTS_DIR);
+    // Make all .sh files executable
+    fs.readdirSync(SCRIPTS_DIR).forEach(file => {
+      if (file.endsWith('.sh')) {
+        fs.chmodSync(path.join(SCRIPTS_DIR, file), '755');
+      }
+    });
+    logSuccess(`Installed ${count} script files (Codex integration)`);
+  } else {
+    logWarn('Scripts not found in package');
+  }
+
+  // Step 11c: Install merlin-state defaults (without overwriting user state)
+  logStep('11c/13', 'Installing merlin-state defaults...');
+  const stateSrc = path.join(filesDir, 'merlin-state');
+  if (fs.existsSync(stateSrc)) {
+    ensureDir(MERLIN_STATE_DIR);
+    const stateFiles = fs.readdirSync(stateSrc);
+    let installedCount = 0;
+    let skippedCount = 0;
+    for (const stateFile of stateFiles) {
+      if (stateFile === '.DS_Store') continue;
+      const destPath = path.join(MERLIN_STATE_DIR, stateFile);
+      // Never overwrite existing state files — preserve user state
+      if (fs.existsSync(destPath)) {
+        skippedCount++;
+      } else {
+        fs.copyFileSync(path.join(stateSrc, stateFile), destPath);
+        installedCount++;
+      }
+    }
+    if (installedCount > 0) logSuccess(`Installed ${installedCount} state file defaults`);
+    if (skippedCount > 0) logSuccess(`Skipped ${skippedCount} existing state files (user state preserved)`);
+  } else {
+    logWarn('Merlin-state defaults not found in package');
+  }
+
   // Helper: create MCP config object based on available binary
   function mcpConfig(apiKey, includeType) {
     const cfg = useGlobalBinary

package/bin/runtime-adapters.cjs

@@ -185,10 +185,19 @@ Before doing real work in a repository:
 
 Do not skip boot. Do not start editing code without Merlin context.
 
+## Discoverability
+
+- If the user asks what Merlin can do, call \`merlin_help\`.
+- If the best Merlin path is unclear, call \`merlin_help(task)\`.
+- For new features or integrations, call \`merlin_recommend_for_task(task)\` before building from scratch.
+- For agent selection, call \`merlin_smart_route(task)\`.
+- For reusable prompt packs, call \`merlin_find_skill(query)\`.
+
 ## Codex + Merlin Workflow
 
 - For codebase questions, start with \`merlin_search("query")\` or \`merlin_get_context("task")\`.
 - Before every code edit, call \`merlin_get_context("your task")\`.
+- Let Merlin choose the route first when helpful: tool vs skill vs custom agent vs direct execution.
 - When local file search is still needed, prefer fast repo-native tools such as \`rg\`.
 - Use Codex's normal execution style: inspect first, edit surgically, verify after changes.
 - Keep progress updates concise and factual while work is in flight.
@@ -211,9 +220,13 @@ Do not skip boot. Do not start editing code without Merlin context.
 
 - \`merlin_get_selected_repo\` — identify the active repository
 - \`merlin_get_project_status\` — load project state and active tasks
+- \`merlin_help(task?)\` — explain Merlin capabilities and recommend the best route
 - \`merlin_get_context(task)\` — fetch targeted implementation context
 - \`merlin_find_files(query)\` — locate files by purpose
 - \`merlin_search(query)\` — semantic code search
+- \`merlin_find_skill(query)\` — find reusable Merlin skills
+- \`merlin_smart_route(task)\` — choose the best specialist agent
+- \`merlin_recommend_for_task(task)\` — find agents and reference codebases before building
 
 ## Defaults
 
@@ -343,6 +356,8 @@ mkdir -p "\${MERLIN_HOME}/analytics" "\${MERLIN_HOME}/sessions" 2>/dev/null || t
 
 _context="MERLIN MODE ACTIVE. Before handling the user request, call merlin_get_selected_repo, then merlin_get_project_status, then merlin_get_rules and merlin_get_brief."
 _context="\${_context} Use Merlin context before edits: call merlin_get_context(task)."
+_context="\${_context} If the best Merlin path is unclear, call merlin_help(task) before acting."
+_context="\${_context} For task routing, prefer merlin_smart_route(task), merlin_find_skill(query), and merlin_recommend_for_task(task) over improvising."
 _context="\${_context} Prefer Merlin skills and custom agents installed in this repository when they match the task."
 _context="\${_context} Keep the Codex experience pragmatic: inspect first, patch surgically, verify before claiming completion."
 _context="\${_context} Prefix visible progress updates with the Merlin badge when practical: ⟡🔮 MERLIN ›"
@@ -375,18 +390,22 @@ fi
 clean=$(printf '%s' "$prompt" | sed -E -e 's/<[^>]+>//g' -e 's|https?://[^ ]*||g' -e 's|/[a-zA-Z0-9._/-]+||g' -e 's/\`[^\`]*\`//g')
 
 suggestion=""
-if echo "$clean" | grep -qiE "resume|pick up|continue|where were we"; then
-  suggestion='Merlin routing: resume context and use the merlin-resume skill.'
+if echo "$clean" | grep -qiE "what can merlin do|how do i use merlin|what is available|available skills|available agents|available tools|help me use merlin"; then
+  suggestion='Merlin routing: call merlin_help first, then pick the recommended tool, skill, or agent path.'
+elif echo "$clean" | grep -qiE "resume|pick up|continue|where were we"; then
+  suggestion='Merlin routing: call merlin_get_project_status, then use the merlin-resume skill.'
 elif echo "$clean" | grep -qiE "progress|status|where are we|how far"; then
-  suggestion='Merlin routing: use the merlin-progress skill.'
+  suggestion='Merlin routing: call merlin_get_project_status, then use the merlin-progress skill.'
 elif echo "$clean" | grep -qiE "map codebase|understand this repo|learn this codebase|explore the architecture"; then
-  suggestion='Merlin routing: use the merlin-map-codebase skill before implementation.'
+  suggestion='Merlin routing: call merlin_search and merlin_get_context, then use the merlin-map-codebase skill before implementation.'
 elif echo "$clean" | grep -qiE "bug|crash|error|not working|fix|failing|exception"; then
-  suggestion='Merlin routing: debug first, then route bounded work to implementation and verification agents.'
+  suggestion='Merlin routing: call merlin_get_context for the bug, then merlin_smart_route(task), then use merlin-verify after the fix.'
 elif echo "$clean" | grep -qiE "refactor|cleanup|clean up|dry|restructure"; then
-  suggestion='Merlin routing: keep scope narrow, preserve behavior, and use implementation plus verification agents.'
+  suggestion='Merlin routing: call merlin_get_context first, keep scope narrow, and use merlin-workflow plus merlin-verify.'
+elif echo "$clean" | grep -qiE "oauth|auth|stripe|prisma|sdk|integration|api|graphql|railway|deploy"; then
+  suggestion='Merlin routing: call merlin_recommend_for_task(task), merlin_find_skill(query), and merlin_smart_route(task) before building.'
 elif echo "$clean" | grep -qiE "build|add|create|implement|new feature|develop"; then
-  suggestion='Merlin routing: gather Merlin context first, then execute with implementation-focused agents.'
+  suggestion='Merlin routing: call merlin_help(task) or merlin_smart_route(task), gather Merlin context, then execute with implementation-focused agents.'
 fi
 
 [ -z "$suggestion" ] && echo "{}" && exit 0
@@ -615,6 +634,18 @@ function installCodexAgents(projectDir) {
 
 function buildCodexSkillSpecs() {
   return [
+    {
+      dir: 'merlin-discover',
+      content: `---
+name: merlin-discover
+description: Use when the user asks what Merlin can do, which Merlin features are available, or which Merlin path should be used for a task in Codex.
+---
+
+Start with \`merlin_help\`.
+If the user also has a concrete task, call \`merlin_help(task)\`.
+Then choose the recommended route: direct Merlin tools, a Merlin skill, a custom Codex agent, or local execution.
+Do not assume the user already knows internal Merlin names.`,
+    },
     {
       dir: 'merlin-map-codebase',
       content: `---

package/dist/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuDpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CAigGxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA+CjD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwDpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CA4gGxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA+CjD"}

package/dist/server/server.js

@@ -19,6 +19,7 @@ import { registerVerificationTools } from './tools/verification.js';
 import { registerAdaptiveTools } from './tools/adaptive.js';
 import { registerAgentTools } from './tools/agents.js';
 import { registerDiscoveryTools } from './tools/discoveries.js';
+import { registerHelpTools } from './tools/help.js';
 import { registerRouteTools } from './tools/route.js';
 import { registerCostTools } from './tools/cost.js';
 import { registerLiteTools, getOrInitLiteClient, enhanceFromCloud } from './tools/lite.js';
@@ -2598,6 +2599,16 @@ export function createServer() {
         });
     } // end free: registerAutoTeachTools
     // ============================================================
+    if (!coreOnly) {
+        // HELP TOOLS - Discover Merlin capabilities and recommended routes
+        // ============================================================
+        registerHelpTools({
+            server,
+            client,
+            resolveRepoId,
+        });
+    } // end free: registerHelpTools
+    // ============================================================
     if (!coreOnly) {
         // AGENT ROUTE TOOLS - Fresh process spawning for specialists (local)
         // ============================================================