monomind 2.7.5 → 2.7.7

package/packages/@monomind/cli/dist/src/commands/hooks-routing-commands.js

@@ -5,7 +5,6 @@
  */
 import { output } from '../output.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
-import { storeCommand } from './transfer-store.js';
 // Route subcommand
 export const routeCommand = {
     name: 'route',
@@ -639,36 +638,23 @@ export const transferFromProjectCommand = {
 // Parent transfer command combining all transfer methods
 export const transferCommand = {
     name: 'transfer',
-    description: 'Transfer patterns via IPFS-based decentralized registry',
-    subcommands: [storeCommand, transferFromProjectCommand],
+    description: 'Transfer learned patterns from another local project',
+    subcommands: [transferFromProjectCommand],
     examples: [
-        { command: 'monomind hooks transfer store list', description: 'List patterns from registry' },
-        { command: 'monomind hooks transfer store search -q routing', description: 'Search patterns' },
-        { command: 'monomind hooks transfer store download -p seraphine-genesis', description: 'Download pattern' },
-        { command: 'monomind hooks transfer store publish', description: 'Publish pattern to registry' },
-        { command: 'monomind hooks transfer from-project -s ../other-project', description: 'Transfer from project' },
+        { command: 'monomind hooks transfer from-project -s ../other-project', description: 'Transfer all patterns from another checkout' },
+        { command: 'monomind hooks transfer from-project -s ../prod --filter security -m 0.9', description: 'Transfer only high-confidence security patterns' },
     ],
     action: async () => {
         output.writeln();
-        output.writeln(output.bold('Pattern Transfer System'));
-        output.writeln(output.dim('Decentralized pattern sharing via IPFS'));
+        output.writeln(output.bold('Pattern Transfer'));
+        output.writeln(output.dim('Copy learned patterns between local project checkouts'));
         output.writeln();
         output.writeln('Subcommands:');
         output.printList([
-            `${output.highlight('store')}        - Pattern marketplace (list, search, download, publish)`,
-            `${output.highlight('from-project')} - Transfer patterns from another project`,
+            `${output.highlight('from-project')} - Transfer patterns from another project directory`,
         ]);
         output.writeln();
-        output.writeln(output.bold('IPFS-Based Features:'));
-        output.printList([
-            'Decentralized registry via IPNS for discoverability',
-            'Content-addressed storage for integrity',
-            'Ed25519 signatures for verification',
-            'Anonymization levels: minimal, standard, strict, paranoid',
-            'Trust levels: unverified, community, verified, official',
-        ]);
-        output.writeln();
-        output.writeln('Run "monomind hooks transfer <subcommand> --help" for details');
+        output.writeln('Run "monomind hooks transfer from-project --help" for options');
         return { success: true };
     }
 };

package/packages/@monomind/cli/dist/src/commands/memory-crud.js

@@ -297,7 +297,10 @@ export const searchCommand = {
                 output.writeln();
             }
         }
-        output.printInfo(`Searching: "${query}" (${searchType})`);
+        // Requested type only — the method that ACTUALLY ran is printed after the
+        // search, from searchResult.searchMethod. Labelling this line "(semantic)"
+        // used to claim a vector search that may never have happened.
+        output.printInfo(`Searching: "${query}" (requested: ${searchType})`);
         output.writeln();
         // Use direct sql.js search with vector similarity
         try {
@@ -318,11 +321,39 @@ export const searchCommand = {
                 namespace: r.namespace,
                 preview: r.content
             }));
+            const actualMethod = searchResult.searchMethod ?? 'unknown';
+            const fallbackReason = searchResult.fallbackReason;
             if (ctx.flags.format === 'json') {
-                output.printJson({ query, searchType, results, searchTime: `${searchResult.searchTime}ms` });
+                output.printJson({
+                    query,
+                    searchType,
+                    searchMethod: actualMethod,
+                    ...(fallbackReason ? { fallbackReason } : {}),
+                    results,
+                    searchTime: `${searchResult.searchTime}ms`,
+                });
                 return { success: true, data: results };
             }
-            // Performance stats
+            // Performance stats — method first, so a keyword fallback is never hidden
+            // behind a "(semantic)" header.
+            const REASON_TEXT = {
+                'no-embedding-model': 'embedding model unavailable',
+                'embedding-failed': 'embedding generation failed',
+                'no-semantic-matches': 'vector search returned no matches',
+            };
+            if (actualMethod === 'semantic') {
+                output.writeln(output.dim('  Method: semantic (vector similarity)'));
+            }
+            else if (actualMethod === 'hybrid') {
+                output.writeln(output.dim('  Method: hybrid (per-entry cosine, keyword overlap where no vector exists)'));
+            }
+            else if (actualMethod === 'unknown') {
+                output.writeln(output.dim('  Method: unknown'));
+            }
+            else {
+                const why = fallbackReason ? REASON_TEXT[fallbackReason] ?? fallbackReason : undefined;
+                output.printWarning(`Method: ${actualMethod}${why ? ` — ${why}` : ''}. Scores are token-overlap fractions, not vector similarity.`);
+            }
             output.writeln(output.dim(`  Search time: ${searchResult.searchTime}ms`));
             output.writeln();
             if (results.length === 0) {

package/packages/@monomind/cli/dist/src/commands/org-observe.js

@@ -178,17 +178,44 @@ export const reportAction = async (ctx, name) => {
     }
     return { success: true };
 };
+/** Read questions.json. A MISSING file legitimately means "no questions" → [].
+ *  Any other failure (unreadable, malformed — e.g. a partial daemon write) THROWS:
+ *  answerAction rewrites this file from what this returns, so silently coercing a
+ *  failed read to [] would atomically replace every recorded question with one. */
 const readQuestions = (cwd, name) => {
+    const path = join(cwd, ORG_DIR, name, 'questions.json');
+    let raw;
     try {
-        return JSON.parse(readFileSync(join(cwd, ORG_DIR, name, 'questions.json'), 'utf8')).questions ?? [];
+        raw = readFileSync(path, 'utf8');
     }
-    catch {
-        return [];
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw new Error(`cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
     }
+    if (parsed?.questions === undefined || parsed.questions === null)
+        return [];
+    if (!Array.isArray(parsed.questions))
+        throw new Error(`${path}: "questions" is not an array`);
+    return parsed.questions;
 };
 /** `org questions <name> [--all]` — list pending (or all) ask_human questions. */
 export const questionsAction = async (ctx, name) => {
-    const all = readQuestions(ctx.cwd, name);
+    let all;
+    try {
+        all = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'questions.json unreadable' };
+    }
     const shown = ctx.flags['all'] === true ? all : all.filter(q => q.answer === null);
     if (!shown.length) {
         log(output.info(all.length ? `No pending questions for org ${name} (${all.length} answered — use --all).` : `No questions recorded for org ${name}.`));
@@ -212,7 +239,14 @@ export const answerAction = async (ctx, name) => {
     const answer = ctx.args.slice(2).join(' ').trim();
     if (!questionId || !answer)
         return { success: false, message: `usage: monomind org answer ${name} <question-id> "answer text"` };
-    const questions = readQuestions(ctx.cwd, name);
+    let questions;
+    try {
+        questions = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'questions.json unreadable — answer not recorded' };
+    }
     const q = questions.find(x => x.questionId === questionId);
     if (!q) {
         log(output.error(`Question "${questionId}" not found for org ${name} — list with: monomind org questions ${name}`));
@@ -246,7 +280,17 @@ export const answerAction = async (ctx, name) => {
     // snapshot can be up to 10s stale (live-delivery timeout), and rewriting
     // from it would delete questions the daemon appended meanwhile and revert
     // answers it recorded (atomic rename prevents torn writes, not lost updates).
-    const fresh = readQuestions(ctx.cwd, name);
+    // A FAILED re-read must abort the write: rewriting from [] would atomically
+    // rename a single-question file over every other recorded question.
+    let fresh;
+    try {
+        fresh = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Refusing to rewrite questions.json — ${err instanceof Error ? err.message : String(err)}`));
+        log(output.warning(`The answer was NOT recorded. Fix or restore ${join(ctx.cwd, ORG_DIR, name, 'questions.json')}, then retry.`));
+        return { success: false, message: 'questions.json unreadable — answer not recorded' };
+    }
     const freshQ = fresh.find(x => x.questionId === questionId);
     if (freshQ && freshQ.answer !== null) {
         return { success: false, message: `question "${questionId}" was answered while this command was running` };

package/packages/@monomind/cli/dist/src/commands/performance.js

@@ -23,6 +23,13 @@ const benchmarkCommand = {
         const suiteRaw = ctx.flags.suite || 'all';
         const VALID_SUITES = new Set(['all', 'wasm', 'neural', 'memory', 'search']);
         const suite = VALID_SUITES.has(suiteRaw) ? suiteRaw : 'all';
+        // Falling back is fine; doing it silently is not. `--suite quick` used to
+        // print "Running all benchmarks" and produce a full run, so the user's
+        // explicit choice was discarded with no indication it had been ignored.
+        if (suiteRaw !== suite) {
+            output.writeln(output.warning(`Unknown benchmark suite "${suiteRaw}" — running "all" instead. ` +
+                `Valid suites: ${[...VALID_SUITES].join(', ')}.`));
+        }
         const MAX_ITERATIONS = 10_000;
         const MAX_WARMUP = 500;
         const iterationsRaw = parseInt(ctx.flags.iterations || '100', 10);
@@ -514,12 +521,24 @@ const bottleneckCommand = {
     ],
     examples: [
         { command: 'monomind performance bottleneck', description: 'Find bottlenecks' },
-        { command: 'monomind performance bottleneck -d full', description: 'Full analysis' },
+        { command: 'monomind performance bottleneck -c network', description: 'Only the Network component' },
     ],
     action: async (ctx) => {
         output.writeln();
         output.writeln(output.bold('Bottleneck Analysis'));
         output.writeln(output.dim('─'.repeat(50)));
+        // Components this command actually knows how to inspect. Used both to
+        // validate --component and to tell the user what they could have asked for.
+        const ANALYZED_COMPONENTS = ['Runtime', 'Vector Search', 'Traces', 'Memory DB', 'Network'];
+        // Only a single depth of analysis is implemented. Accepting `--depth full`
+        // and quietly running the quick analysis discards the user's request with
+        // no indication it was ignored, so say so instead.
+        const depthRaw = ctx.flags.depth || 'quick';
+        if (depthRaw !== 'quick') {
+            output.writeln(output.warning(`--depth ${depthRaw} is not implemented — running the "quick" analysis. ` +
+                `Only "quick" is supported today.`));
+        }
+        const componentFilter = ctx.flags.component?.trim();
         const spinner = output.createSpinner({ text: 'Analyzing system...', spinner: 'dots' });
         spinner.start();
         const fs = await import('node:fs');
@@ -568,10 +587,24 @@ const bottleneckCommand = {
         if (!network.batching) {
             findings.push({ component: 'Network', bottleneck: 'No request batching', severity: output.info('Low'), solution: 'Run: monomind performance optimize --apply -t latency' });
         }
-        if (findings.length === 0) {
-            findings.push({ component: 'System', bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: 'System is performing well' });
+        let results = findings;
+        if (componentFilter) {
+            const known = ANALYZED_COMPONENTS.find(c => c.toLowerCase() === componentFilter.toLowerCase())
+                ?? ANALYZED_COMPONENTS.find(c => c.toLowerCase().includes(componentFilter.toLowerCase()));
+            if (!known) {
+                spinner.fail(`Unknown component "${componentFilter}"`);
+                output.writeln(output.warning(`Analyzed components: ${ANALYZED_COMPONENTS.join(', ')}.`));
+                return { success: false, message: `Unknown component: ${componentFilter}`, exitCode: 1 };
+            }
+            results = findings.filter(f => f.component === known);
+            if (results.length === 0) {
+                results = [{ component: known, bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: `${known} is performing well` }];
+            }
+        }
+        else if (results.length === 0) {
+            results = [{ component: 'System', bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: 'System is performing well' }];
         }
-        spinner.succeed(`Analysis complete — ${findings.length} finding(s)`);
+        spinner.succeed(`Analysis complete — ${results.length} finding(s)`);
         output.writeln();
         output.printTable({
             columns: [
@@ -580,7 +613,7 @@ const bottleneckCommand = {
                 { key: 'severity', header: 'Severity', width: 12 },
                 { key: 'solution', header: 'Solution', width: 50 },
             ],
-            data: findings,
+            data: results,
         });
         return { success: true };
     },

package/packages/@monomind/cli/dist/src/commands/security-misc.js

@@ -11,10 +11,11 @@ export const auditCommand = {
     options: [
         { name: 'action', short: 'a', type: 'string', description: 'Action: list (only supported value — log/export/clear are not implemented)', default: 'list' },
         { name: 'limit', short: 'l', type: 'number', description: 'Number of entries to show', default: '20' },
-        { name: 'filter', short: 'f', type: 'string', description: 'Filter by event type' },
+        { name: 'filter', short: 'f', type: 'string', description: 'Filter by event type (substring, case-insensitive)' },
     ],
     examples: [
         { command: 'monomind security audit --action list', description: 'List audit logs' },
+        { command: 'monomind security audit --filter SWARM', description: 'Only swarm activity events' },
     ],
     action: async (ctx) => {
         const requestedAction = ctx.flags.action || 'list';
@@ -54,7 +55,21 @@ export const auditCommand = {
         const now = new Date().toISOString().replace('T', ' ').substring(0, 19);
         auditEntries.push({ timestamp: now, event: 'AUDIT_RUN', user: 'cli', status: output.success('Success') });
         auditEntries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-        if (auditEntries.length === 0) {
+        // --filter was previously parsed and discarded, so every invocation
+        // returned the full log regardless of what the user asked for.
+        const eventFilter = ctx.flags.filter?.trim();
+        let visibleEntries = auditEntries;
+        if (eventFilter) {
+            const needle = eventFilter.toLowerCase();
+            visibleEntries = auditEntries.filter(e => e.event.toLowerCase().includes(needle));
+            if (visibleEntries.length === 0) {
+                const seen = [...new Set(auditEntries.map(e => e.event))].sort();
+                output.writeln(output.warning(`No audit events match "${eventFilter}".`));
+                output.writeln(output.dim(`Event types present: ${seen.join(', ') || 'none'}`));
+                return { success: true, data: { entries: [], filter: eventFilter } };
+            }
+        }
+        if (visibleEntries.length === 0) {
             output.writeln(output.dim('No audit events found. Initialize a project first: monomind init'));
         }
         else {
@@ -65,7 +80,7 @@ export const auditCommand = {
                     { key: 'user', header: 'User', width: 15 },
                     { key: 'status', header: 'Status', width: 12 },
                 ],
-                data: auditEntries.slice(0, parseInt(ctx.flags.limit || '20', 10)),
+                data: visibleEntries.slice(0, parseInt(ctx.flags.limit || '20', 10)),
             });
         }
         return { success: true };

package/packages/@monomind/cli/dist/src/index.js

@@ -156,42 +156,38 @@ export class CLI {
             let subcommandArgs = positional;
             // Process command path (e.g., ['hooks', 'worker', 'list'])
             // Note: When parser includes subcommand in commandPath, positional already excludes it
+            //
+            // Resolution walks as deep as the tree goes. It previously unrolled
+            // exactly two levels of nesting, so a four-segment invocation silently
+            // resolved to its grandparent and ran that command's action — which for
+            // a group command means printing help instead of doing anything. No
+            // error, no hint. `hooks transfer store list` failed exactly this way,
+            // making the whole pattern-store subtree unreachable without anyone
+            // noticing. This mirrors the loop showHelp() already used (see below),
+            // so `--help` and dispatch now agree on the target at any depth.
+            const findChild = (parent, segment) => parent.subcommands?.find(sc => sc.name === segment || sc.aliases?.includes(segment));
             if (commandPath.length > 1 && command.subcommands) {
-                const subcommandName = commandPath[1];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    // Parser already extracted subcommand from positional, so use as-is
-                    subcommandArgs = positional;
-                    // Check for nested subcommand (level 2)
-                    if (commandPath.length > 2 && subcommand.subcommands) {
-                        const nestedName = commandPath[2];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            // Parser already extracted nested subcommand too
-                            subcommandArgs = positional;
-                        }
-                    }
+                // Parser already lifted the subcommand names out of positional, so
+                // descend using commandPath and leave the remaining args untouched.
+                for (const segment of commandPath.slice(1)) {
+                    const next = findChild(targetCommand, segment);
+                    if (!next)
+                        break;
+                    targetCommand = next;
                 }
+                subcommandArgs = positional;
             }
             else if (positional.length > 0 && command.subcommands) {
-                // Check if first positional is a subcommand
-                const subcommandName = positional[0];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    subcommandArgs = positional.slice(1);
-                    // Check for nested subcommand (level 2 from positional)
-                    if (subcommandArgs.length > 0 && subcommand.subcommands) {
-                        const nestedName = subcommandArgs[0];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            subcommandArgs = subcommandArgs.slice(1);
-                        }
-                    }
+                // Subcommand names are still in positional — consume each one we match.
+                let consumed = 0;
+                while (consumed < subcommandArgs.length) {
+                    const next = findChild(targetCommand, subcommandArgs[consumed]);
+                    if (!next)
+                        break;
+                    targetCommand = next;
+                    consumed++;
                 }
+                subcommandArgs = subcommandArgs.slice(consumed);
             }
             // Validate flags
             const validationErrors = this.parser.validateFlags(flags, targetCommand);

package/packages/@monomind/cli/dist/src/mcp-client.js

@@ -110,6 +110,83 @@ export class MCPClientError extends Error {
         this.name = 'MCPClientError';
     }
 }
+/**
+ * Runtime JSON-Schema type name for a JS value, or undefined for values we do
+ * not model (functions, symbols, bigint). `null` is reported as 'null' so a
+ * declared `type: 'object'` does not silently accept it.
+ *
+ * Note the two JS/JSON mismatches this has to paper over: arrays are objects
+ * in JS but a distinct type in JSON Schema, and JSON has no integer type —
+ * `integer` is a *number* with a constraint, so `3` satisfies both `number`
+ * and `integer` while `3.5` satisfies only `number`.
+ */
+function jsonTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    switch (typeof value) {
+        case 'string': return 'string';
+        case 'boolean': return 'boolean';
+        case 'number': return Number.isInteger(value) ? 'integer' : 'number';
+        case 'object': return 'object';
+        default: return undefined;
+    }
+}
+function matchesDeclaredType(declared, actual) {
+    if (declared === actual)
+        return true;
+    // Every integer is a valid number; the reverse is not true.
+    if (declared === 'number' && actual === 'integer')
+        return true;
+    return false;
+}
+/**
+ * Check present arguments against the `type` each property declares in the
+ * tool's inputSchema and WARN on a mismatch — deliberately non-fatal for now.
+ *
+ * `required` is already hard-enforced above; `type` is not, because nothing
+ * ever checked it, so a tool declaring `{type: 'string'}` has always been free
+ * to receive a number and reach its handler. Turning that into a throw without
+ * knowing how many real callers violate their own schemas would break working
+ * code, so this logs first: run the suite, count the warnings, then decide.
+ *
+ * Absent properties are ignored — that is `required`'s job, not this one's.
+ * Explicit null is also ignored here for the same reason (the required check
+ * already rejects it for required params, and an optional param set to null is
+ * an "unset" idiom, not a type error).
+ */
+function warnOnTypeMismatch(toolName, schema, input) {
+    const properties = schema?.properties;
+    if (!properties || typeof properties !== 'object')
+        return;
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null)
+            continue;
+        const prop = properties[key];
+        if (!prop || typeof prop !== 'object')
+            continue;
+        const declared = prop.type;
+        // Union types (`type: ['string','number']`) pass if any branch matches.
+        const declaredList = typeof declared === 'string'
+            ? [declared]
+            : Array.isArray(declared) && declared.every(t => typeof t === 'string')
+                ? declared
+                : undefined;
+        if (!declaredList || declaredList.length === 0)
+            continue;
+        const actual = jsonTypeOf(value);
+        if (!actual)
+            continue;
+        if (declaredList.some(d => matchesDeclaredType(d, actual)))
+            continue;
+        // Report `integer` as `number` — the distinction is an artefact of how we
+        // classify JS numbers, not something the caller passed.
+        const reported = actual === 'integer' ? 'number' : actual;
+        console.error(`[mcp] tool '${toolName}' param '${key}': schema declares ` +
+            `${declaredList.join('|')}, got ${reported}`);
+    }
+}
 /**
  * Call an MCP tool by name with input parameters
  */
@@ -124,6 +201,25 @@ export async function callMCPTool(toolName, input = {}, context) {
     if (isToolDisabled(toolName)) {
         throw new MCPClientError(`MCP tool '${toolName}' is disabled. Re-enable with: mcp toggle --enable ${toolName}`, toolName);
     }
+    // Enforce the `required` contract each tool advertises in its inputSchema.
+    // 120 of the ~254 tools declare required params, but nothing used to check
+    // them: handlers were invoked with whatever arrived, so a missing argument
+    // surfaced as whatever the handler happened to hit first — e.g.
+    // `monograph_agent_record` leaked a raw `SqliteError: NOT NULL constraint
+    // failed: agent_interactions.session_id` instead of naming the parameter.
+    // This is the single choke point for both the stdio server and the
+    // in-process CLI path, so validating here covers every tool at once.
+    //
+    // Only missing/undefined/null is rejected — empty strings and 0 are left
+    // alone, since some tools legitimately accept them.
+    const required = tool.inputSchema?.required;
+    if (Array.isArray(required) && required.length > 0) {
+        const missing = required.filter(key => input[key] === undefined || input[key] === null);
+        if (missing.length > 0) {
+            throw new MCPClientError(`MCP tool '${toolName}' missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`, toolName);
+        }
+    }
+    warnOnTypeMismatch(toolName, tool.inputSchema, input);
     try {
         const result = await tool.handler(input, context);
         return result;

package/packages/@monomind/cli/dist/src/mcp-tools/agent-tools.js

@@ -353,11 +353,14 @@ export const agentTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['status', 'scale', 'drain'], description: 'Pool action' },
+                action: { type: 'string', enum: ['status', 'scale', 'drain'], description: 'Pool action (default: status)' },
                 targetSize: { type: 'number', description: 'Target pool size (for scale action)' },
                 agentType: { type: 'string', description: 'Agent type filter' },
             },
-            required: ['action'],
+            // `action` is deliberately NOT required: the handler defaults it to
+            // 'status', and the CLI `agent pool` command relies on that default.
+            // It was previously declared required, which nothing enforced — once
+            // required params became enforced, that false contract broke the CLI.
         },
         handler: async (input) => {
             const action = input.action || 'status'; // Default to status

package/packages/@monomind/cli/dist/src/mcp-tools/autopilot-tools.js

@@ -147,7 +147,7 @@ const autopilotProgress = {
 };
 const autopilotLearn = {
     name: 'autopilot_learn',
-    description: 'Discover success patterns from past task completions. Requires memory backend for full functionality.',
+    description: 'Report success patterns from the optional agentic-flow learning module. That module is not a declared dependency and is absent in normal installs, so this returns available:false with an empty pattern list — no pattern discovery occurs.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -197,7 +197,7 @@ const autopilotHistory = {
 };
 const autopilotPredict = {
     name: 'autopilot_predict',
-    description: 'Predict the optimal next action based on current state and learned patterns.',
+    description: 'Suggest the next action by returning the first incomplete discovered task with a fixed 0.5 confidence — a heuristic over local task files, not ML prediction. The optional agentic-flow learning module that would refine this is not a declared dependency and is absent in normal installs.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {

package/packages/@monomind/cli/dist/src/mcp-tools/embeddings-tools.js

@@ -484,7 +484,7 @@ export const allEmbeddingsTools = [
     },
     {
         name: 'embeddings_neural',
-        description: 'Embedding substrate operations (drift, memory physics, coherence)',
+        description: 'Report and adjust pattern-store statistics (drift, consolidate, adapt) from intelligence.ts. Reads real counters — but its "init" action only persists a config blob (sona, flashAttention, ewcPlusPlus, memoryPhysics, swarmCoordination…) for which no implementing code exists anywhere; those flags are stored and echoed back, never acted on. There is no neural substrate and no "memory physics".',
         category: 'embeddings',
         inputSchema: {
             type: 'object',
@@ -502,7 +502,7 @@ export const allEmbeddingsTools = [
                 },
                 decayRate: {
                     type: 'number',
-                    description: 'Memory decay rate (hippocampal dynamics)',
+                    description: 'Decay rate applied to stored pattern confidence (plain exponential decay — the "hippocampal dynamics" framing this once carried described nothing in the code)',
                     default: 0.01,
                 },
             },

package/packages/@monomind/cli/dist/src/mcp-tools/guidance-tools.js

@@ -70,7 +70,7 @@ const CAPABILITY_CATALOG = {
         description: 'Multi-agent coordination with topology-aware communication and consensus.',
         tools: ['swarm_init', 'swarm_status', 'swarm_spawn', 'swarm_terminate', 'swarm_topology', 'swarm_metrics'],
         commands: ['swarm init', 'swarm status', 'swarm spawn', 'swarm terminate'],
-        agents: ['mesh-coordinator', 'queen-coordinator', 'collective-intelligence-coordinator'],
+        agents: ['coordinator', 'mesh-coordinator', 'collective-intelligence-coordinator'],
         skills: ['swarm-orchestration', 'swarm-advanced', 'monomind-swarm'],
         whenToUse: 'When a task requires multiple agents working together (3+ files, features, refactoring).',
     },

package/packages/@monomind/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -204,7 +204,7 @@ function saveAgentStore(store) {
 export const allHiveMindTools = [
     {
         name: 'hive-mind_spawn',
-        description: 'Spawn workers and automatically join them to the hive-mind (combines agent/spawn + hive-mind/join)',
+        description: 'Write worker agent records into the agent store and register their ids on the hive state file (combines agent_spawn + hive-mind_join). Creates bookkeeping entries only — no process, thread, or agent is started. Real concurrency comes from Claude Code\'s Task tool.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -285,7 +285,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_init',
-        description: 'Initialize the hive-mind collective',
+        description: 'Create the hive state file recording topology, consensus strategy, and an empty worker list. Writes JSON state only — nothing is started, and no collective process exists. Note "gossip" and "crdt" strategies are rejected: they are not implemented.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -932,7 +932,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_broadcast',
-        description: 'Broadcast message to all workers',
+        description: 'Append a message to a shared array on the hive state file (capped at 100 entries). This is a noticeboard, not message delivery — there are no live listeners, and a worker only sees it if something later reads that state. The reported recipient count is just the number of ids in the worker list.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -1055,7 +1055,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_memory',
-        description: 'Access hive shared memory',
+        description: 'Read or write a shared JSON blob on the hive state file. Plain key/value bookkeeping in a single local file — not a distributed or replicated store.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',

package/packages/@monomind/cli/dist/src/mcp-tools/hooks-intelligence.js

@@ -671,7 +671,7 @@ export const hooksIntelligenceStats = {
 // Intelligence learn hook
 export const hooksIntelligenceLearn = {
     name: 'hooks_intelligence_learn',
-    description: 'Force immediate SONA learning cycle with EWC++ consolidation',
+    description: 'Run a consolidation pass over the local keyword-pattern store: time-decay confidence weighting, pruning, and an EWC++-style quadratic penalty derived from squared embedding magnitudes. There are no gradients and no model — no ML training occurs.',
     inputSchema: {
         type: 'object',
         properties: {

package/packages/@monomind/cli/dist/src/mcp-tools/hooks-routing.js

@@ -980,7 +980,7 @@ export const hooksExplain = {
 // Pretrain hook - repository analysis for intelligence bootstrap
 export const hooksPretrain = {
     name: 'hooks_pretrain',
-    description: 'Analyze repository to bootstrap intelligence (4-step pipeline)',
+    description: 'Walk the repository counting file extensions and directory patterns to seed the keyword router. This is a filesystem scan writing JSON state — despite the name, no model is trained.',
     inputSchema: {
         type: 'object',
         properties: {