@geminilight/mindos 0.2.1 → 0.4.0

package/app/lib/renderers/index.ts

@@ -1,92 +1,23 @@
+/**
+ * AUTO-GENERATED by scripts/gen-renderer-index.js — do not edit manually.
+ * To regenerate: node scripts/gen-renderer-index.js
+ */
 import { registerRenderer } from './registry';
-import { TodoRenderer } from '@/components/renderers/TodoRenderer';
-import { CsvRenderer } from '@/components/renderers/CsvRenderer';
-import { GraphRenderer } from '@/components/renderers/GraphRenderer';
-import { TimelineRenderer } from '@/components/renderers/TimelineRenderer';
-import { SummaryRenderer } from '@/components/renderers/SummaryRenderer';
-import { ConfigRenderer } from '@/components/renderers/ConfigRenderer';
-import { AgentInspectorRenderer } from '@/components/renderers/AgentInspectorRenderer';
+import { manifest as agentInspector } from '@/components/renderers/agent-inspector/manifest';
+import { manifest as backlinks } from '@/components/renderers/backlinks/manifest';
+import { manifest as config } from '@/components/renderers/config/manifest';
+import { manifest as csv } from '@/components/renderers/csv/manifest';
+import { manifest as diff } from '@/components/renderers/diff/manifest';
+import { manifest as graph } from '@/components/renderers/graph/manifest';
+import { manifest as summary } from '@/components/renderers/summary/manifest';
+import { manifest as timeline } from '@/components/renderers/timeline/manifest';
+import { manifest as todo } from '@/components/renderers/todo/manifest';
+import { manifest as workflow } from '@/components/renderers/workflow/manifest';
 
-registerRenderer({
-  id: 'todo',
-  name: 'TODO Board',
-  description: 'Renders TODO.md/TODO.csv as an interactive kanban board grouped by section. Check items off directly — changes are written back to the source file.',
-  author: 'MindOS',
-  icon: '✅',
-  tags: ['productivity', 'tasks', 'markdown'],
-  builtin: true,
-  match: ({ filePath }) => /\bTODO\b.*\.(md|csv)$/i.test(filePath),
-  component: TodoRenderer,
-});
+const manifests = [
+  agentInspector, backlinks, config, csv, diff, graph, summary, timeline, todo, workflow,
+];
 
-registerRenderer({
-  id: 'csv',
-  name: 'CSV Views',
-  description: 'Renders any CSV file as Table, Gallery, or Board. Each view is independently configurable — choose which columns map to title, description, tag, and group.',
-  author: 'MindOS',
-  icon: '📊',
-  tags: ['csv', 'table', 'gallery', 'board', 'data'],
-  builtin: true,
-  match: ({ extension, filePath }) => extension === 'csv' && !/\bTODO\b/i.test(filePath),
-  component: CsvRenderer,
-});
-
-registerRenderer({
-  id: 'config-panel',
-  name: 'Config Panel',
-  description: 'Renders CONFIG.json as an editable control panel based on uiSchema/keySpecs. Changes are written back to the JSON file directly.',
-  author: 'MindOS',
-  icon: '🧩',
-  tags: ['config', 'json', 'settings', 'schema'],
-  builtin: true,
-  match: ({ filePath, extension }) => extension === 'json' && /(^|\/)CONFIG\.json$/i.test(filePath),
-  component: ConfigRenderer,
-});
-
-registerRenderer({
-  id: 'graph',
-  name: 'Wiki Graph',
-  description: 'Force-directed graph of wikilink references across all markdown files. Supports Global and Local (2-hop) scope filters.',
-  author: 'MindOS',
-  icon: '🕸️',
-  tags: ['graph', 'wiki', 'links', 'visualization'],
-  builtin: true,
-  match: ({ extension }) => extension === 'md',
-  component: GraphRenderer,
-});
-
-registerRenderer({
-  id: 'timeline',
-  name: 'Timeline',
-  description: 'Renders changelog and journal files as a vertical timeline. Any markdown with ## date headings (e.g. ## 2025-01-15) becomes a card in the feed.',
-  author: 'MindOS',
-  icon: '📅',
-  tags: ['timeline', 'changelog', 'journal', 'history'],
-  builtin: true,
-  match: ({ filePath }) => /\b(CHANGELOG|changelog|TIMELINE|timeline|journal|Journal|diary|Diary)\b.*\.md$/i.test(filePath),
-  component: TimelineRenderer,
-});
-
-registerRenderer({
-  id: 'summary',
-  name: 'AI Briefing',
-  description: 'Streams an AI-generated daily briefing summarizing your most recently modified files — key changes, recurring themes, and suggested next actions.',
-  author: 'MindOS',
-  icon: '✨',
-  tags: ['ai', 'summary', 'briefing', 'daily'],
-  builtin: true,
-  match: ({ filePath }) => /\b(SUMMARY|summary|Summary|BRIEFING|briefing|Briefing|DAILY|daily|Daily)\b.*\.md$/i.test(filePath),
-  component: SummaryRenderer,
-});
-
-registerRenderer({
-  id: 'agent-inspector',
-  name: 'Agent Inspector',
-  description: 'Visualizes agent tool-call logs as a filterable timeline. Auto-activates on .agent-log.json (JSON Lines format).',
-  author: 'MindOS',
-  icon: '🔍',
-  tags: ['agent', 'inspector', 'log', 'mcp', 'tools'],
-  builtin: true,
-  match: ({ filePath }) => /\.agent-log\.json$/i.test(filePath),
-  component: AgentInspectorRenderer,
-});
+for (const m of manifests) {
+  registerRenderer(m);
+}

package/app/lib/renderers/registry.ts

@@ -15,8 +15,11 @@ export interface RendererDefinition {
   icon: string;          // emoji or short string
   tags: string[];
   builtin: boolean;      // true = ships with MindOS; false = user-installed (future)
+  entryPath?: string;    // canonical entry file shown on home page (e.g. 'TODO.md')
   match: (ctx: Pick<RendererContext, 'filePath' | 'extension'>) => boolean;
-  component: ComponentType<RendererContext>;
+  // Provide either `component` (eager) or `load` (lazy). Prefer `load` for code-splitting.
+  component?: ComponentType<RendererContext>;
+  load?: () => Promise<{ default: ComponentType<RendererContext> }>;
 }
 
 const registry: RendererDefinition[] = [];

package/app/lib/settings.ts

@@ -21,12 +21,13 @@ export interface AiConfig {
 export interface ServerSettings {
   ai: AiConfig;
   mindRoot: string;   // empty = use env var / default
-  // Fields managed by CLI only (not edited via GUI, preserved on write)
   port?: number;
   mcpPort?: number;
   authToken?: string;
   webPassword?: string;
   startMode?: 'dev' | 'start' | 'daemon';
+  setupPending?: boolean;  // true → / redirects to /setup
+  disabledSkills?: string[];
 }
 
 const DEFAULTS: ServerSettings = {
@@ -108,6 +109,10 @@ export function readSettings(): ServerSettings {
       webPassword: typeof parsed.webPassword === 'string' ? parsed.webPassword : undefined,
       authToken:   typeof parsed.authToken   === 'string' ? parsed.authToken   : undefined,
       mcpPort:     typeof parsed.mcpPort     === 'number' ? parsed.mcpPort     : undefined,
+      port:        typeof parsed.port        === 'number' ? parsed.port        : undefined,
+      startMode:   typeof parsed.startMode   === 'string' ? parsed.startMode as ServerSettings['startMode'] : undefined,
+      setupPending: parsed.setupPending === true ? true : undefined,
+      disabledSkills: Array.isArray(parsed.disabledSkills) ? parsed.disabledSkills as string[] : undefined,
     };
   } catch {
     return { ...DEFAULTS, ai: { ...DEFAULTS.ai, providers: { ...DEFAULTS.ai.providers } } };
@@ -123,6 +128,15 @@ export function writeSettings(settings: ServerSettings): void {
   const merged: Record<string, unknown> = { ...existing, ai: settings.ai, mindRoot: settings.mindRoot };
   if (settings.webPassword !== undefined) merged.webPassword = settings.webPassword;
   if (settings.authToken   !== undefined) merged.authToken   = settings.authToken;
+  if (settings.port        !== undefined) merged.port        = settings.port;
+  if (settings.mcpPort     !== undefined) merged.mcpPort     = settings.mcpPort;
+  if (settings.startMode   !== undefined) merged.startMode   = settings.startMode;
+  if (settings.disabledSkills !== undefined) merged.disabledSkills = settings.disabledSkills;
+  // setupPending: false/undefined → remove the field (cleanup); true → set it
+  if ('setupPending' in settings) {
+    if (settings.setupPending) merged.setupPending = true;
+    else delete merged.setupPending;
+  }
   fs.writeFileSync(SETTINGS_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
 }
 

package/app/lib/template.ts

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Recursively copy `src` to `dest`, skipping files that already exist in dest.
+ */
+export function copyRecursive(src: string, dest: string) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    // Skip if file already exists
+    if (fs.existsSync(dest)) return;
+    const dir = path.dirname(dest);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Apply a built-in template (en / zh / empty) to the given directory.
+ * Returns true on success, throws on error.
+ */
+export function applyTemplate(template: string, destDir: string): void {
+  if (!['en', 'zh', 'empty'].includes(template)) {
+    throw new Error(`Invalid template: ${template}`);
+  }
+
+  // templates/ is at the repo root (sibling of app/)
+  const repoRoot = path.resolve(process.cwd(), '..');
+  const templateDir = path.join(repoRoot, 'templates', template);
+
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`Template "${template}" not found at ${templateDir}`);
+  }
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  copyRecursive(templateDir, destDir);
+}

package/app/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "dev": "next dev -p ${MINDOS_WEB_PORT:-3000}",
+    "prebuild": "node ../scripts/gen-renderer-index.js",
     "build": "next build",
     "start": "next start -p ${MINDOS_WEB_PORT:-3000}",
     "lint": "eslint",

package/app/types/semver.d.ts

@@ -0,0 +1,8 @@
+declare module 'semver' {
+  export function gt(v1: string, v2: string): boolean;
+  export function lt(v1: string, v2: string): boolean;
+  export function gte(v1: string, v2: string): boolean;
+  export function lte(v1: string, v2: string): boolean;
+  export function eq(v1: string, v2: string): boolean;
+  export function valid(v: string | null): string | null;
+}

package/bin/cli.js

@@ -33,6 +33,7 @@
  *   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
  */
 
@@ -58,6 +59,15 @@ import { initSync, startSyncDaemon, stopSyncDaemon, getSyncStatus, manualSync, l
 // ── Commands ──────────────────────────────────────────────────────────────────
 
 const cmd       = process.argv[2];
+
+// ── --version / -v ──────────────────────────────────────────────────────────
+// --help / -h is handled at entry section (resolvedCmd = null → help block)
+if (cmd === '--version' || cmd === '-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').join(' ');
@@ -68,8 +78,8 @@ const commands = {
     const daemonFlag = process.argv.includes('--install-daemon') ? ' --install-daemon' : '';
     run(`node ${resolve(ROOT, 'scripts/setup.js')}${daemonFlag}`);
   },
-  init:  () => run(`node ${resolve(ROOT, 'scripts/setup.js')}`),
-  setup: () => run(`node ${resolve(ROOT, 'scripts/setup.js')}`),
+  init:  async () => commands.onboard(),
+  setup: async () => commands.onboard(),
 
   // ── open ───────────────────────────────────────────────────────────────────
   open: () => {
@@ -123,8 +133,8 @@ const commands = {
     console.log(`${sep}`);
     console.log(`${bold('Claude Code')}`);
     console.log(`${sep}`);
-    console.log(dim('一键安装:') + ` mindos mcp install claude-code -g -y`);
-    console.log(dim('\n手动配置 (~/.claude.json):'));
+    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: {
@@ -138,8 +148,8 @@ const commands = {
     console.log(`\n${sep}`);
     console.log(`${bold('CodeBuddy (Claude Code Internal)')}`);
     console.log(`${sep}`);
-    console.log(dim('一键安装:') + ` mindos mcp install codebuddy -g -y`);
-    console.log(dim('\n手动配置 (~/.claude-internal/.claude.json):'));
+    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: {
@@ -153,8 +163,8 @@ const commands = {
     console.log(`\n${sep}`);
     console.log(`${bold('Cursor')}`);
     console.log(`${sep}`);
-    console.log(dim('一键安装:') + ` mindos mcp install cursor -g -y`);
-    console.log(dim('\n手动配置 (~/.cursor/mcp.json):'));
+    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: {
@@ -168,7 +178,7 @@ const commands = {
     if (localIP) {
       const remoteUrl = `http://${localIP}:${mcpPort}/mcp`;
       console.log(`\n${sep}`);
-      console.log(`${bold('Remote (其他设备)')}`);
+      console.log(`${bold('Remote (other devices)')}`);
       console.log(`${sep}`);
       console.log(`URL: ${cyan(remoteUrl)}`);
       console.log(JSON.stringify({
@@ -200,12 +210,21 @@ const commands = {
     if (devMindRoot) {
       startSyncDaemon(devMindRoot).catch(() => {});
     }
-    printStartupInfo(webPort, mcpPort);
+    await printStartupInfo(webPort, mcpPort);
     run(`npx next 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 = getPlatform();
       if (!platform) {
@@ -225,13 +244,13 @@ const commands = {
           console.error(dim('  Check logs with: mindos logs\n'));
           process.exit(1);
         }
-        printStartupInfo(webPort, mcpPort);
+        await printStartupInfo(webPort, mcpPort);
         // System notification
         try {
           if (process.platform === 'darwin') {
-            execSync(`osascript -e 'display notification "http://localhost:${webPort}" with title "MindOS 已就绪"'`, { stdio: 'ignore' });
+            execSync(`osascript -e 'display notification "http://localhost:${webPort}" with title "MindOS Ready"'`, { stdio: 'ignore' });
           } else if (process.platform === 'linux') {
-            execSync(`notify-send "MindOS 已就绪" "http://localhost:${webPort}"`, { stdio: 'ignore' });
+            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')}`);
@@ -250,6 +269,7 @@ const commands = {
     if (needsBuild()) {
       console.log(yellow('Building MindOS (first run or new version detected)...\n'));
       cleanNextDir();
+      run('node scripts/gen-renderer-index.js', ROOT);
       run('npx next build', resolve(ROOT, 'app'));
       writeBuildStamp();
     }
@@ -261,7 +281,7 @@ const commands = {
     if (mindRoot) {
       startSyncDaemon(mindRoot).catch(() => {});
     }
-    printStartupInfo(webPort, mcpPort);
+    await printStartupInfo(webPort, mcpPort);
     run(`npx next start -p ${webPort} ${extra}`, resolve(ROOT, 'app'));
   },
 
@@ -269,6 +289,7 @@ const commands = {
   build: () => {
     ensureAppDeps();
     cleanNextDir();
+    run('node scripts/gen-renderer-index.js', ROOT);
     run(`npx next build ${extra}`, resolve(ROOT, 'app'));
     writeBuildStamp();
   },
@@ -466,6 +487,23 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
       }
     }
 
+    // 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');
+    }
+
     console.log(hasError
       ? `\n${red('Some checks failed.')} Run ${cyan('mindos onboard')} to reconfigure.\n`
       : `\n${green('All checks passed.')}\n`);
@@ -575,7 +613,7 @@ ${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(CONFIG_PATH)}\n`);
+      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;
@@ -640,13 +678,50 @@ ${dim('Shortcut: mindos start --daemon  →  install + start in one step')}
         if (typeof obj[parts[i]] !== 'object' || !obj[parts[i]]) obj[parts[i]] = {};
         obj = obj[parts[i]];
       }
-      const coerced = isNaN(Number(val)) ? val : Number(val);
+      // 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 = process.argv[4];
+      if (!key) {
+        console.error(red('Usage: mindos config unset <key>'));
+        process.exit(1);
+      }
+      if (!existsSync(CONFIG_PATH)) {
+        console.error(red('No config found. Run `mindos onboard` first.'));
+        process.exit(1);
+      }
+      let config;
+      try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {
+        console.error(red('Failed to parse config file.'));
+        process.exit(1);
+      }
+      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(`
@@ -656,10 +731,13 @@ ${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')}
 `);
   },
 
@@ -670,7 +748,22 @@ ${bold('Examples:')}
     const mindRoot = process.env.MIND_ROOT;
 
     if (sub === 'init') {
-      await initSync(mindRoot);
+      // Parse --non-interactive --remote <url> --branch <branch> --token <token>
+      const args = process.argv.slice(4);
+      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');
+
+      if (nonInteractive) {
+        await initSync(mindRoot, {
+          nonInteractive: true,
+          remote: flagVal('--remote'),
+          token: flagVal('--token'),
+          branch: flagVal('--branch') || 'main',
+        });
+      } else {
+        await initSync(mindRoot);
+      }
       return;
     }
 
@@ -695,6 +788,16 @@ ${bold('Examples:')}
       return;
     }
 
+    // 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(1);
+      }
+    }
+
     // default: sync status
     const status = getSyncStatus(mindRoot);
     if (!status.enabled) {
@@ -727,15 +830,16 @@ ${bold('Examples:')}
 
 // ── Entry ─────────────────────────────────────────────────────────────────────
 
-const resolvedCmd = cmd || (existsSync(CONFIG_PATH) ? getStartMode() : null);
+const resolvedCmd = (cmd === '--help' || cmd === '-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')}
+${bold('🧠 MindOS CLI')} ${dim(`v${pkgVersion}`)}
 
-${bold('Usage:')}
-${row('mindos onboard',                    'Interactive setup (writes ~/.mindos/config.json)')}
+${bold('Core:')}
+${row('mindos onboard',                    'Interactive setup (aliases: init, setup)')}
 ${row('mindos onboard --install-daemon',   'Setup + install & start as background OS service')}
 ${row('mindos start',                      'Start app + MCP server (production, auto-rebuilds if needed)')}
 ${row('mindos start --daemon',             'Install + start as background OS service (survives terminal close)')}
@@ -745,19 +849,28 @@ ${row('mindos dev --turbopack',            'Start with Turbopack (faster HMR)')}
 ${row('mindos stop',                       'Stop running MindOS processes')}
 ${row('mindos restart',                    'Stop then start again')}
 ${row('mindos build',                      'Build the app for production')}
+${row('mindos open',                       'Open Web UI in the default browser')}
+
+${bold('MCP:')}
 ${row('mindos mcp',                        'Start MCP server only')}
 ${row('mindos mcp install [agent]',        'Install MindOS MCP config into Agent (claude-code/cursor/windsurf/…) [-g]')}
-${row('mindos open',                       'Open Web UI in the default browser')}
 ${row('mindos token',                      'Show current auth token and MCP config snippet')}
+
+${bold('Sync:')}
 ${row('mindos sync',                       'Show sync status (init/now/conflicts/on/off)')}
+
+${bold('Gateway (Background Service):')}
 ${row('mindos gateway <subcommand>',       'Manage background service (install/uninstall/start/stop/status/logs)')}
+
+${bold('Config & Diagnostics:')}
+${row('mindos config <subcommand>',        'View/update config (show/validate/set/unset)')}
 ${row('mindos doctor',                     'Health check (config, ports, build, daemon)')}
 ${row('mindos update',                     'Update MindOS to the latest version')}
 ${row('mindos logs',                       'Tail service logs (~/.mindos/mindos.log)')}
-${row('mindos config <subcommand>',        'View/update config (show/validate/set)')}
 ${row('mindos',                            'Start using mode saved in ~/.mindos/config.json')}
 `);
-  process.exit(cmd ? 1 : 0);
+  const isHelp = (cmd === '--help' || cmd === '-h');
+  process.exit((cmd && !isHelp) ? 1 : 0);
 }
 
 commands[resolvedCmd]();

package/bin/lib/build.js

@@ -1,7 +1,8 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { resolve } from 'node:path';
-import { ROOT, BUILD_STAMP } from './constants.js';
+import { ROOT, BUILD_STAMP, DEPS_STAMP } from './constants.js';
 import { red, dim, yellow } from './colors.js';
 import { run } from './utils.js';
 
@@ -36,24 +37,58 @@ export function cleanNextDir() {
   }
 }
 
+function depsHash() {
+  const lockPath = resolve(ROOT, 'app', 'package-lock.json');
+  try {
+    const content = readFileSync(lockPath);
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+
+function depsChanged() {
+  const currentHash = depsHash();
+  if (!currentHash) return true;
+  try {
+    const savedHash = readFileSync(DEPS_STAMP, 'utf-8').trim();
+    return savedHash !== currentHash;
+  } catch {
+    return true;
+  }
+}
+
+function writeDepsStamp() {
+  const hash = depsHash();
+  if (hash) {
+    try { writeFileSync(DEPS_STAMP, hash, 'utf-8'); } catch {}
+  }
+}
+
 export function ensureAppDeps() {
   const appNext = resolve(ROOT, 'app', 'node_modules', 'next', 'package.json');
-  if (!existsSync(appNext)) {
-    try {
-      execSync('npm --version', { stdio: 'pipe' });
-    } catch {
-      console.error(red('\n\u2718 npm not found in PATH.\n'));
-      console.error('  MindOS needs npm to install its app dependencies on first run.');
-      console.error('  This usually means Node.js is installed via a version manager (nvm, fnm, volta, etc.)');
-      console.error('  that only loads in interactive shells, but not in /bin/sh.\n');
-      console.error('  Fix: add your Node.js bin directory to a profile that /bin/sh reads (~/.profile).');
-      console.error('  Example:');
-      console.error(dim('    echo \'export PATH="$HOME/.nvm/versions/node/$(node --version)/bin:$PATH"\' >> ~/.profile'));
-      console.error(dim('    source ~/.profile\n'));
-      console.error('  Then run `mindos start` again.\n');
-      process.exit(1);
-    }
-    console.log(yellow('Installing app dependencies (first run)...\n'));
-    run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+  const needsInstall = !existsSync(appNext) || depsChanged();
+  if (!needsInstall) return;
+
+  try {
+    execSync('npm --version', { stdio: 'pipe' });
+  } catch {
+    console.error(red('\n\u2718 npm not found in PATH.\n'));
+    console.error('  MindOS needs npm to install its app dependencies on first run.');
+    console.error('  This usually means Node.js is installed via a version manager (nvm, fnm, volta, etc.)');
+    console.error('  that only loads in interactive shells, but not in /bin/sh.\n');
+    console.error('  Fix: add your Node.js bin directory to a profile that /bin/sh reads (~/.profile).');
+    console.error('  Example:');
+    console.error(dim('    echo \'export PATH="$HOME/.nvm/versions/node/$(node --version)/bin:$PATH"\' >> ~/.profile'));
+    console.error(dim('    source ~/.profile\n'));
+    console.error('  Then run `mindos start` again.\n');
+    process.exit(1);
   }
+
+  const label = existsSync(appNext)
+    ? 'Updating app dependencies (package-lock.json changed)...\n'
+    : 'Installing app dependencies (first run)...\n';
+  console.log(yellow(label));
+  run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+  writeDepsStamp();
 }

package/bin/lib/colors.js

@@ -1,4 +1,6 @@
-export const isTTY  = process.stdout.isTTY;
+const noColor = 'NO_COLOR' in process.env;
+const forceColor = process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0';
+export const isTTY  = noColor ? false : (forceColor || process.stdout.isTTY);
 export const bold   = (s) => isTTY ? `\x1b[1m${s}\x1b[0m`  : s;
 export const dim    = (s) => isTTY ? `\x1b[2m${s}\x1b[0m`  : s;
 export const cyan   = (s) => isTTY ? `\x1b[36m${s}\x1b[0m` : s;