ruvector 0.1.99 → 0.2.0

package/bin/cli.js

@@ -4,11 +4,21 @@
 process.env.RUVECTOR_CLI = '1';
 
 const { Command } = require('commander');
-const chalk = require('chalk');
-const ora = require('ora');
+const _chalk = require('chalk');
+const chalk = _chalk.default || _chalk;
 const fs = require('fs');
 const path = require('path');
 
+// Lazy load ora (spinner) - only needed for commands with progress indicators
+let _oraModule = null;
+function ora(text) {
+  if (_oraModule === null) {
+    const _ora = require('ora');
+    _oraModule = _ora.default || _ora;
+  }
+  return _oraModule(text);
+}
+
 // Lazy load ruvector (only when needed, not for install/help commands)
 let VectorDB, getVersion, getImplementationType;
 let ruvectorLoaded = false;
@@ -35,59 +45,79 @@ function requireRuvector() {
   }
 }
 
-// Import GNN (optional - graceful fallback if not available)
+// 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
 let RuvectorLayer, TensorCompress, differentiableSearch, getCompressionLevel, hierarchicalForward;
 let gnnAvailable = false;
-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
+
+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;
+  }
 }
 
-// Import Attention (optional - graceful fallback if not available)
+// 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
 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;
-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
+
+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;
+  }
 }
 
 const program = new Command();
@@ -354,6 +384,10 @@ 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)}`));
 
@@ -390,6 +424,9 @@ 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
@@ -677,8 +714,9 @@ program
 // GNN Commands
 // =============================================================================
 
-// Helper to check GNN availability
+// Helper to check GNN availability (triggers lazy load)
 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'));
@@ -874,6 +912,7 @@ 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'));
@@ -903,8 +942,9 @@ gnnCmd
 // Attention Commands
 // =============================================================================
 
-// Helper to require attention module
+// Helper to require attention module (triggers lazy load)
 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'));
@@ -1232,6 +1272,7 @@ 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'));
@@ -1277,6 +1318,7 @@ 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'));
@@ -1333,6 +1375,10 @@ 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'));
@@ -2521,6 +2567,7 @@ 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'));
@@ -7353,4 +7400,730 @@ mcpCmd.command('info')
     console.log();
   });
 
+// ============================================================================
+// Brain Commands — Shared intelligence via @ruvector/pi-brain (lazy-loaded)
+// ============================================================================
+
+let _piBrainClient = null;
+async function getPiBrainClient(opts = {}) {
+  if (_piBrainClient) return _piBrainClient;
+  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;
+  } catch {
+    console.error(chalk.red('Brain commands require @ruvector/pi-brain'));
+    console.error(chalk.yellow('  npm install @ruvector/pi-brain'));
+    process.exit(1);
+  }
+}
+
+const brainCmd = program.command('brain').description('Shared intelligence — search, share, vote on collective knowledge');
+
+brainCmd.command('search <query>')
+  .description('Semantic search across shared knowledge')
+  .option('-l, --limit <n>', 'Max results', '10')
+  .option('-c, --category <cat>', 'Filter by category')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (query, opts) => {
+    const spinner = ora(`Searching brain for "${query}"...`);
+    spinner.start();
+    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);
+    }
+  });
+
+brainCmd.command('share <title>')
+  .description('Share knowledge with the collective brain')
+  .option('-c, --category <cat>', 'Category (pattern, solution, architecture, convention, security, performance, tooling)', 'pattern')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('--content <text>', 'Content body (or pipe via stdin)')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .action(async (title, opts) => {
+    const spinner = ora('Sharing with brain...');
+    spinner.start();
+    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);
+    }
+  });
+
+brainCmd.command('get <id>')
+  .description('Retrieve a specific memory with provenance')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (id, opts) => {
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('vote <id> <direction>')
+  .description('Vote on knowledge quality (up or down)')
+  .option('--url <url>', 'Brain server URL')
+  .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);
+    }
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('list')
+  .description('List recent shared memories')
+  .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')
+  .action(async (opts) => {
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('delete <id>')
+  .description('Delete your own contribution')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .action(async (id, opts) => {
+    try {
+      const client = await getPiBrainClient(opts);
+      await client.delete(id);
+      console.log(chalk.green(`Deleted ${id}`));
+    } catch (e) {
+      console.error(chalk.red('Delete failed:'), e.message);
+      process.exit(1);
+    }
+  });
+
+brainCmd.command('status')
+  .description('Show brain system health and statistics')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('drift')
+  .description('Check knowledge drift between local and shared')
+  .option('-d, --domain <domain>', 'Domain to check')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('partition')
+  .description('Get knowledge topology via mincut partitioning')
+  .option('-d, --domain <domain>', 'Domain to partition')
+  .option('--min-cluster <n>', 'Minimum cluster size', '3')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (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)}`));
+        });
+        console.log();
+      }
+    } catch (e) {
+      console.error(chalk.red('Partition failed:'), e.message);
+      process.exit(1);
+    }
+  });
+
+brainCmd.command('transfer <source> <target>')
+  .description('Transfer learned priors between domains')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (source, target, opts) => {
+    const spinner = ora(`Transferring ${source} -> ${target}...`);
+    spinner.start();
+    try {
+      const client = await getPiBrainClient(opts);
+      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);
+    }
+  });
+
+brainCmd.command('sync [direction]')
+  .description('Sync LoRA weights (pull, push, or both)')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'PI key')
+  .action(async (direction, opts) => {
+    const dir = direction || 'both';
+    const spinner = ora(`LoRA sync (${dir})...`);
+    spinner.start();
+    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);
+    }
+  });
+
+// ============================================================================
+// Edge Commands — Distributed compute via edge-net (native fetch)
+// ============================================================================
+
+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('Edge-net distributed compute network');
+
+edgeCmd.command('status')
+  .description('Query network status (genesis, relay, nodes)')
+  .option('--json', 'JSON output')
+  .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));
+    }
+  });
+
+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')
+  .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'));
+    try {
+      const res = await fetch(`${EDGE_RELAY}/api/join`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${key}` },
+        body: JSON.stringify({ contribution: parseFloat(opts.contribution) })
+      });
+      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);
+    }
+  });
+
+edgeCmd.command('balance')
+  .description('Check rUv balance for current identity')
+  .option('--key <key>', 'PI key')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    const key = opts.key || process.env.PI || '';
+    if (!key) { console.error(chalk.red('PI key required')); 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);
+    }
+  });
+
+edgeCmd.command('tasks')
+  .description('List available distributed compute tasks')
+  .option('--json', 'JSON output')
+  .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);
+    }
+  });
+
+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}`, () => {});
+  });
+
+// ============================================================================
+// Identity Commands — pi key management (Node.js crypto)
+// ============================================================================
+
+const identityCmd = program.command('identity').description('Pi key management for brain, edge, and MCP identity');
+
+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'));
+    console.log();
+  });
+
+identityCmd.command('show')
+  .description('Display current identity derived from PI key')
+  .option('--key <key>', 'PI key (default: PI env var)')
+  .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'));
+      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);
+    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();
+  });
+
+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); }
+    const crypto = require('crypto');
+    const password = crypto.randomBytes(16).toString('hex');
+    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');
+    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.'));
+  });
+
+identityCmd.command('import <file>')
+  .description('Import key from encrypted backup')
+  .option('-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'));
+      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');
+      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);
+    }
+  });
+
+// ============================================================================
+// LLM Commands — LLM orchestration via @ruvector/ruvllm (lazy-loaded)
+// ============================================================================
+
+const llmCmd = program.command('llm').description('LLM orchestration — embeddings, models, benchmarks');
+
+llmCmd.command('embed <text>')
+  .description('Generate embeddings via ruvllm')
+  .option('-m, --model <model>', 'Model name', 'default')
+  .option('--json', 'JSON output')
+  .action(async (text, opts) => {
+    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);
+    }
+  });
+
+llmCmd.command('models')
+  .description('List available LLM models')
+  .action(async () => {
+    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'));
+      } else {
+        console.error(chalk.red('Failed:'), e.message);
+      }
+      process.exit(1);
+    }
+  });
+
+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);
+      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);
+    }
+  });
+
+// ============================================================================
+// SONA Commands — Self-Optimizing Neural Architecture
+// ============================================================================
+
+const sonaCmd = program.command('sona').description('SONA self-optimizing neural architecture');
+
+sonaCmd.command('status')
+  .description('Show SONA engine status')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    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);
+    }
+  });
+
+sonaCmd.command('patterns')
+  .description('List learned SONA patterns')
+  .option('-l, --limit <n>', 'Max results', '20')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    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);
+    }
+  });
+
+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();
+    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);
+    }
+  });
+
+sonaCmd.command('export')
+  .description('Export SONA model weights')
+  .option('-o, --output <path>', 'Output path', 'sona-weights.json')
+  .action(async (opts) => {
+    try {
+      const sona = require('@ruvector/sona');
+      const engine = sona.SonaEngine ? new sona.SonaEngine() : sona;
+      const weights = engine.exportWeights ? await engine.exportWeights() : {};
+      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);
+    }
+  });
+
+sonaCmd.command('stats')
+  .description('Show SONA learning statistics')
+  .option('--json', 'JSON output')
+  .action(async (opts) => {
+    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);
+    }
+  });
+
 program.parse();