@geminilight/mindos 0.6.22 → 0.6.25

package/bin/cli.js

@@ -60,6 +60,16 @@ import { spawnMcp } from './lib/mcp-spawn.js';
 import { ensureMcpBundle } from './lib/mcp-build.js';
 import { mcpInstall } from './lib/mcp-install.js';
 import { initSync, startSyncDaemon, stopSyncDaemon, getSyncStatus, manualSync, listConflicts, setSyncEnabled } from './lib/sync.js';
+import { parseArgs } from './lib/command.js';
+
+// ── New modular commands ──────────────────────────────────────────────────────
+import * as fileCmd from './commands/file.js';
+import * as spaceCmd from './commands/space.js';
+import * as askCmd from './commands/ask.js';
+import * as statusCmd from './commands/status.js';
+import * as apiCmd from './commands/api.js';
+import * as agentCmd from './commands/agent.js';
+import * as searchCmd from './commands/search.js';
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -1298,6 +1308,15 @@ ${bold('Examples:')}
     }
     console.log();
   },
+
+  // ── New modular commands (knowledge operations) ──────────────────────────
+  file:   async () => { const p = parseArgs(process.argv.slice(3)); await fileCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  space:  async () => { const p = parseArgs(process.argv.slice(3)); await spaceCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  ask:    async () => { const p = parseArgs(process.argv.slice(3)); await askCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  status: async () => { const p = parseArgs(process.argv.slice(3)); await statusCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  api:    async () => { const p = parseArgs(process.argv.slice(3)); await apiCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  agent:  async () => { const p = parseArgs(process.argv.slice(3)); await agentCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  search: async () => { const p = parseArgs(process.argv.slice(3)); await searchCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
 };
 
 // ── Entry ─────────────────────────────────────────────────────────────────────
@@ -1308,40 +1327,49 @@ if (!resolvedCmd || !commands[resolvedCmd]) {
   const pkgVersion = (() => { try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; } })();
   const row = (c, d) => `  ${cyan(c.padEnd(36))}${dim(d)}`;
   console.log(`
-${bold('🧠 MindOS CLI')} ${dim(`v${pkgVersion}`)}
+${bold('MindOS CLI')} ${dim(`v${pkgVersion}`)}
 
 ${bold('Core:')}
 ${row('mindos onboard',                    'Interactive setup (aliases: init, setup)')}
-${row('mindos onboard --install-daemon',   'Setup + install & start as background OS service')}
-${row('mindos start',                      'Start app + MCP server (production, auto-rebuilds if needed)')}
-${row('mindos start --daemon',             'Install + start as background OS service (survives terminal close)')}
-${row('mindos start --verbose',            'Start with verbose MCP logging')}
-${row('mindos dev',                        'Start app + MCP server (dev mode)')}
-${row('mindos dev --turbopack',            'Start with Turbopack (faster HMR)')}
-${row('mindos stop',                       'Stop running MindOS processes')}
+${row('mindos start',                      'Start app + MCP server (production)')}
+${row('mindos start --daemon',             'Start as background OS service')}
+${row('mindos dev',                        'Start in dev mode')}
+${row('mindos stop',                       'Stop running processes')}
 ${row('mindos restart',                    'Stop then start again')}
-${row('mindos build',                      'Build the app for production')}
-${row('mindos open',                       'Open Web UI in the default browser')}
+${row('mindos build',                      'Build for production')}
+${row('mindos status',                     'Show service status overview')}
+${row('mindos open',                       'Open Web UI in browser')}
+
+${bold('Knowledge:')}
+${row('mindos file <sub>',                 'File operations (list/read/create/delete/search)')}
+${row('mindos space <sub>',                'Space management (list/create/info)')}
+${row('mindos search "<query>"',           'Search knowledge base via API')}
+${row('mindos ask "<question>"',           'Ask AI using your knowledge base')}
+${row('mindos agent <sub>',               'AI Agent management (list/info)')}
+${row('mindos api <METHOD> <path>',        'Raw API passthrough (for developers/agents)')}
 
 ${bold('MCP:')}
 ${row('mindos mcp',                        'Start MCP server only')}
-${row('mindos mcp install [agent]',        'Install MindOS MCP config into Agent (claude-code/cursor/windsurf/…) [-g]')}
-${row('mindos token',                      'Show current auth token and MCP config snippet')}
+${row('mindos mcp install [agent]',        'Install MCP config into Agent')}
+${row('mindos token',                      'Show auth token and MCP config')}
 
 ${bold('Sync:')}
 ${row('mindos sync',                       'Show sync status (init/now/conflicts/on/off)')}
 
 ${bold('Gateway (Background Service):')}
-${row('mindos gateway <subcommand>',       'Manage background service (install/uninstall/start/stop/status/logs)')}
+${row('mindos gateway <sub>',              'Manage service (install/start/stop/status/logs)')}
 
 ${bold('Config & Diagnostics:')}
-${row('mindos config <subcommand>',        'View/update config (show/validate/set/unset)')}
-${row('mindos doctor',                     'Health check (config, ports, build, daemon)')}
-${row('mindos init-skills',                 'Create user-skill-rules.md for personalization')}
-${row('mindos update',                     'Update MindOS to the latest version')}
-${row('mindos uninstall',                  'Fully uninstall MindOS (stop, remove daemon, npm uninstall)')}
-${row('mindos logs',                       'Tail service logs (~/.mindos/mindos.log)')}
-${row('mindos',                            'Start using mode saved in ~/.mindos/config.json')}
+${row('mindos config <sub>',               'View/update config (show/set/unset/validate)')}
+${row('mindos doctor',                     'Health check')}
+${row('mindos update',                     'Update to latest version')}
+${row('mindos uninstall',                  'Fully uninstall MindOS')}
+${row('mindos logs',                       'Tail service logs')}
+
+${bold('Global Flags:')}
+${row('--json',                            'Output in JSON (for AI agents)')}
+${row('--help, -h',                        'Show help')}
+${row('--version, -v',                     'Show version')}
 `);
   const isHelp = (cmd === '--help' || cmd === '-h');
   process.exit((cmd && !isHelp) ? 1 : 0);

package/bin/commands/agent.js

@@ -0,0 +1,18 @@
+import{bold,dim,cyan,green,red,yellow}from"../lib/colors.js";import{MCP_AGENTS,detectAgentPresence}from"../lib/mcp-agents.js";import{existsSync,readFileSync}from"node:fs";import{resolve}from"node:path";import{homedir}from"node:os";import{output,isJsonMode}from"../lib/command.js";function expandHome(p){return p.startsWith("~/")?resolve(homedir(),p.slice(2)):p}export const meta={name:"agent",group:"Knowledge",summary:"AI Agent management (list/info)",usage:"mindos agent <subcommand>"};export async function run(a,f){const s=a[0];if(!s||f.help||f.h){console.log(bold("mindos agent")+" — AI Agent management
+
+Subcommands:
+  list   List detected AI agents
+  info   Show agent details
+
+Agent Keys: "+Object.keys(MCP_AGENTS).join(", "));return}if(s==="list"||s==="ls")return agentList(f);if(s==="info")return agentInfo(a[1],f);console.error(red("Unknown: "+s));process.exit(1)}function hasMindosConfig(agent){const paths=[agent.global,agent.project].filter(Boolean).map(expandHome);for(const p of paths){try{if(!existsSync(p))continue;const raw=readFileSync(p,"utf-8").replace(///.*$/gm,"").replace(//*[\s\S]*?*//g,"");const data=JSON.parse(raw);const servers=data[agent.key]||{};if(Object.keys(servers).some(k=>k.toLowerCase().includes("mindos")))return true}catch{}}return false}function agentList(f){const agents=[];for(const[key,agent]of Object.entries(MCP_AGENTS)){if(!detectAgentPresence(key))continue;agents.push({key,name:agent.name,installed:true,mindosConnected:hasMindosConfig(agent)})}if(isJsonMode(f)){output({count:agents.length,agents},f);return}if(agents.length===0){console.log(dim("No AI agents detected."));return}console.log("
+"+bold("Detected Agents ("+agents.length+"):")+"
+");for(const a of agents){console.log("  "+a.name.padEnd(20)+" "+(a.mindosConnected?green("● connected"):dim("○ not connected")))}console.log("
+"+dim("Connect: mindos mcp install <agent-key>")+"
+")}function agentInfo(key,f){if(!key){console.error(red("Usage: mindos agent info <key>"));process.exit(1)}const agent=MCP_AGENTS[key];if(!agent){console.error(red("Unknown: "+key));process.exit(1)}const installed=detectAgentPresence(key);const connected=installed?hasMindosConfig(agent):false;const info={key,name:agent.name,installed,mindosConnected:connected,transport:agent.preferredTransport};if(isJsonMode(f)){output(info,f);return}console.log("
+"+bold(agent.name)+"
+  Key:       "+key+"
+  Installed: "+(installed?green("yes"):red("no"))+"
+  MindOS:    "+(connected?green("connected"):yellow("not connected"))+"
+  Transport: "+agent.preferredTransport+(agent.global?"
+  Config:    "+expandHome(agent.global):"")+"
+")}

package/bin/commands/api.js

@@ -0,0 +1,58 @@
+import { bold, dim, cyan, red } from '../lib/colors.js';
+import { loadConfig } from '../lib/config.js';
+
+export const meta = {
+  name: 'api',
+  group: 'Knowledge',
+  summary: 'Raw API passthrough (GET/POST/PUT/DELETE any endpoint)',
+  usage: 'mindos api <METHOD> <path>',
+};
+
+export async function run(args, flags) {
+  if (args.length < 2 || flags.help || flags.h) {
+    console.log(bold('mindos api') + ' — Raw API passthrough\n');
+    console.log('Usage: mindos api <METHOD> <path> [--body <json>]');
+    console.log('Methods: GET, POST, PUT, PATCH, DELETE\n');
+    console.log('Examples:');
+    console.log('  mindos api GET /api/health');
+    console.log('  mindos api GET /api/files');
+    console.log('  mindos api POST /api/ask --body \'{"question":"..."}\'');
+    return;
+  }
+
+  const method = args[0].toUpperCase();
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+    console.error(red('Invalid method: ' + args[0]));
+    process.exit(1);
+  }
+
+  let apiPath = args[1];
+  if (!apiPath.startsWith('/')) apiPath = '/' + apiPath;
+
+  loadConfig();
+  const port = flags.port || process.env.MINDOS_WEB_PORT || '3456';
+  const token = process.env.MINDOS_AUTH_TOKEN || '';
+  const headers = { 'Content-Type': 'application/json' };
+  if (token) headers['Authorization'] = 'Bearer ' + token;
+
+  const fetchOpts = { method, headers };
+  if (flags.body && method !== 'GET') fetchOpts.body = flags.body;
+
+  try {
+    const res = await fetch('http://localhost:' + port + apiPath, fetchOpts);
+    const ct = res.headers.get('content-type') || '';
+    if (ct.includes('json')) {
+      console.log(JSON.stringify(await res.json(), null, 2));
+    } else {
+      console.log(await res.text());
+    }
+    if (!res.ok) process.exit(1);
+  } catch (err) {
+    if (err.cause && err.cause.code === 'ECONNREFUSED') {
+      console.error(red('Connection refused. Start with: mindos start'));
+    } else {
+      console.error(red('Request failed: ' + err.message));
+    }
+    process.exit(1);
+  }
+}

package/bin/commands/ask.js

@@ -0,0 +1,101 @@
+/**
+ * mindos ask — AI question answering via local MindOS API
+ */
+
+import { bold, dim, cyan, green, red } from '../lib/colors.js';
+import { loadConfig } from '../lib/config.js';
+import { output, isJsonMode } from '../lib/command.js';
+
+export const meta = {
+  name: 'ask',
+  group: 'Knowledge',
+  summary: 'Ask AI a question using your knowledge base',
+  usage: 'mindos ask "<question>"',
+  flags: {
+    '--json': 'Output as JSON',
+    '--port <port>': 'MindOS web port (default: 3456)',
+  },
+  examples: [
+    'mindos ask "Summarize my meeting notes from today"',
+    'mindos ask "What are the key points in my RAG research?"',
+    'mindos ask "List all TODOs across my notes" --json',
+  ],
+};
+
+export async function run(args, flags) {
+  const question = args.join(' ');
+
+  if (!question || flags.help || flags.h) {
+    console.log(`
+${bold('mindos ask')} — Ask AI using your knowledge base
+
+${bold('Usage:')}
+  ${cyan('mindos ask "<question>"')}
+
+${bold('Examples:')}
+  ${dim('mindos ask "Summarize my meeting notes"')}
+  ${dim('mindos ask "What are the key insights from my research?" --json')}
+
+${bold('Note:')} MindOS must be running (mindos start).
+`);
+    return;
+  }
+
+  loadConfig();
+  const port = flags.port || process.env.MINDOS_WEB_PORT || '3456';
+  const token = process.env.MINDOS_AUTH_TOKEN || '';
+  const baseUrl = `http://localhost:${port}`;
+
+  // Check if MindOS is running
+  try {
+    const healthRes = await fetch(`${baseUrl}/api/health`);
+    if (!healthRes.ok) throw new Error();
+  } catch {
+    console.error(red('MindOS is not running. Start it with: mindos start'));
+    process.exit(1);
+  }
+
+  if (!isJsonMode(flags)) {
+    process.stdout.write(dim('Thinking...'));
+  }
+
+  try {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+
+    const res = await fetch(`${baseUrl}/api/ask`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ question }),
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`API error (${res.status}): ${errText}`);
+    }
+
+    const data = await res.json();
+
+    if (isJsonMode(flags)) {
+      output(data, flags);
+      return;
+    }
+
+    // Clear "Thinking..." line
+    process.stdout.write('\r' + ' '.repeat(40) + '\r');
+
+    if (data.answer) {
+      console.log(data.answer);
+    } else if (data.text) {
+      console.log(data.text);
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+  } catch (err) {
+    if (!isJsonMode(flags)) {
+      process.stdout.write('\r' + ' '.repeat(40) + '\r');
+    }
+    console.error(red(err.message));
+    process.exit(1);
+  }
+}

package/bin/commands/file.js

@@ -0,0 +1,286 @@
+/**
+ * mindos file — Knowledge base file operations
+ *
+ * Subcommands: list, read, create, delete, rename, move, search
+ * Supports --json for agent consumption
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { resolve, basename, dirname, relative } from 'node:path';
+import { bold, dim, cyan, green, red, yellow } from '../lib/colors.js';
+import { loadConfig } from '../lib/config.js';
+import { output, isJsonMode } from '../lib/command.js';
+
+function getMindRoot() {
+  loadConfig();
+  const root = process.env.MIND_ROOT;
+  if (!root || !existsSync(root)) {
+    console.error(red('Mind root not configured. Run `mindos onboard` first.'));
+    process.exit(1);
+  }
+  return root;
+}
+
+function resolvePath(root, filePath) {
+  // Accept both relative (to mind root) and absolute paths
+  if (filePath.startsWith('/')) return filePath;
+  return resolve(root, filePath);
+}
+
+export const meta = {
+  name: 'file',
+  group: 'Knowledge',
+  summary: 'Knowledge base file operations (list, read, create, delete, search)',
+  usage: 'mindos file <subcommand>',
+  flags: {
+    '--space <name>': 'Filter by space name',
+    '--json': 'Output as JSON',
+    '--recursive, -r': 'Recursive listing',
+  },
+  examples: [
+    'mindos file list',
+    'mindos file list --space "Work"',
+    'mindos file read "notes/meeting.md"',
+    'mindos file create "notes/idea.md" --content "# My Idea"',
+    'mindos file search "RAG implementation"',
+    'mindos file delete "notes/old.md"',
+  ],
+};
+
+export async function run(args, flags) {
+  const sub = args[0];
+  const root = getMindRoot();
+
+  if (!sub || flags.help || flags.h) {
+    printFileHelp();
+    return;
+  }
+
+  switch (sub) {
+    case 'list': return fileList(root, args.slice(1), flags);
+    case 'ls': return fileList(root, args.slice(1), flags);
+    case 'read': return fileRead(root, args[1], flags);
+    case 'cat': return fileRead(root, args[1], flags);
+    case 'create': return fileCreate(root, args[1], flags);
+    case 'delete': return fileDelete(root, args[1], flags);
+    case 'rm': return fileDelete(root, args[1], flags);
+    case 'rename': return fileRename(root, args[1], args[2], flags);
+    case 'mv': return fileRename(root, args[1], args[2], flags);
+    case 'move': return fileRename(root, args[1], args[2], flags);
+    case 'search': return fileSearch(root, args.slice(1).join(' '), flags);
+    default:
+      console.error(red(`Unknown subcommand: ${sub}`));
+      console.error(dim('Available: list, read, create, delete, rename, move, search'));
+      process.exit(1);
+  }
+}
+
+function printFileHelp() {
+  console.log(`
+${bold('mindos file')} — Knowledge base file operations
+
+${bold('Subcommands:')}
+  ${cyan('list'.padEnd(20))}${dim('List files in knowledge base')}
+  ${cyan('read <path>'.padEnd(20))}${dim('Read file content')}
+  ${cyan('create <path>'.padEnd(20))}${dim('Create a new file (--content "...")')}
+  ${cyan('delete <path>'.padEnd(20))}${dim('Delete a file')}
+  ${cyan('rename <old> <new>'.padEnd(20))}${dim('Rename or move a file')}
+  ${cyan('search <query>'.padEnd(20))}${dim('Search files by content')}
+
+${bold('Aliases:')} ls=list, cat=read, rm=delete, mv=rename
+
+${bold('Examples:')}
+  ${dim('mindos file list')}
+  ${dim('mindos file list --json')}
+  ${dim('mindos file read "notes/meeting.md"')}
+  ${dim('mindos file create "ideas/new.md" --content "# New Idea"')}
+  ${dim('mindos file search "machine learning"')}
+`);
+}
+
+function walkFiles(dir, root, opts = {}) {
+  const { recursive = true, space = null } = opts;
+  const results = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = resolve(dir, entry.name);
+    const rel = relative(root, full);
+
+    if (entry.isDirectory()) {
+      if (space && dirname(rel) === '.' && entry.name !== space) continue;
+      if (recursive) results.push(...walkFiles(full, root, { ...opts, space: null }));
+    } else if (entry.isFile()) {
+      results.push({
+        path: rel,
+        name: entry.name,
+        size: statSync(full).size,
+      });
+    }
+  }
+  return results;
+}
+
+function fileList(root, _args, flags) {
+  const files = walkFiles(root, root, {
+    recursive: flags.recursive || flags.r || true,
+    space: flags.space || null,
+  });
+
+  if (isJsonMode(flags)) {
+    output({ count: files.length, files }, flags);
+    return;
+  }
+
+  if (files.length === 0) {
+    console.log(dim('No files found.'));
+    return;
+  }
+
+  console.log(`\n${bold(`Files (${files.length}):`)}\n`);
+  for (const f of files) {
+    const sizeStr = f.size < 1024 ? `${f.size}B` : `${(f.size / 1024).toFixed(1)}K`;
+    console.log(`  ${f.path}  ${dim(sizeStr)}`);
+  }
+  console.log();
+}
+
+function fileRead(root, filePath, flags) {
+  if (!filePath) {
+    console.error(red('Usage: mindos file read <path>'));
+    process.exit(1);
+  }
+  const full = resolvePath(root, filePath);
+  if (!existsSync(full)) {
+    console.error(red(`File not found: ${filePath}`));
+    process.exit(1);
+  }
+  const content = readFileSync(full, 'utf-8');
+
+  if (isJsonMode(flags)) {
+    output({ path: filePath, size: content.length, content }, flags);
+    return;
+  }
+  console.log(content);
+}
+
+function fileCreate(root, filePath, flags) {
+  if (!filePath) {
+    console.error(red('Usage: mindos file create <path> --content "..."'));
+    process.exit(1);
+  }
+  const full = resolvePath(root, filePath);
+  if (existsSync(full) && !flags.force) {
+    console.error(red(`File already exists: ${filePath}`));
+    console.error(dim('Use --force to overwrite.'));
+    process.exit(1);
+  }
+
+  const content = flags.content || `# ${basename(filePath, '.md')}\n`;
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, 'utf-8');
+
+  if (isJsonMode(flags)) {
+    output({ ok: true, path: filePath, size: content.length }, flags);
+    return;
+  }
+  console.log(`${green('✔')} Created: ${cyan(filePath)}`);
+}
+
+function fileDelete(root, filePath, flags) {
+  if (!filePath) {
+    console.error(red('Usage: mindos file delete <path>'));
+    process.exit(1);
+  }
+  const full = resolvePath(root, filePath);
+  if (!existsSync(full)) {
+    console.error(red(`File not found: ${filePath}`));
+    process.exit(1);
+  }
+
+  unlinkSync(full);
+
+  if (isJsonMode(flags)) {
+    output({ ok: true, deleted: filePath }, flags);
+    return;
+  }
+  console.log(`${green('✔')} Deleted: ${filePath}`);
+}
+
+function fileRename(root, oldPath, newPath, flags) {
+  if (!oldPath || !newPath) {
+    console.error(red('Usage: mindos file rename <old-path> <new-path>'));
+    process.exit(1);
+  }
+  const fullOld = resolvePath(root, oldPath);
+  const fullNew = resolvePath(root, newPath);
+
+  if (!existsSync(fullOld)) {
+    console.error(red(`File not found: ${oldPath}`));
+    process.exit(1);
+  }
+  if (existsSync(fullNew) && !flags.force) {
+    console.error(red(`Target already exists: ${newPath}`));
+    process.exit(1);
+  }
+
+  mkdirSync(dirname(fullNew), { recursive: true });
+  renameSync(fullOld, fullNew);
+
+  if (isJsonMode(flags)) {
+    output({ ok: true, from: oldPath, to: newPath }, flags);
+    return;
+  }
+  console.log(`${green('✔')} Renamed: ${oldPath} → ${cyan(newPath)}`);
+}
+
+function fileSearch(root, query, flags) {
+  if (!query) {
+    console.error(red('Usage: mindos file search <query>'));
+    process.exit(1);
+  }
+
+  const files = walkFiles(root, root);
+  const results = [];
+  const queryLower = query.toLowerCase();
+
+  for (const f of files) {
+    try {
+      const content = readFileSync(resolve(root, f.path), 'utf-8');
+      const lines = content.split('\n');
+      const matches = [];
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].toLowerCase().includes(queryLower)) {
+          matches.push({ line: i + 1, text: lines[i].trim().slice(0, 120) });
+        }
+      }
+      if (matches.length > 0 || f.name.toLowerCase().includes(queryLower)) {
+        results.push({ path: f.path, matches });
+      }
+    } catch { /* skip unreadable files */ }
+  }
+
+  if (isJsonMode(flags)) {
+    output({ query, count: results.length, results }, flags);
+    return;
+  }
+
+  if (results.length === 0) {
+    console.log(dim(`No results for "${query}"`));
+    return;
+  }
+
+  console.log(`\n${bold(`Search: "${query}"  (${results.length} files)`)}\n`);
+  for (const r of results) {
+    console.log(`  ${cyan(r.path)}`);
+    for (const m of r.matches.slice(0, 3)) {
+      console.log(`    ${dim(`L${m.line}:`)} ${m.text}`);
+    }
+    if (r.matches.length > 3) {
+      console.log(`    ${dim(`...and ${r.matches.length - 3} more`)}`);
+    }
+  }
+  console.log();
+}

package/bin/commands/search.js

@@ -0,0 +1,51 @@
+import { bold, dim, cyan, red } from '../lib/colors.js';
+import { loadConfig } from '../lib/config.js';
+import { output, isJsonMode } from '../lib/command.js';
+
+export const meta = {
+  name: 'search', group: 'Knowledge',
+  summary: 'Search knowledge base via API',
+  usage: 'mindos search "<query>"',
+  examples: ['mindos search "meeting notes"', 'mindos search "RAG" --limit 5 --json'],
+};
+
+export async function run(args, flags) {
+  const query = args.join(' ');
+  if (!query || flags.help || flags.h) {
+    console.log(bold('mindos search') + ' — Knowledge base search');
+    console.log('');
+    console.log('Usage: mindos search "<query>"');
+    console.log('Flags: --limit <n> (default 20), --json');
+    console.log('Note: MindOS must be running. Offline: mindos file search "<query>"');
+    return;
+  }
+  loadConfig();
+  const port = flags.port || process.env.MINDOS_WEB_PORT || '3456';
+  const token = process.env.MINDOS_AUTH_TOKEN || '';
+  const limit = parseInt(flags.limit) || 20;
+  const headers = {};
+  if (token) headers['Authorization'] = 'Bearer ' + token;
+  try {
+    const res = await fetch('http://localhost:' + port + '/api/search?q=' + encodeURIComponent(query) + '&limit=' + limit, { headers });
+    if (!res.ok) throw new Error('API error (' + res.status + ')');
+    const data = await res.json();
+    const results = data.results || data || [];
+    if (isJsonMode(flags)) { output({ query, count: results.length, results }, flags); return; }
+    if (results.length === 0) { console.log(dim('No results for "' + query + '"')); return; }
+    console.log('');
+    console.log(bold('Search: "' + query + '"  (' + results.length + ' results)'));
+    console.log('');
+    for (const r of results) {
+      const path = r.path || r.filePath || r.name || 'unknown';
+      const snippet = r.snippet || r.preview || r.excerpt || '';
+      const score = r.score ? dim(' (' + (r.score * 100).toFixed(0) + '%)') : '';
+      console.log('  ' + cyan(path) + score);
+      if (snippet) { for (const line of snippet.split('\n').slice(0, 2)) { console.log('    ' + dim(line.trim().slice(0, 100))); } }
+    }
+    console.log('');
+  } catch (err) {
+    if (err.cause && err.cause.code === 'ECONNREFUSED') { console.error(red('MindOS not running. Offline: mindos file search "' + query + '"')); }
+    else { console.error(red(err.message)); }
+    process.exit(1);
+  }
+}