@timmeck/brain 1.0.0 → 1.1.1

package/src/cli/commands/insights.ts

@@ -1,5 +1,18 @@
 import { Command } from 'commander';
 import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, priorityBadge, divider } from '../colors.js';
+
+const TYPE_ICONS: Record<string, string> = {
+  trend: '📈',
+  pattern: '🔄',
+  gap: '⚠',
+  synergy: '⚡',
+  optimization: '🎯',
+  template_candidate: '🎨',
+  project_suggestion: '💡',
+  warning: '🚨',
+  suggestion: '💡',
+};
 
 export function insightsCommand(): Command {
   return new Command('insights')
@@ -16,18 +29,37 @@ export function insightsCommand(): Command {
         });
 
         if (!insights?.length) {
-          console.log('No active insights.');
+          console.log(`${icons.insight}  ${c.dim('No active insights.')}`);
           return;
         }
 
-        console.log(`${insights.length} insights:\n`);
+        console.log(header(`${insights.length} Insights`, icons.insight));
+
+        // Group by type
+        const byType: Record<string, number> = {};
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         for (const ins of insights as any[]) {
-          const priority = ins.priority >= 8 ? 'HIGH' : ins.priority >= 5 ? 'MEDIUM' : 'LOW';
-          console.log(`  [${ins.type}] [${priority}] ${ins.title}`);
-          if (ins.description) console.log(`    ${ins.description.slice(0, 150)}`);
+          byType[ins.type] = (byType[ins.type] || 0) + 1;
+        }
+        const typeSummary = Object.entries(byType)
+          .sort((a, b) => b[1] - a[1])
+          .map(([t, count]) => `${TYPE_ICONS[t] ?? '•'} ${c.cyan(t)} ${c.dim(`(${count})`)}`)
+          .join('  ');
+        console.log(`  ${typeSummary}\n`);
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const ins of insights as any[]) {
+          const typeIcon = TYPE_ICONS[ins.type] ?? '•';
+          const pBadge = priorityBadge(ins.priority ?? 0);
+          const typeTag = c.cyan(`[${ins.type}]`);
+
+          console.log(`  ${typeIcon} ${typeTag} ${pBadge} ${c.value(ins.title)}`);
+          if (ins.description) {
+            console.log(`     ${c.dim(ins.description.slice(0, 150))}`);
+          }
           console.log();
         }
+        console.log(divider());
       });
     });
 }

package/src/cli/commands/learn.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, keyValue, divider } from '../colors.js';
+
+export function learnCommand(): Command {
+  return new Command('learn')
+    .description('Trigger a learning cycle manually (pattern extraction + rule generation)')
+    .action(async () => {
+      await withIpc(async (client) => {
+        console.log(`${icons.brain}  ${c.info('Running learning cycle...')}`);
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result: any = await client.request('learning.run', {});
+
+        console.log(header('Learning Cycle Complete', icons.bolt));
+        console.log(keyValue('New patterns', result.newPatterns ?? 0));
+        console.log(keyValue('Updated rules', result.updatedRules ?? 0));
+        console.log(keyValue('Pruned rules', result.prunedRules ?? 0));
+        console.log(keyValue('New anti-patterns', result.newAntipatterns ?? 0));
+        console.log(keyValue('Duration', `${result.duration ?? 0}ms`));
+        console.log(`\n${divider()}`);
+      });
+    });
+}

package/src/cli/commands/modules.ts

@@ -1,30 +1,53 @@
 import { Command } from 'commander';
 import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, divider } from '../colors.js';
 
 export function modulesCommand(): Command {
   return new Command('modules')
     .description('List registered code modules')
     .option('--language <lang>', 'Filter by language')
+    .option('-l, --limit <n>', 'Maximum results')
     .action(async (opts) => {
       await withIpc(async (client) => {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const modules: any = await client.request('code.modules', {
           language: opts.language,
+          limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
         });
 
         if (!modules?.length) {
-          console.log('No code modules registered.');
+          console.log(`${icons.module}  ${c.dim('No code modules registered.')}`);
           return;
         }
 
-        console.log(`${modules.length} code modules:\n`);
+        console.log(header(`${modules.length} Code Modules`, icons.module));
+
+        // Group by language
+        const byLang: Record<string, number> = {};
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const mod of modules as any[]) {
+          byLang[mod.language] = (byLang[mod.language] || 0) + 1;
+        }
+        const langSummary = Object.entries(byLang)
+          .sort((a, b) => b[1] - a[1])
+          .map(([lang, count]) => `${c.cyan(lang)} ${c.dim(`(${count})`)}`)
+          .join('  ');
+        console.log(`  ${langSummary}\n`);
+
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         for (const mod of modules as any[]) {
-          console.log(`  #${mod.id} [${mod.language}] ${mod.name}`);
-          if (mod.description) console.log(`    ${mod.description.slice(0, 120)}`);
-          console.log(`    File: ${mod.filePath}  Reusability: ${mod.reusabilityScore ?? '?'}`);
+          const score = mod.reusabilityScore ?? mod.reusability_score ?? 0;
+          const scoreColor = score >= 0.7 ? c.green : score >= 0.4 ? c.orange : c.red;
+          const langTag = c.cyan(`[${mod.language}]`);
+
+          console.log(`  ${c.dim(`#${mod.id}`)} ${langTag} ${c.value(mod.name)}`);
+          if (mod.description) {
+            console.log(`     ${c.dim(mod.description.slice(0, 120))}`);
+          }
+          console.log(`     ${c.label('File:')} ${c.dim(mod.filePath ?? mod.file_path)}  ${c.label('Score:')} ${scoreColor(typeof score === 'number' ? score.toFixed(2) : score)}`);
           console.log();
         }
+        console.log(divider());
       });
     });
 }

package/src/cli/commands/network.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, keyValue, divider } from '../colors.js';
 
 export function networkCommand(): Command {
   return new Command('network')
@@ -13,7 +14,7 @@ export function networkCommand(): Command {
           const nodeId = parseInt(nodeIdStr, 10);
 
           if (!nodeType || isNaN(nodeId)) {
-            console.error('Invalid node format. Use: --node error:42');
+            console.error(c.error('Invalid node format. Use: --node error:42'));
             return;
           }
 
@@ -25,14 +26,16 @@ export function networkCommand(): Command {
           });
 
           if (!related?.length) {
-            console.log(`No connections found for ${nodeType}:${nodeId}`);
+            console.log(`${c.dim('No connections found for')} ${c.cyan(`${nodeType}:${nodeId}`)}`);
             return;
           }
 
-          console.log(`Connections from ${nodeType}:${nodeId}:\n`);
+          console.log(header(`Connections from ${nodeType}:${nodeId}`, icons.synapse));
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           for (const r of related as any[]) {
-            console.log(`  → ${r.nodeType}:${r.nodeId} (weight: ${(r.activation ?? r.weight ?? 0).toFixed(3)})`);
+            const weight = (r.activation ?? r.weight ?? 0);
+            const weightColor = weight >= 0.7 ? c.green : weight >= 0.3 ? c.orange : c.dim;
+            console.log(`  ${c.cyan(icons.arrow)} ${c.value(`${r.nodeType}:${r.nodeId}`)} ${c.label('weight:')} ${weightColor(weight.toFixed(3))}`);
           }
         } else {
           // Show general network stats
@@ -43,19 +46,22 @@ export function networkCommand(): Command {
             limit: parseInt(opts.limit, 10),
           });
 
-          console.log('Synapse Network Overview:\n');
-          console.log(`  Total synapses: ${stats.totalSynapses ?? 0}`);
-          console.log(`  Average weight: ${(stats.avgWeight ?? 0).toFixed(3)}`);
+          console.log(header('Synapse Network', icons.synapse));
+          console.log(keyValue('Total synapses', stats.totalSynapses ?? 0));
+          console.log(keyValue('Average weight', (stats.avgWeight ?? 0).toFixed(3)));
           console.log();
 
           if (overview?.strongestSynapses?.length) {
-            console.log('Strongest connections:');
+            console.log(`  ${c.purple.bold('Strongest connections:')}`);
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             for (const s of overview.strongestSynapses as any[]) {
-              console.log(`  ${s.source} → ${s.target} [${s.type}] weight: ${(s.weight ?? 0).toFixed(3)}`);
+              const weight = (s.weight ?? 0);
+              const weightColor = weight >= 0.7 ? c.green : weight >= 0.3 ? c.orange : c.dim;
+              console.log(`  ${c.dim(s.source)} ${c.cyan(icons.arrow)} ${c.dim(s.target)} ${c.label(`[${s.type}]`)} ${weightColor(weight.toFixed(3))}`);
             }
           }
         }
+        console.log(`\n${divider()}`);
       });
     });
 }

package/src/cli/commands/query.ts

@@ -1,42 +1,119 @@
 import { Command } from 'commander';
 import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, statusBadge, divider } from '../colors.js';
 
 export function queryCommand(): Command {
   return new Command('query')
-    .description('Search for errors and solutions')
-    .argument('<search>', 'Error message or description to search for')
-    .option('-l, --limit <n>', 'Maximum results', '10')
+    .description('Search errors, code modules, and insights')
+    .argument('<search>', 'Search term')
+    .option('-l, --limit <n>', 'Maximum results per category', '10')
+    .option('--errors-only', 'Only search errors')
+    .option('--modules-only', 'Only search code modules')
+    .option('--insights-only', 'Only search insights')
+    .option('--page <n>', 'Page number (starting from 1)', '1')
     .action(async (search: string, opts) => {
       await withIpc(async (client) => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const results: any = await client.request('error.query', {
-          search,
-          limit: parseInt(opts.limit, 10),
-        });
-
-        if (!results?.length) {
-          console.log('No matching errors found.');
-          return;
+        const limit = parseInt(opts.limit, 10);
+        const page = parseInt(opts.page, 10) || 1;
+        const offset = (page - 1) * limit;
+        const searchAll = !opts.errorsOnly && !opts.modulesOnly && !opts.insightsOnly;
+        let totalResults = 0;
+
+        // --- Errors ---
+        if (searchAll || opts.errorsOnly) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const results: any = await client.request('error.query', {
+            search,
+            limit: limit + offset,
+          });
+
+          const errors = Array.isArray(results) ? results.slice(offset, offset + limit) : [];
+          if (errors.length > 0) {
+            totalResults += errors.length;
+            console.log(header(`Errors matching "${search}"`, icons.error));
+
+            for (const err of errors) {
+              const badge = statusBadge(err.resolved ? 'resolved' : 'open');
+              const typeTag = c.purple(err.errorType ?? 'unknown');
+              console.log(`  ${c.dim(`#${err.id}`)} ${badge} ${typeTag}`);
+              console.log(`     ${c.dim((err.message ?? '').slice(0, 120))}`);
+
+              // Get solutions for this error
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              const solutions: any = await client.request('solution.query', { error_id: err.id });
+              if (solutions?.length > 0) {
+                console.log(`     ${c.green(`${icons.check} ${solutions.length} solution(s)`)}`);
+                for (const sol of solutions.slice(0, 3)) {
+                  console.log(`       ${c.dim(icons.corner)} ${c.dim((sol.description ?? '').slice(0, 100))}`);
+                }
+              }
+              console.log();
+            }
+          }
         }
 
-        console.log(`Found ${results.length} errors:\n`);
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        for (const err of results as any[]) {
-          const status = err.resolved ? 'RESOLVED' : 'OPEN';
-          console.log(`  #${err.id} [${status}] ${err.errorType ?? 'unknown'}`);
-          console.log(`    ${(err.message ?? '').slice(0, 120)}`);
+        // --- Code Modules ---
+        if (searchAll || opts.modulesOnly) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const modules: any = await client.request('code.find', {
+            query: search,
+            limit: limit + offset,
+          });
+
+          const mods = Array.isArray(modules) ? modules.slice(offset, offset + limit) : [];
+          if (mods.length > 0) {
+            totalResults += mods.length;
+            console.log(header(`Modules matching "${search}"`, icons.module));
 
-          // Get solutions for this error
+            for (const mod of mods) {
+              const score = mod.reusability_score ?? mod.reusabilityScore ?? 0;
+              const scoreColor = score >= 0.7 ? c.green : score >= 0.4 ? c.orange : c.red;
+              console.log(`  ${c.dim(`#${mod.id}`)} ${c.cyan(`[${mod.language}]`)} ${c.value(mod.name)}`);
+              console.log(`     ${c.label('File:')} ${c.dim(mod.file_path ?? mod.filePath)}  ${c.label('Score:')} ${scoreColor(typeof score === 'number' ? score.toFixed(2) : score)}`);
+              if (mod.description) {
+                console.log(`     ${c.dim(mod.description.slice(0, 120))}`);
+              }
+              console.log();
+            }
+          }
+        }
+
+        // --- Insights ---
+        if (searchAll || opts.insightsOnly) {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const solutions: any = await client.request('solution.query', { error_id: err.id });
-          if (solutions?.length > 0) {
-            console.log(`    Solutions: ${solutions.length}`);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            for (const sol of solutions.slice(0, 3) as any[]) {
-              console.log(`      - #${sol.id}: ${(sol.description ?? '').slice(0, 100)}`);
+          const insights: any = await client.request('research.insights', {
+            activeOnly: true,
+            limit: 100,
+          });
+
+          // Client-side search since insights API may not support text search
+          const allInsights = Array.isArray(insights) ? insights : [];
+          const searchLower = search.toLowerCase();
+          const matched = allInsights.filter((i: { title?: string; description?: string }) =>
+            (i.title ?? '').toLowerCase().includes(searchLower) ||
+            (i.description ?? '').toLowerCase().includes(searchLower)
+          ).slice(offset, offset + limit);
+
+          if (matched.length > 0) {
+            totalResults += matched.length;
+            console.log(header(`Insights matching "${search}"`, icons.insight));
+
+            for (const ins of matched) {
+              const typeTag = c.cyan(`[${ins.type}]`);
+              console.log(`  ${typeTag} ${c.value(ins.title)}`);
+              if (ins.description) {
+                console.log(`     ${c.dim(ins.description.slice(0, 150))}`);
+              }
+              console.log();
             }
           }
-          console.log();
+        }
+
+        if (totalResults === 0) {
+          console.log(`\n${icons.search}  ${c.dim(`No results found for "${search}".`)}`);
+        } else {
+          console.log(`  ${c.dim(`Page ${page} — showing ${totalResults} result(s). Use --page ${page + 1} for more.`)}`);
+          console.log(divider());
         }
       });
     });

package/src/cli/commands/start.ts

@@ -3,6 +3,8 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getDataDir } from '../../utils/paths.js';
+import { c, icons } from '../colors.js';
+import { checkForUpdate } from '../update-check.js';
 
 export function startCommand(): Command {
   return new Command('start')
@@ -17,7 +19,7 @@ export function startCommand(): Command {
         const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
         try {
           process.kill(pid, 0); // Check if process exists
-          console.log(`Brain daemon is already running (PID: ${pid})`);
+          console.log(`${icons.brain}  Brain daemon is ${c.green('already running')} ${c.dim(`(PID: ${pid})`)}`);
           return;
         } catch {
           // PID file stale, remove it
@@ -45,15 +47,16 @@ export function startCommand(): Command {
       });
       child.unref();
 
-      console.log(`Brain daemon starting (PID: ${child.pid})`);
+      console.log(`${icons.brain}  ${c.info('Brain daemon starting')} ${c.dim(`(PID: ${child.pid})`)}`);
 
       // Wait briefly for PID file to appear
-      setTimeout(() => {
+      setTimeout(async () => {
         if (fs.existsSync(pidPath)) {
-          console.log('Brain daemon started successfully.');
+          console.log(`${icons.ok}  ${c.success('Brain daemon started successfully.')}`);
         } else {
-          console.log('Brain daemon may still be starting. Check: brain status');
+          console.log(`${icons.clock}  ${c.warn('Brain daemon may still be starting.')} Check: ${c.cyan('brain status')}`);
         }
+        await checkForUpdate();
       }, 1000);
     });
 }

package/src/cli/commands/status.ts

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getDataDir } from '../../utils/paths.js';
 import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, keyValue, divider } from '../colors.js';
+import { checkForUpdate, getCurrentVersion } from '../update-check.js';
 
 export function statusCommand(): Command {
   return new Command('status')
@@ -11,7 +13,7 @@ export function statusCommand(): Command {
       const pidPath = path.join(getDataDir(), 'brain.pid');
 
       if (!fs.existsSync(pidPath)) {
-        console.log('Brain Daemon: NOT RUNNING');
+        console.log(`${icons.brain}  Brain Daemon: ${c.red.bold('NOT RUNNING')}`);
         return;
       }
 
@@ -23,11 +25,12 @@ export function statusCommand(): Command {
       } catch { /* not running */ }
 
       if (!running) {
-        console.log('Brain Daemon: NOT RUNNING (stale PID file)');
+        console.log(`${icons.brain}  Brain Daemon: ${c.red.bold('NOT RUNNING')} ${c.dim('(stale PID file)')}`);
         return;
       }
 
-      console.log(`Brain Daemon: RUNNING (PID ${pid})`);
+      console.log(header(`Brain Status v${getCurrentVersion()}`, icons.brain));
+      console.log(`  ${c.green(`${icons.dot} RUNNING`)} ${c.dim(`(PID ${pid})`)}`);
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       await withIpc(async (client) => {
@@ -43,27 +46,30 @@ export function statusCommand(): Command {
           dbSize = `${(stat.size / 1024 / 1024).toFixed(1)} MB`;
         } catch { /* ignore */ }
 
-        console.log(`Database: ${dbPath} (${dbSize})`);
+        console.log(keyValue('Database', `${dbPath} (${dbSize})`));
         console.log();
 
-        console.log('Error Brain:');
-        console.log(`  Errors: ${summary.errors?.total ?? 0} total, ${summary.errors?.unresolved ?? 0} unresolved, ${summary.errors?.last7d ?? 0} last 7d`);
-        console.log(`  Solutions: ${summary.solutions?.total ?? 0}`);
-        console.log(`  Rules: ${summary.rules?.active ?? 0} active`);
-        console.log(`  Anti-Patterns: ${summary.antipatterns?.total ?? 0}`);
+        console.log(`  ${icons.error}  ${c.purple.bold('Error Brain')}`);
+        console.log(`     ${c.label('Errors:')}     ${c.value(summary.errors?.total ?? 0)} total, ${c.red(summary.errors?.unresolved ?? 0)} unresolved, ${c.dim(`${summary.errors?.last7d ?? 0} last 7d`)}`);
+        console.log(`     ${c.label('Solutions:')}  ${c.value(summary.solutions?.total ?? 0)}`);
+        console.log(`     ${c.label('Rules:')}      ${c.green(summary.rules?.active ?? 0)} active`);
+        console.log(`     ${c.label('Anti-Pat.:')} ${c.value(summary.antipatterns?.total ?? 0)}`);
         console.log();
 
-        console.log('Code Brain:');
-        console.log(`  Modules: ${summary.modules?.total ?? 0} registered`);
+        console.log(`  ${icons.module}  ${c.blue.bold('Code Brain')}`);
+        console.log(`     ${c.label('Modules:')}    ${c.value(summary.modules?.total ?? 0)} registered`);
         console.log();
 
-        console.log('Synapse Network:');
-        console.log(`  Synapses: ${network.totalSynapses ?? 0}`);
-        console.log(`  Avg weight: ${(network.avgWeight ?? 0).toFixed(2)}`);
+        console.log(`  ${icons.synapse}  ${c.cyan.bold('Synapse Network')}`);
+        console.log(`     ${c.label('Synapses:')}   ${c.value(network.totalSynapses ?? 0)}`);
+        console.log(`     ${c.label('Avg weight:')} ${c.value((network.avgWeight ?? 0).toFixed(2))}`);
         console.log();
 
-        console.log('Research Brain:');
-        console.log(`  Insights: ${summary.insights?.active ?? 0} active`);
+        console.log(`  ${icons.insight}  ${c.orange.bold('Research Brain')}`);
+        console.log(`     ${c.label('Insights:')}   ${c.value(summary.insights?.active ?? 0)} active`);
+
+        await checkForUpdate();
+        console.log(`\n${divider()}`);
       });
     });
 }

package/src/cli/commands/stop.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getDataDir } from '../../utils/paths.js';
+import { c, icons } from '../colors.js';
 
 export function stopCommand(): Command {
   return new Command('stop')
@@ -10,7 +11,7 @@ export function stopCommand(): Command {
       const pidPath = path.join(getDataDir(), 'brain.pid');
 
       if (!fs.existsSync(pidPath)) {
-        console.log('Brain daemon is not running (no PID file found).');
+        console.log(`${icons.brain}  ${c.dim('Brain daemon is not running (no PID file found).')}`);
         return;
       }
 
@@ -18,12 +19,12 @@ export function stopCommand(): Command {
 
       try {
         process.kill(pid, 'SIGTERM');
-        console.log(`Brain daemon stopped (PID: ${pid})`);
+        console.log(`${icons.brain}  ${c.success('Brain daemon stopped')} ${c.dim(`(PID: ${pid})`)}`);
       } catch (err) {
         if ((err as NodeJS.ErrnoException).code === 'ESRCH') {
-          console.log('Brain daemon was not running (stale PID file removed).');
+          console.log(`${icons.brain}  ${c.dim('Brain daemon was not running (stale PID file removed).')}`);
         } else {
-          console.error(`Failed to stop daemon: ${err}`);
+          console.error(`${icons.error}  ${c.error(`Failed to stop daemon: ${err}`)}`);
         }
       }
 

package/src/cli/ipc-helper.ts

@@ -1,5 +1,6 @@
 import { IpcClient } from '../ipc/client.js';
 import { getPipeName } from '../utils/paths.js';
+import { c, icons } from './colors.js';
 
 export async function withIpc<T>(fn: (client: IpcClient) => Promise<T>): Promise<T> {
   const client = new IpcClient(getPipeName(), 5000);
@@ -8,11 +9,11 @@ export async function withIpc<T>(fn: (client: IpcClient) => Promise<T>): Promise
     return await fn(client);
   } catch (err) {
     if (err instanceof Error && err.message.includes('ENOENT')) {
-      console.error('Brain daemon is not running. Start it with: brain start');
+      console.error(`${icons.error}  ${c.error('Brain daemon is not running.')} Start it with: ${c.cyan('brain start')}`);
     } else if (err instanceof Error && err.message.includes('ECONNREFUSED')) {
-      console.error('Brain daemon is not responding. Try: brain stop && brain start');
+      console.error(`${icons.error}  ${c.error('Brain daemon is not responding.')} Try: ${c.cyan('brain stop && brain start')}`);
     } else {
-      console.error(`Error: ${err instanceof Error ? err.message : err}`);
+      console.error(`${icons.error}  ${c.error(err instanceof Error ? err.message : String(err))}`);
     }
     process.exit(1);
   } finally {

package/src/cli/update-check.ts

@@ -0,0 +1,63 @@
+import https from 'node:https';
+import { c, icons } from './colors.js';
+
+// Read current version from package.json at build time
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+const CURRENT_VERSION: string = pkg.version;
+
+export function getCurrentVersion(): string {
+  return CURRENT_VERSION;
+}
+
+function fetchLatestVersion(): Promise<string | null> {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => resolve(null), 3000);
+
+    const req = https.get(
+      'https://registry.npmjs.org/@timmeck/brain/latest',
+      { headers: { Accept: 'application/json' } },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          clearTimeout(timeout);
+          try {
+            const json = JSON.parse(data);
+            resolve(json.version ?? null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('error', () => {
+      clearTimeout(timeout);
+      resolve(null);
+    });
+  });
+}
+
+function isNewer(latest: string, current: string): boolean {
+  const l = latest.split('.').map(Number);
+  const c = current.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((l[i] ?? 0) > (c[i] ?? 0)) return true;
+    if ((l[i] ?? 0) < (c[i] ?? 0)) return false;
+  }
+  return false;
+}
+
+export async function checkForUpdate(): Promise<void> {
+  try {
+    const latest = await fetchLatestVersion();
+    if (latest && isNewer(latest, CURRENT_VERSION)) {
+      console.log();
+      console.log(`  ${icons.star}  ${c.orange.bold(`Update available: v${CURRENT_VERSION} → v${latest}`)}`);
+      console.log(`     Run: ${c.cyan('npm update -g @timmeck/brain')}`);
+    }
+  } catch {
+    // silently ignore — update check is best-effort
+  }
+}