rampup 0.1.0

package/index.js

@@ -0,0 +1,2353 @@
+#!/usr/bin/env node
+
+/**
+ * Ramp CLI - Understand any codebase in hours
+ * AI-powered developer onboarding
+ *
+ * Combines:
+ * - AI-guided codebase learning
+ * - Voice mode for hands-free exploration
+ * - Auto-generated onboarding docs
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import path from 'path';
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import omniConfig from './omni/config.js';
+import { checkAndBurnTokens, getTokenBalance } from './entitlements.js';
+import { loginWithBrowser, clearCredentials, getUserInfo, getIdToken } from './auth.js';
+import { saveKnowledge, searchKnowledge, getMyOrg, formatKnowledgeEntry } from './knowledge.js';
+
+const execAsync = promisify(exec);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const VERSION = '0.1.0';
+
+// ASCII art banner
+const banner = `
+ ${chalk.white('         :::-        ')}
+ ${chalk.white('    :::::--------   ')}
+ ${chalk.white('=-:::::::--------:-+')}   ${chalk.bold.white('██████╗  █████╗ ███╗   ███╗██████╗')}
+ ${chalk.white('++++=-:::::-:....*##')}   ${chalk.bold.white('██╔══██╗██╔══██╗████╗ ████║██╔══██╗')}
+ ${chalk.white('++++++++=:....:*####')}   ${chalk.bold.white('██████╔╝███████║██╔████╔██║██████╔╝')}
+ ${chalk.white('*+++++=:....:*######')}   ${chalk.bold.white('██╔══██╗██╔══██║██║╚██╔╝██║██╔═══╝')}
+ ${chalk.white('**++=:::..:*########')}   ${chalk.bold.white('██║  ██║██║  ██║██║ ╚═╝ ██║██║')}
+ ${chalk.white('*+=-::::-*##########')}   ${chalk.bold.white('╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝')}
+ ${chalk.white('+------*############')}
+ ${chalk.white('   --*##########    ')}   ${chalk.gray('Onboard to any codebase in hours')}
+ ${chalk.white('        ####        ')}   ${chalk.cyan('https://rampup.dev')}
+`;
+
+const program = new Command();
+
+program
+  .name('ramp')
+  .description('AI-powered developer onboarding - Understand any codebase in hours, not weeks')
+  .version(VERSION);
+
+// ============================================
+// EXPLORE & LEARN COMMANDS (Onboarding)
+// ============================================
+
+// Explore a codebase
+program
+  .command('explore [path]')
+  .description('Explore and map a codebase structure')
+  .option('-d, --depth <number>', 'Max directory depth', '3')
+  .option('--no-git', 'Skip git analysis')
+  .action(async (targetPath, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🔍 Exploring Codebase\n'));
+
+    const projectPath = path.resolve(targetPath || '.');
+    const spinner = ora('Scanning project structure...').start();
+
+    try {
+      // Check if directory exists
+      await fs.access(projectPath);
+
+      // Gather project info
+      const stats = {
+        name: path.basename(projectPath),
+        path: projectPath,
+        files: { total: 0, byType: {} },
+        directories: 0,
+        hasPackageJson: false,
+        hasGit: false,
+        languages: [],
+        keyFiles: []
+      };
+
+      // Check for key files
+      const keyFileChecks = [
+        'package.json', 'tsconfig.json', 'vite.config.js', 'webpack.config.js',
+        'README.md', '.gitignore', 'Cargo.toml', 'go.mod', 'requirements.txt',
+        'Dockerfile', 'docker-compose.yml', '.env.example'
+      ];
+
+      for (const file of keyFileChecks) {
+        try {
+          await fs.access(path.join(projectPath, file));
+          stats.keyFiles.push(file);
+          if (file === 'package.json') stats.hasPackageJson = true;
+        } catch {}
+      }
+
+      // Check for git
+      try {
+        await fs.access(path.join(projectPath, '.git'));
+        stats.hasGit = true;
+      } catch {}
+
+      // Scan directory structure
+      async function scanDir(dir, depth = 0) {
+        if (depth > parseInt(options.depth)) return;
+
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            stats.directories++;
+            await scanDir(fullPath, depth + 1);
+          } else {
+            stats.files.total++;
+            const ext = path.extname(entry.name).slice(1) || 'other';
+            stats.files.byType[ext] = (stats.files.byType[ext] || 0) + 1;
+          }
+        }
+      }
+
+      await scanDir(projectPath);
+
+      // Detect languages
+      const langMap = {
+        js: 'JavaScript', ts: 'TypeScript', tsx: 'TypeScript/React',
+        jsx: 'JavaScript/React', py: 'Python', rb: 'Ruby', go: 'Go',
+        rs: 'Rust', java: 'Java', cpp: 'C++', c: 'C', swift: 'Swift'
+      };
+
+      for (const [ext, count] of Object.entries(stats.files.byType)) {
+        if (langMap[ext] && count > 0) {
+          stats.languages.push({ lang: langMap[ext], count });
+        }
+      }
+      stats.languages.sort((a, b) => b.count - a.count);
+
+      // Read package.json if exists
+      let packageInfo = null;
+      if (stats.hasPackageJson) {
+        try {
+          const pkg = JSON.parse(await fs.readFile(path.join(projectPath, 'package.json'), 'utf8'));
+          packageInfo = {
+            name: pkg.name,
+            version: pkg.version,
+            description: pkg.description,
+            dependencies: Object.keys(pkg.dependencies || {}).length,
+            devDependencies: Object.keys(pkg.devDependencies || {}).length,
+            scripts: Object.keys(pkg.scripts || {})
+          };
+        } catch {}
+      }
+
+      spinner.succeed('Scan complete!\n');
+
+      // Display results
+      console.log(chalk.cyan('─── Project Overview ───\n'));
+      console.log(chalk.bold(`📁 ${stats.name}`));
+      console.log(chalk.dim(`   ${stats.path}\n`));
+
+      console.log(chalk.bold('Stats:'));
+      console.log(chalk.dim(`   Files: ${stats.files.total}`));
+      console.log(chalk.dim(`   Directories: ${stats.directories}`));
+      console.log(chalk.dim(`   Git: ${stats.hasGit ? '✓' : '✗'}\n`));
+
+      if (stats.languages.length > 0) {
+        console.log(chalk.bold('Languages:'));
+        stats.languages.slice(0, 5).forEach(({ lang, count }) => {
+          console.log(chalk.dim(`   ${lang}: ${count} files`));
+        });
+        console.log('');
+      }
+
+      if (stats.keyFiles.length > 0) {
+        console.log(chalk.bold('Key Files:'));
+        stats.keyFiles.forEach(f => console.log(chalk.dim(`   ${f}`)));
+        console.log('');
+      }
+
+      if (packageInfo) {
+        console.log(chalk.bold('Package:'));
+        console.log(chalk.dim(`   ${packageInfo.name}@${packageInfo.version}`));
+        if (packageInfo.description) console.log(chalk.dim(`   ${packageInfo.description}`));
+        console.log(chalk.dim(`   ${packageInfo.dependencies} deps, ${packageInfo.devDependencies} devDeps`));
+        if (packageInfo.scripts.length > 0) {
+          console.log(chalk.dim(`   Scripts: ${packageInfo.scripts.slice(0, 5).join(', ')}${packageInfo.scripts.length > 5 ? '...' : ''}`));
+        }
+        console.log('');
+      }
+
+      console.log(chalk.cyan('────────────────────────\n'));
+
+      // Offer next steps
+      const { nextAction } = await inquirer.prompt([{
+        type: 'list',
+        name: 'nextAction',
+        message: 'What would you like to do?',
+        choices: [
+          { name: '📚 Learn this codebase (AI-guided tour)', value: 'learn' },
+          { name: '🏗️  Get architecture overview', value: 'architect' },
+          { name: '🚀 Run a goal on this project', value: 'run' },
+          { name: '✅ Done', value: 'done' }
+        ]
+      }]);
+
+      if (nextAction === 'learn') {
+        await program.parseAsync(['node', 'ramp', 'learn', projectPath]);
+      } else if (nextAction === 'architect') {
+        const desc = packageInfo?.description || `A ${stats.languages[0]?.lang || 'software'} project`;
+        await program.parseAsync(['node', 'ramp', 'design', desc]);
+      } else if (nextAction === 'run') {
+        console.log(chalk.dim(`\nRun: ramprun "<your goal>" -p ${projectPath}\n`));
+      }
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Learn a codebase
+program
+  .command('learn [path]')
+  .description('AI-guided codebase learning and onboarding')
+  .action(async (targetPath) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📚 Learn Codebase\n'));
+
+    const projectPath = path.resolve(targetPath || '.');
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+
+    if (!apiKey) {
+      console.error(chalk.red('Error: ANTHROPIC_API_KEY required for AI-guided learning.\n'));
+      console.log('Set it with:');
+      console.log(chalk.cyan('  export ANTHROPIC_API_KEY=your-api-key\n'));
+      process.exit(1);
+    }
+
+    const spinner = ora('Analyzing codebase...').start();
+
+    try {
+      // Gather context
+      let context = `Project: ${path.basename(projectPath)}\n`;
+
+      // Read README if exists
+      try {
+        const readme = await fs.readFile(path.join(projectPath, 'README.md'), 'utf8');
+        context += `\nREADME:\n${readme.slice(0, 2000)}\n`;
+      } catch {}
+
+      // Read package.json if exists
+      try {
+        const pkg = await fs.readFile(path.join(projectPath, 'package.json'), 'utf8');
+        context += `\npackage.json:\n${pkg}\n`;
+      } catch {}
+
+      // Get directory structure
+      let structure = '';
+      async function getStructure(dir, prefix = '', depth = 0) {
+        if (depth > 2) return;
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+          structure += `${prefix}${entry.isDirectory() ? '📁' : '📄'} ${entry.name}\n`;
+          if (entry.isDirectory()) {
+            await getStructure(path.join(dir, entry.name), prefix + '  ', depth + 1);
+          }
+        }
+      }
+      await getStructure(projectPath);
+      context += `\nStructure:\n${structure.slice(0, 3000)}\n`;
+
+      spinner.succeed('Codebase analyzed!\n');
+
+      // Check entitlements before starting
+      const idempotencyKey = `learn-${Date.now()}`;
+      const entitlementCheck = await checkAndBurnTokens('learn', idempotencyKey);
+      if (!entitlementCheck.allowed) {
+        console.log(chalk.red(`\n❌ ${entitlementCheck.reason}\n`));
+        process.exit(1);
+      }
+
+      // Start interactive learning session
+      const Anthropic = (await import('@anthropic-ai/sdk')).default;
+      const client = new Anthropic({ apiKey });
+
+      const history = [];
+      const systemPrompt = `You are Ramp, an AI coding mentor helping a developer learn a new codebase.
+
+Based on this project context:
+${context}
+
+Help the developer understand:
+1. What this project does
+2. How it's structured
+3. Key files and their purposes
+4. How to get started contributing
+
+Be concise, friendly, and practical. Use the project's actual files and structure in your explanations.
+Start by giving a brief overview of the project.`;
+
+      // Initial overview
+      const overviewSpinner = ora('Generating overview...').start();
+      const overview = await client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1500,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: 'Give me a quick overview of this project.' }]
+      });
+
+      overviewSpinner.stop();
+      const overviewText = overview.content[0].type === 'text' ? overview.content[0].text : '';
+      history.push({ role: 'user', content: 'Give me a quick overview of this project.' });
+      history.push({ role: 'assistant', content: overviewText });
+
+      console.log(chalk.cyan('─── Project Overview ───\n'));
+      console.log(overviewText);
+      console.log(chalk.cyan('\n────────────────────────\n'));
+
+      console.log(chalk.gray('Ask questions about the codebase. Type /exit to quit.\n'));
+
+      // Interactive Q&A
+      while (true) {
+        const { question } = await inquirer.prompt([{
+          type: 'input',
+          name: 'question',
+          message: chalk.green('You:'),
+          prefix: ''
+        }]);
+
+        if (!question.trim()) continue;
+        if (question.toLowerCase() === '/exit' || question.toLowerCase() === '/quit') {
+          console.log(chalk.cyan('\nHappy coding! 🚀\n'));
+          break;
+        }
+
+        history.push({ role: 'user', content: question });
+
+        const thinkingSpinner = ora('Thinking...').start();
+        const response = await client.messages.create({
+          model: 'claude-sonnet-4-20250514',
+          max_tokens: 1500,
+          system: systemPrompt,
+          messages: history
+        });
+        thinkingSpinner.stop();
+
+        const answer = response.content[0].type === 'text' ? response.content[0].text : '';
+        history.push({ role: 'assistant', content: answer });
+
+        console.log(chalk.cyan('\n─── Ramp ───\n'));
+        console.log(answer);
+        console.log(chalk.cyan('\n─────────────\n'));
+      }
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Start - First time onboarding
+program
+  .command('start')
+  .alias('init')
+  .description('Start onboarding to a new codebase')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🚀 Welcome to Ramp!\n'));
+    console.log(chalk.gray('Let\'s get you up to speed on this codebase.\n'));
+
+    const projectPath = process.cwd();
+
+    // Check if we're in a code project
+    let hasCode = false;
+    const codeIndicators = ['package.json', 'Cargo.toml', 'go.mod', 'requirements.txt', 'pom.xml', '.git'];
+    for (const file of codeIndicators) {
+      try {
+        await fs.access(path.join(projectPath, file));
+        hasCode = true;
+        break;
+      } catch {}
+    }
+
+    if (!hasCode) {
+      console.log(chalk.yellow('No codebase detected in current directory.\n'));
+      const { navTo } = await inquirer.prompt([{
+        type: 'input',
+        name: 'navTo',
+        message: 'Enter path to codebase (or press enter to continue here):',
+        default: '.'
+      }]);
+      if (navTo !== '.') {
+        console.log(chalk.dim(`\nRun: cd ${navTo} && rampstart\n`));
+        return;
+      }
+    }
+
+    console.log(chalk.cyan('─────────────────────────────────────────\n'));
+
+    // Step 1: Quick scan
+    console.log(chalk.bold('Step 1: Quick Scan\n'));
+    await program.parseAsync(['node', 'ramp', 'explore', projectPath, '-d', '2']);
+
+    // Step 2: Offer learning
+    console.log(chalk.bold('\nStep 2: Guided Tour\n'));
+    const { wantTour } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'wantTour',
+      message: 'Want an AI-guided tour of this codebase?',
+      default: true
+    }]);
+
+    if (wantTour) {
+      await program.parseAsync(['node', 'ramp', 'learn', projectPath]);
+    } else {
+      console.log(chalk.dim('\nYou can start a tour anytime with: ramplearn\n'));
+      console.log(chalk.bold('Quick commands:'));
+      console.log(chalk.dim('  rampask "how does auth work?"  - Ask about the code'));
+      console.log(chalk.dim('  rampexplore                    - See project structure'));
+      console.log(chalk.dim('  rampguide                      - Generate onboarding doc\n'));
+    }
+  });
+
+// Ask - Quick questions about the codebase
+program
+  .command('ask <question>')
+  .description('Ask a question about the codebase')
+  .option('-p, --path <path>', 'Project path', '.')
+  .action(async (question, options) => {
+    const projectPath = path.resolve(options.path);
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+
+    if (!apiKey) {
+      console.error(chalk.red('Error: ANTHROPIC_API_KEY required.\n'));
+      console.log(chalk.cyan('  export ANTHROPIC_API_KEY=your-api-key\n'));
+      process.exit(1);
+    }
+
+    const spinner = ora('Reading codebase...').start();
+
+    try {
+      // Gather context
+      let context = `Project: ${path.basename(projectPath)}\n`;
+
+      // Read key files
+      const keyFiles = ['README.md', 'package.json', 'tsconfig.json', 'Cargo.toml', 'go.mod'];
+      for (const file of keyFiles) {
+        try {
+          const content = await fs.readFile(path.join(projectPath, file), 'utf8');
+          context += `\n${file}:\n${content.slice(0, 1500)}\n`;
+        } catch {}
+      }
+
+      // Get structure
+      let structure = '';
+      async function getStructure(dir, prefix = '', depth = 0) {
+        if (depth > 2) return;
+        try {
+          const entries = await fs.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+            structure += `${prefix}${entry.name}${entry.isDirectory() ? '/' : ''}\n`;
+            if (entry.isDirectory() && depth < 2) {
+              await getStructure(path.join(dir, entry.name), prefix + '  ', depth + 1);
+            }
+          }
+        } catch {}
+      }
+      await getStructure(projectPath);
+      context += `\nStructure:\n${structure.slice(0, 2000)}\n`;
+
+      // Check entitlements
+      const idempotencyKey = `ask-${Date.now()}`;
+      const entitlementCheck = await checkAndBurnTokens('ask', idempotencyKey);
+      if (!entitlementCheck.allowed) {
+        spinner.fail(entitlementCheck.reason);
+        process.exit(1);
+      }
+
+      spinner.text = 'Thinking...';
+
+      const Anthropic = (await import('@anthropic-ai/sdk')).default;
+      const client = new Anthropic({ apiKey });
+
+      const response = await client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1500,
+        system: `You are Ramp, helping a developer understand a codebase.
+
+Project context:
+${context}
+
+Answer questions concisely and practically. Reference specific files when relevant.`,
+        messages: [{ role: 'user', content: question }]
+      });
+
+      spinner.stop();
+
+      const answer = response.content[0].type === 'text' ? response.content[0].text : '';
+      console.log(chalk.cyan('\n─── Answer ───\n'));
+      console.log(answer);
+      console.log(chalk.cyan('\n──────────────\n'));
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+    }
+  });
+
+// Progress - Track onboarding progress
+program
+  .command('progress')
+  .description('View your onboarding progress')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📊 Your Progress\n'));
+
+    const projectPath = process.cwd();
+    const projectName = path.basename(projectPath);
+    const progressFile = path.join(process.env.HOME, '.ramp', 'progress.json');
+
+    let progress = {};
+    try {
+      progress = JSON.parse(await fs.readFile(progressFile, 'utf8'));
+    } catch {}
+
+    const projectProgress = progress[projectPath] || {
+      started: null,
+      explored: false,
+      learned: false,
+      questionsAsked: 0,
+      filesExplored: [],
+      lastActive: null
+    };
+
+    if (!projectProgress.started) {
+      console.log(chalk.yellow(`You haven't started onboarding to ${projectName} yet.\n`));
+      console.log(chalk.dim('Run: rampstart\n'));
+      return;
+    }
+
+    console.log(chalk.bold(`Project: ${projectName}\n`));
+    console.log(chalk.dim(`Started: ${new Date(projectProgress.started).toLocaleDateString()}`));
+    console.log(chalk.dim(`Last active: ${projectProgress.lastActive ? new Date(projectProgress.lastActive).toLocaleDateString() : 'Never'}\n`));
+
+    console.log(chalk.bold('Milestones:'));
+    console.log(`  ${projectProgress.explored ? '✅' : '⬜'} Explored codebase structure`);
+    console.log(`  ${projectProgress.learned ? '✅' : '⬜'} Completed AI-guided tour`);
+    console.log(`  ${projectProgress.questionsAsked >= 5 ? '✅' : '⬜'} Asked 5+ questions (${projectProgress.questionsAsked}/5)`);
+    console.log(`  ${projectProgress.filesExplored.length >= 10 ? '✅' : '⬜'} Explored 10+ files (${projectProgress.filesExplored.length}/10)\n`);
+
+    const completed = [
+      projectProgress.explored,
+      projectProgress.learned,
+      projectProgress.questionsAsked >= 5,
+      projectProgress.filesExplored.length >= 10
+    ].filter(Boolean).length;
+
+    const percentage = Math.round((completed / 4) * 100);
+    const bar = '█'.repeat(Math.floor(percentage / 10)) + '░'.repeat(10 - Math.floor(percentage / 10));
+    console.log(chalk.bold(`Progress: [${bar}] ${percentage}%\n`));
+
+    if (percentage < 100) {
+      console.log(chalk.dim('Next steps:'));
+      if (!projectProgress.explored) console.log(chalk.dim('  → rampexplore'));
+      if (!projectProgress.learned) console.log(chalk.dim('  → ramplearn'));
+      if (projectProgress.questionsAsked < 5) console.log(chalk.dim('  → rampask "your question"'));
+      console.log('');
+    } else {
+      console.log(chalk.green('🎉 You\'re fully onboarded! Nice work.\n'));
+    }
+  });
+
+// Guide - Generate onboarding documentation
+program
+  .command('guide')
+  .description('Generate an onboarding guide for this codebase')
+  .option('-o, --output <file>', 'Output file', 'ONBOARDING.md')
+  .action(async (options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📖 Generating Onboarding Guide\n'));
+
+    const projectPath = process.cwd();
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+
+    if (!apiKey) {
+      console.error(chalk.red('Error: ANTHROPIC_API_KEY required.\n'));
+      process.exit(1);
+    }
+
+    const spinner = ora('Analyzing codebase...').start();
+
+    try {
+      // Gather comprehensive context
+      let context = `Project: ${path.basename(projectPath)}\n`;
+
+      // Read README
+      try {
+        const readme = await fs.readFile(path.join(projectPath, 'README.md'), 'utf8');
+        context += `\nExisting README:\n${readme.slice(0, 3000)}\n`;
+      } catch {}
+
+      // Read package.json or equivalent
+      try {
+        const pkg = await fs.readFile(path.join(projectPath, 'package.json'), 'utf8');
+        context += `\npackage.json:\n${pkg}\n`;
+      } catch {}
+
+      // Get full structure
+      let structure = '';
+      async function getStructure(dir, prefix = '', depth = 0) {
+        if (depth > 3) return;
+        try {
+          const entries = await fs.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') continue;
+            structure += `${prefix}${entry.name}${entry.isDirectory() ? '/' : ''}\n`;
+            if (entry.isDirectory()) {
+              await getStructure(path.join(dir, entry.name), prefix + '  ', depth + 1);
+            }
+          }
+        } catch {}
+      }
+      await getStructure(projectPath);
+      context += `\nFull structure:\n${structure.slice(0, 5000)}\n`;
+
+      // Sample some key files
+      const sampleFiles = ['src/index.ts', 'src/index.js', 'src/main.ts', 'src/App.tsx', 'src/app.py', 'main.go'];
+      for (const file of sampleFiles) {
+        try {
+          const content = await fs.readFile(path.join(projectPath, file), 'utf8');
+          context += `\n${file}:\n${content.slice(0, 1000)}\n`;
+        } catch {}
+      }
+
+      // Check entitlements
+      const idempotencyKey = `guide-${Date.now()}`;
+      const entitlementCheck = await checkAndBurnTokens('guide', idempotencyKey);
+      if (!entitlementCheck.allowed) {
+        spinner.fail(entitlementCheck.reason);
+        process.exit(1);
+      }
+
+      spinner.text = 'Generating guide...';
+
+      const Anthropic = (await import('@anthropic-ai/sdk')).default;
+      const client = new Anthropic({ apiKey });
+
+      const response = await client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 4000,
+        system: `You are creating an onboarding guide for new developers joining this project.
+
+Project context:
+${context}
+
+Generate a comprehensive ONBOARDING.md that includes:
+1. Project Overview (what it does, who it's for)
+2. Architecture Overview (high-level structure, key patterns)
+3. Getting Started (setup steps, prerequisites)
+4. Key Concepts (important abstractions, terminology)
+5. Directory Guide (what each major folder contains)
+6. Common Tasks (how to add features, fix bugs, run tests)
+7. Key Files to Read First (most important files for understanding)
+8. Gotchas & Tips (things that might trip up new devs)
+
+Be specific to THIS codebase. Use actual file names and paths.
+Format as clean Markdown.`,
+        messages: [{ role: 'user', content: 'Generate the onboarding guide.' }]
+      });
+
+      spinner.stop();
+
+      const guide = response.content[0].type === 'text' ? response.content[0].text : '';
+
+      // Save to file
+      await fs.writeFile(path.join(projectPath, options.output), guide);
+      console.log(chalk.green(`✓ Generated ${options.output}\n`));
+
+      // Preview
+      console.log(chalk.cyan('─── Preview ───\n'));
+      console.log(guide.slice(0, 1500) + (guide.length > 1500 ? '\n\n...(truncated)' : ''));
+      console.log(chalk.cyan('\n───────────────\n'));
+
+      console.log(chalk.dim(`Full guide saved to: ${options.output}\n`));
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+    }
+  });
+
+// ============================================
+// VOICE COMMAND - Talk to your codebase
+// ============================================
+
+program
+  .command('voice')
+  .description('Voice-based codebase learning (talk to your code)')
+  .option('-p, --path <path>', 'Project path', '.')
+  .action(async (options) => {
+    console.log(chalk.bold.blue('\n🎙️  Voice Mode\n'));
+    console.log(chalk.gray('Talk to your codebase. Say "exit" or press Ctrl+C to quit.\n'));
+
+    const projectPath = path.resolve(options.path);
+
+    // Check if user is logged in
+    const token = await getIdToken();
+    if (!token) {
+      console.log(chalk.yellow('Please log in to use voice mode.\n'));
+      const { shouldLogin } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'shouldLogin',
+        message: 'Would you like to log in now?',
+        default: true,
+      }]);
+
+      if (shouldLogin) {
+        try {
+          await loginWithBrowser();
+          console.log(chalk.green('\n✓ Logged in successfully!\n'));
+        } catch (error) {
+          console.error(chalk.red(`Login failed: ${error.message}`));
+          process.exit(1);
+        }
+      } else {
+        console.log(chalk.dim('\nRun `ramp login` to authenticate.\n'));
+        process.exit(0);
+      }
+    }
+
+    // Get fresh token after potential login
+    const authToken = await getIdToken();
+
+    const API_URL = process.env.RAMP_API_URL || 'https://entitlement-service.rian-19c.workers.dev';
+
+    // Track usage
+    const usageFile = path.join(process.env.HOME, '.ramp', 'voice-usage.json');
+    let usage = { totalMinutes: 0, sessions: [] };
+    try {
+      await fs.mkdir(path.join(process.env.HOME, '.ramp'), { recursive: true });
+      usage = JSON.parse(await fs.readFile(usageFile, 'utf8'));
+    } catch {}
+
+    const sessionStart = Date.now();
+    let sessionMinutes = 0;
+
+    // Gather codebase context once
+    const spinner = ora('Reading codebase...').start();
+    let context = `Project: ${path.basename(projectPath)}\n`;
+
+    try {
+      const keyFiles = ['README.md', 'package.json', 'tsconfig.json'];
+      for (const file of keyFiles) {
+        try {
+          const content = await fs.readFile(path.join(projectPath, file), 'utf8');
+          context += `\n${file}:\n${content.slice(0, 1500)}\n`;
+        } catch {}
+      }
+
+      let structure = '';
+      async function getStructure(dir, prefix = '', depth = 0) {
+        if (depth > 2) return;
+        try {
+          const entries = await fs.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+            structure += `${prefix}${entry.name}${entry.isDirectory() ? '/' : ''}\n`;
+            if (entry.isDirectory()) {
+              await getStructure(path.join(dir, entry.name), prefix + '  ', depth + 1);
+            }
+          }
+        } catch {}
+      }
+      await getStructure(projectPath);
+      context += `\nStructure:\n${structure.slice(0, 2000)}\n`;
+
+      spinner.succeed('Ready! Listening...\n');
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exit(1);
+    }
+
+    const conversationHistory = [];
+
+    // Helper function to call backend chat API
+    async function chatWithBackend(messages, systemPrompt) {
+      const response = await fetch(`${API_URL}/ai/chat`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${authToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          product: 'ramp',
+          messages,
+          system: systemPrompt,
+          max_tokens: 500,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.message || `API error: ${response.status}`);
+      }
+
+      return await response.json();
+    }
+
+    // Helper function to call backend TTS API
+    async function textToSpeech(text) {
+      const response = await fetch(`${API_URL}/ai/tts`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${authToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          product: 'ramp',
+          text,
+          voice: 'nova',
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`TTS error: ${response.status}`);
+      }
+
+      return Buffer.from(await response.arrayBuffer());
+    }
+
+    // Voice interaction loop
+    async function voiceLoop() {
+      while (true) {
+        try {
+          // For now, use text input with voice output
+          // Full voice input requires native audio recording
+          const { input } = await inquirer.prompt([{
+            type: 'input',
+            name: 'input',
+            message: chalk.green('🎤 You:'),
+            prefix: ''
+          }]);
+
+          if (!input.trim()) continue;
+          if (input.toLowerCase() === 'exit' || input.toLowerCase() === 'quit') {
+            break;
+          }
+
+          const startTime = Date.now();
+          conversationHistory.push({ role: 'user', content: input });
+
+          // Get AI response
+          const thinkingSpinner = ora('Thinking...').start();
+
+          const systemPrompt = `You are Ramp, a voice assistant helping a developer understand a codebase.
+Keep responses concise (2-3 sentences) since they'll be spoken aloud.
+
+Project context:
+${context}
+
+Be helpful, friendly, and practical. Reference specific files when relevant.`;
+
+          const chatResponse = await chatWithBackend(conversationHistory, systemPrompt);
+          const answer = chatResponse.content || chatResponse.text || '';
+          conversationHistory.push({ role: 'assistant', content: answer });
+
+          thinkingSpinner.stop();
+
+          // Generate speech
+          const speechSpinner = ora('Speaking...').start();
+
+          try {
+            const audioBuffer = await textToSpeech(answer);
+
+            // Save and play audio
+            const audioPath = `/tmp/ramp-voice-${Date.now()}.mp3`;
+            await fs.writeFile(audioPath, audioBuffer);
+
+            speechSpinner.stop();
+            console.log(chalk.cyan(`\n🔊 Ramp: ${answer}\n`));
+
+            // Play audio (macOS)
+            if (process.platform === 'darwin') {
+              await execAsync(`afplay "${audioPath}"`).catch(() => {});
+            } else if (process.platform === 'linux') {
+              await execAsync(`mpg123 "${audioPath}" 2>/dev/null || play "${audioPath}" 2>/dev/null`).catch(() => {});
+            }
+
+            // Clean up
+            await fs.unlink(audioPath).catch(() => {});
+
+          } catch (ttsError) {
+            speechSpinner.stop();
+            // Fallback to text if TTS fails
+            console.log(chalk.cyan(`\n💬 Ramp: ${answer}\n`));
+          }
+
+          // Track usage
+          const elapsed = (Date.now() - startTime) / 1000 / 60;
+          sessionMinutes += elapsed;
+
+        } catch (error) {
+          if (error.name === 'ExitPromptError') break;
+          console.error(chalk.red(`Error: ${error.message}`));
+        }
+      }
+    }
+
+    // Handle exit
+    process.on('SIGINT', async () => {
+      console.log(chalk.cyan('\n\n👋 Ending voice session...\n'));
+      await saveUsage();
+      process.exit(0);
+    });
+
+    async function saveUsage() {
+      const totalSessionMinutes = (Date.now() - sessionStart) / 1000 / 60;
+      usage.totalMinutes += totalSessionMinutes;
+      usage.sessions.push({
+        date: new Date().toISOString(),
+        project: path.basename(projectPath),
+        minutes: totalSessionMinutes
+      });
+      await fs.writeFile(usageFile, JSON.stringify(usage, null, 2));
+
+      console.log(chalk.dim(`Session: ${totalSessionMinutes.toFixed(2)} min`));
+      console.log(chalk.dim(`Total usage: ${usage.totalMinutes.toFixed(2)} min\n`));
+    }
+
+    await voiceLoop();
+    await saveUsage();
+  });
+
+// Voice usage stats
+program
+  .command('voice:usage')
+  .description('View voice minutes usage')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📊 Voice Usage\n'));
+
+    const usageFile = path.join(process.env.HOME, '.ramp', 'voice-usage.json');
+    let usage = { totalMinutes: 0, sessions: [] };
+
+    try {
+      usage = JSON.parse(await fs.readFile(usageFile, 'utf8'));
+    } catch {
+      console.log(chalk.dim('No voice usage yet.\n'));
+      console.log(chalk.dim('Start with: ramp voice\n'));
+      return;
+    }
+
+    console.log(chalk.bold(`Total: ${usage.totalMinutes.toFixed(2)} minutes\n`));
+
+    if (usage.sessions.length > 0) {
+      console.log(chalk.bold('Recent Sessions:'));
+      usage.sessions.slice(-10).reverse().forEach(s => {
+        const date = new Date(s.date).toLocaleDateString();
+        console.log(chalk.dim(`  ${date} - ${s.project}: ${s.minutes.toFixed(2)} min`));
+      });
+      console.log('');
+    }
+
+    // Show tier info
+    const freeMinutes = 10;
+    const remaining = Math.max(0, freeMinutes - usage.totalMinutes);
+
+    console.log(chalk.bold('Plan: Free Tier'));
+    console.log(chalk.dim(`  ${remaining.toFixed(2)} / ${freeMinutes} minutes remaining\n`));
+
+    if (remaining <= 0) {
+      console.log(chalk.yellow('⚡ Upgrade to Pro for unlimited voice minutes'));
+      console.log(chalk.dim('   rampupgrade\n'));
+    }
+  });
+
+// ============================================
+// BILLING & ACCOUNT
+// ============================================
+
+program
+  .command('login')
+  .description('Log in to your Ramp account')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🔐 Login\n'));
+
+    const configDir = path.join(process.env.HOME, '.ramp');
+    const authFile = path.join(configDir, 'auth.json');
+
+    // Check if already logged in
+    try {
+      const auth = JSON.parse(await fs.readFile(authFile, 'utf8'));
+      if (auth.token) {
+        console.log(chalk.green(`Already logged in as ${auth.email}\n`));
+        const { logout } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'logout',
+          message: 'Log out?',
+          default: false
+        }]);
+        if (logout) {
+          await fs.unlink(authFile);
+          console.log(chalk.dim('\nLogged out.\n'));
+        }
+        return;
+      }
+    } catch {}
+
+    console.log(chalk.dim('Create an account at: https://rampup.dev\n'));
+
+    const { email, token } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'email',
+        message: 'Email:'
+      },
+      {
+        type: 'password',
+        name: 'token',
+        message: 'API Token (from rampup.dev/settings):'
+      }
+    ]);
+
+    // In production, validate token against backend
+    // For now, just save it
+    await fs.mkdir(configDir, { recursive: true });
+    await fs.writeFile(authFile, JSON.stringify({ email, token, created: new Date().toISOString() }, null, 2));
+
+    console.log(chalk.green('\n✓ Logged in successfully!\n'));
+  });
+
+program
+  .command('upgrade')
+  .description('Upgrade your Ramp plan')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('⚡ Upgrade Plan\n'));
+
+    // Check current usage
+    const usageFile = path.join(process.env.HOME, '.ramp', 'voice-usage.json');
+    let usage = { totalMinutes: 0 };
+    try {
+      usage = JSON.parse(await fs.readFile(usageFile, 'utf8'));
+    } catch {}
+
+    console.log(chalk.bold('Current: Free Tier'));
+    console.log(chalk.dim(`  Voice: ${usage.totalMinutes.toFixed(2)} / 10 min used\n`));
+
+    console.log(chalk.bold('Available Plans:\n'));
+
+    console.log(chalk.cyan('  Starter - $29/mo'));
+    console.log(chalk.dim('    • 100 voice minutes'));
+    console.log(chalk.dim('    • Unlimited text queries'));
+    console.log(chalk.dim('    • 5 team members\n'));
+
+    console.log(chalk.cyan('  Pro - $99/mo'));
+    console.log(chalk.dim('    • 500 voice minutes'));
+    console.log(chalk.dim('    • Unlimited everything'));
+    console.log(chalk.dim('    • 25 team members'));
+    console.log(chalk.dim('    • Priority support\n'));
+
+    console.log(chalk.cyan('  Enterprise - Custom'));
+    console.log(chalk.dim('    • Unlimited voice minutes'));
+    console.log(chalk.dim('    • Unlimited team members'));
+    console.log(chalk.dim('    • SSO, audit logs'));
+    console.log(chalk.dim('    • Dedicated support\n'));
+
+    console.log(chalk.dim('Upgrade at: https://rampup.dev/pricing\n'));
+
+    const { openBrowser } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'openBrowser',
+      message: 'Open pricing page?',
+      default: true
+    }]);
+
+    if (openBrowser) {
+      const open = (await import('open')).default;
+      await open('https://rampup.dev/pricing');
+    }
+  });
+
+program
+  .command('status')
+  .description('View account status and usage')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📊 Account Status\n'));
+
+    const configDir = path.join(process.env.HOME, '.ramp');
+
+    // Auth status
+    let auth = null;
+    try {
+      auth = JSON.parse(await fs.readFile(path.join(configDir, 'auth.json'), 'utf8'));
+    } catch {}
+
+    if (auth) {
+      console.log(chalk.bold('Account:'));
+      console.log(chalk.dim(`  Email: ${auth.email}`));
+      console.log(chalk.dim(`  Plan: Free Tier\n`));
+    } else {
+      console.log(chalk.yellow('Not logged in.'));
+      console.log(chalk.dim('  Run: ramplogin\n'));
+    }
+
+    // Voice usage
+    let voiceUsage = { totalMinutes: 0 };
+    try {
+      voiceUsage = JSON.parse(await fs.readFile(path.join(configDir, 'voice-usage.json'), 'utf8'));
+    } catch {}
+
+    console.log(chalk.bold('Usage This Month:'));
+    const freeMinutes = 10;
+    const voiceRemaining = Math.max(0, freeMinutes - voiceUsage.totalMinutes);
+    const voicePercent = Math.min(100, (voiceUsage.totalMinutes / freeMinutes) * 100);
+    const voiceBar = '█'.repeat(Math.floor(voicePercent / 10)) + '░'.repeat(10 - Math.floor(voicePercent / 10));
+    console.log(chalk.dim(`  Voice: [${voiceBar}] ${voiceUsage.totalMinutes.toFixed(1)}/${freeMinutes} min`));
+
+    // Progress data
+    let progress = {};
+    try {
+      progress = JSON.parse(await fs.readFile(path.join(configDir, 'progress.json'), 'utf8'));
+    } catch {}
+    const projectCount = Object.keys(progress).length;
+    console.log(chalk.dim(`  Projects explored: ${projectCount}`));
+
+    console.log('');
+
+    if (voiceRemaining <= 2) {
+      console.log(chalk.yellow('⚠️  Running low on voice minutes!'));
+      console.log(chalk.dim('   Run: rampupgrade\n'));
+    }
+  });
+
+// ============================================
+// ORCHESTRATION COMMANDS (Secondary)
+// ============================================
+
+// Run a goal
+program
+  .command('run <goal>')
+  .description('Execute a development goal with AI orchestration')
+  .option('-p, --project <path>', 'Project path', process.cwd())
+  .option('--task-manager <provider>', 'Task manager AI provider', 'anthropic')
+  .option('--task-manager-model <model>', 'Task manager model', 'claude-sonnet-4-20250514')
+  .option('--operator <provider>', 'Operator AI provider', 'anthropic')
+  .option('--operator-model <model>', 'Operator model', 'claude-sonnet-4-20250514')
+  .option('--no-claude-code', 'Use AI directly instead of Claude Code')
+  .option('--reviewer <provider>', 'Enable reviewer with provider')
+  .option('--reviewer-model <model>', 'Reviewer model', 'gpt-4o')
+  .option('-v, --verbose', 'Verbose output')
+  .action(async (goal, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🚀 Running Goal\n'));
+
+    const spinner = ora('Initializing AI orchestrator...').start();
+
+    try {
+      const { AIOrchestrator } = await import('../server/ai/orchestrator.mjs');
+
+      const orchestrator = new AIOrchestrator({
+        taskManagerProvider: options.taskManager,
+        taskManagerModel: options.taskManagerModel,
+        operatorProvider: options.operator,
+        operatorModel: options.operatorModel,
+        useClaudeCode: options.claudeCode !== false,
+        enableReviewer: !!options.reviewer,
+        reviewerProvider: options.reviewer,
+        reviewerModel: options.reviewerModel,
+      });
+
+      orchestrator.on('initialized', () => spinner.succeed('AI orchestrator initialized'));
+      orchestrator.on('phase:planning', () => spinner.start('Planning tasks...'));
+      orchestrator.on('phase:planned', ({ tasks }) => {
+        spinner.succeed(`Planned ${tasks.length} tasks`);
+        console.log(chalk.dim('\nTasks:'));
+        tasks.forEach((t, i) => console.log(chalk.dim(`  ${i + 1}. ${t.title}`)));
+        console.log('');
+      });
+      orchestrator.on('task:started', ({ task }) => spinner.start(`Executing: ${task.title}`));
+      orchestrator.on('task:output', ({ chunk }) => {
+        if (options.verbose) process.stdout.write(chalk.dim(chunk));
+      });
+      orchestrator.on('task:completed', ({ task }) => spinner.succeed(`Completed: ${task.title}`));
+      orchestrator.on('task:failed', ({ task, error }) => spinner.fail(`Failed: ${task.title} - ${error}`));
+      orchestrator.on('goal:completed', ({ completed, failed, total }) => {
+        console.log('');
+        console.log(chalk.bold.green('✅ Goal completed!'));
+        console.log(chalk.dim(`   Completed: ${completed}/${total}`));
+        if (failed > 0) console.log(chalk.dim(`   Failed: ${failed}`));
+      });
+
+      await orchestrator.initialize();
+      orchestrator.setProject(path.resolve(options.project));
+      await orchestrator.executeGoal(goal);
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Plan only
+program
+  .command('plan <goal>')
+  .description('Plan tasks for a goal without executing')
+  .option('-p, --project <path>', 'Project path', process.cwd())
+  .option('--provider <provider>', 'AI provider', 'anthropic')
+  .option('--model <model>', 'AI model', 'claude-sonnet-4-20250514')
+  .option('-o, --output <file>', 'Output plan to file')
+  .action(async (goal, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📋 Planning: ') + goal + '\n');
+
+    const spinner = ora('Analyzing project and planning...').start();
+
+    try {
+      const { AIOrchestrator } = await import('../server/ai/orchestrator.mjs');
+
+      const orchestrator = new AIOrchestrator({
+        taskManagerProvider: options.provider,
+        taskManagerModel: options.model,
+      });
+
+      await orchestrator.initialize();
+      orchestrator.setProject(path.resolve(options.project));
+
+      const tasks = await orchestrator.planGoal(goal);
+      spinner.succeed(`Planned ${tasks.length} tasks\n`);
+
+      tasks.forEach((task, i) => {
+        console.log(chalk.bold(`${i + 1}. ${task.title}`));
+        console.log(chalk.dim(`   Type: ${task.type} | Complexity: ${task.complexity}`));
+        console.log(chalk.dim(`   ${task.description}`));
+        if (task.acceptanceCriteria?.length) {
+          console.log(chalk.dim('   Acceptance Criteria:'));
+          task.acceptanceCriteria.forEach(c => console.log(chalk.dim(`     - ${c}`)));
+        }
+        console.log('');
+      });
+
+      if (options.output) {
+        await fs.writeFile(options.output, JSON.stringify(tasks, null, 2));
+        console.log(chalk.green(`Plan saved to ${options.output}`));
+      }
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// ARCHITECTURE COMMANDS (from Archie)
+// ============================================
+
+function getApiKey() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error(chalk.red('\nError: ANTHROPIC_API_KEY environment variable is not set.\n'));
+    console.log('Set it with:');
+    console.log(chalk.cyan('  export ANTHROPIC_API_KEY=your-api-key\n'));
+    process.exit(1);
+  }
+  return apiKey;
+}
+
+// Mermaid diagram utilities
+function getMermaidLiveUrl(mermaidCode) {
+  const state = {
+    code: mermaidCode.trim(),
+    mermaid: { theme: 'default' },
+    autoSync: true,
+    updateDiagram: true,
+  };
+  const json = JSON.stringify(state);
+  const base64 = Buffer.from(json).toString('base64');
+  return `https://mermaid.live/edit#base64:${base64}`;
+}
+
+function extractMermaidDiagrams(markdown) {
+  const diagrams = [];
+  const mermaidRegex = /```mermaid\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = mermaidRegex.exec(markdown)) !== null) {
+    const code = match[1].trim();
+    const beforeMatch = markdown.slice(0, match.index);
+    const headingMatch = beforeMatch.match(/###?\s+([^\n]+)\n*$/);
+    const title = headingMatch ? headingMatch[1].trim() : undefined;
+    diagrams.push({ code, title });
+  }
+
+  return diagrams;
+}
+
+async function openDiagramInBrowser(mermaidCode, title = 'Architecture Diagram') {
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${title}</title>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+  <style>
+    body { font-family: system-ui; background: #1a1a2e; color: #eee; margin: 0; padding: 20px; min-height: 100vh; }
+    .container { max-width: 1200px; margin: 0 auto; }
+    h1 { color: #00d9ff; }
+    .diagram-container { background: #16213e; border-radius: 12px; padding: 30px; }
+    .mermaid { display: flex; justify-content: center; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>🏗️ ${title}</h1>
+    <div class="diagram-container">
+      <div class="mermaid">${mermaidCode}</div>
+    </div>
+  </div>
+  <script>mermaid.initialize({ startOnLoad: true, theme: 'dark' });</script>
+</body>
+</html>`;
+
+  const tempFile = `/tmp/ramp-diagram-${Date.now()}.html`;
+  await fs.writeFile(tempFile, html);
+
+  const command = process.platform === 'darwin' ? `open "${tempFile}"` :
+    process.platform === 'win32' ? `start "${tempFile}"` : `xdg-open "${tempFile}"`;
+
+  await execAsync(command);
+}
+
+// Simple Architect class
+class Architect {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.history = [];
+  }
+
+  async chat(userMessage) {
+    const Anthropic = (await import('@anthropic-ai/sdk')).default;
+    const client = new Anthropic({ apiKey: this.apiKey });
+
+    this.history.push({ role: 'user', content: userMessage });
+
+    const response = await client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 8192,
+      system: `You are Ramp Architect, an expert software architect. You help developers design systems with:
+- Clear tech stack recommendations
+- Architecture diagrams (Mermaid format)
+- Project structure
+- Trade-off analysis
+- Cost estimates
+Be opinionated and specific. Give clear paths forward.`,
+      messages: this.history,
+    });
+
+    const assistantMessage = response.content[0].type === 'text' ? response.content[0].text : '';
+    this.history.push({ role: 'assistant', content: assistantMessage });
+    return assistantMessage;
+  }
+
+  clearHistory() {
+    this.history = [];
+  }
+}
+
+// Design command
+program
+  .command('design <description>')
+  .description('Get architecture recommendation for a product idea')
+  .option('-o, --output <file>', 'Save recommendation to file')
+  .action(async (description, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🏗️ Designing Architecture\n'));
+
+    const apiKey = getApiKey();
+    const architect = new Architect(apiKey);
+
+    const spinner = ora('Analyzing your product idea...').start();
+
+    try {
+      const prompt = `I want to build: ${description}
+
+Please provide a complete architecture recommendation including:
+1. Tech stack recommendation with rationale
+2. Architecture diagram (Mermaid)
+3. Project structure
+4. Key decisions and trade-offs
+5. Getting started steps
+6. Cost estimates
+
+Be specific and opinionated.`;
+
+      const response = await architect.chat(prompt);
+      spinner.succeed('Architecture recommendation ready!');
+
+      console.log(chalk.cyan('\n─── Architecture Recommendation ───\n'));
+      console.log(response);
+      console.log(chalk.cyan('\n───────────────────────────────────\n'));
+
+      if (options.output) {
+        await fs.writeFile(options.output, response);
+        console.log(chalk.green(`✓ Saved to ${options.output}`));
+      }
+
+      // Check for diagrams
+      const foundDiagrams = extractMermaidDiagrams(response);
+      if (foundDiagrams.length > 0) {
+        const { wantDiagrams } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'wantDiagrams',
+          message: `Found ${foundDiagrams.length} diagram(s). Open in browser?`,
+          default: true,
+        }]);
+
+        if (wantDiagrams) {
+          for (const diagram of foundDiagrams) {
+            await openDiagramInBrowser(diagram.code, diagram.title || 'Architecture Diagram');
+          }
+          console.log(chalk.green('✓ Diagrams opened\n'));
+        }
+      }
+
+    } catch (error) {
+      spinner.fail('Error generating architecture');
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Compare command
+program
+  .command('compare')
+  .description('Compare two architecture approaches')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('⚖️ Compare Approaches\n'));
+
+    const apiKey = getApiKey();
+    const architect = new Architect(apiKey);
+
+    const { context, approach1, approach2 } = await inquirer.prompt([
+      { type: 'input', name: 'context', message: 'What are you building?' },
+      { type: 'input', name: 'approach1', message: 'First approach:' },
+      { type: 'input', name: 'approach2', message: 'Second approach:' },
+    ]);
+
+    const spinner = ora('Comparing approaches...').start();
+
+    try {
+      const prompt = `I'm building: ${context}
+
+Please compare these two approaches:
+1. ${approach1}
+2. ${approach2}
+
+Provide a detailed comparison with:
+- Pros and cons of each
+- Performance implications
+- Development speed
+- Maintenance burden
+- Cost considerations
+- Clear recommendation with reasoning`;
+
+      const response = await architect.chat(prompt);
+      spinner.succeed('Comparison ready!');
+
+      console.log(chalk.cyan('\n─── Comparison ───\n'));
+      console.log(response);
+      console.log(chalk.cyan('\n──────────────────\n'));
+
+    } catch (error) {
+      spinner.fail('Error comparing approaches');
+      console.error(chalk.red(error.message));
+    }
+  });
+
+// Interactive architect mode
+program
+  .command('architect')
+  .alias('arch')
+  .description('Interactive architecture advisor chat')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🏗️ Architecture Advisor\n'));
+
+    const apiKey = getApiKey();
+    const architect = new Architect(apiKey);
+
+    console.log(chalk.gray('Describe your product idea or ask architecture questions.'));
+    console.log(chalk.gray('Commands: /diagram, /clear, /exit\n'));
+
+    let lastResponse = '';
+
+    while (true) {
+      const { input } = await inquirer.prompt([{
+        type: 'input',
+        name: 'input',
+        message: chalk.green('You:'),
+        prefix: '',
+      }]);
+
+      if (!input.trim()) continue;
+
+      if (input.startsWith('/')) {
+        const command = input.slice(1).toLowerCase().split(' ')[0];
+
+        if (command === 'exit' || command === 'quit' || command === 'q') {
+          console.log(chalk.cyan('\nHappy building! 🚀\n'));
+          process.exit(0);
+        }
+
+        if (command === 'clear') {
+          architect.clearHistory();
+          console.log(chalk.yellow('\n✓ Conversation cleared\n'));
+          continue;
+        }
+
+        if (command === 'diagram' || command === 'd') {
+          if (!lastResponse) {
+            console.log(chalk.yellow('\nNo diagrams yet. Describe your product first.\n'));
+            continue;
+          }
+
+          const diagrams = extractMermaidDiagrams(lastResponse);
+          if (diagrams.length === 0) {
+            console.log(chalk.yellow('\nNo Mermaid diagrams found.\n'));
+            continue;
+          }
+
+          console.log(chalk.cyan(`\nOpening ${diagrams.length} diagram(s)...\n`));
+          for (const diagram of diagrams) {
+            await openDiagramInBrowser(diagram.code, diagram.title);
+          }
+          continue;
+        }
+
+        console.log(chalk.yellow(`\nUnknown command: ${command}\n`));
+        continue;
+      }
+
+      // Check entitlements before AI call
+      const idempotencyKey = `architect-${Date.now()}`;
+      const entitlementCheck = await checkAndBurnTokens('architect', idempotencyKey);
+      if (!entitlementCheck.allowed) {
+        console.log(chalk.red(`\n❌ ${entitlementCheck.reason}\n`));
+        continue;
+      }
+
+      const spinner = ora('Thinking...').start();
+      try {
+        const response = await architect.chat(input);
+        spinner.stop();
+        lastResponse = response;
+
+        console.log(chalk.cyan('\n─── Ramp ───\n'));
+        console.log(response);
+        console.log(chalk.cyan('\n─────────────\n'));
+
+        const foundDiagrams = extractMermaidDiagrams(response);
+        if (foundDiagrams.length > 0) {
+          console.log(chalk.gray(`💡 Found ${foundDiagrams.length} diagram(s). Use /diagram to view.\n`));
+        }
+      } catch (error) {
+        spinner.fail('Error');
+        console.error(chalk.red(error.message));
+      }
+    }
+  });
+
+// ============================================
+// AUTH COMMANDS
+// ============================================
+
+program
+  .command('login')
+  .description('Login to Ramp with your account')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('🔐 Login to Ramp\n'));
+
+    // Check if already logged in
+    const existingUser = await getUserInfo();
+    if (existingUser) {
+      console.log(chalk.yellow(`Already logged in as ${existingUser.email}`));
+      const { confirm } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Login with a different account?',
+        default: false,
+      }]);
+      if (!confirm) return;
+    }
+
+    try {
+      const user = await loginWithBrowser();
+      console.log(chalk.green(`\n✓ Logged in as ${user.email}\n`));
+      console.log(chalk.gray('Your credentials are saved at ~/.ramp/credentials.json\n'));
+    } catch (error) {
+      console.error(chalk.red(`\nLogin failed: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('logout')
+  .description('Logout from Ramp')
+  .action(async () => {
+    console.log(banner);
+
+    const user = await getUserInfo();
+    if (!user) {
+      console.log(chalk.yellow('Not currently logged in.\n'));
+      return;
+    }
+
+    await clearCredentials();
+    console.log(chalk.green(`✓ Logged out from ${user.email}\n`));
+  });
+
+program
+  .command('whoami')
+  .description('Show current logged in user')
+  .action(async () => {
+    const user = await getUserInfo();
+
+    if (!user) {
+      console.log(chalk.yellow('Not logged in. Run `ramplogin` to authenticate.\n'));
+      return;
+    }
+
+    console.log(chalk.cyan('\n  Logged in as:'));
+    console.log(`    Email: ${chalk.bold(user.email)}`);
+    if (user.displayName) {
+      console.log(`    Name: ${user.displayName}`);
+    }
+    console.log(`    UID: ${chalk.gray(user.uid)}\n`);
+  });
+
+// ============================================
+// CREDITS COMMAND
+// ============================================
+
+program
+  .command('credits')
+  .description('Check your AI credits balance')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('💳 Credit Balance\n'));
+
+    const spinner = ora('Checking balance...').start();
+
+    try {
+      const balance = await getTokenBalance();
+
+      if (!balance) {
+        spinner.warn('Not logged in to entitlement service');
+        console.log(chalk.gray('\nSet RAMP_TOKEN with your Firebase ID token to check balance.\n'));
+        return;
+      }
+
+      spinner.succeed('Balance retrieved!\n');
+
+      for (const token of balance.balances || []) {
+        console.log(chalk.cyan(`  ${token.tokenType}:`));
+        console.log(`    Balance: ${chalk.bold(token.balance)}`);
+        console.log(`    Used: ${token.lifetimeUsed}`);
+        console.log(`    Granted: ${token.lifetimeGranted}\n`);
+      }
+
+      console.log(chalk.gray('Visit rampup.dev to purchase more credits.\n'));
+    } catch (error) {
+      spinner.fail('Failed to check balance');
+      console.error(chalk.red(error.message));
+    }
+  });
+
+// ============================================
+// TEMPLATE COMMANDS
+// ============================================
+
+program
+  .command('create <name>')
+  .description('Create a new project from template')
+  .option('-t, --template <template>', 'Template to use', 'saas-starter')
+  .option('-d, --dir <directory>', 'Output directory', '.')
+  .action(async (name, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue(`📦 Creating project: ${name}\n`));
+
+    const spinner = ora('Initializing template...').start();
+
+    try {
+      const templatePath = path.join(__dirname, '..', 'templates', options.template);
+      const outputPath = path.join(path.resolve(options.dir), name);
+
+      try {
+        await fs.access(templatePath);
+      } catch {
+        spinner.fail(`Template not found: ${options.template}`);
+        const templates = await fs.readdir(path.join(__dirname, '..', 'templates'));
+        console.log(chalk.dim('\nAvailable templates:'));
+        templates.forEach(t => console.log(chalk.dim(`  - ${t}`)));
+        return;
+      }
+
+      spinner.text = 'Copying template files...';
+      await copyDir(templatePath, outputPath);
+
+      const pkgPath = path.join(outputPath, 'package.json');
+      try {
+        const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
+        pkg.name = name;
+        await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+      } catch {}
+
+      spinner.succeed(`Project created at ${outputPath}`);
+
+      console.log(chalk.dim('\nNext steps:'));
+      console.log(chalk.dim(`  cd ${name}`));
+      console.log(chalk.dim('  npm install'));
+      console.log(chalk.dim('  npm run dev\n'));
+
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+    }
+  });
+
+program
+  .command('templates')
+  .description('List available project templates')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📁 Available Templates\n'));
+
+    try {
+      const templatesDir = path.join(__dirname, '..', 'templates');
+      const templates = await fs.readdir(templatesDir);
+
+      for (const template of templates) {
+        const infoPath = path.join(templatesDir, template, 'template.json');
+        try {
+          const info = JSON.parse(await fs.readFile(infoPath, 'utf-8'));
+          console.log(chalk.bold(`${template}`));
+          console.log(chalk.dim(`  ${info.description}`));
+        } catch {
+          console.log(chalk.bold(`${template}`));
+        }
+        console.log('');
+      }
+    } catch {
+      console.log(chalk.dim('No templates found'));
+    }
+  });
+
+// ============================================
+// OMNI - AI Context Bridge Commands
+// ============================================
+
+// Context store for Omni
+class ContextStore {
+  constructor() {
+    this.currentContext = null;
+    this.history = {};
+  }
+
+  async init() {
+    try {
+      const data = await fs.readFile(omniConfig.contextStorePath, 'utf8');
+      this.history = JSON.parse(data);
+    } catch {
+      // No existing contexts
+    }
+  }
+
+  async save() {
+    const dir = path.dirname(omniConfig.contextStorePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(omniConfig.contextStorePath, JSON.stringify(this.history, null, 2));
+  }
+
+  async setContext(name) {
+    this.currentContext = name;
+    if (!this.history[name]) {
+      this.history[name] = { messages: [], lastAccessed: new Date().toISOString() };
+    } else {
+      this.history[name].lastAccessed = new Date().toISOString();
+    }
+    await this.save();
+    return this.history[name];
+  }
+
+  async addMessage(role, content, source) {
+    if (!this.currentContext) throw new Error('No active context');
+    this.history[this.currentContext].messages.push({
+      role, content, source, timestamp: new Date().toISOString()
+    });
+    await this.save();
+  }
+
+  getCurrent() {
+    if (!this.currentContext) return null;
+    return { name: this.currentContext, ...this.history[this.currentContext] };
+  }
+
+  list() {
+    return Object.keys(this.history).map(name => ({
+      name,
+      messages: this.history[name].messages.length,
+      lastAccessed: this.history[name].lastAccessed
+    }));
+  }
+}
+
+function formatContextForSharing(context) {
+  if (!context?.messages?.length) return 'No previous conversation context.';
+
+  const lines = [
+    '### Conversation Context ###',
+    'Sharing context from a previous conversation:',
+    ''
+  ];
+
+  const recent = context.messages.slice(-10);
+  recent.forEach((msg, i) => {
+    const role = msg.role === 'user' ? 'Human' : 'AI';
+    const source = msg.source ? ` (${msg.source})` : '';
+    lines.push(`${role}${source}: ${msg.content.slice(0, 300)}${msg.content.length > 300 ? '...' : ''}`);
+    if (i < recent.length - 1) lines.push('');
+  });
+
+  lines.push('', 'Please continue with this context in mind.');
+  return lines.join('\n');
+}
+
+// Omni interactive mode
+async function omniInteractive() {
+  const store = new ContextStore();
+  await store.init();
+
+  console.log(chalk.cyan('\n─── Omni - AI Context Bridge ───\n'));
+  console.log(chalk.gray('Bridge conversations between AI applications\n'));
+
+  // Select or create context
+  const contexts = store.list();
+  let contextName;
+
+  if (contexts.length > 0) {
+    console.log(chalk.dim('Existing contexts:'));
+    contexts.forEach((c, i) => console.log(chalk.dim(`  ${i + 1}. ${c.name} (${c.messages} msgs)`)));
+    console.log('');
+  }
+
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'Select or create context:',
+    choices: [
+      ...contexts.map(c => ({ name: `${c.name} (${c.messages} messages)`, value: c.name })),
+      { name: '+ Create new context', value: '_new' }
+    ]
+  }]);
+
+  if (action === '_new') {
+    const { name } = await inquirer.prompt([{
+      type: 'input',
+      name: 'name',
+      message: 'Context name:',
+      default: `context-${Date.now()}`
+    }]);
+    contextName = name;
+  } else {
+    contextName = action;
+  }
+
+  await store.setContext(contextName);
+  console.log(chalk.green(`\n✓ Active context: ${contextName}\n`));
+
+  // Main loop
+  while (true) {
+    const current = store.getCurrent();
+    const { choice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'choice',
+      message: `Context: ${current.name} (${current.messages.length} msgs) - What to do?`,
+      choices: [
+        { name: '📋 Copy context to clipboard', value: 'copy' },
+        { name: '🚀 Open Claude app', value: 'claude' },
+        { name: '💬 Open ChatGPT app', value: 'chatgpt' },
+        { name: '➕ Add message to context', value: 'add' },
+        { name: '👁️  View context', value: 'view' },
+        { name: '🔄 Switch context', value: 'switch' },
+        { name: '🚪 Exit', value: 'exit' }
+      ]
+    }]);
+
+    switch (choice) {
+      case 'copy': {
+        const formatted = formatContextForSharing(current);
+        const clipboardy = (await import('clipboardy')).default;
+        await clipboardy.write(formatted);
+        console.log(chalk.green('✓ Context copied to clipboard\n'));
+        break;
+      }
+
+      case 'claude':
+      case 'chatgpt': {
+        const formatted = formatContextForSharing(current);
+        const clipboardy = (await import('clipboardy')).default;
+        await clipboardy.write(formatted);
+
+        const appPath = choice === 'claude' ? omniConfig.paths.claude : omniConfig.paths.chatGpt;
+        const open = (await import('open')).default;
+
+        console.log(chalk.cyan(`Opening ${choice}...`));
+        await open(appPath);
+        console.log(chalk.green('✓ Context copied. Paste into the app.\n'));
+        break;
+      }
+
+      case 'add': {
+        const { role, content } = await inquirer.prompt([
+          {
+            type: 'list',
+            name: 'role',
+            message: 'Message role:',
+            choices: [
+              { name: 'User (human)', value: 'user' },
+              { name: 'Assistant (AI)', value: 'assistant' }
+            ]
+          },
+          {
+            type: 'input',
+            name: 'content',
+            message: 'Message content:'
+          }
+        ]);
+        await store.addMessage(role, content, 'manual');
+        console.log(chalk.green('✓ Message added\n'));
+        break;
+      }
+
+      case 'view':
+        console.log(chalk.cyan('\n─── Context Messages ───\n'));
+        if (current.messages.length === 0) {
+          console.log(chalk.dim('No messages yet.\n'));
+        } else {
+          current.messages.forEach((msg, i) => {
+            const role = msg.role === 'user' ? chalk.blue('Human') : chalk.green('AI');
+            const source = msg.source ? chalk.dim(` (${msg.source})`) : '';
+            console.log(`${i + 1}. ${role}${source}: ${msg.content.slice(0, 100)}${msg.content.length > 100 ? '...' : ''}`);
+          });
+          console.log('');
+        }
+        break;
+
+      case 'switch': {
+        const contexts = store.list();
+        const { newCtx } = await inquirer.prompt([{
+          type: 'list',
+          name: 'newCtx',
+          message: 'Select context:',
+          choices: [
+            ...contexts.map(c => ({ name: `${c.name} (${c.messages} msgs)`, value: c.name })),
+            { name: '+ Create new', value: '_new' }
+          ]
+        }]);
+
+        if (newCtx === '_new') {
+          const { name } = await inquirer.prompt([{ type: 'input', name: 'name', message: 'Context name:' }]);
+          await store.setContext(name);
+        } else {
+          await store.setContext(newCtx);
+        }
+        console.log(chalk.green(`✓ Switched to: ${store.currentContext}\n`));
+        break;
+      }
+
+      case 'exit':
+        console.log(chalk.cyan('\nGoodbye!\n'));
+        process.exit(0);
+    }
+  }
+}
+
+// Omni command
+program
+  .command('omni')
+  .description('AI Context Bridge - share context between AI apps')
+  .action(omniInteractive);
+
+// Omni list contexts
+program
+  .command('omni:list')
+  .description('List all saved conversation contexts')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📋 Saved Contexts\n'));
+
+    const store = new ContextStore();
+    await store.init();
+    const contexts = store.list();
+
+    if (contexts.length === 0) {
+      console.log(chalk.dim('No contexts found. Use "ramp omni" to create one.\n'));
+    } else {
+      contexts.forEach(c => {
+        console.log(chalk.bold(c.name));
+        console.log(chalk.dim(`  Messages: ${c.messages}`));
+        console.log(chalk.dim(`  Last used: ${new Date(c.lastAccessed).toLocaleString()}`));
+        console.log('');
+      });
+    }
+  });
+
+// Omni send context
+program
+  .command('omni:send <context> <target>')
+  .description('Send context to AI app (claude|chatgpt)')
+  .action(async (contextName, target) => {
+    console.log(banner);
+
+    const store = new ContextStore();
+    await store.init();
+
+    if (!store.history[contextName]) {
+      console.error(chalk.red(`Context "${contextName}" not found.`));
+      process.exit(1);
+    }
+
+    await store.setContext(contextName);
+    const current = store.getCurrent();
+    const formatted = formatContextForSharing(current);
+
+    const clipboardy = (await import('clipboardy')).default;
+    await clipboardy.write(formatted);
+
+    const targetLower = target.toLowerCase();
+    if (targetLower !== 'claude' && targetLower !== 'chatgpt') {
+      console.error(chalk.red('Target must be "claude" or "chatgpt"'));
+      process.exit(1);
+    }
+
+    const appPath = targetLower === 'claude' ? omniConfig.paths.claude : omniConfig.paths.chatGpt;
+    const open = (await import('open')).default;
+
+    console.log(chalk.cyan(`Opening ${target}...`));
+    await open(appPath);
+    console.log(chalk.green('✓ Context copied to clipboard. Paste into the app.\n'));
+  });
+
+// ============================================
+// UTILITY COMMANDS
+// ============================================
+
+program
+  .command('models')
+  .description('List available AI models')
+  .action(async () => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📦 Available AI Models\n'));
+
+    try {
+      const { getAvailableProviders } = await import('../server/ai/providers/index.mjs');
+      const providers = getAvailableProviders();
+
+      providers.forEach(provider => {
+        console.log(chalk.bold(`${provider.displayName}:`));
+        provider.models.forEach(model => {
+          console.log(chalk.dim(`  ${model.id} - ${model.name}`));
+        });
+        console.log('');
+      });
+    } catch {
+      console.log(chalk.dim('Anthropic Claude models:'));
+      console.log(chalk.dim('  claude-sonnet-4-20250514'));
+      console.log(chalk.dim('  claude-opus-4-20250514'));
+    }
+  });
+
+// Interactive mode (default)
+program
+  .command('interactive')
+  .alias('i')
+  .description('Interactive mode')
+  .action(async () => {
+    console.log(banner);
+
+    const { mode } = await inquirer.prompt([{
+      type: 'list',
+      name: 'mode',
+      message: 'How do you want to learn this codebase?',
+      choices: [
+        { name: '🎤  Voice chat (talk to your code)', value: 'voice' },
+        { name: '💬  Text chat', value: 'learn' },
+        { name: '📁  More options...', value: 'more' },
+      ],
+    }]);
+
+    if (mode === 'voice') {
+      await program.parseAsync(['node', 'ramp', 'voice']);
+    } else if (mode === 'learn') {
+      await program.parseAsync(['node', 'ramp', 'learn']);
+    } else if (mode === 'more') {
+      // Show expanded options
+      const { moreMode } = await inquirer.prompt([{
+        type: 'list',
+        name: 'moreMode',
+        message: 'Choose an option:',
+        choices: [
+          { name: '🚀  Start Onboarding', value: 'start' },
+          { name: '🔍  Explore Codebase', value: 'explore' },
+          { name: '📚  Learn with AI Guide', value: 'learn' },
+          { name: '❓  Ask a Question', value: 'ask' },
+          { name: '📖  Generate Onboarding Doc', value: 'guide' },
+          { name: '📊  View Progress', value: 'progress' },
+          new inquirer.Separator('── More Tools ──'),
+          { name: '🏗️  Design Architecture', value: 'architect' },
+          { name: '🚀  Run AI Goal', value: 'run' },
+        ],
+      }]);
+
+      if (moreMode === 'start') {
+        await program.parseAsync(['node', 'ramp', 'start']);
+      } else if (moreMode === 'explore') {
+        await program.parseAsync(['node', 'ramp', 'explore']);
+      } else if (moreMode === 'learn') {
+        await program.parseAsync(['node', 'ramp', 'learn']);
+      } else if (moreMode === 'ask') {
+        const { question } = await inquirer.prompt([{
+          type: 'input',
+          name: 'question',
+          message: 'What do you want to know?'
+        }]);
+        if (question) {
+          await program.parseAsync(['node', 'ramp', 'ask', question]);
+        }
+      } else if (moreMode === 'guide') {
+        await program.parseAsync(['node', 'ramp', 'guide']);
+      } else if (moreMode === 'progress') {
+        await program.parseAsync(['node', 'ramp', 'progress']);
+      } else if (moreMode === 'architect') {
+        await program.parseAsync(['node', 'ramp', 'architect']);
+      } else {
+        console.log(chalk.dim(`\nRun: ramp ${moreMode} <args>\n`));
+      }
+    }
+  });
+
+// Helper function
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+// ============================================
+// KNOWLEDGE BASE COMMANDS
+// ============================================
+
+// Track last Q&A for saving
+let lastQA = null;
+
+// Search team knowledge base
+program
+  .command('kb [query]')
+  .alias('knowledge')
+  .description('Search your team\'s knowledge base')
+  .option('-r, --repo <url>', 'Filter by repository URL')
+  .option('-c, --category <category>', 'Filter by category (general, architecture, onboarding, debugging)')
+  .option('-n, --limit <number>', 'Max results', '5')
+  .action(async (query, options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('📚 Team Knowledge Base\n'));
+
+    const spinner = ora('Searching knowledge base...').start();
+
+    try {
+      const org = await getMyOrg();
+      if (!org) {
+        spinner.fail('You are not part of a team');
+        console.log(chalk.dim('\nJoin or create a team at rampup.dev to use the knowledge base.\n'));
+        return;
+      }
+
+      spinner.text = `Searching ${org.name}'s knowledge base...`;
+
+      const result = await searchKnowledge({
+        query: query || '',
+        repoUrl: options.repo,
+        category: options.category,
+        limit: parseInt(options.limit, 10),
+      });
+
+      spinner.stop();
+
+      if (result.items.length === 0) {
+        console.log(chalk.yellow('No entries found.'));
+        if (query) {
+          console.log(chalk.dim(`\nTry a different search or run: rampsave to add new knowledge\n`));
+        } else {
+          console.log(chalk.dim(`\nYour team hasn't saved any knowledge yet. Run: rampsave to add the first entry!\n`));
+        }
+        return;
+      }
+
+      console.log(chalk.bold(`Found ${result.total} entries${query ? ` matching "${query}"` : ''}:\n`));
+
+      for (let i = 0; i < result.items.length; i++) {
+        const entry = result.items[i];
+        console.log(chalk.cyan('─'.repeat(60)));
+        console.log(formatKnowledgeEntry(entry));
+      }
+
+      console.log(chalk.cyan('─'.repeat(60)));
+
+      if (result.hasMore) {
+        console.log(chalk.dim(`\n${result.total - result.items.length} more results. Use --limit to see more.\n`));
+      }
+
+    } catch (error) {
+      spinner.fail('Search failed');
+      console.error(chalk.red(error.message));
+    }
+  });
+
+// Save to knowledge base
+program
+  .command('save')
+  .description('Save a Q&A to your team\'s knowledge base')
+  .option('-q, --question <text>', 'The question')
+  .option('-a, --answer <text>', 'The answer')
+  .option('-r, --repo <url>', 'Associated repository URL')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .option('-c, --category <category>', 'Category: general, architecture, onboarding, debugging', 'general')
+  .action(async (options) => {
+    console.log(banner);
+    console.log(chalk.bold.blue('💾 Save to Knowledge Base\n'));
+
+    try {
+      const org = await getMyOrg();
+      if (!org) {
+        console.log(chalk.red('You are not part of a team.'));
+        console.log(chalk.dim('\nJoin or create a team at rampup.dev to save knowledge.\n'));
+        return;
+      }
+
+      let question = options.question;
+      let answer = options.answer;
+
+      // If not provided, prompt interactively
+      if (!question || !answer) {
+        if (lastQA) {
+          console.log(chalk.dim('Last Q&A from this session:'));
+          console.log(chalk.dim(`Q: ${lastQA.question.substring(0, 100)}...`));
+          console.log(chalk.dim(`A: ${lastQA.answer.substring(0, 100)}...`));
+          console.log('');
+
+          const { useLastQA } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'useLastQA',
+              message: 'Save this Q&A?',
+              default: true,
+            }
+          ]);
+
+          if (useLastQA) {
+            question = lastQA.question;
+            answer = lastQA.answer;
+          }
+        }
+
+        if (!question) {
+          const { inputQuestion } = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'inputQuestion',
+              message: 'Question:',
+              validate: (input) => input.trim().length > 0 || 'Question is required',
+            }
+          ]);
+          question = inputQuestion;
+        }
+
+        if (!answer) {
+          const { inputAnswer } = await inquirer.prompt([
+            {
+              type: 'editor',
+              name: 'inputAnswer',
+              message: 'Answer (opens editor):',
+              validate: (input) => input.trim().length > 0 || 'Answer is required',
+            }
+          ]);
+          answer = inputAnswer;
+        }
+      }
+
+      // Parse tags
+      const tags = options.tags ? options.tags.split(',').map(t => t.trim()) : [];
+
+      // Confirm before saving
+      console.log(chalk.bold('\nSaving to knowledge base:'));
+      console.log(chalk.cyan(`Category: ${options.category}`));
+      if (tags.length > 0) console.log(chalk.cyan(`Tags: ${tags.join(', ')}`));
+      if (options.repo) console.log(chalk.cyan(`Repo: ${options.repo}`));
+      console.log(chalk.dim(`Q: ${question.substring(0, 80)}${question.length > 80 ? '...' : ''}`));
+
+      const spinner = ora('Saving to knowledge base...').start();
+
+      const entry = await saveKnowledge({
+        question,
+        answer,
+        repoUrl: options.repo,
+        tags,
+        category: options.category,
+      });
+
+      spinner.succeed('Saved successfully!');
+      console.log(chalk.dim(`\nEntry ID: ${entry.id}`));
+      console.log(chalk.dim(`Team members can find this with: rampkb "${question.split(' ').slice(0, 3).join(' ')}..."\n`));
+
+    } catch (error) {
+      console.error(chalk.red(error.message));
+    }
+  });
+
+// Default to interactive
+program.action(() => {
+  program.parseAsync(['node', 'ramp', 'interactive']);
+});
+
+program.parse();