ruvector 0.2.0 → 0.2.1

package/bin/cli.js

@@ -45,79 +45,59 @@ function requireRuvector() {
   }
 }
 
-// Lazy load GNN (optional - loaded on first use, not at startup)
-// Saves ~6ms startup time by deferring require('@ruvector/gnn')
-let _gnnModule = undefined; // undefined = not yet attempted, null = failed, object = loaded
+// Import GNN (optional - graceful fallback if not available)
 let RuvectorLayer, TensorCompress, differentiableSearch, getCompressionLevel, hierarchicalForward;
 let gnnAvailable = false;
-
-function loadGnn() {
-  if (_gnnModule !== undefined) return _gnnModule;
-  try {
-    const gnn = require('@ruvector/gnn');
-    RuvectorLayer = gnn.RuvectorLayer;
-    TensorCompress = gnn.TensorCompress;
-    differentiableSearch = gnn.differentiableSearch;
-    getCompressionLevel = gnn.getCompressionLevel;
-    hierarchicalForward = gnn.hierarchicalForward;
-    _gnnModule = gnn;
-    gnnAvailable = true;
-    return gnn;
-  } catch (e) {
-    _gnnModule = null;
-    gnnAvailable = false;
-    return null;
-  }
+try {
+  const gnn = require('@ruvector/gnn');
+  RuvectorLayer = gnn.RuvectorLayer;
+  TensorCompress = gnn.TensorCompress;
+  differentiableSearch = gnn.differentiableSearch;
+  getCompressionLevel = gnn.getCompressionLevel;
+  hierarchicalForward = gnn.hierarchicalForward;
+  gnnAvailable = true;
+} catch (e) {
+  // GNN not available - commands will show helpful message
 }
 
-// Lazy load Attention (optional - loaded on first use, not at startup)
-// Saves ~5ms startup time by deferring require('@ruvector/attention')
-let _attentionModule = undefined; // undefined = not yet attempted
+// Import Attention (optional - graceful fallback if not available)
 let DotProductAttention, MultiHeadAttention, HyperbolicAttention, FlashAttention, LinearAttention, MoEAttention;
 let GraphRoPeAttention, EdgeFeaturedAttention, DualSpaceAttention, LocalGlobalAttention;
 let benchmarkAttention, computeAttentionAsync, batchAttentionCompute, parallelAttentionCompute;
 let expMap, logMap, mobiusAddition, poincareDistance, projectToPoincareBall;
 let attentionInfo, attentionVersion;
 let attentionAvailable = false;
-
-function loadAttention() {
-  if (_attentionModule !== undefined) return _attentionModule;
-  try {
-    const attention = require('@ruvector/attention');
-    // Core mechanisms
-    DotProductAttention = attention.DotProductAttention;
-    MultiHeadAttention = attention.MultiHeadAttention;
-    HyperbolicAttention = attention.HyperbolicAttention;
-    FlashAttention = attention.FlashAttention;
-    LinearAttention = attention.LinearAttention;
-    MoEAttention = attention.MoEAttention;
-    // Graph attention
-    GraphRoPeAttention = attention.GraphRoPeAttention;
-    EdgeFeaturedAttention = attention.EdgeFeaturedAttention;
-    DualSpaceAttention = attention.DualSpaceAttention;
-    LocalGlobalAttention = attention.LocalGlobalAttention;
-    // Utilities
-    benchmarkAttention = attention.benchmarkAttention;
-    computeAttentionAsync = attention.computeAttentionAsync;
-    batchAttentionCompute = attention.batchAttentionCompute;
-    parallelAttentionCompute = attention.parallelAttentionCompute;
-    // Hyperbolic math
-    expMap = attention.expMap;
-    logMap = attention.logMap;
-    mobiusAddition = attention.mobiusAddition;
-    poincareDistance = attention.poincareDistance;
-    projectToPoincareBall = attention.projectToPoincareBall;
-    // Meta
-    attentionInfo = attention.info;
-    attentionVersion = attention.version;
-    _attentionModule = attention;
-    attentionAvailable = true;
-    return attention;
-  } catch (e) {
-    _attentionModule = null;
-    attentionAvailable = false;
-    return null;
-  }
+try {
+  const attention = require('@ruvector/attention');
+  // Core mechanisms
+  DotProductAttention = attention.DotProductAttention;
+  MultiHeadAttention = attention.MultiHeadAttention;
+  HyperbolicAttention = attention.HyperbolicAttention;
+  FlashAttention = attention.FlashAttention;
+  LinearAttention = attention.LinearAttention;
+  MoEAttention = attention.MoEAttention;
+  // Graph attention
+  GraphRoPeAttention = attention.GraphRoPeAttention;
+  EdgeFeaturedAttention = attention.EdgeFeaturedAttention;
+  DualSpaceAttention = attention.DualSpaceAttention;
+  LocalGlobalAttention = attention.LocalGlobalAttention;
+  // Utilities
+  benchmarkAttention = attention.benchmarkAttention;
+  computeAttentionAsync = attention.computeAttentionAsync;
+  batchAttentionCompute = attention.batchAttentionCompute;
+  parallelAttentionCompute = attention.parallelAttentionCompute;
+  // Hyperbolic math
+  expMap = attention.expMap;
+  logMap = attention.logMap;
+  mobiusAddition = attention.mobiusAddition;
+  poincareDistance = attention.poincareDistance;
+  projectToPoincareBall = attention.projectToPoincareBall;
+  // Meta
+  attentionInfo = attention.info;
+  attentionVersion = attention.version;
+  attentionAvailable = true;
+} catch (e) {
+  // Attention not available - commands will show helpful message
 }
 
 const program = new Command();
@@ -384,10 +364,6 @@ program
   .command('info')
   .description('Show ruvector information')
   .action(() => {
-    // Trigger lazy load of optional modules for availability check
-    loadGnn();
-    loadAttention();
-
     console.log(chalk.cyan('\nruvector Information'));
     console.log(chalk.white(`  CLI Version: ${chalk.yellow(packageJson.version)}`));
 
@@ -424,9 +400,6 @@ program
   .action(async (packages, options) => {
     const { execSync } = require('child_process');
 
-    // Trigger lazy load to check availability
-    loadGnn();
-
     // Available optional packages - all ruvector npm packages
     const availablePackages = {
       // Core packages
@@ -714,9 +687,8 @@ program
 // GNN Commands
 // =============================================================================
 
-// Helper to check GNN availability (triggers lazy load)
+// Helper to check GNN availability
 function requireGnn() {
-  loadGnn();
   if (!gnnAvailable) {
     console.error(chalk.red('Error: GNN module not available.'));
     console.error(chalk.yellow('Install it with: npm install @ruvector/gnn'));
@@ -912,7 +884,6 @@ gnnCmd
   .command('info')
   .description('Show GNN module information')
   .action(() => {
-    loadGnn();
     if (!gnnAvailable) {
       console.log(chalk.yellow('\nGNN Module: Not installed'));
       console.log(chalk.white('Install with: npm install @ruvector/gnn'));
@@ -942,9 +913,8 @@ gnnCmd
 // Attention Commands
 // =============================================================================
 
-// Helper to require attention module (triggers lazy load)
+// Helper to require attention module
 function requireAttention() {
-  loadAttention();
   if (!attentionAvailable) {
     console.error(chalk.red('Error: @ruvector/attention is not installed'));
     console.error(chalk.yellow('Install it with: npm install @ruvector/attention'));
@@ -1272,7 +1242,6 @@ attentionCmd
   .command('info')
   .description('Show attention module information')
   .action(() => {
-    loadAttention();
     if (!attentionAvailable) {
       console.log(chalk.yellow('\nAttention Module: Not installed'));
       console.log(chalk.white('Install with: npm install @ruvector/attention'));
@@ -1318,7 +1287,6 @@ attentionCmd
   .description('List all available attention mechanisms')
   .option('-v, --verbose', 'Show detailed information')
   .action((options) => {
-    loadAttention();
     console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
     console.log(chalk.cyan('              Available Attention Mechanisms'));
     console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
@@ -1375,10 +1343,6 @@ program
   .action(async (options) => {
     const { execSync } = require('child_process');
 
-    // Trigger lazy load of optional modules for availability check
-    loadGnn();
-    loadAttention();
-
     console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
     console.log(chalk.cyan('                    RuVector Doctor'));
     console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
@@ -2567,7 +2531,6 @@ program
     }
 
     if (options.gnn) {
-      loadGnn();
       if (!gnnAvailable) {
         console.log(chalk.yellow('  @ruvector/gnn not installed.'));
         console.log(chalk.white('  Install with: npm install @ruvector/gnn'));
@@ -7400,20 +7363,232 @@ mcpCmd.command('info')
     console.log();
   });
 
+// ============================================================================
+// MCP tools subcommand
+// ============================================================================
+
+mcpCmd.command('tools')
+  .description('List all MCP tools organized by group')
+  .option('--group <name>', 'Filter by group (hooks, workers, rvf, rvlite, brain, edge, identity)')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const toolGroups = {
+      'hooks-core': [
+        { name: 'hooks_stats', args: '(none)', desc: 'Get intelligence statistics' },
+        { name: 'hooks_route', args: 'task, file?', desc: 'Route task to best agent' },
+        { name: 'hooks_remember', args: 'content, type?', desc: 'Store context in vector memory' },
+        { name: 'hooks_recall', args: 'query, limit?', desc: 'Search vector memory' },
+        { name: 'hooks_init', args: 'project_path?, force?', desc: 'Initialize hooks in project' },
+        { name: 'hooks_pretrain', args: 'scan_path?, patterns?', desc: 'Pretrain from repository' },
+        { name: 'hooks_build_agents', args: 'project_path?', desc: 'Generate agent configs' },
+        { name: 'hooks_verify', args: '(none)', desc: 'Verify hooks configuration' },
+        { name: 'hooks_doctor', args: 'fix?', desc: 'Diagnose setup issues' },
+        { name: 'hooks_export', args: 'format?', desc: 'Export intelligence data' },
+      ],
+      'hooks-trajectory': [
+        { name: 'hooks_trajectory_start', args: 'task, context?', desc: 'Start learning trajectory' },
+        { name: 'hooks_trajectory_step', args: 'trajectory_id, action, result', desc: 'Record trajectory step' },
+        { name: 'hooks_trajectory_end', args: 'trajectory_id, outcome, score?', desc: 'End trajectory with outcome' },
+      ],
+      'hooks-coedit': [
+        { name: 'hooks_pre_edit', args: 'file, changes', desc: 'Pre-edit analysis' },
+        { name: 'hooks_post_edit', args: 'file, changes, result', desc: 'Post-edit learning' },
+        { name: 'hooks_pre_command', args: 'command, args?', desc: 'Pre-command analysis' },
+        { name: 'hooks_post_command', args: 'command, exit_code, output?', desc: 'Post-command learning' },
+        { name: 'hooks_pre_task', args: 'task, context?', desc: 'Pre-task routing' },
+        { name: 'hooks_post_task', args: 'task, result, duration?', desc: 'Post-task learning' },
+      ],
+      'hooks-errors': [
+        { name: 'hooks_error_learn', args: 'error, context?', desc: 'Learn from errors' },
+        { name: 'hooks_error_patterns', args: 'limit?', desc: 'Get learned error patterns' },
+        { name: 'hooks_error_suggest', args: 'error', desc: 'Suggest fix for error' },
+      ],
+      'hooks-analysis': [
+        { name: 'hooks_complexity', args: 'file', desc: 'Analyze code complexity' },
+        { name: 'hooks_dependencies', args: 'file', desc: 'Analyze dependencies' },
+        { name: 'hooks_security_scan', args: 'file', desc: 'Security vulnerability scan' },
+        { name: 'hooks_test_coverage', args: 'file', desc: 'Estimate test coverage' },
+        { name: 'hooks_dead_code', args: 'file', desc: 'Detect dead code' },
+        { name: 'hooks_duplicate_code', args: 'file', desc: 'Find duplicate code' },
+      ],
+      'hooks-learning': [
+        { name: 'hooks_pattern_store', args: 'pattern, category, confidence?', desc: 'Store a learned pattern' },
+        { name: 'hooks_pattern_search', args: 'query, category?, limit?', desc: 'Search patterns' },
+        { name: 'hooks_attention', args: 'query, context', desc: 'Attention-weighted relevance' },
+      ],
+      'hooks-compress': [
+        { name: 'hooks_compress_context', args: 'content, max_tokens?', desc: 'Compress context' },
+        { name: 'hooks_compress_code', args: 'code, language?', desc: 'Compress code representation' },
+        { name: 'hooks_compress_diff', args: 'diff', desc: 'Compress diff' },
+      ],
+      'hooks-events': [
+        { name: 'hooks_session_start', args: '(none)', desc: 'Signal session start' },
+        { name: 'hooks_session_end', args: 'summary?', desc: 'Signal session end' },
+        { name: 'hooks_notify', args: 'message, level?', desc: 'Send notification' },
+        { name: 'hooks_transfer', args: 'target, data', desc: 'Transfer context' },
+      ],
+      'hooks-model': [
+        { name: 'hooks_model_route', args: 'task, complexity?', desc: 'Route to optimal model tier' },
+        { name: 'hooks_model_outcome', args: 'model, task, success, tokens?', desc: 'Record model outcome' },
+        { name: 'hooks_model_stats', args: '(none)', desc: 'Get model routing stats' },
+      ],
+      'workers': [
+        { name: 'workers_list', args: '(none)', desc: 'List available workers' },
+        { name: 'workers_status', args: 'worker_id?', desc: 'Get worker status' },
+        { name: 'workers_dispatch', args: 'worker, task, args?', desc: 'Dispatch task to worker' },
+        { name: 'workers_cancel', args: 'job_id', desc: 'Cancel running job' },
+        { name: 'workers_detect', args: 'file', desc: 'Auto-detect applicable workers' },
+        { name: 'workers_complexity', args: 'file', desc: 'Worker: complexity analysis' },
+        { name: 'workers_dependencies', args: 'file', desc: 'Worker: dependency analysis' },
+        { name: 'workers_security', args: 'file', desc: 'Worker: security scan' },
+        { name: 'workers_coverage', args: 'file', desc: 'Worker: test coverage' },
+        { name: 'workers_dead_code', args: 'file', desc: 'Worker: dead code detection' },
+        { name: 'workers_duplicates', args: 'file', desc: 'Worker: duplicate detection' },
+        { name: 'workers_performance', args: 'file', desc: 'Worker: performance analysis' },
+      ],
+      'rvf': [
+        { name: 'rvf_create', args: 'path, dimension?, metric?', desc: 'Create new .rvf vector store' },
+        { name: 'rvf_open', args: 'path', desc: 'Open existing .rvf store' },
+        { name: 'rvf_ingest', args: 'path, vectors, ids?, metadata?', desc: 'Insert vectors' },
+        { name: 'rvf_query', args: 'path, vector, k?, filter?', desc: 'Query nearest neighbors' },
+        { name: 'rvf_delete', args: 'path, ids', desc: 'Delete vectors by ID' },
+        { name: 'rvf_status', args: 'path', desc: 'Get store status' },
+        { name: 'rvf_compact', args: 'path', desc: 'Compact store' },
+        { name: 'rvf_derive', args: 'parent_path, child_path', desc: 'COW-branch to child store' },
+        { name: 'rvf_segments', args: 'path', desc: 'List file segments' },
+        { name: 'rvf_examples', args: '(none)', desc: 'List example .rvf files' },
+      ],
+      'rvlite': [
+        { name: 'rvlite_sql', args: 'query, db_path?', desc: 'Execute SQL query' },
+        { name: 'rvlite_cypher', args: 'query, db_path?', desc: 'Execute Cypher graph query' },
+        { name: 'rvlite_sparql', args: 'query, db_path?', desc: 'Execute SPARQL RDF query' },
+      ],
+      'brain': [
+        { name: 'brain_search', args: 'query, category?, limit?', desc: 'Semantic search shared brain' },
+        { name: 'brain_share', args: 'title, content, category, tags?, code_snippet?', desc: 'Share knowledge' },
+        { name: 'brain_get', args: 'id', desc: 'Retrieve memory by ID' },
+        { name: 'brain_vote', args: 'id, direction', desc: 'Quality vote (up/down)' },
+        { name: 'brain_list', args: 'category?, limit?', desc: 'List recent memories' },
+        { name: 'brain_delete', args: 'id', desc: 'Delete own contribution' },
+        { name: 'brain_status', args: '(none)', desc: 'System health' },
+        { name: 'brain_drift', args: 'domain?', desc: 'Check knowledge drift' },
+        { name: 'brain_partition', args: 'domain?, min_cluster_size?', desc: 'Knowledge topology' },
+        { name: 'brain_transfer', args: 'source_domain, target_domain', desc: 'Cross-domain transfer' },
+        { name: 'brain_sync', args: 'direction?', desc: 'LoRA weight sync' },
+      ],
+      'edge': [
+        { name: 'edge_status', args: '(none)', desc: 'Network status' },
+        { name: 'edge_join', args: 'contribution?', desc: 'Join compute network' },
+        { name: 'edge_balance', args: '(none)', desc: 'Check rUv balance' },
+        { name: 'edge_tasks', args: 'limit?', desc: 'List compute tasks' },
+      ],
+      'identity': [
+        { name: 'identity_generate', args: '(none)', desc: 'Generate new pi key' },
+        { name: 'identity_show', args: '(none)', desc: 'Show current identity' },
+      ],
+    };
+
+    if (opts.json) {
+      const output = {};
+      Object.entries(toolGroups).forEach(([group, tools]) => {
+        if (!opts.group || group === opts.group || group.startsWith(opts.group)) {
+          output[group] = tools;
+        }
+      });
+      console.log(JSON.stringify(output, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold.cyan('\nRuVector MCP Tools\n'));
+    let total = 0;
+    Object.entries(toolGroups).forEach(([group, tools]) => {
+      if (opts.group && group !== opts.group && !group.startsWith(opts.group)) return;
+      console.log(chalk.bold.yellow(`  ${group} (${tools.length}):`));
+      tools.forEach(t => {
+        console.log(`    ${chalk.green(t.name.padEnd(28))} ${chalk.dim(t.args.padEnd(40))} ${t.desc}`);
+      });
+      console.log();
+      total += tools.length;
+    });
+    console.log(chalk.bold(`Total: ${total} MCP tools\n`));
+  });
+
+// ============================================================================
+// MCP test subcommand
+// ============================================================================
+
+mcpCmd.command('test')
+  .description('Test MCP server setup and tool registration')
+  .action(() => {
+    console.log(chalk.bold.cyan('\nMCP Server Test Results'));
+    console.log(chalk.dim('-'.repeat(40)));
+
+    const mcpServerPath = path.join(__dirname, 'mcp-server.js');
+    if (fs.existsSync(mcpServerPath)) {
+      console.log(`  ${chalk.green('PASS')} mcp-server.js exists`);
+    } else {
+      console.log(`  ${chalk.red('FAIL')} mcp-server.js not found`);
+      process.exit(1);
+    }
+
+    try {
+      const { execSync } = require('child_process');
+      execSync(`node -c ${mcpServerPath}`, { stdio: 'pipe' });
+      console.log(`  ${chalk.green('PASS')} mcp-server.js syntax valid`);
+    } catch {
+      console.log(`  ${chalk.red('FAIL')} mcp-server.js has syntax errors`);
+      process.exit(1);
+    }
+
+    try {
+      require('@modelcontextprotocol/sdk/server/index.js');
+      console.log(`  ${chalk.green('PASS')} @modelcontextprotocol/sdk installed`);
+    } catch {
+      console.log(`  ${chalk.red('FAIL')} @modelcontextprotocol/sdk not installed`);
+      process.exit(1);
+    }
+
+    try {
+      const src = fs.readFileSync(mcpServerPath, 'utf8');
+      const toolsStart = src.indexOf('const TOOLS = [');
+      const toolsSection = toolsStart >= 0 ? src.slice(toolsStart) : src;
+      const toolDefs = toolsSection.match(/name:\s*'([a-z][a-z0-9_]*)'\s*,\s*\n\s*description:/g) || [];
+      const toolNames = toolDefs.map(m => m.match(/name:\s*'([a-z][a-z0-9_]*)'/)[1]);
+      const groups = {};
+      toolNames.forEach(n => {
+        const g = n.split('_')[0];
+        groups[g] = (groups[g] || 0) + 1;
+      });
+
+      Object.entries(groups).sort((a, b) => b[1] - a[1]).forEach(([group, count]) => {
+        console.log(`  ${chalk.green('PASS')} ${group}: ${count} tools`);
+      });
+      console.log(chalk.bold(`\n  Total: ${toolNames.length} tools registered`));
+    } catch (e) {
+      console.log(`  ${chalk.yellow('WARN')} Could not parse tool count: ${e.message}`);
+    }
+
+    try {
+      const src = fs.readFileSync(mcpServerPath, 'utf8');
+      const verMatch = src.match(/version:\s*'([^']+)'/);
+      if (verMatch) {
+        const pkg = require(path.join(__dirname, '..', 'package.json'));
+        const match = verMatch[1] === pkg.version;
+        console.log(`  ${match ? chalk.green('PASS') : chalk.yellow('WARN')} Server version: ${verMatch[1]}${match ? '' : ` (package: ${pkg.version})`}`);
+      }
+    } catch {}
+
+    console.log(chalk.bold.green('\n  All checks passed.\n'));
+    console.log(chalk.dim('  Setup: claude mcp add ruvector npx ruvector mcp start\n'));
+  });
+
 // ============================================================================
 // Brain Commands — Shared intelligence via @ruvector/pi-brain (lazy-loaded)
 // ============================================================================
 
-let _piBrainClient = null;
-async function getPiBrainClient(opts = {}) {
-  if (_piBrainClient) return _piBrainClient;
+async function requirePiBrain() {
   try {
-    const piBrain = require('@ruvector/pi-brain');
-    const PiBrainClient = piBrain.PiBrainClient || piBrain.default;
-    const url = opts.url || process.env.BRAIN_URL || 'https://pi.ruv.io';
-    const key = opts.key || process.env.PI || '';
-    _piBrainClient = new PiBrainClient({ url, key });
-    return _piBrainClient;
+    return require('@ruvector/pi-brain');
   } catch {
     console.error(chalk.red('Brain commands require @ruvector/pi-brain'));
     console.error(chalk.yellow('  npm install @ruvector/pi-brain'));
@@ -7421,114 +7596,90 @@ async function getPiBrainClient(opts = {}) {
   }
 }
 
-const brainCmd = program.command('brain').description('Shared intelligence — search, share, vote on collective knowledge');
+function getBrainConfig(opts) {
+  return {
+    url: opts.url || process.env.BRAIN_URL || 'https://pi.ruv.io',
+    key: opts.key || process.env.PI
+  };
+}
+
+const brainCmd = program.command('brain').description('Shared intelligence — search, share, and manage collective knowledge');
 
 brainCmd.command('search <query>')
-  .description('Semantic search across shared knowledge')
-  .option('-l, --limit <n>', 'Max results', '10')
+  .description('Semantic search across shared brain knowledge')
   .option('-c, --category <cat>', 'Filter by category')
+  .option('-l, --limit <n>', 'Max results', '10')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (query, opts) => {
-    const spinner = ora(`Searching brain for "${query}"...`);
-    spinner.start();
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
-      const results = await client.search(query, { limit: parseInt(opts.limit), category: opts.category });
-      spinner.stop();
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(results, null, 2));
-      } else {
-        const items = results.memories || results.results || results || [];
-        if (items.length === 0) {
-          console.log(chalk.yellow('No results found.'));
-        } else {
-          items.forEach((m, i) => {
-            console.log(chalk.bold.cyan(`${i + 1}. ${m.title || m.id}`));
-            if (m.category) console.log(chalk.dim(`   Category: ${m.category}`));
-            if (m.quality_score != null) console.log(chalk.dim(`   Quality: ${(m.quality_score * 100).toFixed(0)}%`));
-            if (m.content) console.log(`   ${m.content.slice(0, 120)}${m.content.length > 120 ? '...' : ''}`);
-            console.log();
-          });
-        }
-      }
-    } catch (e) {
-      spinner.stop();
-      console.error(chalk.red('Search failed:'), e.message);
-      process.exit(1);
-    }
+      const client = new piBrain.PiBrainClient(config);
+      const results = await client.search(query, { category: opts.category, limit: parseInt(opts.limit) });
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(results, null, 2)); return; }
+      console.log(chalk.bold.cyan(`\nBrain Search: "${query}"\n`));
+      if (!results.length) { console.log(chalk.dim('  No results found.\n')); return; }
+      results.forEach((r, i) => {
+        console.log(`  ${chalk.yellow(i + 1 + '.')} ${chalk.bold(r.title || r.id)}`);
+        if (r.category) console.log(`     ${chalk.dim('Category:')} ${r.category}`);
+        if (r.score) console.log(`     ${chalk.dim('Score:')} ${r.score.toFixed(3)}`);
+        console.log();
+      });
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('share <title>')
   .description('Share knowledge with the collective brain')
-  .option('-c, --category <cat>', 'Category (pattern, solution, architecture, convention, security, performance, tooling)', 'pattern')
+  .requiredOption('-c, --category <cat>', 'Category (pattern, solution, architecture, convention, security, performance, tooling)')
   .option('-t, --tags <tags>', 'Comma-separated tags')
-  .option('--content <text>', 'Content body (or pipe via stdin)')
+  .option('--content <text>', 'Content body')
+  .option('--code <snippet>', 'Code snippet')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
+  .option('--key <key>', 'Pi key')
   .action(async (title, opts) => {
-    const spinner = ora('Sharing with brain...');
-    spinner.start();
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
-      let content = opts.content || '';
-      if (!content && !process.stdin.isTTY) {
-        const chunks = [];
-        for await (const chunk of process.stdin) chunks.push(chunk);
-        content = Buffer.concat(chunks).toString('utf8');
-      }
-      if (!content) { spinner.stop(); console.error(chalk.red('Provide content via --content or stdin')); process.exit(1); }
-      const tags = opts.tags ? opts.tags.split(',').map(t => t.trim()) : [];
-      const result = await client.share({ title, content, category: opts.category, tags });
-      spinner.succeed(chalk.green(`Shared: ${result.id || 'ok'}`));
-    } catch (e) {
-      spinner.fail(chalk.red('Share failed: ' + e.message));
-      process.exit(1);
-    }
+      const client = new piBrain.PiBrainClient(config);
+      const result = await client.share({ title, content: opts.content || title, category: opts.category, tags: opts.tags ? opts.tags.split(',').map(t => t.trim()) : [], code_snippet: opts.code });
+      console.log(chalk.green(`Shared: ${result.id || 'OK'}`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('get <id>')
-  .description('Retrieve a specific memory with provenance')
+  .description('Retrieve a specific memory by ID')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (id, opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       const result = await client.get(id);
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(chalk.bold.cyan(result.title || result.id));
-        if (result.category) console.log(chalk.dim(`Category: ${result.category}`));
-        if (result.content) console.log(`\n${result.content}`);
-        if (result.tags && result.tags.length) console.log(chalk.dim(`\nTags: ${result.tags.join(', ')}`));
-        if (result.contributor_pseudonym) console.log(chalk.dim(`Contributor: ${result.contributor_pseudonym}`));
-      }
-    } catch (e) {
-      console.error(chalk.red('Get failed:'), e.message);
-      process.exit(1);
-    }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result, null, 2)); return; }
+      console.log(chalk.bold.cyan(`\nMemory: ${id}\n`));
+      if (result.title) console.log(`  ${chalk.bold('Title:')} ${result.title}`);
+      if (result.content) console.log(`  ${chalk.bold('Content:')} ${result.content}`);
+      if (result.category) console.log(`  ${chalk.bold('Category:')} ${result.category}`);
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('vote <id> <direction>')
-  .description('Vote on knowledge quality (up or down)')
+  .description('Quality vote on a memory (up or down)')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
+  .option('--key <key>', 'Pi key')
   .action(async (id, direction, opts) => {
-    if (!['up', 'down'].includes(direction)) {
-      console.error(chalk.red('Direction must be "up" or "down"'));
-      process.exit(1);
-    }
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       await client.vote(id, direction);
       console.log(chalk.green(`Voted ${direction} on ${id}`));
-    } catch (e) {
-      console.error(chalk.red('Vote failed:'), e.message);
-      process.exit(1);
-    }
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('list')
@@ -7536,594 +7687,533 @@ brainCmd.command('list')
   .option('-c, --category <cat>', 'Filter by category')
   .option('-l, --limit <n>', 'Max results', '20')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       const results = await client.list({ category: opts.category, limit: parseInt(opts.limit) });
-      const items = results.memories || results || [];
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(items, null, 2));
-      } else {
-        if (items.length === 0) { console.log(chalk.yellow('No memories found.')); return; }
-        items.forEach((m, i) => {
-          const quality = m.quality_score != null ? chalk.dim(` [${(m.quality_score * 100).toFixed(0)}%]`) : '';
-          console.log(`${chalk.bold(i + 1 + '.')} ${m.title || m.id}${quality} ${chalk.dim(m.category || '')}`);
-        });
-      }
-    } catch (e) {
-      console.error(chalk.red('List failed:'), e.message);
-      process.exit(1);
-    }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(results, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nShared Brain Memories\n'));
+      if (!results.length) { console.log(chalk.dim('  No memories found.\n')); return; }
+      results.forEach((r, i) => {
+        console.log(`  ${chalk.yellow(i + 1 + '.')} ${chalk.bold(r.title || r.id)} ${chalk.dim(`[${r.category || 'unknown'}]`)}`);
+      });
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('delete <id>')
   .description('Delete your own contribution')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
+  .option('--key <key>', 'Pi key')
   .action(async (id, opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       await client.delete(id);
-      console.log(chalk.green(`Deleted ${id}`));
-    } catch (e) {
-      console.error(chalk.red('Delete failed:'), e.message);
-      process.exit(1);
-    }
+      console.log(chalk.green(`Deleted: ${id}`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('status')
-  .description('Show brain system health and statistics')
+  .description('Show shared brain system health')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       const status = await client.status();
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(status, null, 2));
-      } else {
-        console.log(chalk.bold.cyan('\nBrain Status'));
-        console.log(chalk.dim('-'.repeat(40)));
-        Object.entries(status).forEach(([k, v]) => {
-          console.log(`  ${chalk.bold(k)}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
-        });
-        console.log();
-      }
-    } catch (e) {
-      console.error(chalk.red('Status failed:'), e.message);
-      process.exit(1);
-    }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(status, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nBrain Status\n'));
+      Object.entries(status).forEach(([k, v]) => {
+        console.log(`  ${chalk.bold(k + ':')} ${v}`);
+      });
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('drift')
-  .description('Check knowledge drift between local and shared')
+  .description('Check if shared knowledge has drifted')
   .option('-d, --domain <domain>', 'Domain to check')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       const report = await client.drift({ domain: opts.domain });
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(report, null, 2));
-      } else {
-        console.log(chalk.bold.cyan('\nDrift Report'));
-        console.log(chalk.dim('-'.repeat(40)));
-        console.log(`  CV: ${report.cv || 'N/A'}`);
-        console.log(`  Drifting: ${report.is_drifting ? chalk.red('YES') : chalk.green('NO')}`);
-        if (report.suggested_action) console.log(`  Action: ${report.suggested_action}`);
-        console.log();
-      }
-    } catch (e) {
-      console.error(chalk.red('Drift check failed:'), e.message);
-      process.exit(1);
-    }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(report, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nDrift Report\n'));
+      console.log(`  ${chalk.bold('Drifting:')} ${report.is_drifting ? chalk.red('Yes') : chalk.green('No')}`);
+      if (report.cv) console.log(`  ${chalk.bold('CV:')} ${report.cv}`);
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('partition')
-  .description('Get knowledge topology via mincut partitioning')
+  .description('Get knowledge partitioned by mincut topology')
   .option('-d, --domain <domain>', 'Domain to partition')
-  .option('--min-cluster <n>', 'Minimum cluster size', '3')
+  .option('--min-size <n>', 'Minimum cluster size', '3')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
-      const result = await client.partition({ domain: opts.domain, min_cluster_size: parseInt(opts.minCluster) });
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        const clusters = result.clusters || [];
-        console.log(chalk.bold.cyan(`\nKnowledge Partitions: ${clusters.length} clusters`));
-        console.log(chalk.dim('-'.repeat(40)));
-        clusters.forEach((c, i) => {
-          console.log(`  ${chalk.bold('Cluster ' + (i + 1))}: ${c.size || (c.members && c.members.length) || '?'} memories`);
-          if (c.label) console.log(`    Label: ${c.label}`);
-          if (c.edge_strength != null) console.log(chalk.dim(`    Edge strength: ${c.edge_strength.toFixed(3)}`));
+      const client = new piBrain.PiBrainClient(config);
+      const result = await client.partition({ domain: opts.domain, min_cluster_size: parseInt(opts.minSize) });
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nKnowledge Partitions\n'));
+      if (result.clusters) {
+        result.clusters.forEach((c, i) => {
+          console.log(`  ${chalk.yellow('Cluster ' + (i + 1) + ':')} ${c.size || 'unknown'} entries`);
         });
-        console.log();
       }
-    } catch (e) {
-      console.error(chalk.red('Partition failed:'), e.message);
-      process.exit(1);
-    }
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('transfer <source> <target>')
-  .description('Transfer learned priors between domains')
+  .description('Apply learned priors from one domain to another')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
   .action(async (source, target, opts) => {
-    const spinner = ora(`Transferring ${source} -> ${target}...`);
-    spinner.start();
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
+      const client = new piBrain.PiBrainClient(config);
       const result = await client.transfer(source, target);
-      spinner.stop();
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(chalk.green(`Transfer complete: ${source} -> ${target}`));
-        if (result.acceleration_factor) console.log(`  Acceleration: ${result.acceleration_factor.toFixed(2)}x`);
-        if (result.improved_target != null) console.log(`  Target improved: ${result.improved_target ? 'yes' : 'no'}`);
-      }
-    } catch (e) {
-      spinner.stop();
-      console.error(chalk.red('Transfer failed:'), e.message);
-      process.exit(1);
-    }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result, null, 2)); return; }
+      console.log(chalk.green(`Transfer ${source} -> ${target}: ${result.status || 'OK'}`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 brainCmd.command('sync [direction]')
-  .description('Sync LoRA weights (pull, push, or both)')
+  .description('Synchronize LoRA weights (pull, push, or both)')
   .option('--url <url>', 'Brain server URL')
-  .option('--key <key>', 'PI key')
+  .option('--key <key>', 'Pi key')
   .action(async (direction, opts) => {
-    const dir = direction || 'both';
-    const spinner = ora(`LoRA sync (${dir})...`);
-    spinner.start();
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
     try {
-      const client = await getPiBrainClient(opts);
-      const result = await client.loraSync({ direction: dir });
-      spinner.succeed(chalk.green(`LoRA sync ${dir}: ${result.status || 'ok'}`));
-    } catch (e) {
-      spinner.fail(chalk.red('Sync failed: ' + e.message));
-      process.exit(1);
-    }
+      const client = new piBrain.PiBrainClient(config);
+      const result = await client.sync(direction || 'both');
+      console.log(chalk.green(`Sync ${direction || 'both'}: ${result.status || 'OK'}`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 // ============================================================================
-// Edge Commands — Distributed compute via edge-net (native fetch)
+// Edge Commands — Distributed compute via @ruvector/edge-net
 // ============================================================================
 
-const EDGE_GENESIS = 'https://edge-net-genesis-875130704813.us-central1.run.app';
-const EDGE_RELAY = 'https://edge-net-relay-875130704813.us-central1.run.app';
-const EDGE_DASHBOARD = 'https://edge-net-dashboard-875130704813.us-central1.run.app';
+const edgeCmd = program.command('edge').description('Distributed P2P compute network — status, join, balance, tasks');
 
-const edgeCmd = program.command('edge').description('Edge-net distributed compute network');
+const EDGE_GENESIS = 'https://edge-net-genesis-875130704813.us-central1.run.app';
 
 edgeCmd.command('status')
-  .description('Query network status (genesis, relay, nodes)')
-  .option('--json', 'JSON output')
+  .description('Show edge compute network status')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
-    const spinner = ora('Querying edge network...');
-    spinner.start();
     try {
-      const res = await fetch(`${EDGE_GENESIS}/api/status`);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      const data = await res.json();
-      spinner.stop();
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(data, null, 2));
-      } else {
-        console.log(chalk.bold.cyan('\nEdge Network Status'));
-        console.log(chalk.dim('-'.repeat(40)));
-        if (data.nodes != null) console.log(`  Nodes: ${data.nodes}`);
-        if (data.total_compute != null) console.log(`  Compute: ${data.total_compute}`);
-        if (data.ruv_supply != null) console.log(`  rUv Supply: ${data.ruv_supply}`);
-        if (data.phase) console.log(`  Phase: ${data.phase}`);
-        console.log();
-      }
-    } catch (e) {
-      spinner.stop();
-      console.error(chalk.red('Edge status failed:'), e.message);
-      console.error(chalk.dim('  Genesis URL: ' + EDGE_GENESIS));
-    }
+      const resp = await fetch(`${EDGE_GENESIS}/status`);
+      const data = await resp.json();
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nEdge Network Status\n'));
+      Object.entries(data).forEach(([k, v]) => console.log(`  ${chalk.bold(k + ':')} ${v}`));
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 edgeCmd.command('join')
-  .description('Join as a compute node')
-  .option('--contribution <n>', 'Contribution factor (0.0 - 1.0)', '0.3')
-  .option('--key <key>', 'PI key')
+  .description('Join the edge compute network as a compute node')
+  .option('--contribution <level>', 'Contribution level 0.0-1.0', '0.3')
   .action(async (opts) => {
-    const key = opts.key || process.env.PI || '';
-    if (!key) {
-      console.error(chalk.red('PI key required. Set PI env var or use --key'));
-      console.error(chalk.yellow('  Generate one: npx ruvector identity generate'));
-      process.exit(1);
-    }
-    console.log(chalk.cyan(`Joining edge network (contribution=${opts.contribution})...`));
-    console.log(chalk.dim('This is a long-running process. Press Ctrl+C to leave.\n'));
+    const piKey = process.env.PI;
+    if (!piKey) { console.error(chalk.red('Set PI environment variable first. Run: npx ruvector identity generate')); process.exit(1); }
     try {
-      const res = await fetch(`${EDGE_RELAY}/api/join`, {
+      const resp = await fetch(`${EDGE_GENESIS}/join`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${key}` },
-        body: JSON.stringify({ contribution: parseFloat(opts.contribution) })
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${piKey}` },
+        body: JSON.stringify({ contribution: parseFloat(opts.contribution), pi_key: piKey })
       });
-      if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
-      const data = await res.json();
-      console.log(chalk.green('Joined network.'), data.node_id ? `Node: ${data.node_id}` : '');
-    } catch (e) {
-      console.error(chalk.red('Join failed:'), e.message);
-      process.exit(1);
-    }
+      const data = await resp.json();
+      console.log(chalk.green(`Joined edge network: ${data.node_id || 'OK'}`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 edgeCmd.command('balance')
-  .description('Check rUv balance for current identity')
-  .option('--key <key>', 'PI key')
-  .option('--json', 'JSON output')
+  .description('Check rUv credit balance')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
-    const key = opts.key || process.env.PI || '';
-    if (!key) { console.error(chalk.red('PI key required')); process.exit(1); }
+    const piKey = process.env.PI;
+    if (!piKey) { console.error(chalk.red('Set PI environment variable first.')); process.exit(1); }
     try {
-      const crypto = require('crypto');
-      const pseudonym = crypto.createHash('shake256', { outputLength: 16 }).update(key).digest('hex');
-      const res = await fetch(`${EDGE_GENESIS}/api/balance/${pseudonym}`);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      const data = await res.json();
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(data, null, 2));
-      } else {
-        console.log(chalk.bold.cyan(`\nrUv Balance: ${data.balance != null ? data.balance : 'N/A'}`));
-        if (data.earned != null) console.log(chalk.dim(`  Earned: ${data.earned}`));
-        if (data.spent != null) console.log(chalk.dim(`  Spent: ${data.spent}`));
-        console.log();
-      }
-    } catch (e) {
-      console.error(chalk.red('Balance check failed:'), e.message);
-    }
+      const resp = await fetch(`${EDGE_GENESIS}/balance/${piKey}`, { headers: { 'Authorization': `Bearer ${piKey}` } });
+      const data = await resp.json();
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nrUv Balance\n'));
+      console.log(`  ${chalk.bold('Balance:')} ${data.balance || 0} rUv`);
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 edgeCmd.command('tasks')
   .description('List available distributed compute tasks')
-  .option('--json', 'JSON output')
+  .option('-l, --limit <n>', 'Max tasks', '20')
+  .option('--json', 'Output as JSON')
   .action(async (opts) => {
     try {
-      const res = await fetch(`${EDGE_GENESIS}/api/tasks`);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      const data = await res.json();
-      const tasks = data.tasks || data || [];
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(tasks, null, 2));
-      } else {
-        if (tasks.length === 0) { console.log(chalk.yellow('No tasks available.')); return; }
-        console.log(chalk.bold.cyan(`\n${tasks.length} available tasks\n`));
-        tasks.forEach((t, i) => {
-          console.log(`  ${chalk.bold(i + 1 + '.')} ${t.type || t.id} -- ${t.reward || '?'} rUv`);
-        });
-        console.log();
-      }
-    } catch (e) {
-      console.error(chalk.red('Tasks query failed:'), e.message);
-    }
+      const resp = await fetch(`${EDGE_GENESIS}/tasks?limit=${opts.limit}`);
+      const data = await resp.json();
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nEdge Compute Tasks\n'));
+      const tasks = Array.isArray(data) ? data : data.tasks || [];
+      if (!tasks.length) { console.log(chalk.dim('  No tasks available.\n')); return; }
+      tasks.forEach((t, i) => console.log(`  ${chalk.yellow(i + 1 + '.')} ${t.name || t.id} ${chalk.dim(`[${t.status || 'pending'}]`)}`));
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 edgeCmd.command('dashboard')
   .description('Open edge-net dashboard in browser')
   .action(() => {
-    const url = EDGE_DASHBOARD;
-    console.log(chalk.cyan(`Opening: ${url}`));
-    const { exec } = require('child_process');
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    exec(`${cmd} ${url}`, () => {});
+    const url = 'https://edge-net-dashboard-875130704813.us-central1.run.app';
+    console.log(chalk.cyan(`Dashboard: ${url}`));
+    try {
+      const { execSync } = require('child_process');
+      const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+      execSync(`${cmd} ${url}`, { stdio: 'ignore' });
+    } catch { console.log(chalk.dim('  Open the URL above in your browser.')); }
   });
 
 // ============================================================================
-// Identity Commands — pi key management (Node.js crypto)
+// Identity Commands — Pi key management
 // ============================================================================
 
-const identityCmd = program.command('identity').description('Pi key management for brain, edge, and MCP identity');
+const identityCmd = program.command('identity').description('Pi key identity management — generate, show, export, import');
 
 identityCmd.command('generate')
   .description('Generate a new pi key')
   .action(() => {
     const crypto = require('crypto');
     const key = crypto.randomBytes(32).toString('hex');
-    const pseudonym = crypto.createHash('shake256', { outputLength: 16 }).update(key).digest('hex');
-    console.log(chalk.bold.cyan('\nNew Pi Key Generated\n'));
-    console.log(chalk.bold('Key:       ') + chalk.yellow(key));
-    console.log(chalk.bold('Pseudonym: ') + chalk.green(pseudonym));
-    console.log(chalk.dim('\nStore this key securely. Set it as:'));
-    console.log(chalk.dim('  export PI=' + key));
-    console.log(chalk.dim('  # or add to .env file'));
+    const hash = crypto.createHash('shake256', { outputLength: 16 });
+    hash.update(key);
+    const pseudonym = hash.digest('hex');
+    console.log(chalk.bold.cyan('\nNew Pi Identity Generated\n'));
+    console.log(`  ${chalk.bold('Pi Key:')}     ${chalk.yellow(key)}`);
+    console.log(`  ${chalk.bold('Pseudonym:')}  ${chalk.green(pseudonym)}`);
     console.log();
+    console.log(chalk.dim('  Store securely. Set PI env var to use:'));
+    console.log(chalk.cyan(`  export PI=${key}\n`));
   });
 
 identityCmd.command('show')
-  .description('Display current identity derived from PI key')
-  .option('--key <key>', 'PI key (default: PI env var)')
+  .description('Show current pi key pseudonym and derived identities')
+  .option('--json', 'Output as JSON')
   .action((opts) => {
-    const key = opts.key || process.env.PI || '';
-    if (!key) {
-      console.error(chalk.red('No PI key found. Set PI env var or use --key'));
-      console.error(chalk.yellow('  Generate one: npx ruvector identity generate'));
+    const piKey = process.env.PI;
+    if (!piKey) {
+      console.error(chalk.red('No PI environment variable set.'));
+      console.error(chalk.yellow('  Run: npx ruvector identity generate'));
       process.exit(1);
     }
     const crypto = require('crypto');
-    const pseudonym = crypto.createHash('shake256', { outputLength: 16 }).update(key).digest('hex');
-    const mcpToken = crypto.createHmac('sha256', key).update('mcp').digest('hex').slice(0, 32);
+    const hash = crypto.createHash('shake256', { outputLength: 16 });
+    hash.update(piKey);
+    const pseudonym = hash.digest('hex');
+    const mcpToken = crypto.createHmac('sha256', piKey).update('mcp').digest('hex').slice(0, 32);
+    if (opts.json || !process.stdout.isTTY) {
+      console.log(JSON.stringify({ pseudonym, mcp_token: mcpToken, key_prefix: piKey.slice(0, 8) + '...' }, null, 2));
+      return;
+    }
     console.log(chalk.bold.cyan('\nPi Identity\n'));
-    console.log(chalk.bold('Brain Pseudonym: ') + chalk.green(pseudonym));
-    console.log(chalk.bold('MCP Token:       ') + chalk.dim(mcpToken));
-    console.log(chalk.bold('Key (first 8):   ') + chalk.dim(key.slice(0, 8) + '...'));
+    console.log(`  ${chalk.bold('Key:')}        ${piKey.slice(0, 8)}...${piKey.slice(-8)}`);
+    console.log(`  ${chalk.bold('Pseudonym:')}  ${chalk.green(pseudonym)}`);
+    console.log(`  ${chalk.bold('MCP Token:')} ${chalk.dim(mcpToken)}`);
     console.log();
   });
 
-identityCmd.command('export')
-  .description('Export key to encrypted file')
-  .option('-o, --output <path>', 'Output file', 'pi-key.enc')
-  .option('--key <key>', 'PI key')
-  .action((opts) => {
-    const key = opts.key || process.env.PI || '';
-    if (!key) { console.error(chalk.red('No PI key found.')); process.exit(1); }
+identityCmd.command('export <file>')
+  .description('Export pi key to encrypted file')
+  .action((file) => {
+    const piKey = process.env.PI;
+    if (!piKey) { console.error(chalk.red('No PI environment variable set.')); process.exit(1); }
     const crypto = require('crypto');
-    const password = crypto.randomBytes(16).toString('hex');
+    const passphrase = crypto.randomBytes(16).toString('hex');
+    const key = crypto.scryptSync(passphrase, 'ruvector-pi', 32);
     const iv = crypto.randomBytes(16);
-    const cipher = crypto.createCipheriv('aes-256-gcm', crypto.scryptSync(password, 'ruvector', 32), iv);
-    let encrypted = cipher.update(key, 'utf8', 'hex');
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    let encrypted = cipher.update(piKey, 'utf8', 'hex');
     encrypted += cipher.final('hex');
-    const tag = cipher.getAuthTag().toString('hex');
-    const data = JSON.stringify({ iv: iv.toString('hex'), tag, data: encrypted, v: 1 });
-    fs.writeFileSync(opts.output, data);
-    console.log(chalk.green(`Key exported to ${opts.output}`));
-    console.log(chalk.bold('Passphrase: ') + chalk.yellow(password));
-    console.log(chalk.dim('Store this passphrase separately from the export file.'));
+    const tag = cipher.getAuthTag();
+    const data = { iv: iv.toString('hex'), tag: tag.toString('hex'), data: encrypted };
+    fs.writeFileSync(file, JSON.stringify(data));
+    console.log(chalk.green(`Exported to ${file}`));
+    console.log(chalk.bold(`Passphrase: ${chalk.yellow(passphrase)}`));
+    console.log(chalk.dim('  Store passphrase separately from the export file.\n'));
   });
 
 identityCmd.command('import <file>')
-  .description('Import key from encrypted backup')
-  .option('-p, --passphrase <pass>', 'Decryption passphrase')
+  .description('Import pi key from encrypted backup')
+  .requiredOption('-p, --passphrase <pass>', 'Decryption passphrase')
   .action((file, opts) => {
-    if (!opts.passphrase) { console.error(chalk.red('Passphrase required (--passphrase)')); process.exit(1); }
     try {
       const crypto = require('crypto');
       const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
-      const decipher = crypto.createDecipheriv('aes-256-gcm', crypto.scryptSync(opts.passphrase, 'ruvector', 32), Buffer.from(raw.iv, 'hex'));
+      const key = crypto.scryptSync(opts.passphrase, 'ruvector-pi', 32);
+      const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(raw.iv, 'hex'));
       decipher.setAuthTag(Buffer.from(raw.tag, 'hex'));
-      let key = decipher.update(raw.data, 'hex', 'utf8');
-      key += decipher.final('utf8');
-      const pseudonym = crypto.createHash('shake256', { outputLength: 16 }).update(key).digest('hex');
+      let decrypted = decipher.update(raw.data, 'hex', 'utf8');
+      decrypted += decipher.final('utf8');
       console.log(chalk.green('Key imported successfully.'));
-      console.log(chalk.bold('Pseudonym: ') + chalk.green(pseudonym));
-      console.log(chalk.dim(`\nSet it: export PI=${key}`));
-    } catch (e) {
-      console.error(chalk.red('Import failed:'), e.message);
-      process.exit(1);
-    }
+      console.log(chalk.cyan(`  export PI=${decrypted}\n`));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 // ============================================================================
-// LLM Commands — LLM orchestration via @ruvector/ruvllm (lazy-loaded)
+// LLM Commands — Text embeddings via @ruvector/ruvllm (lazy-loaded)
 // ============================================================================
 
-const llmCmd = program.command('llm').description('LLM orchestration — embeddings, models, benchmarks');
+const llmCmd = program.command('llm').description('LLM embeddings and inference via @ruvector/ruvllm');
+
+function requireRuvllm() {
+  try { return require('@ruvector/ruvllm'); } catch {
+    console.error(chalk.red('LLM commands require @ruvector/ruvllm'));
+    console.error(chalk.yellow('  npm install @ruvector/ruvllm'));
+    process.exit(1);
+  }
+}
 
 llmCmd.command('embed <text>')
-  .description('Generate embeddings via ruvllm')
-  .option('-m, --model <model>', 'Model name', 'default')
-  .option('--json', 'JSON output')
-  .action(async (text, opts) => {
+  .description('Generate text embeddings')
+  .option('-m, --model <model>', 'Model name')
+  .option('--json', 'Output as JSON')
+  .action((text, opts) => {
+    const ruvllm = requireRuvllm();
     try {
-      const ruvllm = require('@ruvector/ruvllm');
-      const embed = ruvllm.embed || (ruvllm.default && ruvllm.default.embed);
-      if (!embed) throw new Error('ruvllm.embed not found');
-      const result = await embed(text, { model: opts.model });
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(result));
-      } else {
-        const vec = result.embedding || result;
-        console.log(chalk.cyan(`Embedding (dim=${Array.isArray(vec) ? vec.length : '?'}):`));
-        if (Array.isArray(vec)) console.log(chalk.dim(`  [${vec.slice(0, 8).map(v => v.toFixed(4)).join(', ')}${vec.length > 8 ? ', ...' : ''}]`));
-      }
-    } catch (e) {
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('LLM commands require @ruvector/ruvllm'));
-        console.error(chalk.yellow('  npm install @ruvector/ruvllm'));
-      } else {
-        console.error(chalk.red('Embed failed:'), e.message);
-      }
-      process.exit(1);
-    }
+      const embedding = ruvllm.embed ? ruvllm.embed(text, opts.model) : ruvllm.generateEmbedding(text);
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify({ embedding, dimension: embedding.length })); return; }
+      console.log(chalk.bold.cyan('\nEmbedding Generated\n'));
+      console.log(`  ${chalk.bold('Dimension:')} ${embedding.length}`);
+      console.log(`  ${chalk.bold('Preview:')} [${embedding.slice(0, 5).map(v => v.toFixed(4)).join(', ')}...]`);
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
 llmCmd.command('models')
   .description('List available LLM models')
-  .action(async () => {
+  .action(() => {
+    const ruvllm = requireRuvllm();
     try {
-      const ruvllm = require('@ruvector/ruvllm');
-      const models = ruvllm.listModels ? await ruvllm.listModels() : [];
-      if (models.length === 0) { console.log(chalk.yellow('No models found.')); return; }
-      console.log(chalk.bold.cyan('\nAvailable Models\n'));
-      models.forEach(m => {
-        console.log(`  ${chalk.bold(m.name || m.id)} ${chalk.dim(m.provider || '')} ${chalk.dim(m.size || '')}`);
-      });
-      console.log();
-    } catch (e) {
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('Requires @ruvector/ruvllm: npm install @ruvector/ruvllm'));
+      if (typeof ruvllm.listModels === 'function') {
+        const models = ruvllm.listModels();
+        models.forEach(m => console.log(`  ${chalk.green(m.name || m)} ${chalk.dim(m.description || '')}`));
       } else {
-        console.error(chalk.red('Failed:'), e.message);
+        console.log(chalk.dim('  Model listing requires @ruvector/ruvllm >=2.1.0'));
+        console.log(chalk.dim('  Available: MiniLM-L6 (default embedding model)'));
       }
-      process.exit(1);
-    }
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 llmCmd.command('benchmark')
   .description('Benchmark LLM inference performance')
-  .option('-n, --iterations <n>', 'Iterations', '100')
-  .option('-m, --model <model>', 'Model name', 'default')
-  .action(async (opts) => {
-    const spinner = ora('Running LLM benchmark...');
-    spinner.start();
-    try {
-      const ruvllm = require('@ruvector/ruvllm');
-      const embed = ruvllm.embed || (ruvllm.default && ruvllm.default.embed);
-      if (!embed) throw new Error('ruvllm.embed not found');
-      const n = parseInt(opts.iterations);
+  .option('-n, --iterations <n>', 'Number of iterations', '100')
+  .action((opts) => {
+    const ruvllm = requireRuvllm();
+    const n = parseInt(opts.iterations);
+    const text = 'The quick brown fox jumps over the lazy dog';
+    const times = [];
+    for (let i = 0; i < n; i++) {
       const start = performance.now();
-      for (let i = 0; i < n; i++) await embed(`benchmark text ${i}`, { model: opts.model });
-      const elapsed = performance.now() - start;
-      spinner.stop();
-      console.log(chalk.bold.cyan('\nLLM Benchmark Results'));
-      console.log(chalk.dim('-'.repeat(40)));
-      console.log(`  Iterations: ${n}`);
-      console.log(`  Total: ${(elapsed / 1000).toFixed(2)}s`);
-      console.log(`  Avg: ${(elapsed / n).toFixed(2)}ms/embed`);
-      console.log(`  Throughput: ${(n / (elapsed / 1000)).toFixed(1)} embeds/s`);
-      console.log();
-    } catch (e) {
-      spinner.stop();
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('Requires @ruvector/ruvllm'));
-      } else {
-        console.error(chalk.red('Benchmark failed:'), e.message);
-      }
-      process.exit(1);
-    }
+      ruvllm.embed ? ruvllm.embed(text) : ruvllm.generateEmbedding(text);
+      times.push(performance.now() - start);
+    }
+    times.sort((a, b) => a - b);
+    console.log(chalk.bold.cyan('\nLLM Benchmark\n'));
+    console.log(`  ${chalk.bold('Iterations:')} ${n}`);
+    console.log(`  ${chalk.bold('P50:')} ${times[Math.floor(n * 0.5)].toFixed(2)}ms`);
+    console.log(`  ${chalk.bold('P95:')} ${times[Math.floor(n * 0.95)].toFixed(2)}ms`);
+    console.log(`  ${chalk.bold('P99:')} ${times[Math.floor(n * 0.99)].toFixed(2)}ms`);
+    console.log(`  ${chalk.bold('Mean:')} ${(times.reduce((a, b) => a + b, 0) / n).toFixed(2)}ms`);
+    console.log();
+  });
+
+llmCmd.command('info')
+  .description('Show RuvLLM module information')
+  .action(() => {
+    const ruvllm = requireRuvllm();
+    console.log(chalk.bold.cyan('\nRuvLLM Info\n'));
+    console.log(`  ${chalk.bold('Version:')} ${typeof ruvllm.version === 'function' ? ruvllm.version() : ruvllm.version || 'unknown'}`);
+    console.log(`  ${chalk.bold('SIMD:')} ${ruvllm.simdEnabled ? 'enabled' : 'not detected'}`);
+    console.log();
   });
 
 // ============================================================================
-// SONA Commands — Self-Optimizing Neural Architecture
+// SONA Commands — Self-Optimizing Neural Architecture (lazy-loaded)
 // ============================================================================
 
-const sonaCmd = program.command('sona').description('SONA self-optimizing neural architecture');
+const sonaCmd = program.command('sona').description('SONA adaptive learning — status, patterns, train, export');
+
+function loadSona() {
+  try { return require('@ruvector/sona'); } catch {
+    console.error(chalk.red('SONA commands require @ruvector/sona'));
+    console.error(chalk.yellow('  npm install @ruvector/sona'));
+    process.exit(1);
+  }
+}
 
 sonaCmd.command('status')
-  .description('Show SONA engine status')
-  .option('--json', 'JSON output')
-  .action(async (opts) => {
+  .description('Show SONA learning engine status')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const sona = loadSona();
     try {
-      const sona = require('@ruvector/sona');
-      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
-      const status = engine.status ? await engine.status() : { state: 'loaded' };
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(status, null, 2));
-      } else {
-        console.log(chalk.bold.cyan('\nSONA Engine Status'));
-        console.log(chalk.dim('-'.repeat(40)));
-        Object.entries(status).forEach(([k, v]) => {
-          console.log(`  ${chalk.bold(k)}: ${v}`);
-        });
-        console.log();
-      }
-    } catch (e) {
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('Requires @ruvector/sona: npm install @ruvector/sona'));
-      } else {
-        console.error(chalk.red('Failed:'), e.message);
-      }
-      process.exit(1);
-    }
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : new sona.SonaCoordinator();
+      const status = engine.getStatus ? engine.getStatus() : { ready: true };
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(status, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nSONA Status\n'));
+      Object.entries(status).forEach(([k, v]) => console.log(`  ${chalk.bold(k + ':')} ${v}`));
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
-sonaCmd.command('patterns')
-  .description('List learned SONA patterns')
-  .option('-l, --limit <n>', 'Max results', '20')
-  .option('--json', 'JSON output')
-  .action(async (opts) => {
+sonaCmd.command('patterns <query>')
+  .description('Search learned patterns')
+  .option('-t, --threshold <n>', 'Similarity threshold', '0.5')
+  .option('--json', 'Output as JSON')
+  .action((query, opts) => {
+    const sona = loadSona();
     try {
-      const sona = require('@ruvector/sona');
-      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
-      const patterns = engine.findPatterns ? await engine.findPatterns({ limit: parseInt(opts.limit) }) : [];
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(patterns, null, 2));
-      } else {
-        if (patterns.length === 0) { console.log(chalk.yellow('No patterns found.')); return; }
-        console.log(chalk.bold.cyan(`\n${patterns.length} SONA Patterns\n`));
-        patterns.forEach((p, i) => {
-          console.log(`  ${chalk.bold(i + 1 + '.')} ${p.name || p.type || p.id} ${chalk.dim(p.confidence ? `(${(p.confidence * 100).toFixed(0)}%)` : '')}`);
-        });
-        console.log();
-      }
-    } catch (e) {
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('Requires @ruvector/sona'));
-      } else {
-        console.error(chalk.red('Failed:'), e.message);
-      }
-      process.exit(1);
-    }
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : new sona.SonaCoordinator();
+      const patterns = engine.findPatterns ? engine.findPatterns(query, { threshold: parseFloat(opts.threshold) }) : [];
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(patterns, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nLearned Patterns\n'));
+      if (!patterns.length) { console.log(chalk.dim('  No patterns found.\n')); return; }
+      patterns.forEach((p, i) => console.log(`  ${chalk.yellow(i + 1 + '.')} ${p.name || p.pattern || JSON.stringify(p).slice(0, 80)}`));
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
-sonaCmd.command('train')
-  .description('Start SONA training trajectory')
-  .option('-d, --data <path>', 'Training data path')
-  .option('--epochs <n>', 'Epochs', '10')
-  .action(async (opts) => {
-    const spinner = ora('Training SONA...');
-    spinner.start();
+sonaCmd.command('train <data>')
+  .description('Record a training trajectory')
+  .option('--outcome <outcome>', 'Outcome (success/failure)', 'success')
+  .action((data, opts) => {
+    const sona = loadSona();
     try {
-      const sona = require('@ruvector/sona');
-      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
-      if (!engine.beginTrajectory) throw new Error('SONA engine does not support training');
-      const result = await engine.beginTrajectory({ data: opts.data, epochs: parseInt(opts.epochs) });
-      spinner.succeed(chalk.green('Training complete'));
-      if (result) console.log(chalk.dim(JSON.stringify(result, null, 2)));
-    } catch (e) {
-      spinner.fail(chalk.red('Training failed: ' + e.message));
-      process.exit(1);
-    }
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : new sona.SonaCoordinator();
+      if (engine.recordTrajectory) { engine.recordTrajectory(data, opts.outcome); }
+      else if (engine.train) { engine.train(data); }
+      console.log(chalk.green('Training trajectory recorded.'));
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 sonaCmd.command('export')
-  .description('Export SONA model weights')
-  .option('-o, --output <path>', 'Output path', 'sona-weights.json')
-  .action(async (opts) => {
+  .description('Export SONA learned weights to JSON')
+  .option('-o, --output <file>', 'Output file', 'sona-weights.json')
+  .action((opts) => {
+    const sona = loadSona();
     try {
-      const sona = require('@ruvector/sona');
-      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
-      const weights = engine.exportWeights ? await engine.exportWeights() : {};
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : new sona.SonaCoordinator();
+      const weights = engine.exportWeights ? engine.exportWeights() : engine.export ? engine.export() : {};
       fs.writeFileSync(opts.output, JSON.stringify(weights, null, 2));
       console.log(chalk.green(`Exported to ${opts.output}`));
-    } catch (e) {
-      console.error(chalk.red('Export failed:'), e.message);
-      process.exit(1);
-    }
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
   });
 
 sonaCmd.command('stats')
-  .description('Show SONA learning statistics')
-  .option('--json', 'JSON output')
-  .action(async (opts) => {
+  .description('Show detailed SONA learning statistics')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const sona = loadSona();
     try {
-      const sona = require('@ruvector/sona');
-      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
-      const stats = engine.stats ? await engine.stats() : { trajectories: 0, patterns: 0 };
-      if (opts.json || !process.stdout.isTTY) {
-        console.log(JSON.stringify(stats, null, 2));
-      } else {
-        console.log(chalk.bold.cyan('\nSONA Statistics'));
-        console.log(chalk.dim('-'.repeat(40)));
-        Object.entries(stats).forEach(([k, v]) => {
-          console.log(`  ${chalk.bold(k)}: ${v}`);
-        });
-        console.log();
-      }
-    } catch (e) {
-      if (e.code === 'MODULE_NOT_FOUND') {
-        console.error(chalk.red('Requires @ruvector/sona'));
-      } else {
-        console.error(chalk.red('Failed:'), e.message);
-      }
-      process.exit(1);
-    }
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : new sona.SonaCoordinator();
+      const stats = engine.getStats ? engine.getStats() : engine.stats ? engine.stats() : {};
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(stats, null, 2)); return; }
+      console.log(chalk.bold.cyan('\nSONA Statistics\n'));
+      Object.entries(stats).forEach(([k, v]) => console.log(`  ${chalk.bold(k + ':')} ${v}`));
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
+  });
+
+sonaCmd.command('info')
+  .description('Show SONA module availability')
+  .action(() => {
+    const sona = loadSona();
+    console.log(chalk.bold.cyan('\nSONA Info\n'));
+    console.log(`  ${chalk.bold('Version:')} ${typeof sona.version === 'function' ? sona.version() : sona.version || 'unknown'}`);
+    console.log(`  ${chalk.bold('Engine:')} ${sona.SonaEngine ? 'Native' : 'JS Fallback'}`);
+    console.log();
+  });
+
+// ============================================================================
+// Route Commands — Semantic routing via @ruvector/router (lazy-loaded)
+// ============================================================================
+
+const routeCmd = program.command('route').description('Semantic routing — classify inputs to routes via HNSW + SIMD');
+
+function requireRouter() {
+  try { return require('@ruvector/router'); } catch {
+    console.error(chalk.red('Route commands require @ruvector/router'));
+    console.error(chalk.yellow('  npm install @ruvector/router'));
+    process.exit(1);
+  }
+}
+
+routeCmd.command('classify <input>')
+  .description('Classify input to a semantic route')
+  .option('--json', 'Output as JSON')
+  .action((input, opts) => {
+    const router = requireRouter();
+    try {
+      const result = router.classify ? router.classify(input) : { route: 'default', confidence: 1.0 };
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result)); return; }
+      console.log(chalk.bold.cyan('\nRoute Classification\n'));
+      console.log(`  ${chalk.bold('Input:')} ${input}`);
+      console.log(`  ${chalk.bold('Route:')} ${chalk.green(result.route)}`);
+      console.log(`  ${chalk.bold('Confidence:')} ${result.confidence}`);
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); }
+  });
+
+routeCmd.command('benchmark')
+  .description('Benchmark routing throughput')
+  .option('-n, --iterations <n>', 'Number of iterations', '1000')
+  .action((opts) => {
+    const router = requireRouter();
+    const n = parseInt(opts.iterations);
+    const input = 'test input for routing benchmark';
+    const start = performance.now();
+    for (let i = 0; i < n; i++) {
+      router.classify ? router.classify(input) : null;
+    }
+    const elapsed = performance.now() - start;
+    console.log(chalk.bold.cyan('\nRoute Benchmark\n'));
+    console.log(`  ${chalk.bold('Iterations:')} ${n}`);
+    console.log(`  ${chalk.bold('Total:')} ${elapsed.toFixed(2)}ms`);
+    console.log(`  ${chalk.bold('Per-route:')} ${(elapsed / n).toFixed(3)}ms`);
+    console.log(`  ${chalk.bold('Throughput:')} ${Math.floor(n / (elapsed / 1000))}/sec`);
+    console.log();
+  });
+
+routeCmd.command('info')
+  .description('Show router module information')
+  .action(() => {
+    const router = requireRouter();
+    console.log(chalk.bold.cyan('\nRouter Info\n'));
+    console.log(`  ${chalk.bold('Version:')} ${typeof router.version === 'function' ? router.version() : router.version || 'unknown'}`);
+    console.log();
   });
 
 program.parse();