monomind 2.7.6 → 2.7.8

package/packages/@monomind/cli/dist/src/init/executor.js

@@ -410,17 +410,37 @@ try { await buildAsync(${JSON.stringify(targetDir)}); } finally {
  * Non-fatal: best-effort health check and auto-install.
  */
 async function runDoctorFix(targetDir, result) {
+    // Run the doctor THIS binary ships, in-process.
+    //
+    // This used to be `execSync('npx monomind@latest doctor --install')`, which
+    // was wrong in three ways at once: it downloaded and ran a DIFFERENT version
+    // than the one the user deliberately invoked (so `monomind@2.7.0 init` was
+    // finished by whatever `latest` happened to be), it silently required network
+    // — on a machine without it, the 120s timeout elapsed and init reported
+    // "skipped" with no explanation — and `stdio: 'ignore'` discarded everything
+    // it said, so a failed health check looked identical to a passing one.
     try {
-        const { execSync } = await import('child_process');
-        execSync('npx monomind@latest doctor --install', {
+        const { doctorCommand } = await import('../commands/doctor.js');
+        if (!doctorCommand.action) {
+            result.skipped.push('doctor: auto-fix unavailable (run: monomind doctor --install)');
+            return;
+        }
+        const res = await doctorCommand.action({
+            args: [],
+            flags: { install: true },
             cwd: targetDir,
-            stdio: 'ignore',
-            timeout: 120000,
         });
-        result.created.files.push('doctor --install (health check + auto-fix)');
+        // Report what actually happened rather than asserting success either way.
+        if (res && res.success === false) {
+            result.skipped.push('doctor: reported issues (run: monomind doctor for details)');
+        }
+        else {
+            result.created.files.push('doctor --install (health check + auto-fix)');
+        }
     }
-    catch {
-        result.skipped.push('doctor: auto-fix skipped (run: monomind doctor --install)');
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        result.skipped.push(`doctor: auto-fix failed (${detail}) — run: monomind doctor --install`);
     }
 }
 /**
@@ -953,6 +973,73 @@ async function writeMCPConfig(targetDir, options, result) {
     atomicWriteFile(mcpPath, content);
     result.created.files.push('.mcp.json');
 }
+/**
+ * Provenance manifest for generated .claude content.
+ *
+ * init used to "clean stale" entries by deleting every name under
+ * .claude/{skills,commands,agents} that was absent from the current version's
+ * SKILLS_MAP/COMMANDS_MAP/AGENTS_MAP. Every user-authored command and skill is
+ * absent from those maps, so that pass deleted user content on the very first
+ * run — unrecoverable data loss.
+ *
+ * The manifest records exactly which entries *this tool* wrote, so the stale
+ * sweep can be restricted to those. Anything init did not write is never
+ * removed. Projects initialised by an older version have no manifest, so their
+ * first run under the fix deletes nothing and seeds the manifest instead;
+ * stale generated content may survive one extra run, which is the correct
+ * trade (preserving stale generated content is recoverable, deleting user
+ * content is not).
+ */
+const INIT_MANIFEST_REL = path.join('.monomind', 'init-manifest.json');
+/**
+ * Read the provenance manifest. Returns null when absent or unreadable —
+ * callers must treat that as "provenance unknown", i.e. delete nothing.
+ */
+function readInitManifest(targetDir) {
+    const manifestPath = path.join(targetDir, INIT_MANIFEST_REL);
+    try {
+        if (!fs.existsSync(manifestPath))
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return {
+            version: typeof parsed.version === 'number' ? parsed.version : 1,
+            skills: Array.isArray(parsed.skills) ? parsed.skills.filter((s) => typeof s === 'string') : [],
+            commands: Array.isArray(parsed.commands) ? parsed.commands.filter((s) => typeof s === 'string') : [],
+            agents: Array.isArray(parsed.agents) ? parsed.agents.filter((s) => typeof s === 'string') : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Names init previously generated in one section. Empty set when no manifest
+ * exists — which makes the stale sweep a no-op rather than a delete-everything.
+ */
+function previouslyGenerated(targetDir, section) {
+    return new Set(readInitManifest(targetDir)?.[section] ?? []);
+}
+/**
+ * Record the entries init just wrote for one section, merging into any
+ * existing manifest so a partial run (e.g. --only-claude, or a section whose
+ * source dir was missing) never drops provenance for the other sections.
+ */
+function recordGenerated(targetDir, section, entries) {
+    const manifestPath = path.join(targetDir, INIT_MANIFEST_REL);
+    const existing = readInitManifest(targetDir);
+    const manifest = existing ?? { version: 1, skills: [], commands: [], agents: [] };
+    manifest.version = 1;
+    manifest[section] = [...new Set(entries)].sort();
+    try {
+        fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+        atomicWriteFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    }
+    catch {
+        // Non-fatal: without a manifest the next run simply deletes nothing.
+    }
+}
 /**
  * Copy skills from source
  */
@@ -992,11 +1079,14 @@ async function copySkills(targetDir, options, result) {
         skillsToCopy.push(...fs.readdirSync(sourceSkillsDir).filter(n => n.startsWith(prefix) &&
             fs.existsSync(path.join(sourceSkillsDir, n, 'SKILL.md'))));
     }
-    // Remove stale skill directories no longer in the current version's map
+    // Remove stale skill directories that a PREVIOUS init generated and this
+    // version no longer ships. Entries init never wrote (user-authored skills,
+    // skills installed by other tools) are left untouched — see readInitManifest.
     const knownSkills = new Set([...new Set(skillsToCopy)]);
+    const priorSkills = previouslyGenerated(targetDir, 'skills');
     if (fs.existsSync(targetSkillsDir)) {
         for (const existing of fs.readdirSync(targetSkillsDir)) {
-            if (!knownSkills.has(existing)) {
+            if (!knownSkills.has(existing) && priorSkills.has(existing)) {
                 const stalePath = path.join(targetSkillsDir, existing);
                 fs.rmSync(stalePath, { recursive: true, force: true });
                 result.created.files.push(`[cleaned] .claude/skills/${existing} (stale)`);
@@ -1004,14 +1094,19 @@ async function copySkills(targetDir, options, result) {
         }
     }
     // Always copy/overwrite skills (never skip — ensures new version content lands)
+    const writtenSkills = [];
     for (const skillName of knownSkills) {
         const sourcePath = path.join(sourceSkillsDir, skillName);
         const targetPath = path.join(targetSkillsDir, skillName);
         if (fs.existsSync(sourcePath)) {
-            if (fs.existsSync(targetPath)) {
-                fs.rmSync(targetPath, { recursive: true, force: true });
-            }
+            // Deliberately NOT rmSync'd first. copyDirRecursive overwrites every
+            // file it ships, so wiping the directory adds nothing except destroying
+            // anything the user put inside it — notes beside a shipped skill, an
+            // extra command in a shipped folder. `init --force` did exactly that.
+            // The cost of not wiping is that a file removed from a newer version
+            // lingers; the cost of wiping is silent data loss, which is worse.
             copyDirRecursive(sourcePath, targetPath);
+            writtenSkills.push(skillName);
             result.created.files.push(`.claude/skills/${skillName}`);
             result.summary.skillsCount++;
         }
@@ -1022,6 +1117,12 @@ async function copySkills(targetDir, options, result) {
             result.errors.push(`Skill '${skillName}' listed in SKILLS_MAP has no source directory at ${sourcePath} — skipped`);
         }
     }
+    // Record provenance so the next run can distinguish "we wrote this" from
+    // "the user wrote this". Keep entries this run did not re-write but that a
+    // previous run generated and that still exist, so provenance is not lost
+    // when a section is partially skipped.
+    const retainedSkills = [...priorSkills].filter(n => !writtenSkills.includes(n) && fs.existsSync(path.join(targetSkillsDir, n)));
+    recordGenerated(targetDir, 'skills', [...writtenSkills, ...retainedSkills]);
 }
 /**
  * Copy commands from source
@@ -1084,11 +1185,13 @@ async function copyCommands(targetDir, options, result) {
         result.errors.push('Could not find source commands directory');
         return;
     }
-    // Remove stale command files/directories no longer in the current version's map
+    // Remove stale command files/directories that a PREVIOUS init generated and
+    // this version no longer ships. User-authored commands are never touched.
     const knownCommands = new Set([...new Set(commandsToCopy)]);
+    const priorCommands = previouslyGenerated(targetDir, 'commands');
     if (fs.existsSync(targetCommandsDir)) {
         for (const existing of fs.readdirSync(targetCommandsDir)) {
-            if (!knownCommands.has(existing)) {
+            if (!knownCommands.has(existing) && priorCommands.has(existing)) {
                 const stalePath = path.join(targetCommandsDir, existing);
                 fs.rmSync(stalePath, { recursive: true, force: true });
                 result.created.files.push(`[cleaned] .claude/commands/${existing} (stale)`);
@@ -1096,23 +1199,27 @@ async function copyCommands(targetDir, options, result) {
         }
     }
     // Always copy/overwrite commands (never skip — ensures new version content lands)
+    const writtenCommands = [];
     for (const cmdName of knownCommands) {
         const sourcePath = path.join(sourceCommandsDir, cmdName);
         const targetPath = path.join(targetCommandsDir, cmdName);
         if (fs.existsSync(sourcePath)) {
-            if (fs.existsSync(targetPath)) {
-                fs.rmSync(targetPath, { recursive: true, force: true });
-            }
+            // No pre-copy rmSync — see the note in copySkills. Both branches below
+            // overwrite what they ship, so wiping first only destroys files the user
+            // added inside a shipped command directory.
             if (fs.statSync(sourcePath).isDirectory()) {
                 copyDirRecursive(sourcePath, targetPath);
             }
             else {
                 fs.copyFileSync(sourcePath, targetPath);
             }
+            writtenCommands.push(cmdName);
             result.created.files.push(`.claude/commands/${cmdName}`);
             result.summary.commandsCount++;
         }
     }
+    const retainedCommands = [...priorCommands].filter(n => !writtenCommands.includes(n) && fs.existsSync(path.join(targetCommandsDir, n)));
+    recordGenerated(targetDir, 'commands', [...writtenCommands, ...retainedCommands]);
 }
 /**
  * Copy agents from source
@@ -1147,11 +1254,13 @@ async function copyAgents(targetDir, options, result) {
         result.errors.push('Could not find source agents directory');
         return;
     }
-    // Remove stale agent category directories no longer in the current version's map
+    // Remove stale agent category directories that a PREVIOUS init generated and
+    // this version no longer ships. User-authored agent dirs are never touched.
     const knownAgents = new Set([...new Set(agentsToCopy)]);
+    const priorAgents = previouslyGenerated(targetDir, 'agents');
     if (fs.existsSync(targetAgentsDir)) {
         for (const existing of fs.readdirSync(targetAgentsDir)) {
-            if (!knownAgents.has(existing)) {
+            if (!knownAgents.has(existing) && priorAgents.has(existing)) {
                 const stalePath = path.join(targetAgentsDir, existing);
                 fs.rmSync(stalePath, { recursive: true, force: true });
                 result.created.files.push(`[cleaned] .claude/agents/${existing} (stale)`);
@@ -1159,20 +1268,27 @@ async function copyAgents(targetDir, options, result) {
         }
     }
     // Always copy/overwrite agents (never skip — ensures new version content lands)
+    const writtenAgents = [];
     for (const agentCategory of knownAgents) {
         const sourcePath = path.join(sourceAgentsDir, agentCategory);
         const targetPath = path.join(targetAgentsDir, agentCategory);
         if (fs.existsSync(sourcePath)) {
-            if (fs.existsSync(targetPath)) {
-                fs.rmSync(targetPath, { recursive: true, force: true });
-            }
+            // Deliberately NOT rmSync'd first. copyDirRecursive overwrites every
+            // file it ships, so wiping the directory adds nothing except destroying
+            // anything the user put inside it — notes beside a shipped skill, an
+            // extra command in a shipped folder. `init --force` did exactly that.
+            // The cost of not wiping is that a file removed from a newer version
+            // lingers; the cost of wiping is silent data loss, which is worse.
             copyDirRecursive(sourcePath, targetPath);
             // Count agent files (.md only — .yaml agents were migrated to .md)
             const mdFiles = countFiles(sourcePath, '.md');
             result.summary.agentsCount += mdFiles;
+            writtenAgents.push(agentCategory);
             result.created.files.push(`.claude/agents/${agentCategory}`);
         }
     }
+    const retainedAgents = [...priorAgents].filter(n => !writtenAgents.includes(n) && fs.existsSync(path.join(targetAgentsDir, n)));
+    recordGenerated(targetDir, 'agents', [...writtenAgents, ...retainedAgents]);
 }
 /**
  * Find source helpers directory.

package/packages/@monomind/cli/dist/src/init/settings-generator.js

@@ -226,7 +226,10 @@ function generateHooksConfig(config, graphify = true) {
                 ],
             },
             {
-                matcher: 'Write|Edit|MultiEdit',
+                // NotebookEdit is listed explicitly: its content field (`new_source`)
+                // is scanned by the same secrets gate as Write/Edit/MultiEdit, so it
+                // must not depend on `Edit` happening to substring-match.
+                matcher: 'Write|Edit|MultiEdit|NotebookEdit',
                 hooks: [
                     {
                         // Was 'pre-edit' — not a registered hook-handler.cjs dispatch

package/packages/@monomind/cli/dist/src/knowledge/document-pipeline.d.ts

@@ -26,6 +26,10 @@ export interface KnowledgeExcerpt {
     similarity: number;
     chunkIndex: number;
     scope: string;
+    /** True when this chunk belongs to a document version that has since been
+     *  re-ingested (its contentHash is no longer the file's current one). Only
+     *  ever set when the caller opted into `includeSuperseded`. */
+    superseded?: boolean;
 }
 export interface DocumentMeta {
     filePath: string;
@@ -40,6 +44,16 @@ export declare function ingestDirectory(dirPath: string, scope?: string, opts?:
     rootDir?: string;
     onProgress?: (file: string, done: number, total: number) => void;
 }): Promise<BatchIngestResult>;
+/** Content hashes of the documents currently indexed under `rootDir`. */
+export declare function liveContentHashes(rootDir: string): Set<string>;
+/**
+ * True when `key` is a document chunk whose version is no longer current.
+ * Non-`doc:` keys are never superseded, and an empty `live` set means the
+ * metadata log is missing/unreadable — in that case nothing is filtered,
+ * because "no metadata" must not read as "everything is stale".
+ */
+export declare function isSupersededKey(key: string, live: Set<string>): boolean;
+export declare function supersededOverfetchLimit(limit: number, live: Set<string>): number;
 export declare function searchKnowledge(query: string, opts?: {
     scope?: string;
     limit?: number;
@@ -47,6 +61,9 @@ export declare function searchKnowledge(query: string, opts?: {
     rootDir?: string;
     /** which store(s): project-only, global-only, or both (default). */
     store?: 'project' | 'global' | 'all';
+    /** Return chunks from superseded document versions too, flagged
+     *  `superseded: true`. Default false — see the note above `liveContentHashes`. */
+    includeSuperseded?: boolean;
 }): Promise<KnowledgeExcerpt[]>;
 export declare function listDocuments(rootDir?: string, scope?: string): DocumentMeta[];
 export declare function removeDocument(filePath: string, scope?: string, rootDir?: string): Promise<void>;

package/packages/@monomind/cli/dist/src/knowledge/document-pipeline.js

@@ -358,6 +358,52 @@ export async function ingestDirectory(dirPath, scope = 'shared', opts) {
 /** Small additive boost so project knowledge wins ties against the global
  *  brain — local context is more likely to be what the user means. */
 const PROJECT_SCOPE_BOOST = 0.05;
+// ── Superseded-version filtering ───────────────────────────────────
+//
+// Chunk keys are `doc:<contentHash>:<chunkIndex>`. Re-ingesting a changed file
+// produces a NEW contentHash, so its chunks land under new keys — the previous
+// version's rows are never touched (`removeDocument` only tombstones metadata;
+// the bridge exposes no delete-by-prefix). The store therefore accumulates every
+// version a document has ever had, and all of them stay searchable.
+//
+// Measured on this repo's own store (2026-07-26): 9,067 `doc:`-keyed rows in
+// `knowledge:shared` spanning 798 distinct content hashes, of which only 139
+// are current — 8,542 rows (94.2%) are orphaned older versions.
+//
+// Nothing is deleted here. The current-hash set from doc-metadata.jsonl is used
+// to decide what search RETURNS; `includeSuperseded` puts the old versions back
+// (flagged `superseded: true`) for anyone who wants document history.
+/** Content hashes of the documents currently indexed under `rootDir`. */
+export function liveContentHashes(rootDir) {
+    const live = new Set();
+    for (const m of readMetadata(rootDir))
+        if (m.contentHash)
+            live.add(m.contentHash);
+    return live;
+}
+/**
+ * True when `key` is a document chunk whose version is no longer current.
+ * Non-`doc:` keys are never superseded, and an empty `live` set means the
+ * metadata log is missing/unreadable — in that case nothing is filtered,
+ * because "no metadata" must not read as "everything is stale".
+ */
+export function isSupersededKey(key, live) {
+    if (!key || !key.startsWith('doc:'))
+        return false;
+    if (live.size === 0)
+        return false;
+    return !live.has(key.split(':')[1] ?? '');
+}
+/** How many rows to ask the backend for per requested result when superseded
+ *  filtering is active — most rows in a long-lived store are old versions, so
+ *  a 1:1 fetch would return an almost-empty page. */
+const SUPERSEDED_OVERFETCH = 20;
+const SUPERSEDED_OVERFETCH_CAP = 300;
+export function supersededOverfetchLimit(limit, live) {
+    if (live.size === 0)
+        return limit;
+    return Math.min(Math.max(limit * SUPERSEDED_OVERFETCH, limit), SUPERSEDED_OVERFETCH_CAP);
+}
 export async function searchKnowledge(query, opts) {
     const bridge = await getBridge();
     if (!bridge)
@@ -373,17 +419,28 @@ export async function searchKnowledge(query, opts) {
     if (store !== 'project') {
         targets.push({ ns: namespace('global'), dbPath: GLOBAL_BRAIN_SENTINEL, root: globalBrainRoot(), label: 'global', boost: 0 });
     }
+    const includeSuperseded = opts?.includeSuperseded === true;
     const perTarget = await Promise.all(targets.map(async (t) => {
+        const meta = readMetadata(t.root);
+        const live = new Set();
+        for (const m of meta)
+            if (m.contentHash)
+                live.add(m.contentHash);
+        // Old versions dominate a long-lived store, so a 1:1 fetch would come back
+        // nearly empty once they are filtered out. Over-fetch, then trim.
+        const fetchLimit = includeSuperseded ? limit : supersededOverfetchLimit(limit, live);
         const result = await bridge.bridgeSearchEntries({
-            query, namespace: t.ns, limit, threshold: minScore, dbPath: t.dbPath,
+            query, namespace: t.ns, limit: fetchLimit, threshold: minScore, dbPath: t.dbPath,
         }).catch(() => null);
         if (!result?.success || !result.results.length)
             return [];
-        const meta = readMetadata(t.root);
         const hashToFile = new Map();
         for (const m of meta)
             hashToFile.set(m.contentHash, m.filePath);
-        return result.results.map((r) => {
+        const kept = includeSuperseded
+            ? result.results
+            : result.results.filter((r) => !isSupersededKey(String(r.key ?? ''), live));
+        return kept.slice(0, limit).map((r) => {
             const parts = r.key.startsWith('doc:') ? r.key.split(':') : [];
             const hash = parts[1] ?? '';
             const idx = parseInt(parts[2] ?? '0', 10);
@@ -391,6 +448,7 @@ export async function searchKnowledge(query, opts) {
             // hash→file map can misattribute when two documents share identical
             // content, and goes empty when a re-ingested file's hash changed.
             const srcTag = (r.tags ?? []).find((tag) => tag.startsWith('src:'));
+            const superseded = includeSuperseded && isSupersededKey(String(r.key ?? ''), live);
             return {
                 id: r.id,
                 filePath: srcTag ? srcTag.slice(4) : hashToFile.get(hash) ?? '',
@@ -398,6 +456,7 @@ export async function searchKnowledge(query, opts) {
                 similarity: r.score + t.boost,
                 chunkIndex: isNaN(idx) ? 0 : idx,
                 scope: t.label,
+                ...(superseded ? { superseded: true } : {}),
             };
         });
     }));

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
  */
@@ -142,6 +219,7 @@ export async function callMCPTool(toolName, input = {}, context) {
             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/embeddings-tools.js

@@ -544,9 +544,13 @@ export const allEmbeddingsTools = [
                         message: 'Embedding substrate initialized',
                     };
                 case 'drift':
-                    // Get real drift metrics if available
+                    // Get real drift metrics if available.
+                    // initializeIntelligence() MUST run first: getIntelligenceStats()
+                    // reads module singletons (sonaCoordinator / reasoningBank) that are
+                    // null until init, so a populated store otherwise reports 0 patterns.
                     try {
-                        const { getIntelligenceStats } = await import('../memory/intelligence.js');
+                        const { getIntelligenceStats, initializeIntelligence } = await import('../memory/intelligence.js');
+                        await initializeIntelligence();
                         const stats = getIntelligenceStats();
                         return {
                             success: true,
@@ -564,17 +568,20 @@ export const allEmbeddingsTools = [
                                 : 'No patterns stored yet - drift detection inactive',
                         };
                     }
-                    catch {
+                    catch (e) {
+                        // Failing to read the store is NOT a drift report of zero.
                         return {
-                            success: true,
+                            success: false,
                             action: 'drift',
+                            error: `Intelligence store unavailable — drift status unknown: ${e.message}`,
                             status: { semanticDrift: { enabled: false, reason: 'Intelligence module unavailable' } },
                         };
                     }
                 case 'consolidate':
-                    // Get real consolidation metrics
+                    // Get real consolidation metrics — same init requirement as 'drift'.
                     try {
-                        const { getIntelligenceStats } = await import('../memory/intelligence.js');
+                        const { getIntelligenceStats, initializeIntelligence } = await import('../memory/intelligence.js');
+                        await initializeIntelligence();
                         const stats = getIntelligenceStats();
                         return {
                             success: true,
@@ -590,10 +597,11 @@ export const allEmbeddingsTools = [
                             message: `ReasoningBank: ${stats.reasoningBankSize} patterns, ${stats.trajectoriesRecorded} trajectories`,
                         };
                     }
-                    catch {
+                    catch (e) {
                         return {
-                            success: true,
+                            success: false,
                             action: 'consolidate',
+                            error: `Intelligence store unavailable — consolidation status unknown: ${e.message}`,
                             status: { memoryPhysics: { enabled: false, reason: 'Intelligence module unavailable' } },
                         };
                     }

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

@@ -82,36 +82,50 @@ const knowledgeSearch = {
             limit: { type: 'number', description: 'Max results (default: 10)' },
             minScore: { type: 'number', description: 'Minimum similarity threshold (default: 0.3)' },
             surfaces: { type: 'array', items: { type: 'string' }, description: "Override routing: any of 'chunks','kg','rules','memory'" },
+            includeSuperseded: { type: 'boolean', description: 'Also return chunks from older, re-ingested versions of a document (flagged superseded). Default false.' },
         },
         required: ['query'],
     },
     handler: async (input) => {
         const { searchKnowledge } = await import('../knowledge/document-pipeline.js');
-        const { routeQuery, rrfFuse } = await import('../memory/query-router.js');
+        const { routeQuery, rrfFuse, recordRouteOverride } = await import('../memory/query-router.js');
         try {
             const query = String(input.query);
             const limit = input.limit ? Number(input.limit) : 10;
             const route = routeQuery(query);
-            const surfaces = Array.isArray(input.surfaces) && input.surfaces.length
+            const explicitSurfaces = Array.isArray(input.surfaces) && input.surfaces.length
                 ? input.surfaces
-                : (route.confident ? route.surfaces : ['chunks', ...route.surfaces.filter(s => s !== 'chunks')]);
+                : null;
+            const surfaces = explicitSurfaces
+                ?? (route.confident ? route.surfaces : ['chunks', ...route.surfaces.filter(s => s !== 'chunks')]);
+            const chunkOpts = {
+                scope: input.scope ? String(input.scope) : undefined,
+                limit,
+                minScore: input.minScore ? Number(input.minScore) : undefined,
+                includeSuperseded: input.includeSuperseded === true,
+            };
             const bridge = await import('../memory/memory-bridge.js');
             const kg = await import('../memory/memory-kg.js');
             const [excerpts, graph, rules, memories] = await Promise.all([
-                surfaces.includes('chunks')
-                    ? searchKnowledge(query, {
-                        scope: input.scope ? String(input.scope) : undefined,
-                        limit,
-                        minScore: input.minScore ? Number(input.minScore) : undefined,
-                    })
-                    : [],
+                surfaces.includes('chunks') ? searchKnowledge(query, chunkOpts) : [],
                 surfaces.includes('kg') ? kg.kgSearch({ query, limit: 6 }) : null,
                 surfaces.includes('rules') ? bridge.bridgeSearchEntries({ query, namespace: 'rules', limit: 3, threshold: 0.35 }) : null,
                 surfaces.includes('memory') ? bridge.bridgeSearchEntries({ query, namespace: 'patterns', limit: 3 }) : null,
             ]);
+            // Confident non-chunk routing against an empty surface (e.g. a project
+            // with no KG yet) must not read as "no knowledge" — fall back to chunks.
+            // Same rule the CLI `doc search` path applies; without it agents got
+            // "no results" where the CLI returned document excerpts.
+            let fellBack = false;
+            let chunkExcerpts = excerpts;
+            if (!explicitSurfaces && !chunkExcerpts.length && !(graph?.triplets?.length) && !(rules?.results?.length) && !(memories?.results?.length) && !surfaces.includes('chunks')) {
+                fellBack = true;
+                recordRouteOverride(surfaces[0], 'chunks');
+                chunkExcerpts = await searchKnowledge(query, chunkOpts);
+            }
             // Rank-fuse heterogeneous lists (raw scores aren't comparable).
             const fused = rrfFuse([
-                excerpts.map(e => ({ id: e.id || `${e.filePath}#${e.chunkIndex}`, kind: 'excerpt', ...e })),
+                chunkExcerpts.map(e => ({ id: e.id || `${e.filePath}#${e.chunkIndex}`, kind: 'excerpt', ...e })),
                 (graph?.triplets ?? []).map((t, i) => ({ id: `kg:${i}:${t.source}|${t.relation}|${t.target}`, kind: 'triplet', ...t })),
                 (rules?.results ?? []).map(r => ({ id: r.id, kind: 'rule', key: r.key, text: r.content, importance: 0.7 })),
                 (memories?.results ?? []).map(r => ({ id: r.id, kind: 'memory', key: r.key, text: r.content })),
@@ -122,10 +136,10 @@ const knowledgeSearch = {
                         text: JSON.stringify({
                             success: true,
                             count: fused.length,
-                            routing: { surfaces, confident: route.confident },
+                            routing: { surfaces, confident: route.confident, fellBackToChunks: fellBack },
                             results: fused,
                             // Back-compat: excerpt-only view for existing consumers.
-                            excerpts,
+                            excerpts: chunkExcerpts,
                         }),
                     }],
             };

package/packages/@monomind/cli/dist/src/memory/memory-bridge.d.ts

@@ -63,7 +63,11 @@ export declare function bridgeSearchEntries(options: {
         tags?: string[];
     }[];
     searchTime: number;
-    searchMethod?: string;
+    /** What actually ran, never what was requested. 'keyword-fallback' means the
+     *  vector path was attempted and did not produce the results. */
+    searchMethod?: 'semantic' | 'keyword' | 'keyword-fallback';
+    /** Why the vector path did not serve these results (absent when it did). */
+    fallbackReason?: 'no-embedding-model' | 'empty-query' | 'embedding-failed' | 'no-semantic-matches';
     error?: string;
 } | null>;
 export declare function bridgeListEntries(options: {