monomind 2.5.1 → 2.5.2

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/pin.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// Pattern adapted from impeccable (Apache-2.0) — rebranded for monomind
+/**
+ * Pin/unpin sub-commands as standalone skill shortcuts.
+ *
+ * Usage:
+ *   node <scripts_path>/pin.mjs pin <command>
+ *   node <scripts_path>/pin.mjs unpin <command>
+ *
+ * `pin audit` creates a lightweight audit skill that redirects to Monodesign's audit workflow.
+ * `unpin audit` removes that shortcut.
+ *
+ * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
+ * in the project root and creates/removes the pin in all of them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
+import { basename, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// All known harness directories
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+const CODEX_HARNESSES = new Set(['.codex', '.agents']);
+
+// Valid sub-command names
+const VALID_COMMANDS = [
+  'craft', 'init', 'extract', 'document', 'shape',
+  'critique', 'audit',
+  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
+  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
+  'clarify', 'adapt', 'optimize',
+];
+
+// Marker to identify pinned skills (so unpin doesn't delete user skills)
+const PIN_MARKER = '<!-- monodesign-pinned-skill -->';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an monodesign skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const skillsDir = join(projectRoot, harness, 'skills');
+    // Only pin in harness dirs that already have monodesign installed
+    const monodesignDir = join(skillsDir, 'monodesign');
+    if (existsSync(monodesignDir) || existsSync(join(skillsDir, 'i-monodesign'))) {
+      dirs.push(skillsDir);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+  const metadataPath = join(__dirname, 'command-metadata.json');
+  if (existsSync(metadataPath)) {
+    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  }
+  return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function commandPrefixForSkillsDir(skillsDir) {
+  return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
+}
+
+function generatePinnedSkill(command, metadata, commandPrefix) {
+  const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}monodesign ${command}.`;
+  const hint = metadata[command]?.argumentHint || '[target]';
+
+  return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`${commandPrefix}monodesign ${command}\`.
+
+Invoke ${commandPrefix}monodesign ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+  const metadata = loadCommandMetadata();
+  const harnessDirs = findHarnessDirs(projectRoot);
+
+  if (harnessDirs.length === 0) {
+    console.log('No harness directories with monodesign installed found.');
+    return false;
+  }
+
+  let created = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const commandPrefix = commandPrefixForSkillsDir(skillsDir);
+    const content = generatePinnedSkill(command, metadata, commandPrefix);
+    // Check if skill already exists (and isn't a pin)
+    const skillDir = join(skillsDir, command);
+    if (existsSync(skillDir)) {
+      const existingMd = join(skillDir, 'SKILL.md');
+      if (existsSync(existingMd)) {
+        const existing = readFileSync(existingMd, 'utf-8');
+        if (!existing.includes(PIN_MARKER)) {
+          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
+          continue;
+        }
+      }
+    }
+
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+    console.log(`  + ${skillDir}`);
+    created++;
+  }
+
+  if (created > 0) {
+    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+    console.log('Use the pinned command directly in each harness.');
+  }
+
+  return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+  const harnessDirs = findHarnessDirs(projectRoot);
+  let removed = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const skillDir = join(skillsDir, command);
+    if (!existsSync(skillDir)) continue;
+
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    // Safety: only remove if it's a pinned skill
+    const content = readFileSync(skillMd, 'utf-8');
+    if (!content.includes(PIN_MARKER)) {
+      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
+      continue;
+    }
+
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  - ${skillDir}`);
+    removed++;
+  }
+
+  if (removed > 0) {
+    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+    console.log(`Use Monodesign's '${command}' workflow directly to access it.`);
+  } else {
+    console.log(`No pinned '${command}' shortcut found.`);
+  }
+
+  return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+  console.log('Usage: node pin.mjs <pin|unpin> <command>');
+  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+  process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+  pin(command, root);
+} else {
+  unpin(command, root);
+}

package/packages/@monomind/cli/.claude/skills/monodesign/teach.md

@@ -1,69 +1,18 @@
 ---
 name: monodesign-teach
-description: Create or update PRODUCT.md — extract product context, users, brand voice, and design principles from the codebase, existing files, and conversation to anchor all future monodesign work.
+description: Alias of /monodesign init — set up a project for monodesign by producing PRODUCT.md (strategic context), optionally DESIGN.md (visual system), and pre-configuring live mode.
 type: design-sub-command
 argument-hint: "[project path or description]"
 user-invocable: true
 ---
 
-# Monodesign: Teach
+# Monodesign: Teach (alias of Init)
 
-Create or update `PRODUCT.md` — the required context anchor for all `/monodesign` sub-commands.
+`teach` is the historical name for the setup command and remains fully supported; it is an alias of `init`. Both invocations behave identically.
 
-`PRODUCT.md` is not a design document — it's the product context document. It answers: who uses this, what is it for, what is the brand personality, and what design anti-references should be avoided.
+Follow `commands/init.md` and the authoritative flow in `reference/init.md` from the monodesign skill directory: one codebase crawl plus a short strategic interview produces **PRODUCT.md** (register, users, purpose, brand personality, anti-references, design principles), offers **DESIGN.md** via `/monodesign document`, and pre-configures `.monodesign/live/config.json` for `/monodesign live`.
 
-## When to Run
+Notes preserved from the teach era:
 
-Run `/monodesign teach` when:
-- Starting work on a new project with no `PRODUCT.md`
-- The existing `PRODUCT.md` is empty, placeholder (<200 chars), or has `[TODO]` markers
-- The product has significantly evolved and the `PRODUCT.md` is stale
-
-## Discovery Protocol
-
-**Step 1: Gather existing signals**
-
-Read the following files if they exist:
-- `README.md` — what is this product?
-- `package.json` — name, description, keywords
-- Any landing page copy (`index.html`, `src/pages/index.astro`, etc.)
-- Existing `PRODUCT.md` (to assess completeness)
-
-If a description or tagline exists, extract: target user, core value proposition, brand personality signals.
-
-**Step 2: Ask for what's missing**
-
-Ask the user 3–5 targeted questions based on what couldn't be inferred:
-- Who specifically uses this? (Role, context, skill level)
-- What's the one thing this does better than alternatives?
-- Three words that describe the brand personality
-- What design style do you want to AVOID? (anti-references)
-- Is this a marketing surface, product UI, or both?
-
-**Step 3: Write PRODUCT.md**
-
-```markdown
-# Product
-
-## Register
-[brand | product | both]
-
-## Users
-[Specific description of who uses this — not "developers", but "senior engineers at mid-size SaaS companies who need to..."]
-
-## Product Purpose
-[What this does and why it matters to those users. One paragraph.]
-
-## Brand Personality
-[3 words + a description of the tone. Direct, specific, no hedging.]
-
-## Anti-references
-[Specific things this product should NOT look like. Brand names, aesthetics, clichés to avoid.]
-
-## Design Principles
-[3–5 opinionated principles that guide all design decisions.]
-```
-
-## After Writing
-
-Confirm with the user that the PRODUCT.md is accurate before continuing to any design work. The PRODUCT.md is the foundation — if it's wrong, everything built on it is built on the wrong foundation.
+- A legacy `.monodesign.md` at the project root is auto-renamed to `PRODUCT.md` by the context loader; mention this once and merge into that content rather than starting fresh.
+- If teach was invoked as a setup blocker by another monodesign command, complete the init flow, then resume the original task with the fresh context.

package/packages/@monomind/cli/dist/src/commands/design-detect.d.ts

@@ -1,6 +1,6 @@
 /**
  * CLI Design Detect Command
- * Thin wrapper around impeccable's design anti-pattern detector
+ * Thin wrapper around the bundled @monoes/monodesign anti-pattern detector
  *
  * github.com/monoes/monomind
  */
@@ -16,6 +16,12 @@ export interface DesignDetectResult {
     patterns: DesignAntiPattern[];
     count: number;
 }
+/**
+ * Resolve the bundled monodesign CLI entry (cli/bin/cli.js) from the
+ * @monoes/monodesign package. Falls back to the monorepo sibling layout when
+ * running from a source checkout without installed workspace links.
+ */
+export declare function resolveMonodesignCli(): string | null;
 export declare const designCommand: Command;
 export default designCommand;
 //# sourceMappingURL=design-detect.d.ts.map

package/packages/@monomind/cli/dist/src/commands/design-detect.js

@@ -1,39 +1,52 @@
 /**
  * CLI Design Detect Command
- * Thin wrapper around impeccable's design anti-pattern detector
+ * Thin wrapper around the bundled @monoes/monodesign anti-pattern detector
  *
  * github.com/monoes/monomind
  */
 import { output } from '../output.js';
-import { spawn, execFile } from 'child_process';
-import { promisify } from 'util';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { paletteSubcommand } from './design-palette.js';
-const execFileAsync = promisify(execFile);
 // ─── Helpers ─────────────────────────────────────────────────────────────────
-async function isImpeccableAvailable() {
+/**
+ * Resolve the bundled monodesign CLI entry (cli/bin/cli.js) from the
+ * @monoes/monodesign package. Falls back to the monorepo sibling layout when
+ * running from a source checkout without installed workspace links.
+ */
+export function resolveMonodesignCli() {
+    // 1. Normal resolution through the package's "./engine" export.
     try {
-        await execFileAsync('npx', ['--no-install', 'impeccable', '--version'], { timeout: 5000 });
-        return true;
+        const require = createRequire(import.meta.url);
+        const enginePath = require.resolve('@monoes/monodesign/engine');
+        const binPath = join(dirname(enginePath), '..', 'bin', 'cli.js');
+        if (existsSync(binPath))
+            return binPath;
     }
     catch {
-        // Try checking via which
-        try {
-            await execFileAsync('which', ['impeccable'], { timeout: 3000 });
-            return true;
-        }
-        catch {
-            return false;
-        }
+        // fall through to monorepo-relative lookup
     }
+    // 2. Monorepo layout: packages/@monomind/cli/{src|dist/src}/commands/ → packages/@monoes/monodesign
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const toCliRoot of ['../..', '../../..']) {
+        // <cli root>/../../@monoes/monodesign = packages/@monoes/monodesign
+        const candidate = join(here, toCliRoot, '..', '..', '@monoes', 'monodesign', 'cli', 'bin', 'cli.js');
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
 }
-function runImpeccable(args) {
+function runMonodesign(cliPath, args) {
     return new Promise((resolve) => {
-        const child = spawn('npx', ['impeccable', 'detect', ...args], {
+        const child = spawn(process.execPath, [cliPath, ...args], {
             stdio: 'inherit',
             shell: false,
         });
         child.on('error', (err) => {
-            output.printError(`Failed to run impeccable: ${err.message}`);
+            output.printError(`Failed to run the monodesign detector: ${err.message}`);
             resolve(1);
         });
         child.on('close', (code) => {
@@ -41,10 +54,18 @@ function runImpeccable(args) {
         });
     });
 }
+function printEngineMissing() {
+    output.writeln();
+    output.writeln(output.warning('The bundled monodesign detection engine could not be found.'));
+    output.writeln();
+    output.writeln('The detector ships with @monoes/monodesign. Reinstall monomind to restore it:');
+    output.writeln(output.dim('  npm install -g monomind   # or: pnpm install (in a monomind checkout)'));
+    output.writeln();
+}
 // ─── detect subcommand ────────────────────────────────────────────────────────
 const detectSubcommand = {
     name: 'detect',
-    description: 'Detect design anti-patterns in HTML/CSS files using impeccable',
+    description: 'Detect design anti-patterns in HTML/CSS files using the bundled monodesign engine',
     options: [
         {
             name: 'target',
@@ -70,28 +91,37 @@ const detectSubcommand = {
         output.writeln();
         output.writeln(output.bold('Design Anti-Pattern Detection'));
         output.writeln(output.dim('─'.repeat(50)));
-        const available = await isImpeccableAvailable();
-        if (!available) {
-            output.writeln();
-            output.writeln(output.warning('impeccable is not installed.'));
-            output.writeln();
-            output.writeln('Install it to enable design anti-pattern detection:');
-            output.writeln(output.dim('  npm install -g impeccable'));
-            output.writeln();
-            output.writeln('Or run directly without installing:');
-            output.writeln(output.dim('  npx impeccable detect <file-or-dir>'));
-            output.writeln();
-            output.writeln(output.dim('impeccable checks for 46 known design anti-patterns across:'));
-            output.writeln(output.dim('  • slop  — AI tells: purple palettes, side-tabs, card grids, italic-serif heroes'));
-            output.writeln(output.dim('  • quality — spacing, hierarchy, readability, contrast, motion, typography'));
-            return { success: false, message: 'impeccable not installed' };
+        const cliPath = resolveMonodesignCli();
+        if (!cliPath) {
+            printEngineMissing();
+            return { success: false, message: 'monodesign detection engine not found' };
         }
         output.writeln(output.dim(`Scanning: ${target}`));
         output.writeln();
-        const forwardArgs = [target];
+        const forwardArgs = ['detect', target];
         if (jsonOutput)
             forwardArgs.push('--json');
-        const exitCode = await runImpeccable(forwardArgs);
+        const exitCode = await runMonodesign(cliPath, forwardArgs);
+        return { success: exitCode === 0, exitCode };
+    },
+};
+// ─── ignores subcommand ───────────────────────────────────────────────────────
+const ignoresSubcommand = {
+    name: 'ignores',
+    description: 'Manage monodesign detector ignore rules, files, and values',
+    examples: [
+        { command: 'monomind design ignores list', description: 'Show current ignore configuration' },
+        { command: 'monomind design ignores add-rule <rule-id>', description: 'Ignore a detector rule project-wide' },
+        { command: 'monomind design ignores add-file <path>', description: 'Exclude a file from detection' },
+        { command: 'monomind design ignores remove-rule <rule-id>', description: 'Re-enable an ignored rule' },
+    ],
+    action: async (ctx) => {
+        const cliPath = resolveMonodesignCli();
+        if (!cliPath) {
+            printEngineMissing();
+            return { success: false, message: 'monodesign detection engine not found' };
+        }
+        const exitCode = await runMonodesign(cliPath, ['ignores', ...ctx.args]);
         return { success: exitCode === 0, exitCode };
     },
 };
@@ -99,10 +129,11 @@ const detectSubcommand = {
 export const designCommand = {
     name: 'design',
     description: 'Design tooling: anti-pattern detection, OKLCH palette seeding, and design quality checks',
-    subcommands: [detectSubcommand, paletteSubcommand],
+    subcommands: [detectSubcommand, ignoresSubcommand, paletteSubcommand],
     examples: [
         { command: 'monomind design detect', description: 'Detect design anti-patterns' },
         { command: 'monomind design detect -t ./src --json', description: 'JSON output for CI' },
+        { command: 'monomind design ignores list', description: 'Manage detector ignore rules' },
         { command: 'monomind design palette', description: 'Pick an OKLCH brand seed color' },
         { command: 'monomind design palette --from "my-product"', description: 'Deterministic seed from product name' },
     ],
@@ -113,7 +144,8 @@ export const designCommand = {
         output.writeln();
         output.writeln('Subcommands:');
         output.printList([
-            'detect   - Detect design anti-patterns using impeccable',
+            'detect   - Detect design anti-patterns (bundled monodesign engine)',
+            'ignores  - Manage detector ignore rules, files, and values',
             'palette  - OKLCH brand seed — returns anchor color + mood + composition strategy',
         ]);
         output.writeln();

package/packages/@monomind/cli/dist/src/commands/design-palette.d.ts

@@ -1,7 +1,7 @@
 /**
  * CLI Design Palette Command
  * OKLCH brand-seed picker — returns one anchor seed color + mood + composition strategy.
- * Ported from impeccable's palette.mjs (129 hand-curated seeds).
+ * Pattern adapted from impeccable (Apache-2.0) — rebranded for monomind (129 hand-curated seeds).
  *
  * github.com/monoes/monomind
  */

package/packages/@monomind/cli/dist/src/commands/design-palette.js

@@ -1,7 +1,7 @@
 /**
  * CLI Design Palette Command
  * OKLCH brand-seed picker — returns one anchor seed color + mood + composition strategy.
- * Ported from impeccable's palette.mjs (129 hand-curated seeds).
+ * Pattern adapted from impeccable (Apache-2.0) — rebranded for monomind (129 hand-curated seeds).
  *
  * github.com/monoes/monomind
  */
@@ -496,8 +496,8 @@ export const paletteSubcommand = {
         const idFlag = ctx.flags.id;
         const fromFlag = ctx.flags.from;
         const jsonFlag = ctx.flags.json;
-        // Respect IMPECCABLE_PALETTE_SEED env var as a fallback for --from
-        const fromKey = fromFlag || process.env['IMPECCABLE_PALETTE_SEED'];
+        // Respect MONODESIGN_PALETTE_SEED env var as a fallback for --from
+        const fromKey = fromFlag || process.env['MONODESIGN_PALETTE_SEED'];
         let seed;
         if (idFlag) {
             const found = SEEDS.find((s) => s.id === idFlag);

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

@@ -88,6 +88,7 @@ const searchDocCommand = {
         { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
         { name: 'min-score', description: 'Minimum similarity (default: 0.3)', type: 'number', default: 0.3 },
         { name: 'store', description: 'Which store(s): project | global | all (default: all — project results win ties)', type: 'string', default: 'all' },
+        { name: 'surfaces', description: "Override routing: comma list of chunks,kg,rules,memory (default: rule-based router picks)", type: 'string' },
     ],
     examples: [
         { command: 'monomind doc search -q "authentication flow"', description: 'Search project + global brain' },
@@ -100,28 +101,84 @@ const searchDocCommand = {
             return { success: false, exitCode: 1 };
         }
         const { searchKnowledge } = await import('../knowledge/document-pipeline.js');
+        const { routeQuery, rrfFuse, recordRouteOverride } = await import('../memory/query-router.js');
         const storeFlag = String(ctx.flags.store || 'all');
-        const excerpts = await searchKnowledge(query, {
-            scope: String(ctx.flags.scope || 'shared'),
-            limit: Number(ctx.flags.limit || 10),
-            minScore: Number(ctx.flags['min-score'] || 0.3),
-            store: storeFlag === 'project' || storeFlag === 'global' ? storeFlag : 'all',
-        });
-        if (!excerpts.length) {
+        const limit = Number(ctx.flags.limit || 10);
+        // Same surface routing as the MCP knowledge_search tool and the warm
+        // /api/knowledge/search endpoint: the rule-based router picks which
+        // retrieval surfaces to spend queries on; --surfaces overrides it.
+        const route = routeQuery(query);
+        const VALID_SURFACES = ['chunks', 'kg', 'rules', 'memory'];
+        const rawSurfaces = String(ctx.flags.surfaces || '').split(',').map(s => s.trim()).filter(Boolean);
+        const requested = rawSurfaces.filter(s => VALID_SURFACES.includes(s));
+        const invalidSurfaces = rawSurfaces.filter(s => !VALID_SURFACES.includes(s));
+        if (invalidSurfaces.length) {
+            output.writeln(output.dim(`ignoring unknown surface(s): ${invalidSurfaces.join(',')} (valid: ${VALID_SURFACES.join(',')})`));
+        }
+        const surfaces = requested.length
+            ? requested
+            : (route.confident ? route.surfaces : ['chunks', ...route.surfaces.filter(s => s !== 'chunks')]);
+        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: String(ctx.flags.scope || 'shared'),
+                    limit,
+                    minScore: Number(ctx.flags['min-score'] || 0.3),
+                    store: storeFlag === 'project' || storeFlag === 'global' ? storeFlag : 'all',
+                })
+                : [],
+            surfaces.includes('kg') ? kg.kgSearch({ query, limit: 6 }).catch(() => null) : null,
+            surfaces.includes('rules') ? bridge.bridgeSearchEntries({ query, namespace: 'rules', limit: 3, threshold: 0.35 }).catch(() => null) : null,
+            surfaces.includes('memory') ? bridge.bridgeSearchEntries({ query, namespace: 'patterns', limit: 3 }).catch(() => null) : 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.
+        let fellBack = false;
+        let chunkExcerpts = excerpts;
+        if (!requested.length && !chunkExcerpts.length && !(graph?.triplets?.length) && !(rules?.results?.length) && !(memories?.results?.length) && !surfaces.includes('chunks')) {
+            fellBack = true;
+            recordRouteOverride(surfaces[0], 'chunks');
+            chunkExcerpts = await searchKnowledge(query, {
+                scope: String(ctx.flags.scope || 'shared'),
+                limit,
+                minScore: Number(ctx.flags['min-score'] || 0.3),
+                store: storeFlag === 'project' || storeFlag === 'global' ? storeFlag : 'all',
+            });
+        }
+        const fused = rrfFuse([
+            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, score: r.score, importance: 0.7 })),
+            (memories?.results ?? []).map(r => ({ id: r.id, kind: 'memory', key: r.key, text: r.content, score: r.score })),
+        ], limit);
+        if (!fused.length) {
             output.writeln(output.dim('No results found.'));
             return { success: true, data: [] };
         }
-        output.writeln(output.bold(`${excerpts.length} results:`));
+        output.writeln(output.bold(`${fused.length} results ${output.dim(`(surfaces: ${fellBack ? surfaces.join(',') + ' → chunks fallback' : surfaces.join(',')})`)}:`));
         output.writeln();
-        for (let i = 0; i < excerpts.length; i++) {
-            const ex = excerpts[i];
-            const origin = ex.scope === 'global' ? ` ${output.dim('[global]')}` : '';
-            output.writeln(`${output.highlight(`${i + 1}.`)} ${output.dim(`(${ex.similarity.toFixed(3)})`)} ${ex.filePath || 'unknown'}${origin}`);
-            const preview = ex.text.length > 200 ? ex.text.slice(0, 200) + '...' : ex.text;
-            output.writeln(`   ${output.dim(preview)}`);
+        for (let i = 0; i < fused.length; i++) {
+            const r = fused[i];
+            const n = output.highlight(`${i + 1}.`);
+            if (r.kind === 'triplet') {
+                const fact = r.fact && r.fact !== `${r.source} ${r.relation} ${r.target}` ? ` ${output.dim(`(${String(r.fact).slice(0, 160)})`)}` : '';
+                output.writeln(`${n} ${output.dim('[kg]')} ${r.source} —${r.relation}→ ${r.target}${fact}`);
+            }
+            else if (r.kind === 'rule' || r.kind === 'memory') {
+                output.writeln(`${n} ${output.dim(`[${r.kind}]`)} ${String(r.text || '').replace(/\s+/g, ' ').slice(0, 200)}`);
+            }
+            else {
+                const origin = r.scope === 'global' ? ` ${output.dim('[global]')}` : '';
+                const sim = typeof r.similarity === 'number' ? `(${r.similarity.toFixed(3)}) ` : '';
+                output.writeln(`${n} ${output.dim(sim)}${r.filePath || 'unknown'}${origin}`);
+                const text = String(r.text || '');
+                output.writeln(`   ${output.dim(text.length > 200 ? text.slice(0, 200) + '...' : text)}`);
+            }
             output.writeln();
         }
-        return { success: true, data: excerpts };
+        return { success: true, data: fused };
     },
 };
 const listDocCommand = {

package/packages/@monomind/cli/dist/src/commands/doctor-project-checks.d.ts

@@ -6,6 +6,10 @@ import type { HealthCheck } from './doctor-env-checks.js';
 export type { HealthCheck };
 export declare function checkConfigFile(): Promise<HealthCheck>;
 export declare function checkMemoryDatabase(): Promise<HealthCheck>;
+/** Memory knowledge graph (cognee port): entities/relations/rules distilled
+ * from sessions and org runs. Informational — an empty graph on a fresh
+ * project is normal, so it never fails. */
+export declare function checkMemoryKnowledgeGraph(): Promise<HealthCheck>;
 /** Second Brain: when this project has an indexed knowledge base, semantic
  * search needs the local embedding model. Its absence is silent (search
  * degrades to keyword matching) — surface it here instead. */