@geminilight/mindos 0.6.40 → 0.6.41

package/bin/cli.js

@@ -1,178 +1,68 @@
 #!/usr/bin/env node
 
 /**
- * MindOS CLI
+ * MindOS CLI — thin router.
  *
- * Usage:
- *   mindos onboard                  — interactive setup → writes ~/.mindos/config.json
- *   mindos onboard --install-daemon — setup + install & start as background OS service
- *   mindos start                    — start app + MCP server (production, auto-rebuilds if needed)
- *   mindos start --daemon           — install + start as background OS service
- *   mindos start --verbose          — start with verbose MCP logging
- *   mindos dev                      — start app + MCP server (dev mode)
- *   mindos dev --turbopack          — start with Turbopack (faster HMR)
- *   mindos build                    — build the app for production
- *   mindos mcp                      — start MCP server only
- *   mindos stop                     — stop running MindOS processes
- *   mindos restart                  — stop then start
- *   mindos open                     — open Web UI in the default browser
- *   mindos token                    — show current auth token and MCP config snippet
- *   mindos sync                     — show sync status
- *   mindos sync init                — configure remote git repo for sync
- *   mindos sync now                 — manual trigger sync
- *   mindos sync conflicts           — list conflict files
- *   mindos sync on|off              — enable/disable auto-sync
- *   mindos gateway install          — install background service (systemd/launchd)
- *   mindos gateway uninstall        — remove background service
- *   mindos gateway start            — start the background service
- *   mindos gateway stop             — stop the background service
- *   mindos gateway status           — show service status
- *   mindos gateway logs             — tail service logs
- *   mindos doctor                   — health check (config, ports, build, daemon)
- *   mindos uninstall                — fully uninstall MindOS (stop, remove daemon, npm uninstall)
- *   mindos update                   — update to latest version
- *   mindos logs                     — tail service logs (~/.mindos/mindos.log)
- *   mindos config show              — print current config (API keys masked)
- *   mindos config set <key> <val>   — update a single config field
- *   mindos config unset <key>       — remove a config field
- *   mindos config validate          — validate config file
+ * All command logic lives in bin/commands/*.js.
+ * This file only parses args, dispatches commands, and renders global help.
  */
 
-import { execSync, execFileSync, spawn as nodeSpawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, rmSync, cpSync, unlinkSync, mkdirSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 
-import { ROOT, CONFIG_PATH, BUILD_STAMP, LOG_PATH, MINDOS_DIR } from './lib/constants.js';
-import { bold, dim, cyan, green, red, yellow } from './lib/colors.js';
+import { ROOT } from './lib/constants.js';
+import { bold, dim, cyan } from './lib/colors.js';
+import { parseArgs, printCommandHelp } from './lib/command.js';
 
-// Resolve the local next binary to avoid npx pulling a mismatched global version
-const NEXT_BIN = resolve(ROOT, 'app', 'node_modules', '.bin', 'next');
-import { run, npmInstall } from './lib/utils.js';
-import { loadConfig, getStartMode, isDaemonMode } from './lib/config.js';
-import { needsBuild, writeBuildStamp, cleanNextDir, ensureAppDeps, hasPrebuiltStandalone } from './lib/build.js';
-import { isPortInUse, assertPortFree } from './lib/port.js';
-import { savePids, clearPids } from './lib/pid.js';
-import { stopMindos, killByPort } from './lib/stop.js';
-import { printStartupInfo, getLocalIP } from './lib/startup.js';
-import { spawnMcp } from './lib/mcp-spawn.js';
-import { parseArgs, EXIT } 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 ──────────────────────────────────────────────────────
+// ── Modular commands ──────────────────────────────────────────────────────────
+import * as agentCmd from './commands/agent.js';
+import * as askCmd from './commands/ask.js';
 import * as fileCmd from './commands/file.js';
 import * as spaceCmd from './commands/space.js';
-import * as askCmd from './commands/ask.js';
+import * as searchCmd from './commands/search.js';
+import * as startCmd from './commands/start.js';
+import * as devCmd from './commands/dev.js';
+import * as stopCmd from './commands/stop.js';
+import * as restartCmd from './commands/restart.js';
+import * as buildCmd from './commands/build.js';
 import * as statusCmd from './commands/status.js';
+import * as openCmd from './commands/open.js';
+import * as mcpCmd from './commands/mcp-cmd.js';
+import * as tokenCmd from './commands/token.js';
+import * as syncCmd from './commands/sync-cmd.js';
+import * as gatewayCmd from './commands/gateway.js';
+import * as onboardCmd from './commands/onboard.js';
+import * as configCmd from './commands/config.js';
+import * as doctorCmd from './commands/doctor.js';
+import * as updateCmd from './commands/update.js';
+import * as uninstallCmd from './commands/uninstall.js';
+import * as logsCmd from './commands/logs.js';
 import * as apiCmd from './commands/api.js';
-import * as agentCmd from './commands/agent.js';
-import * as searchCmd from './commands/search.js';
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-/**
- * Dynamically resolve the new ROOT after `npm install -g`.
- * This is needed because constants are evaluated at module load time.
- */
-function getUpdatedRoot() {
-  try {
-    const mindosBin = execSync('which mindos', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
-    if (mindosBin) {
-      // mindos bin is usually at <root>/bin/cli.js or a symlink to it
-      let cliPath;
-      try {
-        cliPath = execSync(`readlink -f "${mindosBin}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
-      } catch {
-        try {
-          cliPath = execSync(`realpath "${mindosBin}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
-        } catch {
-          cliPath = mindosBin;
-        }
-      }
-      if (cliPath) {
-        // cliPath is like /path/to/node_modules/@geminilight/mindos/bin/cli.js
-        // ROOT is /path/to/node_modules/@geminilight/mindos
-        return resolve(dirname(cliPath), '..');
-      }
-    }
-  } catch {}
-  // Fallback to static ROOT
-  return ROOT;
-}
-
-/**
- * Build the app in the given root if the build stamp doesn't match the package version.
- * Used by `mindos update` to pre-build before restarting the daemon.
- */
-function buildIfNeeded(newRoot) {
-  // Check for prebuilt standalone first (npm package ships with it)
-  const standaloneServer = resolve(newRoot, '_standalone', 'server.js');
-  const standaloneStamp = resolve(newRoot, '_standalone', '.mindos-build-version');
-  if (existsSync(standaloneServer)) {
-    try {
-      const builtVersion = readFileSync(standaloneStamp, 'utf-8').trim();
-      const pkgVersion = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
-      if (builtVersion === pkgVersion) return; // prebuilt standalone matches, no build needed
-    } catch { /* fall through to legacy build */ }
+import * as initSkillsCmd from './commands/init-skills.js';
+
+// ── Command registry ──────────────────────────────────────────────────────────
+
+const modules = [
+  agentCmd, askCmd,
+  fileCmd, spaceCmd, searchCmd,
+  startCmd, devCmd, stopCmd, restartCmd, buildCmd, statusCmd, openCmd,
+  mcpCmd, tokenCmd,
+  syncCmd,
+  gatewayCmd,
+  onboardCmd, configCmd, doctorCmd, updateCmd, uninstallCmd, logsCmd, apiCmd,
+  initSkillsCmd,
+];
+
+const commands = {};
+for (const mod of modules) {
+  commands[mod.meta.name] = mod;
+  if (mod.meta.aliases) {
+    for (const alias of mod.meta.aliases) commands[alias] = mod;
   }
-
-  const newBuildStamp = resolve(newRoot, 'app', '.next', '.mindos-build-version');
-  const newNextBin = resolve(newRoot, 'app', 'node_modules', '.bin', 'next');
-
-  let needBuild = true;
-  try {
-    const builtVersion = readFileSync(newBuildStamp, 'utf-8').trim();
-    const pkgVersion = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
-    needBuild = builtVersion !== pkgVersion;
-  } catch {
-    needBuild = true;
-  }
-
-  if (!needBuild) return;
-
-  console.log(yellow('\n  Building MindOS (version change detected)...\n'));
-  const appPkg = resolve(newRoot, 'app', 'package.json');
-  if (existsSync(appPkg)) {
-    run('npm install', resolve(newRoot, 'app'));
-  }
-  const nextDir = resolve(newRoot, 'app', '.next');
-  if (existsSync(nextDir)) {
-    run(`rm -rf "${nextDir}"`, newRoot);
-  }
-  run('node scripts/gen-renderer-index.js', newRoot);
-  run(`${newNextBin} build`, resolve(newRoot, 'app'));
-  const version = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
-  writeFileSync(newBuildStamp, version, 'utf-8');
 }
 
-// ── Commands ──────────────────────────────────────────────────────────────────
+// ── Parse args ────────────────────────────────────────────────────────────────
 
-// ── Unified arg parsing ────────────────────────────────────────────────────
 const { command: cmd, args: cliArgs, flags: cliFlags } = parseArgs(process.argv.slice(2));
 
 if (cliFlags.version || cliFlags.v) {
@@ -181,1264 +71,138 @@ if (cliFlags.version || cliFlags.v) {
   process.exit(0);
 }
 
-// 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 = cliFlags['install-daemon'] ? ' --install-daemon' : '';
-    run(`node ${resolve(ROOT, 'scripts/setup.js')}${daemonFlag}`);
-  },
-  init:  async () => commands.onboard(),
-  setup: async () => commands.onboard(),
-
-  // ── open ───────────────────────────────────────────────────────────────────
-  open: () => {
-    loadConfig();
-    const webPort = process.env.MINDOS_WEB_PORT || '3456';
-    const url = `http://localhost:${webPort}`;
-    let cmd;
-    if (process.platform === 'darwin') {
-      cmd = 'open';
-    } else if (process.platform === 'linux') {
-      // WSL detection
-      try {
-        const uname = execSync('uname -r', { encoding: 'utf-8' });
-        cmd = uname.toLowerCase().includes('microsoft') ? 'wslview' : 'xdg-open';
-      } catch {
-        cmd = 'xdg-open';
-      }
-    } else {
-      cmd = 'start';
-    }
-    try {
-      execSync(`${cmd} ${url}`, { stdio: 'ignore' });
-      console.log(`${green('✔')} Opening ${cyan(url)}`);
-    } catch {
-      console.log(dim(`Could not open browser automatically. Visit: ${cyan(url)}`));
-    }
-  },
-
-  // ── token ──────────────────────────────────────────────────────────────────
-  token: () => {
-    if (!existsSync(CONFIG_PATH)) {
-      console.error(red('No config found. Run `mindos onboard` first.'));
-      process.exit(EXIT.ERROR);
-    }
-    let config = {};
-    try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {}
-    const token = config.authToken || '';
-    if (!token) {
-      console.log(dim('No auth token set. Run `mindos onboard` to configure one.'));
-      process.exit(0);
-    }
-    const mcpPort = config.mcpPort || 8781;
-    const localIP = getLocalIP();
-    const localUrl = `http://localhost:${mcpPort}/mcp`;
-
-    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) {
-      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'));
-  },
-
-  // ── dev ────────────────────────────────────────────────────────────────────
-  dev: async () => {
-    loadConfig();
-    if (!process.env.MINDOS_WEB_PORT) process.env.MINDOS_WEB_PORT = '3456';
-    if (!process.env.MINDOS_MCP_PORT) process.env.MINDOS_MCP_PORT = '8781';
-    process.env.MINDOS_CLI_PATH = resolve(ROOT, 'bin', 'cli.js');
-    process.env.MINDOS_NODE_BIN = process.execPath;
-    const webPort = process.env.MINDOS_WEB_PORT;
-    const mcpPort = process.env.MINDOS_MCP_PORT;
-    await assertPortFree(Number(webPort), 'web');
-    await assertPortFree(Number(mcpPort), 'mcp');
-    ensureAppDeps({ force: true }); // dev mode always needs app/node_modules
-    const mcp = spawnMcp(isVerbose);
-    savePids(process.pid, mcp.pid);
-    process.on('exit', () => { stopSyncDaemon().catch(() => {}); clearPids(); });
-    const devMindRoot = process.env.MIND_ROOT;
-    if (devMindRoot) {
-      startSyncDaemon(devMindRoot).catch(() => {});
-    }
-    await printStartupInfo(webPort, mcpPort);
-    run(`${NEXT_BIN} dev -p ${webPort} ${extra}`, resolve(ROOT, 'app'));
-  },
-
-  // ── start ──────────────────────────────────────────────────────────────────
-  start: async () => {
-    // Check for incomplete setup
-    if (existsSync(CONFIG_PATH)) {
-      try {
-        const cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-        if (cfg.setupPending === true) {
-          console.log(`\n  ${yellow('⚠ Setup was not completed.')} Run ${cyan('mindos onboard')} to finish, or ${cyan('mindos config set setupPending false')} to dismiss.\n`);
-        }
-      } catch {}
-    }
-    if (isDaemon) {
-      const platform = await getPlatform();
-      if (!platform) {
-        console.warn(yellow('Warning: daemon mode not supported on this platform. Falling back to foreground.'));
-      } else {
-        loadConfig();
-        if (!process.env.MINDOS_WEB_PORT) process.env.MINDOS_WEB_PORT = '3456';
-        if (!process.env.MINDOS_MCP_PORT) process.env.MINDOS_MCP_PORT = '8781';
-        const webPort = process.env.MINDOS_WEB_PORT;
-        const mcpPort = process.env.MINDOS_MCP_PORT;
-        console.log(cyan(`Installing MindOS as a background service (${platform})...`));
-        await runGatewayCommand('install');
-        // install() already starts the service via launchctl bootstrap + RunAtLoad=true.
-        // Do NOT call start() here — kickstart -k would kill the just-started process,
-        // causing a port-conflict race condition with KeepAlive restart loops.
-        console.log(dim('  (First run may take a few minutes to install dependencies and build the app.)'));
-        const ready = await waitForHttp(Number(webPort), { retries: 180, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
-        if (!ready) {
-          console.error(red('\n✘ Service started but Web UI did not become ready in time.'));
-          console.error(dim('  Check logs with: mindos logs\n'));
-          process.exit(EXIT.ERROR);
-        }
-        await printStartupInfo(webPort, mcpPort);
-        // System notification
-        try {
-          if (process.platform === 'darwin') {
-            execSync(`osascript -e 'display notification "http://localhost:${webPort}" with title "MindOS Ready"'`, { stdio: 'ignore' });
-          } else if (process.platform === 'linux') {
-            execSync(`notify-send "MindOS Ready" "http://localhost:${webPort}"`, { stdio: 'ignore' });
-          }
-        } catch { /* notification is best-effort */ }
-        console.log(`${green('✔ MindOS is running as a background service')}`);
-        console.log(dim('  View logs:    mindos logs'));
-        console.log(dim('  Stop:         mindos gateway stop'));
-        console.log(dim('  Uninstall:    mindos gateway uninstall\n'));
-        return;
-      }
-    }
-    loadConfig();
-    if (!process.env.MINDOS_WEB_PORT) process.env.MINDOS_WEB_PORT = '3456';
-    if (!process.env.MINDOS_MCP_PORT) process.env.MINDOS_MCP_PORT = '8781';
-    const webPort = process.env.MINDOS_WEB_PORT;
-    const mcpPort = process.env.MINDOS_MCP_PORT;
-
-    // Clean up zombie processes from an abandoned GUI setup session.
-    // setup.js records a temporary port (setupPort) in config; if the user
-    // closed the browser without completing setup, that process is still
-    // running.  Kill it before we proceed.
-    // Also read config for auto-migration below (avoids double readFileSync).
-    let startupCfg = {};
-    try { startupCfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {}
-    if (startupCfg.setupPort && Number(startupCfg.setupPort) !== Number(webPort)) {
-      killByPort(Number(startupCfg.setupPort));
-    }
-
-    // ── Auto-migrate user preferences → .mindos/user-preferences.md ────────
-    try {
-      const mr = startupCfg.mindRoot;
-      if (mr && existsSync(mr)) {
-        const mindosDir = resolve(mr, '.mindos');
-        const newPath = resolve(mindosDir, 'user-preferences.md');
-
-        if (!existsSync(newPath)) {
-          // Ensure .mindos/ directory exists
-          if (!existsSync(mindosDir)) mkdirSync(mindosDir, { recursive: true });
-
-          // Try migrate from previous locations (newest → oldest)
-          const prevPaths = [
-            resolve(mindosDir, 'user-rules.md'),                    // v0.6.x interim
-            resolve(mr, 'user-skill-rules.md'),                     // v0.5.x root
-          ];
-          let migrated = false;
-          for (const prev of prevPaths) {
-            if (existsSync(prev)) {
-              cpSync(prev, newPath);
-              unlinkSync(prev);
-              console.log(`  ${green('✓')} ${dim(`Migrated ${prev.split('/').pop()} → .mindos/user-preferences.md`)}`);
-              migrated = true;
-              break;
-            }
-          }
-          if (!migrated) {
-            // Try legacy location (.agents/skills/{name}/user-rules.md)
-            const isZh = startupCfg.disabledSkills?.includes('mindos');
-            const sName = isZh ? 'mindos-zh' : 'mindos';
-            const oldPath = resolve(mr, '.agents', 'skills', sName, 'user-rules.md');
-            if (existsSync(oldPath)) {
-              cpSync(oldPath, newPath);
-              console.log(`  ${green('✓')} ${dim('Migrated .agents/skills/ user-rules.md → .mindos/user-preferences.md')}`);
-            }
-          }
-        }
-      }
-    } catch { /* best-effort, don't block startup */ }
-
-    // When launched by a daemon manager (launchd/systemd), wait for ports to
-    // free instead of exiting immediately — the previous instance may still be
-    // shutting down after a restart/update.
-    const launchedByDaemon = process.env.LAUNCHED_BY_LAUNCHD === '1'
-      || !!process.env.INVOCATION_ID; /* systemd sets INVOCATION_ID */
-
-    if (launchedByDaemon) {
-      const webOk = await waitForPortFree(Number(webPort), { retries: 60, intervalMs: 500 });
-      const mcpOk = await waitForPortFree(Number(mcpPort), { retries: 60, intervalMs: 500 });
-      if (!webOk || !mcpOk) {
-        console.error('Ports still in use after 30s, exiting.');
-        process.exit(EXIT.ERROR);  // KeepAlive will retry after ThrottleInterval
-      }
-    } else {
-      await assertPortFree(Number(webPort), 'web');
-      await assertPortFree(Number(mcpPort), 'mcp');
-    }
-    process.env.MINDOS_CLI_PATH = resolve(ROOT, 'bin', 'cli.js');
-    process.env.MINDOS_NODE_BIN = process.execPath;
-    ensureAppDeps();
-    if (needsBuild()) {
-      console.log(yellow('Building MindOS (first run or new version detected)...\n'));
-      cleanNextDir();
-      run('node scripts/gen-renderer-index.js', ROOT);
-      run(`${NEXT_BIN} build --webpack`, resolve(ROOT, 'app'));
-      writeBuildStamp();
-    }
-    const mcp = spawnMcp(isVerbose);
-    savePids(process.pid, mcp.pid);
-    process.on('exit', () => { stopSyncDaemon().catch(() => {}); clearPids(); });
-    // Start sync daemon if enabled
-    const mindRoot = process.env.MIND_ROOT;
-    if (mindRoot) {
-      startSyncDaemon(mindRoot).catch(() => {});
-    }
-    await printStartupInfo(webPort, mcpPort);
-    // Prefer prebuilt standalone server (shipped with npm package) over next start.
-    // Standalone includes its own traced node_modules — no app/node_modules needed.
-    if (hasPrebuiltStandalone()) {
-      const standaloneServer = resolve(ROOT, '_standalone', 'server.js');
-      try {
-        execFileSync(process.execPath, [standaloneServer], {
-          cwd: resolve(ROOT, '_standalone'),
-          stdio: 'inherit',
-          env: { ...process.env, NODE_ENV: 'production', HOSTNAME: process.env.MINDOS_WEB_HOST || '0.0.0.0', PORT: webPort },
-        });
-      } catch (err) {
-        process.exit(err.status || 1);
-      }
-    } else {
-      run(
-        `${NEXT_BIN} start -p ${webPort} ${extra}`,
-        resolve(ROOT, 'app'),
-        { HOSTNAME: process.env.MINDOS_WEB_HOST || '0.0.0.0' }
-      );
-    }
-  },
-
-  // ── build ──────────────────────────────────────────────────────────────────
-  build: () => {
-    ensureAppDeps({ force: true }); // build always needs app/node_modules
-    cleanNextDir();
-    run('node scripts/gen-renderer-index.js', ROOT);
-    run(`${NEXT_BIN} build --webpack ${extra}`, resolve(ROOT, 'app'));
-    writeBuildStamp();
-  },
-
-  mcp: async () => {
-    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();
-    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.
-    if (!process.env.MCP_TRANSPORT) {
-      process.env.MCP_TRANSPORT = 'stdio';
-    }
-    const webPort = process.env.MINDOS_WEB_PORT || '3456';
-    process.env.MINDOS_URL = process.env.MINDOS_URL || `http://localhost:${webPort}`;
-    // Only set MCP_PORT for HTTP mode (stdio doesn't bind any port)
-    if (process.env.MCP_TRANSPORT === 'http') {
-      process.env.MCP_PORT = process.env.MINDOS_MCP_PORT || '8781';
-    }
-    run(`node dist/index.cjs`, resolve(ROOT, 'mcp'));
-  },
-
-  // ── stop / restart ─────────────────────────────────────────────────────────
-  stop: () => stopMindos(),
-
-  restart: async () => {
-    // Capture old ports BEFORE loadConfig overwrites env vars, so we can
-    // clean up processes that are still listening on the previous ports
-    // (e.g. user changed ports in the GUI and config was already saved).
-    // Sources: (1) MINDOS_OLD_* set by /api/restart when it strips the
-    //              current env, (2) current MINDOS_*_PORT env vars.
-    const oldWebPort = process.env.MINDOS_OLD_WEB_PORT || process.env.MINDOS_WEB_PORT;
-    const oldMcpPort = process.env.MINDOS_OLD_MCP_PORT || process.env.MINDOS_MCP_PORT;
-
-    loadConfig();
-
-    // After loadConfig, env vars reflect the NEW config (or old if unchanged).
-    const newWebPort = Number(process.env.MINDOS_WEB_PORT || '3456');
-    const newMcpPort = Number(process.env.MINDOS_MCP_PORT || '8781');
-
-    // Collect old ports that differ from new ones — processes may still be
-    // listening there even though config already points to the new ports.
-    const extraPorts = [];
-    if (oldWebPort && Number(oldWebPort) !== newWebPort) extraPorts.push(oldWebPort);
-    if (oldMcpPort && Number(oldMcpPort) !== newMcpPort) extraPorts.push(oldMcpPort);
-
-    stopMindos({ extraPorts });
-
-    // Wait until ALL ports (old + new) are actually free (up to 15s)
-    const allPorts = new Set([newWebPort, newMcpPort]);
-    for (const p of extraPorts) allPorts.add(Number(p));
-
-    const deadline = Date.now() + 15_000;
-    while (Date.now() < deadline) {
-      let anyBusy = false;
-      for (const p of allPorts) {
-        if (await isPortInUse(p)) { anyBusy = true; break; }
-      }
-      if (!anyBusy) break;
-      await new Promise((r) => setTimeout(r, 500));
-    }
-    await commands[getStartMode()]();
-  },
-
-  // ── gateway ────────────────────────────────────────────────────────────────
-  gateway: async () => {
-    const sub = cliArgs[0];
-    if (!sub) {
-      const row = (c, d) => `  ${cyan(c.padEnd(32))}${dim(d)}`;
-      console.log(`
-${bold('mindos gateway')} — manage MindOS as a background OS service
-
-${bold('Subcommands:')}
-${row('mindos gateway install',   'Install and enable the service (systemd/launchd)')}
-${row('mindos gateway uninstall', 'Disable and remove the service')}
-${row('mindos gateway start',     'Start the service')}
-${row('mindos gateway stop',      'Stop the service')}
-${row('mindos gateway status',    'Show service status')}
-${row('mindos gateway logs',      'Tail service logs')}
-
-${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
-`);
-      return;
-    }
-    await runGatewayCommand(sub);
-  },
-
-  // ── init-skills ──────────────────────────────────────────────────────────
-  'init-skills': async () => {
-    console.log(`\n${bold('📦 Initialize Skill Rules')}\n`);
-
-    if (!existsSync(CONFIG_PATH)) {
-      console.log(`  ${red('✘')} Config not found. Run ${cyan('mindos onboard')} first.\n`);
-      process.exit(EXIT.ERROR);
-    }
-    let config;
-    try {
-      config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-    } catch {
-      console.log(`  ${red('✘')} Failed to parse config at ${dim(CONFIG_PATH)}\n`);
-      process.exit(EXIT.ERROR);
-    }
-    const mindRoot = config.mindRoot;
-    if (!mindRoot || !existsSync(mindRoot)) {
-      console.log(`  ${red('✘')} Knowledge base not found: ${dim(mindRoot || '(not set)')}\n`);
-      process.exit(EXIT.ERROR);
-    }
-
-    // Skill operating rules are now built into SKILL.md (shipped with the app).
-    // This command only initializes .mindos/user-preferences.md for personalization.
-    const mindosDir = resolve(mindRoot, '.mindos');
-    const dest = resolve(mindosDir, 'user-preferences.md');
-    if (existsSync(dest)) {
-      console.log(`  ${dim('skip')}  .mindos/user-preferences.md (already exists)\n`);
-    } else {
-      if (!existsSync(mindosDir)) mkdirSync(mindosDir, { recursive: true });
-      const isZh = config.disabledSkills?.includes('mindos');
-      const lang = isZh ? 'zh' : 'en';
-      const src = resolve(ROOT, 'templates', 'skill-rules', lang, 'user-rules.md');
-      if (existsSync(src)) {
-        cpSync(src, dest);
-        console.log(`  ${green('✓')}  .mindos/user-preferences.md created at ${dim(mindosDir)}\n`);
-      } else {
-        console.log(`  ${dim('skip')}  Template not found, create .mindos/user-preferences.md manually if needed.\n`);
-      }
-    }
-    console.log(`  ${dim('Note: Operating rules are now built into the app. No install needed.')}\n`);
-  },
-
-  // ── doctor ─────────────────────────────────────────────────────────────────
-  doctor: async () => {
-    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}`); };
-
-    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)}`, '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(EXIT.ERROR);
-    }
-    let config;
-    try {
-      config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-      ok(`Config file found and valid JSON  ${dim(CONFIG_PATH)}`, 'config');
-    } catch {
-      err(`Config file exists but failed to parse  ${dim(CONFIG_PATH)}`, 'config');
-      hasError = true;
-    }
-
-    // 2. mindRoot
-    if (config) {
-      const mindRoot = config.mindRoot;
-      if (!mindRoot) {
-        err('Config missing required field: mindRoot');
-        hasError = true;
-      } else if (!existsSync(mindRoot.replace(/^~/, homedir()))) {
-        warn(`mindRoot path does not exist: ${dim(mindRoot)}  (will be created on first start)`);
-      } else {
-        ok(`Knowledge base path exists  ${dim(mindRoot)}`);
-      }
-    }
-
-    // 3. AI config
-    if (config) {
-      const provider = config.ai?.provider;
-      const providers = config.ai?.providers;
-      const hasAnthropic = providers?.anthropic?.apiKey || config.ai?.anthropicApiKey;
-      const hasOpenai    = providers?.openai?.apiKey    || config.ai?.openaiApiKey;
-      if (!provider) {
-        warn('AI provider not configured (run `mindos onboard` to set up)');
-      } else if (provider === 'anthropic' && !hasAnthropic) {
-        err('AI provider is "anthropic" but no API key found');
-        hasError = true;
-      } else if (provider === 'openai' && !hasOpenai) {
-        err('AI provider is "openai" but no API key found');
-        hasError = true;
-      } else {
-        ok(`AI provider configured  ${dim(provider)}`);
-      }
-    }
-
-    // 4. Node version
-    const nodeVersion = process.versions.node;
-    const [nodeMajor] = nodeVersion.split('.').map(Number);
-    if (nodeMajor < 18) {
-      err(`Node.js ${nodeVersion} is below minimum required (18+)`);
-      hasError = true;
-    } else {
-      ok(`Node.js ${nodeVersion}`);
-    }
-
-    // 4b. npm reachable from /bin/sh
-    try {
-      const npmVersion = execSync('npm --version', { stdio: 'pipe' }).toString().trim();
-      ok(`npm ${npmVersion} reachable`);
-    } catch {
-      err('npm not found in PATH — app dependencies cannot be installed');
-      console.log(dim('     Node.js may be installed via nvm/fnm/volta and not visible to /bin/sh.'));
-      console.log(dim('     Fix: add your Node.js bin path to ~/.profile so non-interactive shells can find it.'));
-      hasError = true;
-    }
-
-    // 5. Build
-    if (hasPrebuiltStandalone()) {
-      ok('Production build is up to date (prebuilt standalone)');
-    } else if (!existsSync(resolve(ROOT, 'app', '.next'))) {
-      warn(`App not built yet — will build automatically on next ${dim('mindos start')}`);
-    } else if (needsBuild()) {
-      warn(`Build is outdated — will rebuild automatically on next ${dim('mindos start')}`);
-    } else {
-      ok('Production build is up to date');
-    }
-
-    // 6. Ports
-    const webPort = Number(config?.port || process.env.MINDOS_WEB_PORT || 3456);
-    const mcpPort = Number(config?.mcpPort || process.env.MINDOS_MCP_PORT || 8781);
-    const webInUse = await isPortInUse(webPort);
-    const mcpInUse = await isPortInUse(mcpPort);
-    if (webInUse) {
-      ok(`Web server is listening on port ${webPort}`);
-    } else {
-      warn(`Web server is not running on port ${webPort}`);
-    }
-    if (mcpInUse) {
-      ok(`MCP server is listening on port ${mcpPort}`);
-    } else {
-      warn(`MCP server is not running on port ${mcpPort}`);
-    }
-
-    // 7. Daemon status
-    const platform = await getPlatform();
-    if (platform === 'systemd') {
-      try {
-        execSync('systemctl --user is-active mindos', { stdio: 'pipe' });
-        ok('Systemd service mindos is active');
-      } catch {
-        warn('Systemd service mindos is not active  (run `mindos gateway start` to start)');
-      }
-    } else if (platform === 'launchd') {
-      try {
-        const uid = execSync('id -u').toString().trim();
-        execSync(`launchctl print gui/${uid}/com.mindos.app`, { stdio: 'pipe' });
-        ok('LaunchAgent com.mindos.app is loaded');
-      } catch {
-        warn('LaunchAgent com.mindos.app is not loaded  (run `mindos gateway start` to start)');
-      }
-    }
-
-    // 8. Sync status
-    if (config?.mindRoot) {
-      try {
-        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) {
-          err(`Sync error: ${syncStatus.lastError}`);
-          hasError = true;
-        } else if (syncStatus.conflicts && syncStatus.conflicts.length > 0) {
-          warn(`Sync has ${syncStatus.conflicts.length} unresolved conflict(s)  ${dim('(run `mindos sync conflicts` to view)')}`);
-        } else {
-          const unpushed = parseInt(syncStatus.unpushed || '0', 10);
-          const extra = unpushed > 0 ? `  ${dim(`(${unpushed} unpushed commit(s))`)}` : '';
-          ok(`Sync enabled  ${dim(syncStatus.remote || 'origin')}${extra}`);
-        }
-      } catch {
-        warn('Could not check sync status');
-      }
-    }
-
-    // 9. Update check
-    try {
-      const { checkForUpdate } = await import('./lib/update-check.js');
-      const latestVersion = await Promise.race([
-        checkForUpdate(),
-        new Promise(r => setTimeout(() => r(null), 4000)),
-      ]);
-      if (latestVersion) {
-        const currentVersion = (() => { try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; } })();
-        warn(`Update available: v${currentVersion} → ${bold(`v${latestVersion}`)}  ${dim('run `mindos update`')}`);
-      } else {
-        ok('MindOS is up to date');
-      }
-    } catch {
-      warn('Could not check for updates');
-    }
-
-    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(EXIT.ERROR);
-  },
-
-  // ── update ─────────────────────────────────────────────────────────────────
-  update: async () => {
-    const { writeUpdateStatus, writeUpdateFailed, clearUpdateStatus } = await import('./lib/update-status.js');
-    const currentVersion = (() => {
-      try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; }
-    })();
-    console.log(`\n${bold('⬆  Updating MindOS...')}  ${dim(`(current: ${currentVersion})`)}\n`);
-
-    // Stage 1: Download
-    writeUpdateStatus('downloading', { fromVersion: currentVersion });
-    try {
-      execSync('npm install -g @geminilight/mindos@latest', { stdio: 'inherit' });
-    } catch {
-      writeUpdateFailed('downloading', 'npm install failed', { fromVersion: currentVersion });
-      console.error(red('Update failed. Try: npm install -g @geminilight/mindos@latest'));
-      process.exit(EXIT.ERROR);
-    }
-    if (existsSync(BUILD_STAMP)) rmSync(BUILD_STAMP);
-
-    // Resolve the new installation path (after npm install -g, ROOT is stale)
-    const updatedRoot = getUpdatedRoot();
-    const newVersion = (() => {
-      try { return JSON.parse(readFileSync(resolve(updatedRoot, 'package.json'), 'utf-8')).version; } catch { return '?'; }
-    })();
-    const vOpts = { fromVersion: currentVersion, toVersion: newVersion };
-
-    // Stage 2: Skills
-    writeUpdateStatus('skills', vOpts);
-    try {
-      const { checkSkillVersions, updateSkill } = await import('./lib/skill-check.js');
-      const mismatches = checkSkillVersions(updatedRoot);
-      for (const m of mismatches) {
-        updateSkill(m.bundledPath, m.installPath);
-        console.log(`  ${green('✓')} ${dim(`Skill ${m.name}: v${m.installed} → v${m.bundled}`)}`);
-      }
-    } catch { /* best-effort */ }
-
-    if (newVersion !== currentVersion) {
-      console.log(`\n${green(`✔ Updated ${currentVersion} → ${newVersion}`)}`);
-    } else {
-      console.log(`\n${green('✔ Already on the latest version')} ${dim(`(${currentVersion})`)}\n`);
-      return;
-    }
-
-    const updatePlatform = await getPlatform();
-    let daemonRunning = false;
-    if (updatePlatform === 'systemd') {
-      try { execSync('systemctl --user is-active mindos', { stdio: 'pipe' }); daemonRunning = true; } catch {}
-    } else if (updatePlatform === 'launchd') {
-      try {
-        const uid = execSync('id -u').toString().trim();
-        execSync(`launchctl print gui/${uid}/com.mindos.app`, { stdio: 'pipe' });
-        daemonRunning = true;
-      } catch {}
-    }
-
-    if (daemonRunning) {
-      console.log(cyan('\n  Daemon is running — stopping to apply the new version...'));
-      await runGatewayCommand('stop');
-
-      // Stage 3: Rebuild
-      writeUpdateStatus('rebuilding', vOpts);
-      let daemonBuildFailed = '';
-      try {
-        buildIfNeeded(updatedRoot);
-      } catch (err) {
-        daemonBuildFailed = err instanceof Error ? err.message : String(err);
-        console.error(yellow(`\n  Pre-build failed: ${daemonBuildFailed}`));
-        console.error(yellow('  Daemon will attempt to rebuild on startup...\n'));
-      }
-
-      // Stage 4: Restart — always attempt, even if pre-build failed
-      // (daemon has auto-restart; `mindos start` retries the build)
-      writeUpdateStatus('restarting', vOpts);
-      await runGatewayCommand('install');
-      const updateConfig = (() => {
-        try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { return {}; }
-      })();
-      const webPort = updateConfig.port ?? 3456;
-      const mcpPort = updateConfig.mcpPort ?? 8781;
-      console.log(dim('  (Waiting for Web UI to come back up — first run after update includes a rebuild...)'));
-      const ready = await waitForHttp(Number(webPort), { retries: 450, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
-      if (ready) {
-        const localIP = getLocalIP();
-        console.log(`\n${'─'.repeat(53)}`);
-        console.log(`${green('✔')} ${bold(`MindOS updated: ${currentVersion} → ${newVersion}`)}\n`);
-        console.log(`  ${green('●')} Web UI   ${cyan(`http://localhost:${webPort}`)}`);
-        if (localIP) console.log(`             ${cyan(`http://${localIP}:${webPort}`)}`);
-        console.log(`  ${green('●')} MCP      ${cyan(`http://localhost:${mcpPort}/mcp`)}`);
-        console.log(`\n  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}`);
-        console.log(`${'─'.repeat(53)}\n`);
-        writeUpdateStatus('done', vOpts);
-      } else {
-        const failMsg = daemonBuildFailed
-          ? `Build failed (${daemonBuildFailed}), server did not come back up`
-          : 'Server did not come back up in time';
-        writeUpdateFailed('restarting', failMsg, vOpts);
-        console.error(red(`✘ ${failMsg}. Check logs: mindos logs\n`));
-        process.exit(EXIT.ERROR);
-      }
-    } else {
-      // Non-daemon mode: check if a MindOS instance is currently running
-      // (e.g. user started via `mindos start`, or GUI triggered this update).
-      // If so, stop it and restart from the NEW installation path.
-      const updateConfig = (() => {
-        try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { return {}; }
-      })();
-      const webPort = Number(updateConfig.port ?? 3456);
-      const mcpPort = Number(updateConfig.mcpPort ?? 8781);
-
-      const wasRunning = await isPortInUse(webPort) || await isPortInUse(mcpPort);
-
-      if (wasRunning) {
-        console.log(cyan('\n  MindOS is running — restarting to apply the new version...'));
-        stopMindos();
-        // Wait for ports to free (up to 15s)
-        const deadline = Date.now() + 15_000;
-        while (Date.now() < deadline) {
-          const busy = await isPortInUse(webPort) || await isPortInUse(mcpPort);
-          if (!busy) break;
-          await new Promise((r) => setTimeout(r, 500));
-        }
-
-        // Stage 3: Rebuild
-        writeUpdateStatus('rebuilding', vOpts);
-        let buildFailed = '';
-        try {
-          buildIfNeeded(updatedRoot);
-        } catch (err) {
-          buildFailed = err instanceof Error ? err.message : String(err);
-          console.error(yellow(`\n  Pre-build failed: ${buildFailed}`));
-          console.error(yellow('  Starting server anyway (it will retry the build)...\n'));
-        }
-
-        // Stage 4: Restart — always attempt, even if pre-build failed
-        // (`mindos start` has its own build-on-startup logic)
-        writeUpdateStatus('restarting', vOpts);
-        const newCliPath = resolve(updatedRoot, 'bin', 'cli.js');
-        const childEnv = { ...process.env };
-        delete childEnv.MINDOS_WEB_PORT;
-        delete childEnv.MINDOS_MCP_PORT;
-        delete childEnv.MIND_ROOT;
-        delete childEnv.AUTH_TOKEN;
-        delete childEnv.WEB_PASSWORD;
-        const child = nodeSpawn(
-          process.execPath, [newCliPath, 'start'],
-          { detached: true, stdio: 'ignore', env: childEnv },
-        );
-        child.unref();
-
-        console.log(dim('  (Waiting for Web UI to come back up...)'));
-        const ready = await waitForHttp(webPort, { retries: 180, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
-        if (ready) {
-          const localIP = getLocalIP();
-          console.log(`\n${'─'.repeat(53)}`);
-          console.log(`${green('✔')} ${bold(`MindOS updated: ${currentVersion} → ${newVersion}`)}\n`);
-          console.log(`  ${green('●')} Web UI   ${cyan(`http://localhost:${webPort}`)}`);
-          if (localIP) console.log(`             ${cyan(`http://${localIP}:${webPort}`)}`);
-          console.log(`  ${green('●')} MCP      ${cyan(`http://localhost:${mcpPort}/mcp`)}`);
-          console.log(`\n  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}`);
-          console.log(`${'─'.repeat(53)}\n`);
-          writeUpdateStatus('done', vOpts);
-        } else {
-          const failMsg = buildFailed
-            ? `Build failed (${buildFailed}), server did not come back up`
-            : 'Server did not come back up in time';
-          writeUpdateFailed('restarting', failMsg, vOpts);
-          console.error(red(`✘ ${failMsg}. Check logs: mindos logs\n`));
-          process.exit(EXIT.ERROR);
-        }
-      } else {
-        // No running instance — just build and tell user to start manually
-        try {
-          buildIfNeeded(updatedRoot);
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          console.error(yellow(`\n  Pre-build failed: ${msg}`));
-          console.error(dim('  The build will be retried when you run `mindos start`.'));
-        }
-        console.log(`\n${green('✔')} ${bold(`Updated: ${currentVersion} → ${newVersion}`)}`);
-        console.log(dim('  Run `mindos start` to start the updated version.'));
-        console.log(`  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}\n`);
-      }
-    }
-  },
-
-  // ── uninstall ───────────────────────────────────────────────────────────────
-  uninstall: async () => {
-    const readline = await import('node:readline');
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-    // Buffer lines eagerly — readline.question() loses buffered lines when
-    // piped stdin delivers multiple lines at once (Node.js known behavior).
-    const lineBuffer = [];
-    let lineResolve = null;
-    rl.on('line', (line) => {
-      if (lineResolve) {
-        const r = lineResolve;
-        lineResolve = null;
-        r(line);
-      } else {
-        lineBuffer.push(line);
-      }
-    });
-    // On EOF with no pending resolve, close gracefully
-    rl.on('close', () => {
-      if (lineResolve) { lineResolve(''); lineResolve = null; }
-    });
-
-    function prompt(question) {
-      process.stdout.write(question + ' ');
-      if (lineBuffer.length > 0) return Promise.resolve(lineBuffer.shift());
-      return new Promise((resolve) => { lineResolve = resolve; });
-    }
-
-    async function confirm(question) {
-      const a = (await prompt(question + ' [y/N]')).trim().toLowerCase();
-      return a === 'y' || a === 'yes';
-    }
-
-    async function askInput(question) {
-      return (await prompt(question)).trim();
-    }
-
-    async function askPassword(question) {
-      // Mute echoed keystrokes
-      const stdout = process.stdout;
-      const origWrite = stdout.write.bind(stdout);
-      stdout.write = (chunk, ...args) => {
-        // Suppress everything except the prompt itself
-        if (typeof chunk === 'string' && chunk.includes(question)) return origWrite(chunk, ...args);
-        return true;
-      };
-      const answer = await prompt(question);
-      stdout.write = origWrite;
-      console.log(); // newline after hidden input
-      return answer.trim();
-    }
-
-    const done = () => rl.close();
-
-    console.log(`\n${bold('🗑  MindOS Uninstall')}\n`);
-    console.log('  This will:');
-    console.log(`  ${green('✓')} Stop running MindOS processes`);
-    console.log(`  ${green('✓')} Remove background service (if installed)`);
-    console.log(`  ${green('✓')} Uninstall npm package\n`);
-
-    if (!await confirm('Proceed?')) {
-      console.log(dim('\n  Aborted.\n'));
-      done();
-      return;
-    }
-
-    // 1. Stop processes
-    console.log(`\n${cyan('Stopping MindOS...')}`);
-    try { stopMindos(); } catch { /* may not be running */ }
-
-    // 2. Remove daemon (skip if platform unsupported)
-    if (await getPlatform()) {
-      try {
-        await runGatewayCommand('uninstall');
-      } catch {
-        // Daemon may not be installed — that's fine
-      }
-    }
-
-    // Read config before potentially deleting ~/.mindos/
-    let config = {};
-    try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {}
-    const mindRoot = config.mindRoot?.replace(/^~/, homedir());
-
-    // 3. Ask to remove ~/.mindos/
-    if (existsSync(MINDOS_DIR)) {
-      if (await confirm(`Remove config directory (${dim(MINDOS_DIR)})?`)) {
-        rmSync(MINDOS_DIR, { recursive: true, force: true });
-        console.log(`${green('✔')} Removed ${dim(MINDOS_DIR)}`);
-      } else {
-        console.log(dim(`  Kept ${MINDOS_DIR}`));
-      }
-    }
-
-    // 4. Ask to remove knowledge base (triple protection: confirm → type YES → password)
-    if (mindRoot && existsSync(mindRoot)) {
-      if (await confirm(`Remove knowledge base (${dim(mindRoot)})?`)) {
-        const typed = await askInput(`${yellow('⚠  This is irreversible.')} Type ${bold('YES')} to confirm:`);
-        if (typed === 'YES') {
-          const webPassword = config.webPassword;
-          let authorized = true;
-          if (webPassword) {
-            const pw = await askPassword('Enter web password:');
-            if (pw !== webPassword) {
-              console.log(red('  Wrong password. Knowledge base kept.'));
-              authorized = false;
-            }
-          }
-          if (authorized) {
-            rmSync(mindRoot, { recursive: true, force: true });
-            console.log(`${green('✔')} Removed ${dim(mindRoot)}`);
-          }
-        } else {
-          console.log(dim('  Knowledge base kept.'));
-        }
-      } else {
-        console.log(dim(`  Kept ${mindRoot}`));
-      }
-    }
-
-    // 5. npm uninstall -g
-    console.log(`\n${cyan('Uninstalling npm package...')}`);
-    try {
-      execSync('npm uninstall -g @geminilight/mindos', { stdio: ['ignore', 'inherit', 'inherit'] });
-    } catch {
-      console.log(yellow('  npm uninstall failed — you may need to run manually:'));
-      console.log(dim('  npm uninstall -g @geminilight/mindos'));
-    }
-
-    console.log(`\n${green('✔ MindOS uninstalled.')}\n`);
-    done();
-  },
-
-  // ── logs ───────────────────────────────────────────────────────────────────
-  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 = cliFlags['no-follow'] === true;
-    if (noFollow) {
-      execSync(`tail -n 100 ${LOG_PATH}`, { stdio: 'inherit' });
-    } else {
-      execSync(`tail -f ${LOG_PATH}`, { stdio: 'inherit' });
-    }
-  },
-
-  // ── config ─────────────────────────────────────────────────────────────────
-  config: () => {
-    const sub = cliArgs[0];
-
-    function maskKey(val) {
-      if (!val) return val;
-      if (val.length <= 8) return '****';
-      return val.slice(0, 6) + '****';
-    }
-
-    if (sub === 'show') {
-      if (!existsSync(CONFIG_PATH)) {
-        console.error(red('No config found. Run `mindos onboard` first.'));
-        process.exit(EXIT.ERROR);
-      }
-      let config;
-      try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {
-        console.error(red('Failed to parse config file.'));
-        process.exit(EXIT.ERROR);
-      }
-      const display = JSON.parse(JSON.stringify(config));
-      if (display.ai?.providers?.anthropic?.apiKey)
-        display.ai.providers.anthropic.apiKey = maskKey(display.ai.providers.anthropic.apiKey);
-      if (display.ai?.providers?.openai?.apiKey)
-        display.ai.providers.openai.apiKey = maskKey(display.ai.providers.openai.apiKey);
-      if (display.ai?.anthropicApiKey)
-        display.ai.anthropicApiKey = maskKey(display.ai.anthropicApiKey);
-      if (display.ai?.openaiApiKey)
-        display.ai.openaiApiKey = maskKey(display.ai.openaiApiKey);
-      if (display.authToken)
-        display.authToken = maskKey(display.authToken);
-      if (display.webPassword)
-        display.webPassword = maskKey(display.webPassword);
-      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;
-    }
-
-    if (sub === 'validate') {
-      if (!existsSync(CONFIG_PATH)) {
-        console.error(red('No config found. Run `mindos onboard` first.'));
-        process.exit(EXIT.ERROR);
-      }
-      let config;
-      try {
-        config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-      } catch (e) {
-        console.error(red(`✘ Invalid JSON: ${e.message}`));
-        process.exit(EXIT.ERROR);
-      }
-      const issues = [];
-      if (!config.mindRoot) issues.push('missing required field: mindRoot');
-      if (!config.ai?.provider) issues.push('missing field: ai.provider');
-      if (config.ai?.provider === 'anthropic') {
-        const key = config.ai?.providers?.anthropic?.apiKey || config.ai?.anthropicApiKey;
-        if (!key) issues.push('ai.provider is "anthropic" but no API key found');
-      }
-      if (config.ai?.provider === 'openai') {
-        const key = config.ai?.providers?.openai?.apiKey || config.ai?.openaiApiKey;
-        if (!key) issues.push('ai.provider is "openai" but no API key found');
-      }
-      if (issues.length) {
-        console.error(`\n${red('✘ Config has issues:')}`);
-        issues.forEach(i => console.error(`  ${red('•')} ${i}`));
-        console.error(`\n  ${dim('Run `mindos onboard` to fix.\n')}`);
-        process.exit(EXIT.ERROR);
-      }
-      console.log(`\n${green('✔ Config is valid')}\n`);
-      return;
-    }
-
-    if (sub === 'set') {
-      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:'));
-        console.error(dim('    mindos config set port 3002'));
-        console.error(dim('    mindos config set mcpPort 8788'));
-        console.error(dim('    mindos config set ai.provider openai'));
-        process.exit(EXIT.ARGS);
-      }
-      if (!existsSync(CONFIG_PATH)) {
-        console.error(red('No config found. Run `mindos onboard` first.'));
-        process.exit(EXIT.ERROR);
-      }
-      let config;
-      try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {
-        console.error(red('Failed to parse config file.'));
-        process.exit(EXIT.ERROR);
-      }
-      const parts = key.split('.');
-      let obj = config;
-      for (let i = 0; i < parts.length - 1; i++) {
-        if (typeof obj[parts[i]] !== 'object' || !obj[parts[i]]) obj[parts[i]] = {};
-        obj = obj[parts[i]];
-      }
-      // Coerce string values to appropriate types
-      function coerceValue(v) {
-        if (v === 'true') return true;
-        if (v === 'false') return false;
-        if (v === 'null') return null;
-        if (v === '""' || v === "''") return '';
-        if (v.trim() !== '' && !isNaN(Number(v))) return Number(v);
-        return v;
-      }
-      const coerced = coerceValue(val);
-      obj[parts[parts.length - 1]] = coerced;
-      writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
-      console.log(`${green('✔')} Set ${cyan(key)} = ${bold(String(coerced))}`);
-      return;
-    }
-
-    if (sub === 'unset') {
-      const key = cliArgs[1];
-      if (!key) {
-        console.error(red('Usage: mindos config unset <key>'));
-        process.exit(EXIT.ARGS);
-      }
-      if (!existsSync(CONFIG_PATH)) {
-        console.error(red('No config found. Run `mindos onboard` first.'));
-        process.exit(EXIT.ERROR);
-      }
-      let config;
-      try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {
-        console.error(red('Failed to parse config file.'));
-        process.exit(EXIT.ERROR);
-      }
-      const parts = key.split('.');
-      let obj = config;
-      for (let i = 0; i < parts.length - 1; i++) {
-        if (!obj[parts[i]]) { console.log(dim(`Key "${key}" not found`)); return; }
-        obj = obj[parts[i]];
-      }
-      if (!(parts[parts.length - 1] in obj)) { console.log(dim(`Key "${key}" not found`)); return; }
-      delete obj[parts[parts.length - 1]];
-      writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
-      console.log(`${green('✔')} Removed ${cyan(key)}`);
-      return;
-    }
-
-    // no subcommand or unknown → show help
-    const row = (c, d) => `  ${cyan(c.padEnd(32))}${dim(d)}`;
-    console.log(`
-${bold('mindos config')} — view and update MindOS configuration
-
-${bold('Subcommands:')}
-${row('mindos config show',          'Print current config (API keys masked)')}
-${row('mindos config validate',      'Validate config file')}
-${row('mindos config set <key> <v>', 'Update a single field (dot-notation supported)')}
-${row('mindos config unset <key>',   'Remove a config field')}
-
-${bold('Examples:')}
-  ${dim('mindos config set port 3002')}
-  ${dim('mindos config set ai.provider openai')}
-  ${dim('mindos config set setupPending false')}
-  ${dim('mindos config unset webPassword')}
-`);
-  },
-
-  // ── sync ──────────────────────────────────────────────────────────────────
-  sync: async () => {
-    const sub = cliArgs[0];
-    loadConfig();
-    const mindRoot = process.env.MIND_ROOT;
-
-    if (sub === 'init') {
-      // Flags are already parsed by parseArgs into cliFlags
-      const nonInteractive = cliFlags['non-interactive'] === true;
-
-      if (nonInteractive) {
-        await initSync(mindRoot, {
-          nonInteractive: true,
-          remote: typeof cliFlags.remote === 'string' ? cliFlags.remote : '',
-          token: typeof cliFlags.token === 'string' ? cliFlags.token : '',
-          branch: (typeof cliFlags.branch === 'string' ? cliFlags.branch : '') || 'main',
-        });
-      } else {
-        await initSync(mindRoot);
-      }
-      return;
-    }
-
-    if (sub === 'now') {
-      try {
-        console.log(dim('Pulling...'));
-        await manualSync(mindRoot);
-        console.log(green('✔ Sync complete'));
-      } catch (err) {
-        console.error(red(err.message));
-        process.exit(EXIT.ERROR);
-      }
-      return;
-    }
+// ── Help generation ───────────────────────────────────────────────────────────
+// Summaries come from each module's meta.summary — single source of truth.
+// [displayName, module] — displayName may differ from meta.name (e.g. init → onboard).
+
+const coreEntries = [
+  ['agent',  agentCmd],
+  ['ask',    askCmd],
+  ['start',  startCmd],
+  ['stop',   stopCmd],
+  ['status', statusCmd],
+  ['open',   openCmd],
+  ['file',   fileCmd],
+  ['space',  spaceCmd],
+  ['search', searchCmd],
+  ['mcp',    mcpCmd],
+  ['init',   onboardCmd],
+  ['config', configCmd],
+  ['doctor', doctorCmd],
+  ['update', updateCmd],
+];
+
+const additionalEntries = [
+  ['dev',         devCmd],
+  ['build',       buildCmd],
+  ['restart',     restartCmd],
+  ['sync',        syncCmd],
+  ['gateway',     gatewayCmd],
+  ['token',       tokenCmd],
+  ['logs',        logsCmd],
+  ['api',         apiCmd],
+  ['init-skills', initSkillsCmd],
+  ['uninstall',   uninstallCmd],
+];
+
+function showGlobalHelp(showAll = false) {
+  const pkgVersion = (() => {
+    try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; }
+    catch { return '?'; }
+  })();
+  const row = ([name, mod]) => `  ${cyan(name.padEnd(14))}${dim(mod.meta.summary)}`;
+
+  const lines = [
+    '',
+    `${bold('MindOS CLI')} ${dim(`v${pkgVersion}`)}`,
+    '',
+    `${bold('USAGE')}`,
+    `  ${cyan('mindos <command> [flags]')}`,
+    '',
+    `${bold('COMMANDS')}`,
+    ...coreEntries.map(row),
+  ];
 
-    if (sub === 'conflicts') {
-      await listConflicts(mindRoot);
-      return;
-    }
+  if (showAll) {
+    lines.push('', `${bold('ADDITIONAL COMMANDS')}`);
+    lines.push(...additionalEntries.map(row));
+  }
 
-    if (sub === 'on') {
-      await setSyncEnabled(true);
-      return;
-    }
+  const flagRow = (f, d) => `  ${cyan(f.padEnd(14))}${dim(d)}`;
+  lines.push(
+    '',
+    `${bold('FLAGS')}`,
+    flagRow('--help, -h', 'Show help'),
+    flagRow('--version, -v', 'Show version'),
+    flagRow('--json', 'Output as JSON'),
+    '',
+    `  ${dim('Run')} ${cyan('mindos <command> --help')} ${dim('for details on any command.')}`,
+  );
+
+  if (!showAll) {
+    lines.push(`  ${dim('Run')} ${cyan('mindos --all')} ${dim('to see all commands.')}`);
+  }
 
-    if (sub === 'off') {
-      await setSyncEnabled(false);
-      await stopSyncDaemon();
-      return;
-    }
+  lines.push('');
+  console.log(lines.join('\n'));
+}
 
-    // Unknown subcommand check
-    if (sub) {
-      const validSubs = ['init', 'now', 'conflicts', 'on', 'off'];
-      if (!validSubs.includes(sub)) {
-        console.error(red(`Unknown sync subcommand: ${sub}`));
-        console.error(dim(`Available: ${validSubs.join(' | ')}`));
-        process.exit(EXIT.ARGS);
-      }
-    }
+/**
+ * Show help for a specific command.
+ * Delegates to the command's own printHelp() if it exists,
+ * otherwise auto-generates from meta.
+ */
+function showCommandHelp(mod) {
+  if (typeof mod.printHelp === 'function') {
+    mod.printHelp();
+  } else {
+    printCommandHelp(mod);
+  }
+}
 
-    // default: sync status
-    const status = await getSyncStatus(mindRoot);
+// ── Entry ─────────────────────────────────────────────────────────────────────
 
-    if (cliFlags.json) {
-      console.log(JSON.stringify(status, null, 2));
-      return;
-    }
+const showAll = cliFlags.all === true || cliFlags.a === true;
 
-    if (!status.enabled) {
-      console.log(`\n${bold('Sync Status')}`);
-      console.log(dim('  Not configured. Run `mindos sync init` to set up.\n'));
-      return;
-    }
-    const ago = status.lastSync
-      ? (() => {
-          const diff = Date.now() - new Date(status.lastSync).getTime();
-          if (diff < 60000) return 'just now';
-          if (diff < 3600000) return `${Math.floor(diff / 60000)} minutes ago`;
-          return `${Math.floor(diff / 3600000)} hours ago`;
-        })()
-      : 'never';
+// --help can be boolean (--help) or string (--help agent)
+const helpValue = cliFlags.help || cliFlags.h;
+const hasHelp = helpValue !== undefined && helpValue !== false;
 
-    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}`);
-    console.log(`  ${dim('Unpushed:')}    ${status.unpushed} commits`);
-    console.log(`  ${dim('Conflicts:')}   ${status.conflicts.length ? yellow(`${status.conflicts.length} file(s)`) : green('none')}`);
-    console.log(`  ${dim('Auto-sync:')}   ${green('● enabled')} ${dim(`(commit: ${status.autoCommitInterval}s, pull: ${status.autoPullInterval / 60}min)`)}`);
-    if (status.lastError) {
-      console.log(`  ${dim('Last error:')}  ${red(status.lastError)}`);
-    }
-    console.log();
-  },
+// `mindos --all` → show full help
+if (showAll && !cmd) {
+  showGlobalHelp(true);
+  process.exit(0);
+}
 
-  // ── New modular commands (knowledge operations) ──────────────────────────
-  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),
-};
+// `mindos help <cmd>` → show help for <cmd>
+if (cmd === 'help') {
+  const target = cliArgs[0];
+  if (target && commands[target]) {
+    showCommandHelp(commands[target]);
+  } else {
+    showGlobalHelp(showAll);
+  }
+  process.exit(0);
+}
 
-// ── Entry ─────────────────────────────────────────────────────────────────────
+// `mindos --help <cmd>` → parseArgs puts <cmd> as the value of --help
+if (hasHelp && typeof helpValue === 'string' && commands[helpValue]) {
+  showCommandHelp(commands[helpValue]);
+  process.exit(0);
+}
 
-const resolvedCmd = (cliFlags.help || cliFlags.h) ? null : (cmd || (existsSync(CONFIG_PATH) ? getStartMode() : null));
+// Resolve which command to run (or show global help)
+const resolvedCmd = (hasHelp && !cmd) ? null : (cmd || 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)}`;
-
-  // 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')}`);
+  showGlobalHelp(showAll);
+  process.exit((cmd && !hasHelp) ? 1 : 0);
+}
 
-  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);
+// `mindos <cmd> --help` → show help for <cmd> instead of executing it
+if (hasHelp) {
+  showCommandHelp(commands[resolvedCmd]);
+  process.exit(0);
 }
 
-commands[resolvedCmd]();
+commands[resolvedCmd].run(cliArgs, cliFlags);