create-merlin-brain 3.11.0 → 3.13.0

package/dist/server/cost/tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/server/cost/tracker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/server/cost/tracker.ts"],"names":[],"mappings":"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"}

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;AA8CpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CAs4FxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAoCjD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkDpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CAi7FxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAoCjD"}

package/dist/server/server.js

@@ -25,6 +25,10 @@ import { registerLiteTools, getOrInitLiteClient, enhanceFromCloud } from './tool
 import { registerConfigSyncTools } from './tools/config-sync.js';
 import { registerSightsIndexTools } from './tools/sights-index.js';
 import { registerAgentsIndexTools } from './tools/agents-index.js';
+import { registerSessionRestoreTools } from './tools/session-restore.js';
+import { registerSessionSearchTools } from './tools/session-search.js';
+import { registerPromoteTools } from './tools/promote.js';
+import { registerLearningTools } from './tools/learning.js';
 import { registerAutoTeachTools, assessContextConfidence, buildTeachBackPrompt } from './tools/auto-teach.js';
 import { registerSmartRouteTools } from './tools/smart-route.js';
 import { wrapResponse, getStats, getCompactStats, formatSaveNotification, markSessionStatusShown } from './stats.js';
@@ -48,7 +52,7 @@ export function createServer() {
         name: 'merlin',
         version: VERSION,
         description: 'Merlin Brain. MANDATORY BOOT: Call merlin_get_selected_repo then merlin_get_project_status BEFORE responding to user. Call merlin_get_context before every file edit. Never run claude --agent via Bash — use Skill("merlin:route") instead.',
-    });
+    }); // pluginTrustMessage: future MCP SDK field for trust display
     const client = getClient();
     // Tool loading tiers:
     // 1. Core tools (always loaded): get_context, search, find_files, get_brief, etc.
@@ -276,7 +280,7 @@ export function createServer() {
     // ============================================================
     // ── CORE tool: always loaded, used at every session start ──────────────
     // Tool: merlin_get_brief
-    server.tool('merlin_get_brief', 'Get structured project brief at session start. Returns ~500-token summary covering product purpose, tech stack, architecture, active tasks, shipped APIs, and coding rules. Call after selecting a repo to orient yourself before coding, planning, or reviewing.', {
+    server.tool('merlin_get_brief', 'CALL AFTER merlin_get_selected_repo to orient yourself. Returns ~500-token project brief: product purpose, tech stack, architecture pattern, service map, active tasks (in-progress/pending/completed counts), shipped APIs you must not duplicate, and top coding rules. Use at session start, before planning a new feature, or when joining an unfamiliar project.', {
         repoUrl: z.string().optional().describe('GitHub URL of the repository (uses selected repo if omitted)'),
     }, async ({ repoUrl }) => {
         try {
@@ -407,7 +411,7 @@ export function createServer() {
     });
     // ── CORE tool: MANDATORY before every file edit or code modification ────
     // Tool: merlin_get_context
-    server.tool('merlin_get_context', `MANDATORY before every file edit, code modification, or feature implementation. Call before EACH file you modify — not just once per session. Returns codebase conventions, relevant file locations, how-to guide, anti-patterns, and auto-apply behavior patterns for the given task. Without this, you WILL duplicate existing code or break established patterns. Re-call every few minutes — the codebase changes. Works in both cloud (Sights) and local Lite mode.`, {
+    server.tool('merlin_get_context', `MANDATORY before every file edit, code modification, or feature implementation. Call before EACH file you modify. Returns: codebase conventions, relevant file paths with exports, step-by-step how-to guide, anti-patterns to avoid, auto-apply behavior patterns, language-specific rules (TypeScript/Python/Go/etc.), and current project blockers. Without this you WILL duplicate existing code or violate established patterns. Re-call every few minutes — the codebase changes. Works in both cloud (Sights) and offline Lite mode.`, {
         task: z.string().describe('What you want to know or do (e.g., "how does profile creation work", "add authentication", "where is the payment logic")'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ task, repoUrl }) => {
@@ -620,7 +624,7 @@ export function createServer() {
     });
     // ── CORE tool: always loaded, used before reading or modifying any file ─
     // Tool: merlin_find_files
-    server.tool('merlin_find_files', 'Find files by purpose, description, or architectural layer (routes, services, models, utils, components, hooks, middleware, etc.). Returns file paths, exports, and what to modify for specific tasks. Call BEFORE creating new files to check if something similar already exists. ALWAYS re-fetch before editing — files may have changed. Use this to locate existing functions before adding duplicates.', {
+    server.tool('merlin_find_files', 'Find files by purpose, description, or architectural layer. Call BEFORE creating any new file to check if something similar already exists. Returns file paths, exports, dependencies, and which files to modify for a given task. Supports layer filters: routes, services, models, utils, components, hooks, middleware, config, tests. Always re-fetch before editing — files may have moved. Use to locate existing functions before adding duplicates.', {
         query: z.string().describe('What you are looking for (e.g., "authentication", "database models", "API routes", "payment handling")'),
         layer: z.string().optional().describe('Filter by layer (routes, services, models, utils, components, etc.)'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
@@ -713,7 +717,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for style/rule questions ────────────
     // Tool: merlin_get_conventions
-    server.tool('merlin_get_conventions', 'Get all coding conventions, anti-patterns, style rules, naming guidelines, and change guides for the repository. Use when reviewing code quality, enforcing standards, understanding what patterns to avoid, or learning how to make specific types of changes. Returns category-organized rules with examples and example files.', {
+    server.tool('merlin_get_conventions', 'Get ALL coding conventions, anti-patterns, style rules, naming guidelines, and step-by-step change guides for the codebase. Returns rules organized by category (naming, structure, error handling, testing, etc.) with code examples and example files. Use when reviewing code quality, auditing for style violations, understanding what patterns to avoid, or learning the full rulebook before a major refactor.', {
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ repoUrl }) => {
         try {
@@ -809,7 +813,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for onboarding/orientation ──────────
     // Tool: merlin_quickstart
-    server.tool('merlin_quickstart', 'Get a 60-second overview and onboarding guide for the codebase. Returns the project quickstart document covering repo structure, entry points, dev commands, and key concepts. Use when first working with an unfamiliar repository, introducing a new team member, or needing a fast orientation without digging into code.', {
+    server.tool('merlin_quickstart', 'Get a 60-second onboarding guide for a new contributor or agent. Returns the project quickstart document: repo folder structure, entry points, development commands (install/build/test/run), environment setup, key concepts, and where to start. Use when first encountering an unfamiliar codebase, onboarding a new team member, or needing a fast orientation without reading the code.', {
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ repoUrl }) => {
         try {
@@ -867,7 +871,7 @@ export function createServer() {
     });
     // ── CORE tool: always loaded, used for searching documentation ──────────
     // Tool: merlin_search
-    server.tool('merlin_search', 'Search project documentation, wiki, and knowledge base by keyword or concept. Returns matching documentation sections, guides, and explanations that update in real-time as the team commits code. Use to find API docs, architecture notes, setup instructions, or any documented behavior. Complements merlin_get_context for targeted keyword search. Wiki updates in real-time — always fetch fresh.', {
+    server.tool('merlin_search', 'Keyword search across project documentation, wiki, architecture notes, API docs, and knowledge base. Returns matching doc sections with real-time content from the latest commit. Use to find specific functions, API endpoints, configuration options, architecture decisions, or any documented behavior. Complement to merlin_get_context — use this for targeted keyword lookup when you know what you\'re searching for.', {
         query: z.string().describe('What you want to find (e.g., "profile creation flow", "authentication", "payment API")'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ query, repoUrl }) => {
@@ -919,7 +923,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for listing available Sights ─────────
     // Tool: merlin_list_repos
-    server.tool('merlin_list_repos', 'List all repositories you have connected and analyzed on Merlin Sights. Returns repo names, GitHub URLs, analysis status (completed/pending/failed), and creation dates. Use to discover which Sights are available, find the URL for merlin_select_repo, or audit your connected repositories.', {}, async () => {
+    server.tool('merlin_list_repos', 'List all repositories you have connected and analyzed on Merlin Sights. Returns repo names, GitHub URLs, analysis status (ready/processing/queued/incomplete), and last-analyzed dates. Use to discover which Sights are available, find the correct URL for merlin_select_repo, or audit your connected repositories.', {}, async () => {
         try {
             const repos = await client.getRepositories();
             if (repos.length === 0) {
@@ -983,7 +987,7 @@ export function createServer() {
     });
     // ── CORE tool: always loaded, used to connect a specific repo ───────────
     // Tool: merlin_select_repo
-    server.tool('merlin_select_repo', 'Explicitly select which Merlin Sight (analyzed repository) to use for this session. Overrides auto-detection from git remote. Call when auto-detection picks the wrong repo, when working on a repo with multiple remotes, or when the auto-detected repo is not connected to Sights. Takes a GitHub URL and sets it as the active Sight for all subsequent tool calls.', {
+    server.tool('merlin_select_repo', 'Explicitly select which Merlin Sight (analyzed repository) to use for this session. Overrides auto-detection from git remote. Call when: auto-detection picks the wrong repo, working with multiple remotes, the auto-detected repo is not in Sights, or you want to pin a specific Sight. Sets the active repository for ALL subsequent tool calls in this session.', {
         repoUrl: z.string().describe('GitHub URL of the repository to use (e.g., "github.com/user/repo" or full URL)'),
         projectDir: z.string().optional().describe('Local project directory path (helps when auto-detection fails). Get via Bash(pwd).'),
     }, async ({ repoUrl, projectDir }) => {
@@ -1074,7 +1078,7 @@ export function createServer() {
     });
     // ── CORE tool: MANDATORY first call at every session start ──────────────
     // Tool: merlin_get_selected_repo
-    server.tool('merlin_get_selected_repo', 'CALL THIS FIRST at every session start. Connects to Merlin Sights, auto-detects the current repository from git remote, returns repository info (name, URL, analysis status), available Sights list, and repo root path for file operations. Must be called before any other Merlin tool. Without this, context tools cannot resolve the correct codebase.', {}, async () => {
+    server.tool('merlin_get_selected_repo', 'CALL THIS FIRST at every session start — required before all other Merlin tools. Connects to Merlin Sights, auto-detects the current repository from git remote, returns: repository name + URL, analysis status, available Sights list, absolute repo root path for Glob/file operations, and session stats. Without this call, context tools cannot resolve the correct codebase.', {}, async () => {
         // Mark session status as shown - this is the required first call
         markSessionStatusShown();
         recordToolCall('merlin_get_selected_repo');
@@ -1206,7 +1210,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for polling analysis completion ──────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_check_repo_status
-        server.tool('merlin_check_repo_status', 'Poll whether a repository analysis is complete after calling merlin_connect_repo. Returns status: pending, analyzing, completed, or failed, plus estimated time remaining. Use in a loop with 30-second intervals after connecting a new repo until status is "completed" before using context tools.', {
+        server.tool('merlin_check_repo_status', 'Poll whether a repository analysis is complete after calling merlin_connect_repo. Returns status (pending/analyzing/completed/locked/failed) and next action. Use in a loop with 30-second intervals after connecting a new repo until "completed", then use merlin_get_context normally. Auto-unlocks locked repos if tokens are available.', {
             repoUrl: z.string().optional().describe('GitHub URL of the repository (uses selected repo if omitted)'),
         }, async ({ repoUrl }) => {
             try {
@@ -1309,7 +1313,7 @@ export function createServer() {
     } // end cloud: merlin_check_repo_status
     // ── DEFERRED tool: loaded on-demand for onboarding new repositories ──────
     // Tool: merlin_connect_repo
-    server.tool('merlin_connect_repo', 'Connect and submit a new GitHub repository to Merlin Sights for analysis and indexing. Use when working on a repo not yet in Sights — analysis takes 2-5 minutes. After connecting, poll with merlin_check_repo_status until completed, then use merlin_get_context and merlin_find_files as normal.', {
+    server.tool('merlin_connect_repo', 'Submit a new GitHub repository to Merlin Sights for analysis and indexing. Use when working on a repo not yet connected to Sights — analysis takes 2-5 minutes. After connecting, poll merlin_check_repo_status until status is "completed", then use merlin_get_context and merlin_find_files normally. Also writes .merlin.json and updates CLAUDE.md in the local repo.', {
         repoUrl: z.string().describe('GitHub URL of the repository (e.g., "https://github.com/user/repo")'),
         branch: z.string().optional().default('main').describe('Branch to analyze (default: main)'),
     }, async ({ repoUrl, branch }) => {
@@ -1484,7 +1488,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for change impact assessment ─────────
     // Tool: merlin_impact_analysis
-    server.tool('merlin_impact_analysis', 'Analyze what could break if you modify a specific file. Returns all dependent files, importers, and downstream consumers that may need updates. Use before refactoring, renaming exports, changing function signatures, or modifying shared utilities to prevent cascading breakage.', {
+    server.tool('merlin_impact_analysis', 'Analyze what could break if you modify a specific file. Returns all dependent files, importers, and downstream consumers that need updates. Use before refactoring, renaming exports, changing function signatures, or modifying shared utilities — prevents cascading breakage by showing the full dependency graph.', {
         filePath: z.string().describe('The file path you plan to modify (e.g., "src/services/user.ts")'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ filePath, repoUrl }) => {
@@ -1515,7 +1519,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for finding existing patterns ─────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_similar_code
-        server.tool('merlin_similar_code', 'Find similar existing implementations in the codebase before writing new code. Returns matching patterns, functions, or components already built that serve similar purposes. Use when implementing anything new — there is likely an existing pattern to follow or extend. Prevents duplicating code and enforces DRY principles.', {
+        server.tool('merlin_similar_code', 'Find existing implementations in the codebase that match what you\'re about to build. Returns matching functions, components, or patterns already in production. Use before writing any new code — prevents duplication, enforces DRY. Complements merlin_find_files with semantic similarity matching rather than layer/purpose filtering.', {
             description: z.string().describe('What you\'re trying to implement (e.g., "API endpoint with authentication", "database query with pagination", "React form with validation")'),
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ description, repoUrl }) => {
@@ -1547,7 +1551,7 @@ export function createServer() {
     } // end cloud: merlin_similar_code
     // ── DEFERRED tool: loaded on-demand for getting real code patterns ────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_code_examples
-        server.tool('merlin_code_examples', 'Get real code examples extracted from this codebase for specific tasks. Returns actual patterns, templates, and snippets used in production. Use when you need to see how a pattern is really implemented (not just described) — e.g., "add endpoint", "add test", "error handling", "database query".', {
+        server.tool('merlin_code_examples', 'Get real production code examples extracted from this codebase for a specific task type. Returns actual patterns, templates, and snippets. Use when you need to see how something is really implemented — not just described — e.g., "add API endpoint", "write a test", "error handling pattern", "database query with pagination", "React form with validation".', {
             task: z.string().optional().describe('Specific task (e.g., "add endpoint", "add test", "error handling"). Leave empty for all examples.'),
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ task, repoUrl }) => {
@@ -1579,7 +1583,7 @@ export function createServer() {
     } // end cloud: merlin_code_examples
     // ── DEFERRED tool: loaded on-demand for natural language codebase Q&A ──
     // Tool: merlin_ask
-    server.tool('merlin_ask', 'Ask any natural language question about the codebase and get an AI-generated answer with source citations. Uses semantic search and RAG to find relevant context across documentation, code, and conventions. Use when you need a direct answer with explanation rather than raw files — e.g., "how does authentication work?", "where is billing handled?", "where should I add a new API endpoint?", "why is X structured this way?".', {
+    server.tool('merlin_ask', 'Ask a natural language question about the codebase and get an AI-generated answer with source citations. Uses semantic search + RAG across docs, code, conventions, and history. Use when you need a direct explanation rather than raw file paths — e.g., "how does authentication work?", "where is billing handled?", "where should I add a new API endpoint?", "why does X exist?". Returns answer with high/medium relevance sources.', {
         question: z.string().describe('Your question in natural language (e.g., "How does the payment flow work?", "Where is user validation handled?", "What patterns are used for error handling?")'),
         quick: z.boolean().optional().default(false).describe('If true, returns a faster but shorter answer without detailed sources'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
@@ -1648,7 +1652,7 @@ export function createServer() {
     // ============================================================
     // ── DEFERRED tool: loaded on-demand for persisting cross-session data ────
     // Tool: merlin_write_state
-    server.tool('merlin_write_state', 'Persist arbitrary state to Merlin cloud storage for cross-session and cross-agent memory. Use to save project artifacts (PROJECT.md, ROADMAP.md, STATE.md), planning data, decisions, agent outputs, or any data that needs to survive context resets. Supports optimistic locking via version parameter to prevent concurrent overwrites.', {
+    server.tool('merlin_write_state', 'Persist arbitrary state to Merlin cloud storage for cross-session and cross-agent memory. Save project artifacts (PROJECT.md content, ROADMAP.md, STATE.md), decisions, agent outputs, or any data that must survive context resets or agent handoffs. Supports optimistic locking via version parameter to prevent concurrent overwrites.', {
         key: z.string().describe('State key (e.g., "project", "roadmap", "state", "phase_3")'),
         value: z.any().describe('The state data to store (will be JSON serialized)'),
         agentId: z.string().optional().describe('Agent identifier for tracking who wrote the state'),
@@ -1707,7 +1711,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for restoring cross-session data ─────
     // Tool: merlin_read_state
-    server.tool('merlin_read_state', 'Read previously persisted state from Merlin cloud storage. Use to restore cross-session memory like PROJECT.md, ROADMAP.md, STATE.md, agent outputs, or any data saved with merlin_write_state. Returns the stored value and metadata (version, last updated, written by).', {
+    server.tool('merlin_read_state', 'Read previously persisted state from Merlin cloud storage by key. Restores cross-session memory: PROJECT.md content, ROADMAP.md, STATE.md, agent outputs, or any data saved with merlin_write_state. Returns the stored value plus metadata (version number, last updated timestamp, written-by agent).', {
         key: z.string().describe('State key to read (e.g., "project", "roadmap", "state")'),
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ key, repoUrl }) => {
@@ -1751,7 +1755,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for auditing stored state ─────────────
     // Tool: merlin_list_state
-    server.tool('merlin_list_state', 'List all state keys stored in Merlin cloud for this repository. Returns key names, last-updated timestamps, and sizes. Use to discover what cross-session memory is available (PROJECT.md, ROADMAP.md, checkpoints, agent outputs, etc.) before reading specific keys with merlin_read_state.', {
+    server.tool('merlin_list_state', 'List all state keys stored in Merlin cloud for this repository. Returns key names, last-updated timestamps, version numbers, and sizes. Use to discover what cross-session memory exists (PROJECT.md, ROADMAP.md, checkpoints, agent outputs, etc.) before calling merlin_read_state for specific keys.', {
         repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
     }, async ({ repoUrl }) => {
         try {
@@ -1797,7 +1801,7 @@ export function createServer() {
     });
     // ── DEFERRED tool: loaded on-demand for team activity logging ─────────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_log_activity
-        server.tool('merlin_log_activity', 'Log an activity event to the shared team timeline for audit trail and visibility. Use to record task completions, phase transitions, milestone achievements, decisions made, or any significant progress event. Events appear on the Merlin dashboard team timeline for coordination.', {
+        server.tool('merlin_log_activity', 'Log an activity event to the shared team timeline for audit trail, progress visibility, and coordination. Records task completions, phase transitions, milestone achievements, decisions, or any significant event. Events appear on the Merlin dashboard. Use for team handoff visibility and autonomous loop tracking.', {
             eventType: z.string().describe('Event type (e.g., "phase_started", "task_completed", "blocker_hit", "decision_made")'),
             eventData: z.any().optional().describe('Additional event data (JSON object)'),
             agentId: z.string().describe('Agent identifier for tracking'),
@@ -1847,7 +1851,7 @@ export function createServer() {
     } // end cloud: merlin_log_activity
     // ── DEFERRED tool: loaded on-demand for syncing task state to cloud ───────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_sync_task
-        server.tool('merlin_sync_task', 'Sync a task (create or update) to Merlin cloud for team visibility and cross-agent coordination. Use to track work items with status (pending/in_progress/completed/blocked), dependencies (blockedBy/blocks), phase, plan, and owner agent. Tasks appear on the Merlin dashboard and can be queried by other agents.', {
+        server.tool('merlin_sync_task', 'Create or update a task in Merlin cloud for team visibility and cross-agent coordination. Track work items with status (pending/in_progress/completed/blocked), blockedBy/blocks dependencies, phase, plan, owner agent, and affected files. Tasks appear on the Merlin dashboard backlog and are queryable by all agents.', {
             title: z.string().describe('Task title'),
             status: z.enum(['pending', 'in_progress', 'completed', 'blocked', 'skipped']).optional().describe('Task status'),
             description: z.string().optional().describe('Task description'),
@@ -1915,7 +1919,7 @@ export function createServer() {
     } // end cloud: merlin_sync_task
     // ── DEFERRED tool: loaded on-demand for viewing cloud task state ──────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_get_tasks
-        server.tool('merlin_get_tasks', 'Retrieve tasks synced to Merlin cloud. Filter by status (pending/in_progress/completed/blocked), phase, or plan. Returns work items from all agents for team coordination and planning. Use to see what tasks exist before creating duplicates, check what others are working on, or audit overall progress.', {
+        server.tool('merlin_get_tasks', 'Retrieve the team task backlog from Merlin cloud. Filter by status (pending/in_progress/completed/blocked), phase, or plan. Returns all work items across all agents. Use to audit what tasks exist before creating duplicates, check what others are working on, or get an overview of backlog progress.', {
             status: z.string().optional().describe('Filter by status (pending, in_progress, completed, blocked)'),
             phase: z.string().optional().describe('Filter by phase'),
             plan: z.string().optional().describe('Filter by plan'),
@@ -1979,7 +1983,7 @@ export function createServer() {
     } // end cloud: merlin_get_tasks
     // ── DEFERRED tool: loaded on-demand for escalating blockers to humans ────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_report_blocker
-        server.tool('merlin_report_blocker', 'Report a blocker or impediment that requires human attention, decision, or external action. Creates a visible alert on the team dashboard with severity level and context. Use when you hit an auth requirement, need a human decision point, encounter a critical error you cannot resolve, or need clarification before proceeding. Types: human_verify, auth_required, clarification, decision_point, external, error.', {
+        server.tool('merlin_report_blocker', 'Report a blocker requiring human attention, decision, or external action. Creates a visible alert on the team dashboard with severity level and full context. Use when: you need a human to verify something, auth credentials are required, a decision point is reached, or a critical unresolvable error is hit. Types: human_verify, auth_required, clarification, decision_point, external, error.', {
             title: z.string().describe('Brief description of the blocker'),
             blockerType: z.enum(['human_verify', 'auth_required', 'clarification', 'decision_point', 'external', 'error', 'other']).describe('Type of blocker'),
             description: z.string().optional().describe('Detailed description'),
@@ -2033,7 +2037,7 @@ export function createServer() {
     } // end cloud: merlin_report_blocker
     // ── DEFERRED tool: loaded on-demand for checking pending blockers ─────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_get_blockers
-        server.tool('merlin_get_blockers', 'Get open blockers or impediments awaiting resolution. Returns blockers reported by any agent with status, severity, type, and context. Check at session start or before starting work to see if there are critical issues or human-required decisions pending. Filter by status: open, resolved, or all.', {
+        server.tool('merlin_get_blockers', 'Get open blockers or impediments awaiting resolution. Returns blockers reported by any agent: status, severity, type, and context. Use at session start or before beginning autonomous work to check for critical unresolved issues or pending human decisions. Filter by open, resolved, or all.', {
             status: z.string().optional().default('open').describe('Filter by status (open, resolved, all)'),
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ status, repoUrl }) => {
@@ -2086,7 +2090,7 @@ export function createServer() {
     } // end cloud: merlin_get_blockers
     // ── DEFERRED tool: loaded on-demand for human-in-the-loop checkpoints ────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_create_checkpoint
-        server.tool('merlin_create_checkpoint', 'Create a verification checkpoint that signals a human review is needed before work continues. Use for human_verify, auth_gate, decision_point, approval, or review situations. Includes a summary of what was built and a checklist of items for the human to verify. The checkpoint appears on the dashboard and can be resolved to resume work.', {
+        server.tool('merlin_create_checkpoint', 'Create a human-review checkpoint before autonomous work continues. Signals that a human must verify, approve, or make a decision before proceeding. Includes what was built, a verification checklist, and resume context. Types: human_verify, auth_gate, decision_point, approval, review. Checkpoint appears on the dashboard and pauses the agent loop.', {
             title: z.string().describe('Checkpoint title'),
             checkpointType: z.enum(['human_verify', 'auth_gate', 'decision_point', 'approval', 'review']).describe('Type of checkpoint'),
             description: z.string().optional().describe('Detailed description'),
@@ -2146,7 +2150,7 @@ export function createServer() {
     } // end cloud: merlin_create_checkpoint
     // ── DEFERRED tool: loaded on-demand for team coordination overview ────────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_get_team_state
-        server.tool('merlin_get_team_state', 'Get consolidated team coordination state: active agent sessions, pending human checkpoints, open blockers, task summary counts (pending/in-progress/completed), and saved planning artifacts. Use at session start to see what other agents are working on, what decisions are pending, and what state is available for resuming work.', {
+        server.tool('merlin_get_team_state', 'Get consolidated team coordination snapshot: active agent sessions, pending human checkpoints, open blockers, task summary counts (pending/in-progress/completed), and saved planning artifacts. Use at session start to see what other agents are doing, what decisions are pending, and what state is ready to resume.', {
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ repoUrl }) => {
             try {
@@ -2242,7 +2246,7 @@ export function createServer() {
     } // end cloud: merlin_get_team_state
     // ── DEFERRED tool: loaded on-demand for session lifecycle management ──────
     if (hasCloudApi && !coreOnly) { // Tool: merlin_update_session
-        server.tool('merlin_update_session', 'Update your current session status and progress metadata for team visibility and pause/resume support. Records current phase, plan, task, completion count, and health score. Use to mark your session as active/paused/completed and track progress so other agents or humans can see where you are in the workflow.', {
+        server.tool('merlin_update_session', 'Update session status and progress metadata for team visibility and pause/resume coordination. Records current phase, plan, task, completion count, and pause reason. Use to mark session as active/paused/completed so other agents and humans can see progress. Supports autonomous loop handoff — call with resumeContext before pausing.', {
             sessionId: z.string().describe('Unique session identifier'),
             agentId: z.string().describe('Agent identifier'),
             status: z.enum(['active', 'paused', 'completed', 'abandoned']).optional().describe('Session status'),
@@ -2306,7 +2310,7 @@ export function createServer() {
     // CODING RULES
     // ============================================================
     if (hasCloudApi && !coreOnly) { // Tool: merlin_save_rule
-        server.tool('merlin_save_rule', 'Save a coding rule or preference to Merlin. Rules are returned with every context query and must be followed. Use when user expresses a preference that should persist.', {
+        server.tool('merlin_save_rule', 'Save a project-level coding rule that persists across sessions and is returned with every context query. Use when a user expresses a preference that should always be followed — e.g., "max 400 lines per file", "always use async/await", "no console.log in production". Categorize as: file_size, testing, style, patterns, or custom.', {
             rule: z.string().describe('The rule to save (e.g., "max 400 lines per file", "always use async/await", "no console.log in production")'),
             category: z.enum(['file_size', 'testing', 'style', 'patterns', 'custom']).optional().default('custom').describe('Rule category for organization'),
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
@@ -2367,7 +2371,7 @@ export function createServer() {
         });
     } // end cloud: merlin_save_rule
     if (hasCloudApi && !coreOnly) { // Tool: merlin_get_rules
-        server.tool('merlin_get_rules', 'Get all coding rules for this project. Returns rules that must be followed when writing code.', {
+        server.tool('merlin_get_rules', 'Get all project-level coding rules organized by category (file_size, testing, style, patterns, custom). These rules are injected into every context query. Use to audit existing rules before adding new ones, or to review what constraints the user has set.', {
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ repoUrl }) => {
             try {
@@ -2416,7 +2420,7 @@ export function createServer() {
         });
     } // end cloud: merlin_get_rules
     if (hasCloudApi && !coreOnly) { // Tool: merlin_remove_rule
-        server.tool('merlin_remove_rule', 'Remove a coding rule from this project.', {
+        server.tool('merlin_remove_rule', 'Remove a project-level coding rule by its exact text. Call merlin_get_rules first to see all current rules and find the exact text to remove.', {
             rule: z.string().describe('The exact rule text to remove'),
             repoUrl: z.string().optional().describe('GitHub URL of the repository (auto-detected from git if omitted)'),
         }, async ({ rule, repoUrl }) => {
@@ -2613,6 +2617,26 @@ export function createServer() {
         });
     } // end cloud: registerAgentsIndexTools
     // ============================================================
+    if (!coreOnly) {
+        // SESSION RESTORE - Read last session summary for continuity (local, no cloud needed)
+        // ============================================================
+        registerSessionRestoreTools({
+            server,
+            client,
+            resolveRepoId,
+        });
+    } // end free: registerSessionRestoreTools
+    // ============================================================
+    if (!coreOnly) {
+        // SESSION SEARCH - Keyword search across session history (local, no cloud needed)
+        // ============================================================
+        registerSessionSearchTools({
+            server,
+            client,
+            resolveRepoId,
+        });
+    } // end free: registerSessionSearchTools
+    // ============================================================
     if (!coreOnly) {
         // LITE MODE TOOLS - Local file-based context for small repos (always available)
         // ============================================================
@@ -2638,6 +2662,26 @@ export function createServer() {
             },
         });
     } // end cloud: registerConfigSyncTools
+    // ============================================================
+    if (hasCloudApi && !coreOnly) {
+        // BEHAVIOR PROMOTION - Evolve learned behaviors into reusable skills
+        // ============================================================
+        registerPromoteTools({
+            server,
+            client,
+            resolveRepoId,
+        });
+    } // end cloud: registerPromoteTools
+    // ============================================================
+    // PROMPT LEARNING ENGINE - RL-inspired agent effectiveness analysis
+    // DEFERRED: loaded on-demand via /merlin:optimize-prompts
+    // Works locally from outcomes.jsonl — no cloud API required
+    // ============================================================
+    registerLearningTools({
+        server,
+        client,
+        resolveRepoId,
+    });
     return server;
 }
 /** Start the MCP server with stdio transport */