@geminilight/mindos 0.6.25 → 0.6.27

package/bin/cli.js

@@ -54,13 +54,35 @@ import { needsBuild, writeBuildStamp, cleanNextDir, ensureAppDeps } from './lib/
 import { isPortInUse, assertPortFree } from './lib/port.js';
 import { savePids, clearPids } from './lib/pid.js';
 import { stopMindos } from './lib/stop.js';
-import { getPlatform, ensureMindosDir, waitForHttp, waitForPortFree, runGatewayCommand } from './lib/gateway.js';
 import { printStartupInfo, getLocalIP } from './lib/startup.js';
 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';
+import { MCP_AGENTS, detectAgentPresence } from './lib/mcp-agents.js';
+
+// Heavy modules — loaded lazily inside command handlers to speed up CLI cold start
+// gateway.js (426 lines), mcp-install.js (335), sync.js (472), mcp-build.js (74)
+const lazy = {
+  gateway:    () => import('./lib/gateway.js'),
+  mcpInstall: () => import('./lib/mcp-install.js'),
+  sync:       () => import('./lib/sync.js'),
+  mcpBuild:   () => import('./lib/mcp-build.js'),
+};
+
+// Thin wrappers for lazy modules — same API as before, but loaded on first call
+async function getPlatform() { return (await lazy.gateway()).getPlatform(); }
+async function runGatewayCommand(sub) { return (await lazy.gateway()).runGatewayCommand(sub); }
+async function waitForHttp(...a) { return (await lazy.gateway()).waitForHttp(...a); }
+async function waitForPortFree(...a) { return (await lazy.gateway()).waitForPortFree(...a); }
+async function ensureMindosDir() { return (await lazy.gateway()).ensureMindosDir(); }
+async function ensureMcpBundle() { return (await lazy.mcpBuild()).ensureMcpBundle(); }
+async function mcpInstall() { return (await lazy.mcpInstall()).mcpInstall(); }
+async function initSync(...a) { return (await lazy.sync()).initSync(...a); }
+async function startSyncDaemon(...a) { return (await lazy.sync()).startSyncDaemon(...a); }
+async function stopSyncDaemon() { return (await lazy.sync()).stopSyncDaemon(); }
+async function getSyncStatus(...a) { return (await lazy.sync()).getSyncStatus(...a); }
+async function manualSync(...a) { return (await lazy.sync()).manualSync(...a); }
+async function listConflicts(...a) { return (await lazy.sync()).listConflicts(...a); }
+async function setSyncEnabled(...a) { return (await lazy.sync()).setSyncEnabled(...a); }
 
 // ── New modular commands ──────────────────────────────────────────────────────
 import * as fileCmd from './commands/file.js';
@@ -139,24 +161,24 @@ function buildIfNeeded(newRoot) {
 
 // ── Commands ──────────────────────────────────────────────────────────────────
 
-const cmd       = process.argv[2];
+// ── Unified arg parsing ────────────────────────────────────────────────────
+const { command: cmd, args: cliArgs, flags: cliFlags } = parseArgs(process.argv.slice(2));
 
-// ── --version / -v ──────────────────────────────────────────────────────────
-// --help / -h is handled at entry section (resolvedCmd = null → help block)
-if (cmd === '--version' || cmd === '-v') {
+if (cliFlags.version || cliFlags.v) {
   const version = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version;
   console.log(`mindos/${version} node/${process.version} ${process.platform}-${process.arch}`);
   process.exit(0);
 }
 
-const isDaemon  = process.argv.includes('--daemon') || (!cmd && isDaemonMode());
-const isVerbose = process.argv.includes('--verbose');
-const extra     = process.argv.slice(3).filter(a => a !== '--daemon' && a !== '--verbose' && a !== '--turbo').join(' ');
+// Backward compat: derive legacy variables from unified flags
+const isDaemon  = cliFlags.daemon === true || (!cmd && isDaemonMode());
+const isVerbose = cliFlags.verbose === true;
+const extra     = cliArgs.filter(a => !a.startsWith('-')).join(' ');
 
 const commands = {
   // ── onboard ────────────────────────────────────────────────────────────────
   onboard: async () => {
-    const daemonFlag = process.argv.includes('--install-daemon') ? ' --install-daemon' : '';
+    const daemonFlag = cliFlags['install-daemon'] ? ' --install-daemon' : '';
     run(`node ${resolve(ROOT, 'scripts/setup.js')}${daemonFlag}`);
   },
   init:  async () => commands.onboard(),
@@ -204,74 +226,48 @@ const commands = {
     }
     const mcpPort = config.mcpPort || 8781;
     const localIP = getLocalIP();
-
     const localUrl = `http://localhost:${mcpPort}/mcp`;
-    const sep = '━'.repeat(40);
-
-    console.log(`\n${bold('🔑 Auth token:')} ${cyan(token)}\n`);
-
-    // Claude Code
-    console.log(`${sep}`);
-    console.log(`${bold('Claude Code')}`);
-    console.log(`${sep}`);
-    console.log(dim('Quick install:') + ` mindos mcp install claude-code -g -y`);
-    console.log(dim('\nManual config (~/.claude.json):'));
-    console.log(JSON.stringify({
-      mcpServers: {
-        mindos: {
-          url: localUrl,
-          headers: { Authorization: `Bearer ${token}` },
-        },
-      },
-    }, null, 2));
-
-    // CodeBuddy (Claude Code Internal)
-    console.log(`\n${sep}`);
-    console.log(`${bold('CodeBuddy (Claude Code Internal)')}`);
-    console.log(`${sep}`);
-    console.log(dim('Quick install:') + ` mindos mcp install codebuddy -g -y`);
-    console.log(dim('\nManual config (~/.claude-internal/.claude.json):'));
-    console.log(JSON.stringify({
-      mcpServers: {
-        mindos: {
-          url: localUrl,
-          headers: { Authorization: `Bearer ${token}` },
-        },
-      },
-    }, null, 2));
-
-    // Cursor
-    console.log(`\n${sep}`);
-    console.log(`${bold('Cursor')}`);
-    console.log(`${sep}`);
-    console.log(dim('Quick install:') + ` mindos mcp install cursor -g -y`);
-    console.log(dim('\nManual config (~/.cursor/mcp.json):'));
-    console.log(JSON.stringify({
-      mcpServers: {
-        mindos: {
-          url: localUrl,
-          headers: { Authorization: `Bearer ${token}` },
-        },
-      },
-    }, null, 2));
-
-    // Remote
+
+    if (cliFlags.json) {
+      const data = { token, mcpPort, localUrl, remoteUrl: localIP ? `http://${localIP}:${mcpPort}/mcp` : null };
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    const sep = dim('━'.repeat(40));
+    const snippet = (url) => JSON.stringify({
+      mcpServers: { mindos: { url, headers: { Authorization: `Bearer ${token}` } } },
+    }, null, 2);
+
+    console.log(`\n${bold('Auth token:')} ${cyan(token)}\n`);
+
+    // Show installed agents, then up to 3 uninstalled popular ones
+    const installed = [];
+    const others = [];
+    for (const [key, agent] of Object.entries(MCP_AGENTS)) {
+      (detectAgentPresence(key) ? installed : others).push([key, agent]);
+    }
+    const toShow = [...installed.slice(0, 8), ...others.slice(0, Math.max(0, 3 - installed.length))];
+
+    for (const [key, agent] of toShow) {
+      console.log(sep);
+      console.log(bold(agent.name));
+      console.log(dim('Install:') + ` mindos mcp install ${key} -g -y`);
+      if (agent.global) console.log(dim(`Config:  ${agent.global}`));
+      console.log(snippet(localUrl));
+      console.log();
+    }
+
     if (localIP) {
-      const remoteUrl = `http://${localIP}:${mcpPort}/mcp`;
-      console.log(`\n${sep}`);
-      console.log(`${bold('Remote (other devices)')}`);
-      console.log(`${sep}`);
-      console.log(`URL: ${cyan(remoteUrl)}`);
-      console.log(JSON.stringify({
-        mcpServers: {
-          mindos: {
-            url: remoteUrl,
-            headers: { Authorization: `Bearer ${token}` },
-          },
-        },
-      }, null, 2));
+      console.log(sep);
+      console.log(bold('Remote (other devices)'));
+      console.log(`URL: ${cyan(`http://${localIP}:${mcpPort}/mcp`)}`);
+      console.log(snippet(`http://${localIP}:${mcpPort}/mcp`));
     }
 
+    if (toShow.length < installed.length) {
+      console.log(dim(`\n  +${installed.length - toShow.length} more agents detected. Run \`mindos agent list\` to see all.`));
+    }
     console.log(dim('\nRun `mindos onboard` to regenerate.\n'));
   },
 
@@ -289,8 +285,7 @@ const commands = {
     ensureAppDeps();
     const mcp = spawnMcp(isVerbose);
     savePids(process.pid, mcp.pid);
-    process.on('exit', () => { stopSyncDaemon(); clearPids(); });
-    // Start sync daemon if enabled
+    process.on('exit', () => { stopSyncDaemon().catch(() => {}); clearPids(); });
     const devMindRoot = process.env.MIND_ROOT;
     if (devMindRoot) {
       startSyncDaemon(devMindRoot).catch(() => {});
@@ -311,7 +306,7 @@ const commands = {
       } catch {}
     }
     if (isDaemon) {
-      const platform = getPlatform();
+      const platform = await getPlatform();
       if (!platform) {
         console.warn(yellow('Warning: daemon mode not supported on this platform. Falling back to foreground.'));
       } else {
@@ -404,7 +399,7 @@ const commands = {
     }
     const mcp = spawnMcp(isVerbose);
     savePids(process.pid, mcp.pid);
-    process.on('exit', () => { stopSyncDaemon(); clearPids(); });
+    process.on('exit', () => { stopSyncDaemon().catch(() => {}); clearPids(); });
     // Start sync daemon if enabled
     const mindRoot = process.env.MIND_ROOT;
     if (mindRoot) {
@@ -428,12 +423,12 @@ const commands = {
   },
 
   mcp: async () => {
-    const sub = process.argv[3];
-    const restArgs = process.argv.slice(3);
+    const sub = cliArgs[0];
+    const restArgs = cliArgs;
     const hasInstallFlags = restArgs.some(a => ['-g', '--global', '-y', '--yes'].includes(a));
     if (sub === 'install' || hasInstallFlags) { await mcpInstall(); return; }
     loadConfig();
-    ensureMcpBundle();
+    await ensureMcpBundle();
     // `mindos mcp` is the entry point for MCP clients (Claude Code, Cursor, etc.)
     // which communicate over stdin/stdout. Default to stdio; HTTP is handled by
     // `mindos start` via spawnMcp(). Callers can still override via env.
@@ -493,7 +488,7 @@ const commands = {
 
   // ── gateway ────────────────────────────────────────────────────────────────
   gateway: async () => {
-    const sub = process.argv[3];
+    const sub = cliArgs[0];
     if (!sub) {
       const row = (c, d) => `  ${cyan(c.padEnd(32))}${dim(d)}`;
       console.log(`
@@ -556,25 +551,28 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
 
   // ── doctor ─────────────────────────────────────────────────────────────────
   doctor: async () => {
-    const ok  = (msg) => console.log(`  ${green('✔')} ${msg}`);
-    const err = (msg) => console.log(`  ${red('✘')} ${msg}`);
-    const warn= (msg) => console.log(`  ${yellow('!')} ${msg}`);
+    const jsonMode = cliFlags.json === true;
+    const checks = [];
+    const ok  = (msg, key) => { checks.push({ status: 'ok', key, msg }); if (!jsonMode) console.log(`  ${green('✔')} ${msg}`); };
+    const err = (msg, key) => { checks.push({ status: 'error', key, msg }); if (!jsonMode) console.log(`  ${red('✘')} ${msg}`); };
+    const warn= (msg, key) => { checks.push({ status: 'warn', key, msg }); if (!jsonMode) console.log(`  ${yellow('!')} ${msg}`); };
 
-    console.log(`\n${bold('🩺 MindOS Doctor')}\n`);
+    if (!jsonMode) console.log(`\n${bold('MindOS Doctor')}\n`);
     let hasError = false;
 
     // 1. config file
     if (!existsSync(CONFIG_PATH)) {
-      err(`Config not found at ${dim(CONFIG_PATH)}`);
-      console.log(`\n  ${dim('Run `mindos onboard` to create it.')}\n`);
+      err(`Config not found at ${dim(CONFIG_PATH)}`, 'config');
+      if (!jsonMode) { console.log(`\n  ${dim('Run `mindos onboard` to create it.')}\n`); }
+      if (jsonMode) { console.log(JSON.stringify({ ok: false, checks }, null, 2)); }
       process.exit(1);
     }
     let config;
     try {
       config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-      ok(`Config file found and valid JSON  ${dim(CONFIG_PATH)}`);
+      ok(`Config file found and valid JSON  ${dim(CONFIG_PATH)}`, 'config');
     } catch {
-      err(`Config file exists but failed to parse  ${dim(CONFIG_PATH)}`);
+      err(`Config file exists but failed to parse  ${dim(CONFIG_PATH)}`, 'config');
       hasError = true;
     }
 
@@ -657,7 +655,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
     }
 
     // 7. Daemon status
-    const platform = getPlatform();
+    const platform = await getPlatform();
     if (platform === 'systemd') {
       try {
         execSync('systemctl --user is-active mindos', { stdio: 'pipe' });
@@ -678,7 +676,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
     // 8. Sync status
     if (config?.mindRoot) {
       try {
-        const syncStatus = getSyncStatus(config.mindRoot);
+        const syncStatus = await getSyncStatus(config.mindRoot);
         if (!syncStatus.enabled) {
           warn(`Cross-device sync is not configured  ${dim('(run `mindos sync init` to set up)')}`);
         } else if (syncStatus.lastError) {
@@ -713,9 +711,14 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
       warn('Could not check for updates');
     }
 
-    console.log(hasError
-      ? `\n${red('Some checks failed.')} Run ${cyan('mindos onboard')} to reconfigure.\n`
-      : `\n${green('All checks passed.')}\n`);
+    if (jsonMode) {
+      const hasErr = checks.some(c => c.status === 'error');
+      console.log(JSON.stringify({ ok: !hasErr, checks }, null, 2));
+    } else {
+      console.log(hasError
+        ? `\n${red('Some checks failed.')} Run ${cyan('mindos onboard')} to reconfigure.\n`
+        : `\n${green('All checks passed.')}\n`);
+    }
     if (hasError) process.exit(1);
   },
 
@@ -763,7 +766,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
       return;
     }
 
-    const updatePlatform = getPlatform();
+    const updatePlatform = await getPlatform();
     let daemonRunning = false;
     if (updatePlatform === 'systemd') {
       try { execSync('systemctl --user is-active mindos', { stdio: 'pipe' }); daemonRunning = true; } catch {}
@@ -977,7 +980,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
     try { stopMindos(); } catch { /* may not be running */ }
 
     // 2. Remove daemon (skip if platform unsupported)
-    if (getPlatform()) {
+    if (await getPlatform()) {
       try {
         await runGatewayCommand('uninstall');
       } catch {
@@ -1040,14 +1043,14 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
   },
 
   // ── logs ───────────────────────────────────────────────────────────────────
-  logs: () => {
-    ensureMindosDir();
+  logs: async () => {
+    await ensureMindosDir();
     if (!existsSync(LOG_PATH)) {
       console.log(dim(`No log file yet at ${LOG_PATH}`));
       console.log(dim('Logs are created when starting MindOS (mindos start, mindos onboard, or daemon mode).'));
       process.exit(0);
     }
-    const noFollow = process.argv.includes('--no-follow');
+    const noFollow = cliFlags['no-follow'] === true;
     if (noFollow) {
       execSync(`tail -n 100 ${LOG_PATH}`, { stdio: 'inherit' });
     } else {
@@ -1057,7 +1060,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
 
   // ── config ─────────────────────────────────────────────────────────────────
   config: () => {
-    const sub = process.argv[3];
+    const sub = cliArgs[0];
 
     function maskKey(val) {
       if (!val) return val;
@@ -1088,7 +1091,11 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
         display.authToken = maskKey(display.authToken);
       if (display.webPassword)
         display.webPassword = maskKey(display.webPassword);
-      console.log(`\n${bold('📋 MindOS Config')}  ${dim(`v${(() => { try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; } })()}`)}  ${dim(CONFIG_PATH)}\n`);
+      if (cliFlags.json) {
+        console.log(JSON.stringify(display, null, 2));
+        return;
+      }
+      console.log(`\n${bold('MindOS Config')}  ${dim(`v${(() => { try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; } })()}`)}  ${dim(CONFIG_PATH)}\n`);
       console.log(JSON.stringify(display, null, 2));
       console.log();
       return;
@@ -1128,8 +1135,8 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
     }
 
     if (sub === 'set') {
-      const key = process.argv[4];
-      const val = process.argv[5];
+      const key = cliArgs[1];
+      const val = cliArgs[2];
       if (!key || val === undefined) {
         console.error(red('Usage: mindos config set <key> <value>'));
         console.error(dim('  Examples:'));
@@ -1170,7 +1177,7 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
     }
 
     if (sub === 'unset') {
-      const key = process.argv[4];
+      const key = cliArgs[1];
       if (!key) {
         console.error(red('Usage: mindos config unset <key>'));
         process.exit(1);
@@ -1218,13 +1225,13 @@ ${bold('Examples:')}
 
   // ── sync ──────────────────────────────────────────────────────────────────
   sync: async () => {
-    const sub = process.argv[3];
+    const sub = cliArgs[0];
     loadConfig();
     const mindRoot = process.env.MIND_ROOT;
 
     if (sub === 'init') {
       // Parse --non-interactive --remote <url> --branch <branch> --token <token>
-      const args = process.argv.slice(4);
+      const args = cliArgs.slice(1);
       const flagIdx = (flag) => args.indexOf(flag);
       const flagVal = (flag) => { const i = flagIdx(flag); return i >= 0 && i + 1 < args.length ? args[i + 1] : ''; };
       const nonInteractive = args.includes('--non-interactive');
@@ -1245,7 +1252,7 @@ ${bold('Examples:')}
     if (sub === 'now') {
       try {
         console.log(dim('Pulling...'));
-        manualSync(mindRoot);
+        await manualSync(mindRoot);
         console.log(green('✔ Sync complete'));
       } catch (err) {
         console.error(red(err.message));
@@ -1255,18 +1262,18 @@ ${bold('Examples:')}
     }
 
     if (sub === 'conflicts') {
-      listConflicts(mindRoot);
+      await listConflicts(mindRoot);
       return;
     }
 
     if (sub === 'on') {
-      setSyncEnabled(true);
+      await setSyncEnabled(true);
       return;
     }
 
     if (sub === 'off') {
-      setSyncEnabled(false);
-      stopSyncDaemon();
+      await setSyncEnabled(false);
+      await stopSyncDaemon();
       return;
     }
 
@@ -1281,9 +1288,15 @@ ${bold('Examples:')}
     }
 
     // default: sync status
-    const status = getSyncStatus(mindRoot);
+    const status = await getSyncStatus(mindRoot);
+
+    if (cliFlags.json) {
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+
     if (!status.enabled) {
-      console.log(`\n${bold('🔄 Sync Status')}`);
+      console.log(`\n${bold('Sync Status')}`);
       console.log(dim('  Not configured. Run `mindos sync init` to set up.\n'));
       return;
     }
@@ -1296,7 +1309,7 @@ ${bold('Examples:')}
         })()
       : 'never';
 
-    console.log(`\n${bold('🔄 Sync Status')}`);
+    console.log(`\n${bold('Sync Status')}`);
     console.log(`  ${dim('Provider:')}    ${cyan(`${status.provider} (${status.remote})`)}`);
     console.log(`  ${dim('Branch:')}      ${cyan(status.branch)}`);
     console.log(`  ${dim('Last sync:')}   ${ago}`);
@@ -1310,68 +1323,64 @@ ${bold('Examples:')}
   },
 
   // ── 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); },
+  file:   async () => fileCmd.run(cliArgs, cliFlags),
+  space:  async () => spaceCmd.run(cliArgs, cliFlags),
+  ask:    async () => askCmd.run(cliArgs, cliFlags),
+  status: async () => statusCmd.run(cliArgs, cliFlags),
+  api:    async () => apiCmd.run(cliArgs, cliFlags),
+  agent:  async () => agentCmd.run(cliArgs, cliFlags),
+  search: async () => searchCmd.run(cliArgs, cliFlags),
 };
 
 // ── Entry ─────────────────────────────────────────────────────────────────────
 
-const resolvedCmd = (cmd === '--help' || cmd === '-h') ? null : (cmd || (existsSync(CONFIG_PATH) ? getStartMode() : null));
+const resolvedCmd = (cliFlags.help || cliFlags.h) ? null : (cmd || (existsSync(CONFIG_PATH) ? getStartMode() : null));
 
 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('Core:')}
-${row('mindos onboard',                    'Interactive setup (aliases: init, setup)')}
-${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 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 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 <sub>',              'Manage service (install/start/stop/status/logs)')}
-
-${bold('Config & Diagnostics:')}
-${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');
+
+  // Command registry — help is generated entirely from this array.
+  // Modular commands provide meta via their exports; inline commands define meta here.
+  const helpRegistry = [
+    { group: 'Core', usage: 'mindos onboard',        summary: 'Interactive setup (aliases: init, setup)' },
+    { group: 'Core', usage: 'mindos start',           summary: 'Start app + MCP server (production)' },
+    { group: 'Core', usage: 'mindos start --daemon',  summary: 'Start as background OS service' },
+    { group: 'Core', usage: 'mindos dev',             summary: 'Start in dev mode' },
+    { group: 'Core', usage: 'mindos stop',            summary: 'Stop running processes' },
+    { group: 'Core', usage: 'mindos restart',         summary: 'Stop then start again' },
+    { group: 'Core', usage: 'mindos build',           summary: 'Build for production' },
+    statusCmd.meta,
+    { group: 'Core', usage: 'mindos open',            summary: 'Open Web UI in browser' },
+    fileCmd.meta, spaceCmd.meta, searchCmd.meta, askCmd.meta, agentCmd.meta, apiCmd.meta,
+    { group: 'MCP', usage: 'mindos mcp',              summary: 'Start MCP server only' },
+    { group: 'MCP', usage: 'mindos mcp install [agent]', summary: 'Install MCP config into Agent' },
+    { group: 'MCP', usage: 'mindos token',            summary: 'Show auth token and MCP config' },
+    { group: 'Sync', usage: 'mindos sync',            summary: 'Show sync status (init/now/conflicts/on/off)' },
+    { group: 'Gateway', usage: 'mindos gateway <sub>', summary: 'Manage service (install/start/stop/status/logs)' },
+    { group: 'Config', usage: 'mindos config <sub>',  summary: 'View/update config (show/set/unset/validate)' },
+    { group: 'Config', usage: 'mindos doctor',         summary: 'Health check' },
+    { group: 'Config', usage: 'mindos update',         summary: 'Update to latest version' },
+    { group: 'Config', usage: 'mindos uninstall',      summary: 'Fully uninstall MindOS' },
+    { group: 'Config', usage: 'mindos logs',           summary: 'Tail service logs' },
+  ];
+
+  const groupLabels = [
+    ['Core', 'Core'], ['Knowledge', 'Knowledge'], ['MCP', 'MCP'],
+    ['Sync', 'Sync'], ['Gateway', 'Gateway (Background Service)'], ['Config', 'Config & Diagnostics'],
+  ];
+  const groups = {};
+  for (const e of helpRegistry) {
+    const g = e.group || 'Other';
+    if (!groups[g]) groups[g] = [];
+    groups[g].push(row(e.usage || `mindos ${e.name}`, e.summary));
+  }
+  const sections = groupLabels
+    .filter(([k]) => groups[k])
+    .map(([k, label]) => `${bold(`${label}:`)}\n${groups[k].join('\n')}`);
+
+  console.log(`\n${bold('MindOS CLI')} ${dim(`v${pkgVersion}`)}\n\n${sections.join('\n\n')}\n\n${bold('Global Flags:')}\n${row('--json', 'Output in JSON (for AI agents)')}\n${row('--help, -h', 'Show help')}\n${row('--version, -v', 'Show version')}\n`);
+  const isHelp = cliFlags.help || cliFlags.h;
   process.exit((cmd && !isHelp) ? 1 : 0);
 }