codehere 0.1.1 → 0.2.2

package/dist/index.js

@@ -1,23 +1,50 @@
 #!/usr/bin/env node
-/**
- * CodeHere CLI Entry Point
- *
- * ARCHITECTURE: Lazy Loading Pattern
- * All heavy imports (DB, WASM, storage) are dynamically imported
- * inside action handlers to prevent startup hangs.
- *
- * Only lightweight, pure-JS modules are imported at top-level:
- * - commander: CLI framework
- * - dotenv: Environment variables
- * - path/fs: Node.js built-ins
- * - ui.js: Formatting utilities (no DB/WASM)
- */
 import { Command } from 'commander';
 import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-// UI utilities - safe, no DB/WASM dependencies
-import { colors, createBanner, success, error, warning, sectionHeader, newline, createWelcomeMessage, isMinimalStyle, printMinimalHeader, } from './ui.js';
+import { readFileSync, existsSync } from 'fs';
+import { indexRepositoryParallel } from './embed.js';
+import { executeAskCommand } from './presentation/cli/commands/ask-command.js';
+import { executeReactCommand } from './presentation/cli/commands/react-command.js';
+import { executeSmartCommand } from './presentation/cli/commands/smart-command.js';
+import { executeFixCommand } from './presentation/cli/commands/fix-command.js';
+import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
+import { executeConfigCommand } from './presentation/cli/commands/config-command.js';
+import { executeHelpCommand } from './presentation/cli/commands/help-command.js';
+import { initLogFile, logEntry } from './log.js';
+import { performHealthCheck, formatHealthStatus, getMetrics } from './monitoring.js';
+import { refactorMultiFile, findFilesByPattern } from './refactor.js';
+import { getGitStatus, formatGitStatus, getAllGitDiffs, analyzeDiff, getGitDiff } from './git.js';
+import { executePlanCommand } from './presentation/cli/commands/plan-command.js';
+import { executeOrchestrateCommand } from './presentation/cli/commands/orchestrate-command.js';
+import { executeDocsCommand } from './presentation/cli/commands/docs-command.js';
+import { executeProductCommand } from './presentation/cli/commands/product-command.js';
+import { executeStatusCommand } from './presentation/cli/commands/status-command.js';
+import { executeSuggestCommand } from './presentation/cli/commands/suggest-command.js';
+import { executeRunCommand } from './presentation/cli/commands/run-command.js';
+import { executeModelsCommand } from './presentation/cli/commands/models-command.js';
+import { executeReviewCommand } from './presentation/cli/commands/review-command.js';
+import { executeHookCommand } from './presentation/cli/commands/hook-command.js';
+import { executeTrustCommand } from './presentation/cli/commands/trust-command.js';
+import { executeReportCommand } from './presentation/cli/commands/report-command.js';
+import { executeScanToolCommand } from './presentation/cli/commands/scan-tool-command.js';
+import { executeDecisionCommand } from './presentation/cli/commands/decision-command.js';
+import { executeCostCommand } from './presentation/cli/commands/cost-command.js';
+import { executeKnowledgeCommand } from './presentation/cli/commands/knowledge-command.js';
+import { executeLearningDashboardCommand } from './presentation/cli/commands/learning-dashboard-command.js';
+import { executeTraceCommand } from './presentation/cli/commands/trace-command.js';
+import { executeUndoCommand } from './presentation/cli/commands/undo-command.js';
+import { reviewFile, formatReview } from './review.js';
+import { formatLearningInsights, getPerformanceInsights } from './learning.js';
+import { getCacheStats, clearAllCaches } from './cache.js';
+import { planMigration, formatMigrationPlan } from './migrate.js';
+import { generateTests, getTestFilePath, saveTests, improveTests } from './testgen.js';
+import { startSession } from './session.js';
+import { cleanResponse } from './formatter.js';
+import { displayError } from './presentation/cli/error-display.js';
+import { getTelemetryService } from './infrastructure/telemetry/telemetry-service.js';
+import { colors, createSpinner, createBanner, createTable, success, error, warning, info, formatPath, formatNumber, sectionHeader, newline, createWelcomeMessage, isMinimalStyle, printMinimalHeader, requireApiKey, hasAnyApiKey, } from './ui.js';
 // Load environment variables - try agent directory first, then current directory
 try {
     const __filename = fileURLToPath(import.meta.url);
@@ -34,48 +61,25 @@ import { getVersion } from './utils/version.js';
 const program = new Command();
 program
     .name('codehere')
-    .description('AI-powered coding assistant with local embeddings and semantic search')
+    .description('AI coding agent with built-in safety')
     .version(getVersion())
     .configureHelp({
     helpWidth: 80,
     sortSubcommands: true,
-})
-    .addHelpText('beforeAll', () => {
-    return createWelcomeMessage();
 });
 // Smart routing: if query provided as argument, route intelligently
 program
     .argument('[query]', 'Your query - Codehere will understand what you need')
-    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
-    .option('--quick', 'Quick mode - work without indexing by reading files directly')
-    .option('-c, --continue', 'Continue from previous conversation (session continuity)')
-    .option('-m, --model <model>', 'Specify AI model (e.g., gpt-4, claude-3, command-r-plus, llama3)')
     .action(async (query, options) => {
     if (query && query.trim()) {
-        // Lazy load dependencies
-        const { initLogFile, logEntry } = await import('./log.js');
-        const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-        const { executeSmartCommand } = await import('./presentation/cli/commands/smart-command.js');
         // Direct query - use intelligent router
         initLogFile();
-        // Check for valid AI provider (supports Cohere, OpenAI, OpenRouter, Local, Fake)
-        const providerCheck = checkProviderConfiguration();
-        if (!providerCheck.hasValidProvider) {
-            displayProviderError(providerCheck);
-            process.exit(1);
+        if (!hasAnyApiKey()) {
+            requireApiKey();
         }
         try {
             const opts = program.opts();
-            // Set model in environment if specified
-            if (opts.model) {
-                process.env.CODEHERE_MODEL = opts.model;
-            }
-            await executeSmartCommand(query.trim(), {
-                review: opts.review || false,
-                quick: opts.quick || false,
-                continue: opts.continue || false,
-                model: opts.model,
-            });
+            await executeSmartCommand(query.trim(), { review: opts.review || false });
             logEntry({
                 timestamp: new Date().toISOString(),
                 command: 'smart',
@@ -89,25 +93,52 @@ program
         }
     }
     else if (process.stdin.isTTY) {
-        // Lazy load session
-        const { startSession } = await import('./session.js');
-        // Interactive mode - start session
-        await startSession();
+        // Check if first run — show onboarding
+        const codehereDir = join(process.env.HOME || '', '.codehere');
+        const settingsPath = join(process.env.HOME || '', '.claude', 'settings.json');
+        const hasHooks = existsSync(settingsPath) && readFileSync(settingsPath, 'utf-8').includes('codehere');
+        const hasAuditLog = existsSync(join(codehereDir, 'audit', 'hook-events.jsonl'));
+        if (!hasHooks && !hasAuditLog) {
+            // First run — onboarding
+            console.log(createWelcomeMessage());
+            newline();
+            console.log(colors.bold('Welcome! Let\'s get you set up.'));
+            newline();
+            console.log(colors.dim('  codehere works in two layers:'));
+            newline();
+            console.log(colors.bold('  Layer 0 — Safety (no API key, free, instant)'));
+            console.log(colors.dim('  Scans every AI write before it runs. Catches injections,'));
+            console.log(colors.dim('  hardcoded secrets, destructive ops, and more.'));
+            newline();
+            console.log('  → Run ' + colors.cyan('codehere hook install') + ' to activate');
+            console.log('  → Run ' + colors.cyan('codehere trust .') + ' to scan this project');
+            newline();
+            console.log(colors.bold('  Layer 1 — Intelligence (needs API key)'));
+            console.log(colors.dim('  Ask questions, fix code, plan tasks — all with AI.'));
+            console.log(colors.dim('  Works with Anthropic, OpenAI, or Ollama.'));
+            newline();
+            console.log('  → Run ' + colors.cyan('codehere setup') + ' to configure');
+            newline();
+            console.log(colors.dim('Most people start with: ') + colors.cyan('codehere hook install'));
+            newline();
+        }
+        else {
+            // Returning user — interactive session
+            await startSession();
+        }
     }
     else {
-        // Non-interactive - show help
+        // Non-interactive — show quick start
         console.log(createWelcomeMessage());
         newline();
-        console.log(colors.bold('Usage:'));
+        console.log(colors.bold('Quick start:'));
         newline();
-        console.log(colors.cyan('  codehere "<your query>"') + '     Ask anything - Codehere understands');
-        console.log(colors.cyan('  codehere') + '                    Start interactive session');
-        console.log(colors.cyan('  codehere index') + '              Build embeddings index');
+        console.log(colors.cyan('  codehere hook install') + '        Scan every AI write before it runs');
+        console.log(colors.cyan('  codehere trust .') + '            Scan your project now (no API key)');
+        console.log(colors.cyan('  codehere report') + '             Generate security audit report');
         newline();
-        console.log(colors.dim('Examples:'));
-        console.log(colors.dim('  codehere "How does authentication work?"'));
-        console.log(colors.dim('  codehere "Explain src/auth.ts"'));
-        console.log(colors.dim('  codehere "Fix src/utils.ts add error handling"'));
+        console.log(colors.bold('With an API key:'));
+        console.log(colors.cyan('  codehere "<your query>"') + '     Ask, fix, plan — routes automatically');
         newline();
         console.log(colors.dim('Run "codehere --help" for all commands'));
         newline();
@@ -118,7 +149,6 @@ program
     .description('Interactive setup wizard for first-time users')
     .option('-f, --force', 'Force reconfiguration even if already set up')
     .action(async (options) => {
-    const { executeSetupCommand } = await import('./presentation/cli/commands/setup-command.js');
     await executeSetupCommand(options.force || false);
 });
 program
@@ -128,7 +158,6 @@ program
     .argument('[key]', 'Preference key (for get/set)')
     .argument('[value]', 'Preference value (for set)')
     .action(async (action, key, value) => {
-    const { executeConfigCommand } = await import('./presentation/cli/commands/config-command.js');
     await executeConfigCommand(action, key, value);
 });
 program
@@ -140,190 +169,330 @@ program
     .option('-p, --provider <provider>', 'Filter by provider (cohere, openai, openrouter, etc.)')
     .option('--json', 'Output in JSON format')
     .action(async (options) => {
-    const { executeModelsCommand } = await import('./presentation/cli/commands/models-command.js');
-    await executeModelsCommand(options);
+    initLogFile();
+    try {
+        await executeModelsCommand({
+            list: options.list,
+            search: options.search,
+            info: options.info,
+            provider: options.provider,
+            json: options.json,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
 });
 program
-    .command('index')
-    .description('Build embeddings index for semantic search')
-    .argument('[path]', 'Path to repository (defaults to current directory)', process.cwd())
-    .option('--force', 'Force rebuild even if index exists')
-    .option('--cache', 'Use cached embeddings when available (default: true)')
-    .option('--no-cache', 'Disable caching, rebuild all embeddings')
-    .option('--concurrency <n>', 'Maximum concurrent operations (default: 5)', '5')
-    .addHelpText('after', `
-Examples:
-  $ codehere index                    # Index current directory
-  $ codehere index /path/to/repo      # Index specific path
-  $ codehere index --force            # Force rebuild
-  $ codehere index --no-cache         # Rebuild without cache
-  `)
-    .action(async (repoPath, options) => {
-    // Lazy load dependencies
-    const { initLogFile, logEntry } = await import('./log.js');
-    const { indexRepositoryParallel } = await import('./embed.js');
-    initLogFile();
-    if (isMinimalStyle()) {
-        printMinimalHeader('index', repoPath);
+    .command('telemetry')
+    .description('Manage telemetry settings (opt-in, privacy-first)')
+    .option('--enable', 'Enable telemetry')
+    .option('--disable', 'Disable telemetry')
+    .option('--status', 'Show telemetry status')
+    .action(async (options) => {
+    const telemetry = getTelemetryService();
+    if (options.enable) {
+        telemetry.enable();
+        console.log(success('Telemetry is on. Appreciate it!'));
+        console.log(colors.dim('Data is anonymized and no code/content is transmitted.'));
+        newline();
+    }
+    else if (options.disable) {
+        telemetry.disable();
+        console.log(success('Telemetry turned off.'));
+        newline();
     }
     else {
-        console.log(createBanner('Building Embeddings Index', 'Semantic search powered by AI'));
+        console.log(colors.bold('Telemetry Status:'));
+        newline();
+        console.log(telemetry.isEnabled()
+            ? success('Enabled (opt-in)')
+            : colors.dim('Disabled (set --enable to opt-in)'));
+        newline();
+        console.log(colors.dim('Telemetry helps us understand usage patterns and improve Codehere.'));
+        console.log(colors.dim('All data is anonymized. No code or content is transmitted.'));
+        console.log(colors.dim('Enable with: codehere telemetry --enable'));
         newline();
     }
+});
+program
+    .command('help')
+    .description('Show help for commands')
+    .argument('[command]', 'Command name to get help for')
+    .option('--all', 'Show all commands (including advanced)')
+    .action(async (commandName, options) => {
+    if (options?.all && !commandName) {
+        // Temporarily unhide all commands and show Commander's built-in help
+        for (const cmd of program.commands) {
+            cmd._hidden = false;
+        }
+        program.outputHelp();
+    }
+    else {
+        await executeHelpCommand(commandName);
+    }
+});
+program
+    .command('index')
+    .description('Build embeddings index of the repository')
+    .option('-r, --repo <path>', 'Repository path (default: current directory)')
+    .action(async (options) => {
+    initLogFile();
+    // Allow fake AI for testing, or require real API key
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
     try {
-        const startTime = Date.now();
+        if (isMinimalStyle()) {
+            console.log(colors.cyan('Indexing codebase...'));
+            newline();
+        }
+        else {
+            console.log(createBanner('Indexing Repository', 'Building semantic search index'));
+            newline();
+        }
+        const repoPath = options.repo || process.cwd();
         // NEW: Use parallel indexing with caching
         await indexRepositoryParallel(repoPath, {
-            useCache: options.cache !== false,
-            maxConcurrency: parseInt(options.concurrency, 10),
+            useCache: true,
+            maxConcurrency: 5,
         });
-        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
-        newline();
-        console.log(success('✓ Index built successfully'));
-        console.log(colors.dim(`  Completed in ${duration}s`));
-        newline();
-        console.log(colors.bold('Next steps:'));
-        console.log(colors.cyan('  codehere ask "your question"'));
-        console.log(colors.cyan('  codehere "explain the architecture"'));
-        newline();
         logEntry({
             timestamp: new Date().toISOString(),
             command: 'index',
             policyStatus: 'allowed',
         });
+        newline();
+        if (isMinimalStyle()) {
+            console.log(success('All indexed. Ready to go.'));
+        }
+        else {
+            console.log(success('All indexed.'));
+        }
+        process.exit(0);
     }
     catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        // Check for 401 Unauthorized errors
+        if (errorMessage.includes('401') || errorMessage.includes('Unauthorized') || errorMessage.includes('no api key')) {
+            newline();
+            console.error(error('API key rejected — looks like it might be invalid or expired.'));
+            newline();
+            console.log(colors.dim('  Check the key is set and still valid:'));
+            console.log(colors.cyan('    echo $ANTHROPIC_API_KEY') + colors.dim('   (or whichever provider you\'re using)'));
+            console.log(colors.dim('  For testing without API calls: CODEHERE_FAKE_AI=1 codehere index'));
+            newline();
+        }
+        else {
+            console.error(error('Error indexing repository:'), errorMessage);
+        }
         process.exit(1);
     }
 });
 program
     .command('ask')
-    .description('Ask a question about your codebase using semantic search')
-    .argument('<question>', 'Your question')
-    .option('-q, --quick', 'Quick mode - read files directly without using the index')
+    .description('Ask questions about your codebase using semantic search')
+    .argument('<question>', 'The question to ask about your code')
+    .alias('q')
     .addHelpText('after', `
 Examples:
   $ codehere ask "How does authentication work?"
-  $ codehere ask "Where is the user model defined?"
-  $ codehere ask "Explain the API design" --quick
+  $ codehere ask "Where is the user login function?"
+  $ codehere q "Explain the database schema"
 
 This command will:
-  1. Search your codebase using embeddings (or direct file search in --quick mode)
-  2. Find the most relevant code
-  3. Generate a comprehensive answer with context
+  • Search your indexed codebase for relevant code
+  • Use AI to generate a contextual answer
+  • Show which files were used as context
 
-Make sure to run "codehere index" first (or use --quick to bypass indexing)!
+Make sure to run "codehere index" first!
   `)
-    .action(async (question, options) => {
-    // Lazy load ALL dependencies inside action handler
-    const { initLogFile, logEntry } = await import('./log.js');
-    const { executeAskCommand } = await import('./presentation/cli/commands/ask-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
+    .action(async (question) => {
     initLogFile();
-    // Check if any valid provider is configured
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
-        process.exit(1);
+    if (!hasAnyApiKey()) {
+        requireApiKey();
     }
     try {
-        await executeAskCommand(question, { quick: options.quick || false });
+        await executeAskCommand(question);
         logEntry({
             timestamp: new Date().toISOString(),
             command: 'ask',
+            query: question,
             policyStatus: 'allowed',
         });
     }
     catch (err) {
-        const { displayError } = await import('./presentation/cli/error-display.js');
-        displayError(err instanceof Error ? err : new Error(String(err)));
+        const errMessage = err instanceof Error ? err.message : String(err);
+        // If it's a missing embeddings error, exit with 1
+        if (errMessage.includes('No embeddings found')) {
+            process.exit(1);
+        }
+        console.error(error('Error:'), errMessage);
         process.exit(1);
     }
 });
-// Additional commands with lazy loading pattern
 program
-    .command('edit')
-    .description('AI-powered code editing with security, verification, and cost tracking')
-    .argument('<file>', 'File to edit')
-    .argument('<instruction>', 'What to change or add')
-    .option('--no-verify', 'Skip compilation verification (faster, but less safe)')
-    .option('--explain', 'Show explanation of changes (learning mode)')
-    .option('--compare-providers', 'Compare results from multiple providers')
-    .option('--dry-run', 'Show proposed changes without applying')
-    .option('--show-cost', 'Display cost breakdown per operation')
+    .command('fix')
+    .description('Apply AI-generated code edits to a file')
+    .argument('[file]', 'Path to the file to edit')
+    .argument('[instruction]', 'Natural language instruction for the edit')
+    .alias('edit')
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
     .addHelpText('after', `
 Examples:
-  $ codehere edit src/auth.ts "add rate limiting"
-  $ codehere edit src/utils.ts "add error handling" --explain
-  $ codehere edit src/api.ts "optimize performance" --compare-providers
-  $ codehere edit src/config.ts "add new feature" --show-cost
-  $ codehere edit src/file.ts "quick fix" --no-verify
+  $ codehere fix src/auth.ts "Add error handling for invalid tokens"
+  $ codehere fix utils/helpers.js "Rename function foo() to bar()" --review
+  $ codehere edit app.js "Add input validation"
 
-Production-Ready Features:
-  • Enterprise security (SAST, license, bias detection)
-  • NIST AI RMF compliance (healthcare, finance, government)
-  • Policy-as-Code enforcement (automated compliance)
-  • Automatic backup and rollback on failure
-  • Multi-provider support (OpenAI, Cohere, Ollama, local)
-  • Works completely offline (privacy-first)
-  • Cost transparency (see exact costs per operation)
-  • Learning mode (understand WHY changes are made)
+This command will:
+  • Generate a unified diff using AI
+  • Apply safety policy checks
+  • Apply the changes to your file
+  • Log the operation for audit
+
+Options:
+  --review    Enable review & feedback capture (used for trust scoring and Validation Mode)
+
+Safety policies:
+  • Maximum 50 lines changed per edit
+  • Cannot edit files in restricted folders (infra/, billing/)
+  • Only one file can be edited at a time
   `)
     .action(async (file, instruction, options) => {
-    const { initLogFile, logEntry } = await import('./log.js');
-    const { executeFixCommand } = await import('./presentation/cli/commands/fix-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-    initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
+    if (!file || !instruction) {
+        newline();
+        console.log(colors.bold('Usage:') + ' codehere fix <file> "<instruction>"');
+        newline();
+        console.log('Examples:');
+        console.log(colors.cyan('  codehere fix src/auth.ts "add input validation"'));
+        console.log(colors.cyan('  codehere fix src/api.js "switch to parameterized queries"'));
+        newline();
         process.exit(1);
     }
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
     try {
-        // Pass through all options to fix-command
-        // Note: Commander.js --no-verify creates options.verify: false
-        await executeFixCommand(file, instruction, {
-            review: false,
-            noVerify: options.verify === false, // --no-verify flag
-            explain: options.explain,
-            compareProviders: options.compareProviders,
-            showCost: options.showCost,
-            dryRun: options.dryRun,
-        });
+        // Check if embeddings exist for this repository (skip check if using fake AI for testing)
+        if (process.env.CODEHERE_FAKE_AI !== '1') {
+            const { container } = await import('./application/services/dependency-container.js');
+            const embeddingRepo = container.getEmbeddingRepository(process.cwd());
+            const hasEmbeddings = await embeddingRepo.hasEmbeddings();
+            if (!hasEmbeddings) {
+                newline();
+                console.error(colors.red('No embeddings found for this repository.'));
+                newline();
+                console.log('Run:');
+                console.log(colors.cyan('  codehere index'));
+                console.log('');
+                console.log('then re-run this command.');
+                newline();
+                process.exit(1);
+            }
+        }
+        await executeFixCommand(file, instruction, { review: options?.review });
         logEntry({
             timestamp: new Date().toISOString(),
-            command: 'edit',
+            command: 'fix',
+            query: instruction,
+            filepath: file,
             policyStatus: 'allowed',
         });
     }
     catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        displayError(err, {
+            operation: 'edit',
+            query: instruction,
+            filepath: file,
+            showSuggestions: true,
+        });
         process.exit(1);
     }
 });
 program
-    .command('fix')
-    .description('AI-powered bug fixing and code improvements')
-    .argument('<file>', 'File to fix')
-    .argument('<instruction>', 'What to fix or improve')
-    .option('--dry-run', 'Show proposed changes without applying')
-    .action(async (file, instruction, options) => {
-    const { initLogFile, logEntry } = await import('./log.js');
-    const { executeFixCommand } = await import('./presentation/cli/commands/fix-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
+    .command('explain')
+    .description('Get AI explanation of a code file')
+    .argument('<file>', 'Path to the file to explain')
+    .alias('e')
+    .addHelpText('after', `
+Examples:
+  $ codehere explain src/auth.ts
+  $ codehere explain utils/helpers.js
+  $ codehere e app.js
+
+This command will:
+  • Read the file content
+  • Generate an AI explanation
+  • Show file structure, functions, and logic
+  `)
+    .action(async (file) => {
     initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
-        process.exit(1);
+    if (!hasAnyApiKey()) {
+        requireApiKey();
     }
     try {
-        await executeFixCommand(file, instruction, { review: false });
+        // Check if embeddings exist for this repository (skip check if using fake AI for testing)
+        if (process.env.CODEHERE_FAKE_AI !== '1') {
+            const { container } = await import('./application/services/dependency-container.js');
+            const embeddingRepo = container.getEmbeddingRepository(process.cwd());
+            const hasEmbeddings = await embeddingRepo.hasEmbeddings();
+            if (!hasEmbeddings) {
+                newline();
+                console.error(colors.red('No embeddings found for this repository.'));
+                newline();
+                console.log('Run:');
+                console.log(colors.cyan('  codehere index'));
+                console.log('');
+                console.log('then re-run this command.');
+                newline();
+                process.exit(1);
+            }
+        }
+        if (isMinimalStyle()) {
+            printMinimalHeader('explain', file);
+        }
+        else {
+            console.log(createBanner('Explain File', 'AI-powered code explanation'));
+            newline();
+        }
+        const fullPath = join(process.cwd(), file);
+        // Check if file exists
+        const { existsSync } = await import('fs');
+        if (!existsSync(fullPath)) {
+            newline();
+            console.error(error(`File not found: ${file}`));
+            console.log(info(`Looking for: ${fullPath}`));
+            console.log(info('Tip: Use a relative path from your current directory'));
+            newline();
+            process.exit(1);
+        }
+        // Use clean architecture
+        const { container } = await import('./application/services/dependency-container.js');
+        const useCase = container.explainFileUseCase;
+        const explainSpinner = createSpinner('Generating explanation...');
+        explainSpinner.start();
+        const result = await useCase.execute({ filepath: file });
+        explainSpinner.stop();
+        // File info
+        const lines = result.fileContent.split('\n').length;
+        const size = (result.fileContent.length / 1024).toFixed(2);
+        console.log(colors.bold('File:') + ' ' + formatPath(file));
+        console.log(colors.dim(`  Lines: ${lines} | Size: ${size} KB`));
+        newline();
+        // Display explanation with markdown formatting
+        sectionHeader('Explanation');
+        const { formatMarkdownForTerminal } = await import('./infrastructure/ux/stream-markdown.js');
+        console.log(formatMarkdownForTerminal(result.explanation));
+        newline();
         logEntry({
             timestamp: new Date().toISOString(),
-            command: 'fix',
+            command: 'explain',
+            query: `Explain ${file}`,
+            filepath: file,
             policyStatus: 'allowed',
+            retrievedFiles: [file],
         });
     }
     catch (err) {
@@ -331,39 +500,18 @@ program
         process.exit(1);
     }
 });
-program
-    .command('explain')
-    .description('Explain code or architecture in detail')
-    .argument('<path>', 'File or directory to explain')
-    .option('--depth <n>', 'Depth of explanation (1-3)', '2')
-    .action(async (path, options) => {
-    const { initLogFile } = await import('./log.js');
-    const { executeAskCommand } = await import('./presentation/cli/commands/ask-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-    initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
-        process.exit(1);
-    }
-    const depth = parseInt(options.depth, 10);
-    const question = `Explain ${path} in detail (depth: ${depth})`;
-    await executeAskCommand(question, { quick: false });
-});
 program
     .command('health')
     .description('Check system health and metrics')
     .option('-m, --metrics', 'Show detailed metrics')
-    .action(async (options) => {
-    // Lazy load to avoid WASM hang on startup
-    const { performHealthCheck, formatHealthStatus, getMetrics } = await import('./monitoring.js');
+    .action((options) => {
     const health = performHealthCheck();
     if (isMinimalStyle()) {
         printMinimalHeader('health', '');
     }
     else {
         newline();
-        console.log(createBanner('System Health', 'Enterprise monitoring'));
+        console.log(createBanner('System Health', 'Quick status check'));
         newline();
     }
     console.log(formatHealthStatus(health));
@@ -371,67 +519,45 @@ program
         newline();
         sectionHeader('Metrics');
         const metrics = getMetrics();
-        console.log(metrics);
+        const metricsTable = createTable(['Metric', 'Value'], [
+            ['Total Operations', formatNumber(metrics.operations.total)],
+            ['Successful', formatNumber(metrics.operations.successful)],
+            ['Failed', formatNumber(metrics.operations.failed)],
+            ['Retries', formatNumber(metrics.operations.retries)],
+            ['Avg Response Time', `${metrics.performance.avgResponseTime.toFixed(2)}ms`],
+            ['API Calls', formatNumber(metrics.performance.apiCalls)],
+            ['Cache Hits', formatNumber(metrics.performance.cacheHits)],
+        ]);
+        console.log(metricsTable.toString());
+        if (Object.keys(metrics.errors.byType).length > 0) {
+            newline();
+            sectionHeader('Error Summary');
+            const errorTable = createTable(['Error Type', 'Count'], Object.entries(metrics.errors.byType).map(([type, count]) => [
+                type,
+                formatNumber(count),
+            ]));
+            console.log(errorTable.toString());
+        }
     }
     newline();
-});
-program
-    .command('plan')
-    .description('Plan and break down complex coding tasks')
-    .argument('<goal>', 'Goal or task to plan')
-    .option('--review', 'Enable review mode for plan validation')
-    .action(async (goal, options) => {
-    const { initLogFile } = await import('./log.js');
-    const { executePlanCommand } = await import('./presentation/cli/commands/plan-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-    initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
-        process.exit(1);
-    }
-    await executePlanCommand(goal, { review: options.review || false });
-});
-program
-    .command('orchestrate')
-    .description('Multi-agent orchestration for complex projects')
-    .argument('<goal>', 'Project goal')
-    .option('--agents <n>', 'Number of agents', '3')
-    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
-    .action(async (goal, options) => {
-    const { initLogFile } = await import('./log.js');
-    const { executeOrchestrateCommand } = await import('./presentation/cli/commands/orchestrate-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-    initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
+    if (health.status === 'unhealthy') {
         process.exit(1);
     }
-    await executeOrchestrateCommand(goal, {
-        review: options.review || false,
-    });
 });
-// Remaining commands follow the same lazy loading pattern
 program
     .command('refactor')
-    .description('Multi-file refactoring with AI guidance')
-    .argument('<pattern>', 'File pattern (e.g., src/**/*.ts or file1.ts,file2.ts)')
+    .description('Refactor multiple files with coordinated changes')
+    .argument('<pattern>', 'File pattern (e.g., "src/**/*.ts") or comma-separated files')
     .argument('<instruction>', 'Refactoring instruction')
-    .option('--max-files <n>', 'Maximum files to refactor (default: 10)', '10')
-    .option('--dry-run', 'Show proposed changes without applying')
+    .option('--dry-run', 'Show changes without applying')
+    .option('--max-files <number>', 'Maximum files to process', '10')
     .action(async (pattern, instruction, options) => {
-    const { initLogFile } = await import('./log.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
-    const { refactorMultiFile, findFilesByPattern } = await import('./refactor.js');
     initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
-        process.exit(1);
+    if (!hasAnyApiKey()) {
+        requireApiKey();
     }
     try {
-        console.log(createBanner('Multi-File Refactor', 'Enterprise-grade cross-file operations'));
+        console.log(createBanner('Multi-File Refactor', 'Coordinated changes across files'));
         newline();
         // Parse files from pattern
         let files;
@@ -456,34 +582,948 @@ program
         const maxFiles = parseInt(options.maxFiles || '10', 10);
         const result = await refactorMultiFile(files.slice(0, maxFiles), instruction, {
             dryRun: options.dryRun || false,
+            maxFiles,
+        });
+        // Display results
+        sectionHeader('Refactoring Results');
+        const resultsTable = createTable(['Metric', 'Value'], [
+            ['Files Processed', formatNumber(files.length)],
+            ['Files Changed', formatNumber(result.filesChanged.length)],
+            ['Total Lines Added', formatNumber(result.totalChanges.linesAdded)],
+            ['Total Lines Removed', formatNumber(result.totalChanges.linesRemoved)],
+            ['Errors', formatNumber(result.errors.length)],
+        ]);
+        console.log(resultsTable.toString());
+        if (result.errors.length > 0) {
+            newline();
+            sectionHeader('Errors');
+            result.errors.forEach(err => {
+                console.log(error(`${err.file}: ${err.error}`));
+            });
+        }
+        if (result.filesChanged.length > 0) {
+            newline();
+            console.log(success(options.dryRun ? 'Refactor planned.' : 'Refactoring done.'));
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('git-review')
+    .description('Review git changes and suggest improvements')
+    .option('-f, --file <file>', 'Review specific file')
+    .action((options) => {
+    initLogFile();
+    try {
+        console.log(createBanner('Git Review', 'Git-aware code analysis'));
+        newline();
+        const status = getGitStatus();
+        if (!status.isRepo) {
+            console.log(warning('Not a git repository'));
+            return;
+        }
+        console.log(formatGitStatus(status));
+        newline();
+        if (!status.hasChanges) {
+            console.log(info('No changes to review'));
+            return;
+        }
+        // Get diffs
+        const diffs = options.file
+            ? (() => {
+                const diff = getGitDiff(options.file);
+                return diff ? new Map([[options.file, diff]]) : new Map();
+            })()
+            : getAllGitDiffs();
+        if (diffs.size === 0) {
+            console.log(info('No diffs found'));
+            return;
+        }
+        sectionHeader('Change Analysis');
+        for (const [file, diff] of diffs.entries()) {
+            const analysis = analyzeDiff(diff);
+            console.log(colors.bold(file));
+            console.log(colors.dim(`  ${analysis.summary}`));
+            console.log(colors.dim(`  Risk: ${analysis.riskLevel.toUpperCase()}`));
+            if (analysis.suggestions.length > 0) {
+                console.log(colors.yellow('  Suggestions:'));
+                analysis.suggestions.forEach(s => {
+                    console.log(colors.yellow(`    - ${s}`));
+                });
+            }
+            newline();
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('plan')
+    .description('Plan a complex multi-step task')
+    .argument('<instruction>', 'Complex instruction to plan')
+    .option('-e, --execute', 'Execute the plan after creating it')
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
+    .action(async (instruction, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        if (isMinimalStyle()) {
+            printMinimalHeader('plan', instruction);
+        }
+        else {
+            console.log(createBanner('Task Planning', 'Intelligent multi-step execution'));
+            newline();
+            console.log(colors.bold('Instruction:') + ' ' + colors.cyan(instruction));
+        }
+        newline();
+        // Use new memory-based planning
+        await executePlanCommand(instruction, { execute: options.execute, review: options.review });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('decision')
+    .description('Record and query architectural/design decisions')
+    .argument('<action>', 'Action: record, list, query, or explain')
+    .argument('[args...]', 'Arguments for the action')
+    .option('-c, --codebase <path>', 'Codebase path (default: current directory)')
+    .option('-t, --type <type>', 'Decision type filter (for list)')
+    .option('-l, --limit <number>', 'Limit number of results', '10')
+    .action(async (action, args, options) => {
+    initLogFile();
+    try {
+        await executeDecisionCommand(action, args, {
+            codebase: options.codebase,
+            type: options.type,
+            limit: options.limit ? parseInt(options.limit, 10) : undefined,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('knowledge')
+    .description('Query and manage preserved knowledge from codebase')
+    .argument('<action>', 'Action: query, list, summary, or extract')
+    .argument('[args...]', 'Arguments for the action')
+    .option('-c, --codebase <path>', 'Codebase path (default: current directory)')
+    .option('-t, --type <type>', 'Knowledge type filter (for list)')
+    .option('--tags <tags>', 'Comma-separated tags (for list)')
+    .option('-l, --limit <number>', 'Limit number of results', '10')
+    .action(async (action, args, options) => {
+    initLogFile();
+    try {
+        await executeKnowledgeCommand(action, args, {
+            codebase: options.codebase,
+            type: options.type,
+            tags: options.tags ? options.tags.split(',') : undefined,
+            limit: options.limit ? parseInt(options.limit, 10) : undefined,
         });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('learning')
+    .description('Learning dashboard - View patterns, knowledge, and insights')
+    .argument('<action>', 'Action: overview, patterns, knowledge, or insights')
+    .option('-c, --codebase <path>', 'Codebase path (default: current directory)')
+    .action(async (action, options) => {
+    initLogFile();
+    try {
+        await executeLearningDashboardCommand(action, options.codebase);
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('review-file')
+    .description('Automated code review for a file')
+    .argument('<file>', 'File to review')
+    .action(async (file) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        if (isMinimalStyle()) {
+            console.log(colors.bold(`Review: ${file}`));
+            newline();
+        }
+        else {
+            console.log(createBanner('Code Review', 'Automated senior-level analysis'));
+            newline();
+        }
+        const reviewSpinner = createSpinner('Reviewing code...');
+        reviewSpinner.start();
+        const review = await reviewFile(file);
+        reviewSpinner.stop();
+        newline();
+        if (isMinimalStyle()) {
+            console.log(colors.bold('Findings:'));
+            console.log(formatReview(review));
+            newline();
+            console.log(colors.dim(`Score: ${review.score}/100`));
+        }
+        else {
+            console.log(formatReview(review));
+            // Display score
+            newline();
+            sectionHeader('Review Score');
+            const scoreTable = createTable(['Metric', 'Value'], [
+                ['Overall Score', `${review.score}/100`],
+                ['Errors', formatNumber(review.issues.filter(i => i.severity === 'error').length)],
+                ['Warnings', formatNumber(review.issues.filter(i => i.severity === 'warning').length)],
+                ['Info', formatNumber(review.issues.filter(i => i.severity === 'info').length)],
+            ]);
+            console.log(scoreTable.toString());
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('learn')
+    .description('Show learning insights and performance recommendations')
+    .action(() => {
+    try {
+        console.log(createBanner('Learning Insights', 'What we\'ve learned from your codebase'));
+        newline();
+        const insights = formatLearningInsights();
+        console.log(insights);
+        const perfInsights = getPerformanceInsights();
+        if (perfInsights.recommendations.length > 0) {
+            sectionHeader('Performance Recommendations');
+            perfInsights.recommendations.forEach(rec => {
+                console.log(info(rec));
+            });
+        }
+        const cacheStats = getCacheStats();
         newline();
-        console.log(success('✓ Refactoring complete'));
-        console.log(result);
+        sectionHeader('Cache Statistics');
+        const cacheTable = createTable(['Metric', 'Value'], [
+            ['Memory Cache', `${cacheStats.memorySize}/${cacheStats.memoryMaxSize}`],
+            ['File Cache', formatNumber(cacheStats.fileCacheCount)],
+        ]);
+        console.log(cacheTable.toString());
     }
     catch (err) {
         console.error(error('Error:'), err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
 });
+program
+    .command('cache')
+    .description('Manage cache')
+    .option('--clear', 'Clear all caches')
+    .option('--stats', 'Show cache statistics')
+    .action((options) => {
+    if (options.clear) {
+        clearAllCaches();
+        console.log(success('All caches cleared'));
+    }
+    else if (options.stats) {
+        const stats = getCacheStats();
+        sectionHeader('Cache Statistics');
+        const cacheTable = createTable(['Metric', 'Value'], [
+            ['Memory Cache', `${stats.memorySize}/${stats.memoryMaxSize}`],
+            ['File Cache', formatNumber(stats.fileCacheCount)],
+        ]);
+        console.log(cacheTable.toString());
+    }
+    else {
+        console.log(info('Use --clear to clear caches or --stats to show statistics'));
+    }
+});
+program
+    .command('migrate')
+    .description('Plan and execute framework migrations')
+    .argument('<from>', 'Source framework/version')
+    .argument('<to>', 'Target framework/version')
+    .option('-f, --files <files...>', 'Specific files to migrate')
+    .option('--plan-only', 'Only show migration plan, do not execute')
+    .action(async (from, to, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        console.log(createBanner('Migration Assistant', `From ${from} to ${to}`));
+        newline();
+        const plan = await planMigration(from, to, options.files);
+        sectionHeader('Migration Plan');
+        console.log(formatMigrationPlan(plan));
+        if (!options.planOnly) {
+            newline();
+            console.log(info('Migration execution coming soon...'));
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// DocumentationAgent-based docs command
+program
+    .command('docs')
+    .description('Generate documentation using DocumentationAgent')
+    .argument('<generate>', 'Command: generate')
+    .argument('<type>', 'Documentation type: readme, api, or all')
+    .option('--target <dir>', 'Target directory for API docs (default: src)')
+    .option('--update-existing', 'Update existing documentation files')
+    .option('--output <path>', 'Output path for generated docs')
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
+    .addHelpText('after', `
+Examples:
+  $ codehere docs generate readme
+  $ codehere docs generate api --target src
+  $ codehere docs generate all --update-existing
+  $ codehere docs generate readme --review
+
+Warning: This command may modify README.md and docs/api.md files.
+  `)
+    .action(async (cmd, type, options) => {
+    if (cmd !== 'generate') {
+        console.error(error(`Unknown command: ${cmd}. Use 'generate' to create documentation.`));
+        process.exit(1);
+    }
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    initLogFile();
+    await executeDocsCommand(type, {
+        target: options.target,
+        updateExisting: options.updateExisting,
+        outputPath: options.output,
+        review: Boolean(options.review),
+    });
+});
+// Product brain command — project context for context-aware recommendations
+program
+    .command('product')
+    .description('Set up product brain — helps trust and report give context-aware recommendations')
+    .argument('[subcommand]', 'init | show | set | spec', 'show')
+    .argument('[goal]', 'Goal or description (used with spec subcommand)')
+    .option('--risk <level>', 'Set risk level: low, medium, high, critical')
+    .option('--name <name>', 'Update project name')
+    .option('--production', 'Mark as production app')
+    .option('--force', 'Re-run init even if already configured')
+    .addHelpText('after', `
+Examples:
+  $ codehere product init          # interactive setup (2 minutes)
+  $ codehere product show          # display current config
+  $ codehere product set --risk high
+  `)
+    .action(async (subcommand, goal, options) => {
+    await executeProductCommand(subcommand, {
+        risk: options.risk,
+        production: options.production,
+        name: goal || options.name,
+        force: options.force,
+    });
+});
+// Status command
+program
+    .command('status')
+    .description('Security dashboard — hook activity, blocked calls, cost routing')
+    .option('--json', 'Machine-readable JSON')
+    .option('--tasks', 'Show recent tasks (experimental)')
+    .option('--sessions', 'Show per-session audit trail (multi-agent analysis)')
+    .option('--session <id>', 'Drill into a specific session (first 8+ chars of session ID)')
+    .option('--trust', 'Include a quick trust scan of the current directory')
+    .option('--env', 'Show environment details')
+    .option('--track', 'Show command success rates')
+    .addHelpText('after', `
+Examples:
+  $ codehere status                    # full dashboard
+  $ codehere status --sessions         # show per-session breakdown
+  $ codehere status --session abc12345 # drill into a specific session
+  $ codehere status --json             # machine-readable output
+  `)
+    .action(async (options) => {
+    await executeStatusCommand({
+        json: Boolean(options.json),
+        tasks: Boolean(options.tasks),
+        sessions: Boolean(options.sessions),
+        session: options.session,
+        trust: Boolean(options.trust),
+        env: Boolean(options.env),
+        track: Boolean(options.track),
+    });
+});
 // Suggest command - Read-only assistant mode
 program
     .command('suggest')
     .description('Read-only assistant mode - ask questions and get explanations without making changes')
-    .argument('<question>', 'Your question')
-    .option('-q, --quick', 'Quick mode - bypass indexing')
-    .action(async (question, options) => {
-    const { initLogFile } = await import('./log.js');
-    const { executeSuggestCommand } = await import('./presentation/cli/commands/suggest-command.js');
-    const { checkProviderConfiguration, displayProviderError } = await import('./utils/provider-check.js');
+    .argument('<query>', 'The question or request')
+    .option('--file <file>', 'Focus on a specific file')
+    .addHelpText('after', `
+Examples:
+  $ codehere suggest "How does authentication work?"
+  $ codehere suggest "Explain this function" --file src/auth.ts
+
+This command:
+  • Searches your codebase for relevant code
+  • Provides contextual answers and explanations
+  • Does NOT make any changes (read-only mode)
+  • Creates a task record for tracking
+  `)
+    .action(async (query, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        await executeSuggestCommand(query, {
+            file: options.file,
+            stream: false,
+        });
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'suggest',
+            query,
+            policyStatus: 'allowed',
+        });
+    }
+    catch (err) {
+        const errMessage = err instanceof Error ? err.message : String(err);
+        // If it's a missing embeddings error, exit with 1 (message already shown)
+        if (errMessage.includes('No embeddings found')) {
+            process.exit(1);
+        }
+        console.error(error('Error:'), errMessage);
+        process.exit(1);
+    }
+});
+// Run command - Unified agentic execution
+program
+    .command('run')
+    .description('Unified agentic execution - execute a task or goal')
+    .argument('<goal>', 'The goal to execute')
+    .option('--task-id <id>', 'Continue execution of an existing task')
+    .option('--file <file>', 'Focus on a specific file')
+    .option('--files <files>', 'Comma-separated list of files to process')
+    .option('--review', 'Enable review before applying changes')
+    .addHelpText('after', `
+Examples:
+  $ codehere run "Add error handling to the login function"
+  $ codehere run "Refactor authentication module" --file src/auth.ts
+  $ codehere run "Fix bug in payment processing" --task-id task-12345
+
+This command:
+  • Creates a plan for the goal
+  • Executes the plan step-by-step
+  • Creates/updates task records for tracking
+  • Shows risk tier and environment mode (advisory)
+  `)
+    .action(async (goal, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        const files = options.files ? options.files.split(',').map((f) => f.trim()) : undefined;
+        await executeRunCommand(goal, {
+            taskId: options.taskId,
+            file: options.file,
+            files,
+            review: Boolean(options.review),
+        });
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'run',
+            query: goal,
+            policyStatus: 'allowed',
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// Review command - Task review interface
+program
+    .command('review')
+    .description('Review and approve/reject tasks')
+    .argument('[task-id]', 'Task ID to review (omit to list tasks)')
+    .option('--list', 'List tasks needing review')
+    .option('--approve', 'Approve the task')
+    .option('--reject', 'Reject the task')
+    .option('--comment <text>', 'Add a comment to the review')
+    .option('--all', 'Show all completed tasks in list mode')
+    .addHelpText('after', `
+Examples:
+  $ codehere review --list
+  $ codehere review task-12345
+  $ codehere review task-12345 --approve
+  $ codehere review task-12345 --reject --comment "Security concerns"
+
+This command:
+  • Lists tasks that need review
+  • Shows task details (files changed, risk tier, etc.)
+  • Allows approving or rejecting tasks
+  • Updates task status and review records
+  `)
+    .action(async (taskId, options) => {
+    initLogFile();
+    try {
+        await executeReviewCommand(taskId, {
+            list: Boolean(options.list),
+            approve: Boolean(options.approve),
+            reject: Boolean(options.reject),
+            comment: options.comment,
+            all: Boolean(options.all),
+        });
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'review',
+            query: taskId,
+            policyStatus: 'allowed',
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('test')
+    .description('Generate tests for code')
+    .argument('<file>', 'File to generate tests for')
+    .option('--framework <framework>', 'Test framework (jest, pytest, etc.)')
+    .option('--coverage <type>', 'Coverage type (unit, integration, both)', 'unit')
+    .option('--improve', 'Improve existing test file')
+    .option('--save', 'Save tests to file')
+    .action(async (file, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        console.log(createBanner('Test Generator', 'Comprehensive test generation'));
+        newline();
+        const testSpinner = createSpinner('Generating tests...');
+        testSpinner.start();
+        let tests;
+        if (options.improve) {
+            tests = await improveTests(file);
+        }
+        else {
+            tests = await generateTests(file, {
+                framework: options.framework,
+                coverage: options.coverage,
+            });
+        }
+        testSpinner.stop();
+        newline();
+        sectionHeader('Generated Tests');
+        const formattedTests = cleanResponse(tests);
+        console.log(formattedTests);
+        if (options.save) {
+            const testPath = options.improve ? file : getTestFilePath(file, options.framework);
+            saveTests(testPath, tests);
+            console.log(success(`Tests saved to ${testPath}`));
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('react')
+    .description('Execute query using ReAct loop (iterative reasoning with tools)')
+    .argument('<query>', 'The query to process with ReAct reasoning')
+    .addHelpText('after', `
+Examples:
+  $ codehere react "How does authentication work in this codebase?"
+  $ codehere react "Find and explain the user login function"
+  $ codehere react "What files handle API requests?"
+
+This command uses ReAct (Reasoning + Acting) pattern:
+  • Generates thoughts about the problem
+  • Takes actions (uses tools, searches code)
+  • Observes results
+  • Iterates until solution found
+  • Learns from memory of past experiences
+  `)
+    .action(async (query) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        await executeReactCommand(query);
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'react',
+            query: query,
+            policyStatus: 'allowed',
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('orchestrate')
+    .description('Orchestrate multi-agent workflows (plan, execute, validate)')
+    .argument('<goal>', 'The goal to orchestrate')
+    .option('-m, --mode <mode>', 'Orchestration mode: plan-only, execute-only, or full', 'full')
+    .option('-p, --plan-id <planId>', 'Load and execute a previously saved plan by ID')
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
+    .action(async (goal, options) => {
+    initLogFile();
+    if (!hasAnyApiKey()) {
+        requireApiKey();
+    }
+    try {
+        await executeOrchestrateCommand(goal, {
+            mode: options.mode,
+            planId: options.planId,
+            review: options.review,
+        });
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'orchestrate',
+            query: goal,
+            policyStatus: 'allowed',
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('trace')
+    .description('View execution traces and reproduce runs')
+    .argument('<action>', 'Action: list, show, or reproduce')
+    .argument('[runId]', 'Run ID (required for show/reproduce)')
+    .action(async (action, runId) => {
     initLogFile();
-    const providerCheck = checkProviderConfiguration();
-    if (!providerCheck.hasValidProvider) {
-        displayProviderError(providerCheck);
+    try {
+        if (action === 'list') {
+            await executeTraceCommand('list');
+        }
+        else if (action === 'show') {
+            if (!runId) {
+                console.error(error('Run ID is required for "show" action'));
+                console.log(info('Usage: codehere trace show <runId>'));
+                process.exit(1);
+            }
+            await executeTraceCommand('show', runId);
+        }
+        else if (action === 'reproduce') {
+            if (!runId) {
+                console.error(error('Run ID is required for "reproduce" action'));
+                console.log(info('Usage: codehere trace reproduce <runId>'));
+                process.exit(1);
+            }
+            await executeTraceCommand('reproduce', runId);
+        }
+        else {
+            console.error(error(`Unknown action: ${action}`));
+            console.log(info('Available actions: list, show, reproduce'));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
-    await executeSuggestCommand(question, {});
 });
-// Parse and execute
+program
+    .command('undo')
+    .description('Undo file changes by restoring from backups')
+    .argument('<action>', 'Action: undo, list, restore')
+    .argument('[filepath]', 'File path (required for undo/list)')
+    .argument('[backupPath]', 'Backup path (required for restore)')
+    .addHelpText('after', `
+Examples:
+  $ codehere undo undo src/file.ts
+  $ codehere undo list src/file.ts
+  $ codehere undo restore src/file.ts .codehere/backups/file.ts.2024-12-30.backup
+
+Actions:
+  undo    - Restore file from most recent backup
+  list    - List all available backups for a file
+  restore - Restore file from a specific backup path
+  `)
+    .action(async (action, filepath, backupPath) => {
+    initLogFile();
+    try {
+        await executeUndoCommand(action, filepath, backupPath);
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── trust ─────────────────────────────────────────────────────────────────────
+program
+    .command('trust')
+    .description('Layer 0 trust score — instant static analysis, zero API calls')
+    .argument('[target]', 'File, directory, or omit to scan current directory')
+    .option('--diff [ref]', 'Score a git diff (default: HEAD)')
+    .option('--badge', 'Output shield badge markdown')
+    .option('--json', 'Output JSON report')
+    .option('--verbose', 'Show all findings with line numbers')
+    .option('--ci', 'CI mode: exit 1 if score < 60')
+    .action(async (target, options) => {
+    try {
+        await executeTrustCommand(target, {
+            diff: options?.diff === true ? 'HEAD' : options?.diff,
+            badge: options?.badge,
+            json: options?.json,
+            verbose: options?.verbose,
+            ci: options?.ci,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── report ────────────────────────────────────────────────────────────────────
+program
+    .command('report')
+    .description('Generate a shareable security audit report — narrative, not just a score')
+    .argument('[target]', 'File or directory to audit (default: current directory)')
+    .option('--out <file>', 'Write report to a file (default: print to stdout)')
+    .option('--json', 'Output machine-readable JSON instead of markdown')
+    .option('--simple', 'Plain English output — no jargon, for non-technical stakeholders')
+    .addHelpText('after', `
+Examples:
+  $ codehere report                     # audit current dir, print markdown
+  $ codehere report src/               # audit a subdirectory
+  $ codehere report --out report.md    # write to file
+  $ codehere report > report.md        # pipe to file
+  $ codehere report --json             # machine-readable output
+  $ codehere report --simple           # plain English for non-technical stakeholders
+
+The report is a markdown document you can:
+  • Paste directly into a PR description
+  • Commit as a security audit artifact
+  • Include the badge in your README
+  `)
+    .action(async (target, options) => {
+    try {
+        await executeReportCommand(target, {
+            out: options?.out,
+            json: options?.json,
+            simple: options?.simple,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── hook ──────────────────────────────────────────────────────────────────────
+program
+    .command('hook')
+    .description('Manage Claude Agent SDK hook integration (intercepts all tool calls)')
+    .argument('[subcommand]', 'install | uninstall | status | log')
+    .option('--log-only', 'Log events but never block (audit mode)')
+    .option('--block-mode <level>', 'Block threshold: critical (default), high, all')
+    .option('--tail <n>', 'Lines to show in log mode', '20')
+    .option('--debug', 'Verbose debug output')
+    .action(async (subcommand, options) => {
+    try {
+        await executeHookCommand(subcommand, {
+            logOnly: options?.logOnly,
+            blockMode: options?.blockMode,
+            tail: options?.tail ? parseInt(options.tail, 10) : undefined,
+            debug: options?.debug,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── serve (MCP server) ───────────────────────────────────────────────────────
+program
+    .command('serve')
+    .description('Start codehere as an MCP server — expose trust tools to Claude Desktop, Cursor, and any MCP client')
+    .option('-p, --port <number>', 'Port to listen on', '3773')
+    .option('--host <host>', 'Host to bind to (default: 127.0.0.1)', '127.0.0.1')
+    .option('--token <token>', 'Require Bearer token for authentication')
+    .option('--show-config', 'Print the MCP config block to add to Claude Desktop / Cursor settings')
+    .action(async (options) => {
+    const port = parseInt(options?.port ?? '3773', 10);
+    const host = options?.host ?? '127.0.0.1';
+    const token = options?.token;
+    if (options?.showConfig) {
+        const config = {
+            mcpServers: {
+                codehere: {
+                    url: `http://${host}:${port}/mcp`,
+                    ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}),
+                },
+            },
+        };
+        console.log('\nAdd to Claude Desktop or Cursor MCP settings:\n');
+        console.log(JSON.stringify(config, null, 2));
+        newline();
+        console.log(colors.dim('Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json'));
+        console.log(colors.dim('Cursor: Settings > MCP Servers'));
+        newline();
+        return;
+    }
+    try {
+        const { startMCPServer } = await import('./infrastructure/protocols/mcp-server-impl.js');
+        const server = startMCPServer({ port, host, token });
+        newline();
+        console.log(success(`codehere MCP server running`));
+        newline();
+        console.log(colors.bold('Endpoint:') + `  http://${host}:${port}/mcp`);
+        console.log(colors.bold('Health:') + `    http://${host}:${port}/health`);
+        newline();
+        console.log(colors.bold('Tools available:'));
+        console.log('  codehere_trust   — score a file or snippet (0-100, no API)');
+        console.log('  codehere_scan    — scan text for injection/threats');
+        console.log('  codehere_review  — scan a directory, return riskiest files');
+        console.log('  codehere_audit   — read hook audit log');
+        newline();
+        console.log(colors.dim('  Run with --show-config to get the MCP client config block'));
+        console.log(colors.dim('  Press Ctrl+C to stop'));
+        newline();
+        // Keep alive
+        process.on('SIGINT', () => {
+            server.close();
+            console.log(colors.dim('\ncodehere MCP server stopped'));
+            process.exit(0);
+        });
+        await new Promise((resolve) => {
+            server.on('close', resolve);
+        });
+    }
+    catch (err) {
+        console.error(error('Failed to start server:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── scan-tool (called by Claude Code hooks system, not users) ─────────────────
+program
+    .command('scan-tool')
+    .description('Hook handler: reads Claude Code tool event from stdin, outputs block/allow (used by hook system)')
+    .option('--log-only', 'Never block, log only')
+    .option('--block-all', 'Block on any finding, not just critical')
+    .option('--debug', 'Debug output')
+    .action(async (options) => {
+    await executeScanToolCommand({
+        logOnly: options?.logOnly,
+        blockAll: options?.blockAll,
+        debug: options?.debug,
+    });
+});
+// Add completion command
+program
+    .command('completion')
+    .description('Generate shell completion script')
+    .argument('<shell>', 'Shell type: bash, zsh, or fish')
+    .action(async (shell) => {
+    try {
+        switch (shell.toLowerCase()) {
+            case 'bash': {
+                const { generateBashCompletion } = await import('./infrastructure/completion/bash-completion.js');
+                console.log(generateBashCompletion());
+                break;
+            }
+            case 'zsh': {
+                const { generateZshCompletion } = await import('./infrastructure/completion/zsh-completion.js');
+                console.log(generateZshCompletion());
+                break;
+            }
+            case 'fish': {
+                const { generateFishCompletion } = await import('./infrastructure/completion/fish-completion.js');
+                console.log(generateFishCompletion());
+                break;
+            }
+            default:
+                console.error(error(`Unsupported shell: ${shell}`));
+                console.log(info('Supported shells: bash, zsh, fish'));
+                console.log(info('Usage: codehere completion <bash|zsh|fish>'));
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        displayError(err, {
+            operation: 'completion',
+            showSuggestions: true,
+        });
+        process.exit(1);
+    }
+});
+program
+    .command('cost')
+    .description('View API cost tracking and budget status')
+    .argument('[action]', 'Action: status, summary, reset (default: status)')
+    .argument('[run-id]', 'Run ID for detailed breakdown')
+    .action(async (action, runId) => {
+    try {
+        await executeCostCommand(action || 'status', runId);
+    }
+    catch (err) {
+        displayError(err, { operation: 'cost', showSuggestions: true });
+        process.exit(1);
+    }
+});
+// Initialize telemetry and track command
+const telemetry = getTelemetryService();
+// Track command usage (if enabled)
+const commandName = process.argv[2] || 'default';
+if (commandName !== 'telemetry') {
+    telemetry.trackCommand(commandName);
+}
+// Check for first run (install tracking)
+const codebaseRoot = process.cwd();
+const codehereDir = join(codebaseRoot, '.codehere');
+if (!existsSync(codehereDir)) {
+    // First run - track install
+    telemetry.track('install', {
+        version: process.env.npm_package_version || 'unknown',
+        os: process.platform,
+        nodeVersion: process.version,
+    });
+}
+// Slash command routing: `codehere /ask "..."` → `codehere ask "..."`
+// Hide non-core commands from default --help (still usable, shown via `help --all`)
+const CORE_COMMANDS = new Set([
+    'setup', 'index', 'ask', 'fix', 'explain', 'health',
+    'status', 'plan', 'trust', 'report', 'hook', 'serve', 'help',
+]);
+for (const cmd of program.commands) {
+    if (!CORE_COMMANDS.has(cmd.name())) {
+        cmd._hidden = true;
+    }
+}
+// Lets users use slash-prefixed commands from the terminal (like Claude Code's /commands)
+const rawArgs = process.argv.slice(2);
+if (rawArgs.length > 0 && rawArgs[0].startsWith('/') && rawArgs[0].length > 1) {
+    const stripped = rawArgs[0].slice(1); // remove leading /
+    process.argv.splice(2, 1, stripped); // replace /cmd with cmd in-place
+}
 program.parse();
 //# sourceMappingURL=index.js.map