codehere 0.3.0 → 0.5.0-alpha.0

package/dist/index.js

@@ -4,10 +4,10 @@ import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { indexRepositoryParallel } from './embed.js';
-import { generateAndApplyEdit } from './edit.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';
@@ -17,6 +17,13 @@ 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 { executeDecisionCommand } from './presentation/cli/commands/decision-command.js';
 import { executeKnowledgeCommand } from './presentation/cli/commands/knowledge-command.js';
 import { executeLearningDashboardCommand } from './presentation/cli/commands/learning-dashboard-command.js';
@@ -26,12 +33,11 @@ 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 { generateFileDocs, generateREADME, updateDocs, saveDocs } from './docs.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 { colors, createSpinner, createBanner, createTable, success, error, warning, info, formatPath, formatNumber, sectionHeader, newline, statusIndicator, createWelcomeMessage, } from './ui.js';
+import { colors, createSpinner, createBanner, createTable, success, error, warning, info, formatPath, formatNumber, sectionHeader, newline, createWelcomeMessage, isMinimalStyle, printMinimalHeader, } from './ui.js';
 // Load environment variables - try agent directory first, then current directory
 try {
     const __filename = fileURLToPath(import.meta.url);
@@ -60,7 +66,8 @@ program
 // Smart routing: if query provided as argument, route intelligently
 program
     .argument('[query]', 'Your query - Codehere will understand what you need')
-    .action(async (query) => {
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
+    .action(async (query, options) => {
     if (query && query.trim()) {
         // Direct query - use intelligent router
         initLogFile();
@@ -77,7 +84,8 @@ program
             process.exit(1);
         }
         try {
-            await executeSmartCommand(query.trim());
+            const opts = program.opts();
+            await executeSmartCommand(query.trim(), { review: opts.review || false });
             logEntry({
                 timestamp: new Date().toISOString(),
                 command: 'smart',
@@ -129,6 +137,30 @@ program
     .action(async (action, key, value) => {
     await executeConfigCommand(action, key, value);
 });
+program
+    .command('models')
+    .description('List, search, and get info about available AI models')
+    .option('-l, --list', 'List all available models')
+    .option('-s, --search <query>', 'Search models by name or ID')
+    .option('-i, --info <model-id>', 'Get detailed info about a specific model')
+    .option('-p, --provider <provider>', 'Filter by provider (cohere, openai, openrouter, etc.)')
+    .option('--json', 'Output in JSON format')
+    .action(async (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('help')
     .description('Show help for commands')
@@ -142,7 +174,8 @@ program
     .option('-r, --repo <path>', 'Repository path (default: current directory)')
     .action(async (options) => {
     initLogFile();
-    if (!process.env.COHERE_API_KEY) {
+    // Allow fake AI for testing, or require real API key
+    if (!process.env.COHERE_API_KEY && process.env.CODEHERE_FAKE_AI !== '1') {
         newline();
         console.error(error('COHERE_API_KEY not found in environment'));
         newline();
@@ -151,12 +184,20 @@ program
         console.log('  2. Create a .env file in your project root:');
         console.log(colors.cyan('     echo "COHERE_API_KEY=your_key_here" > .env'));
         console.log('  3. Run the command again');
+        console.log('');
+        console.log(colors.dim('Note: For testing without API calls, set CODEHERE_FAKE_AI=1'));
         newline();
         process.exit(1);
     }
     try {
-        console.log(createBanner('Indexing Repository', 'Building semantic search index'));
-        newline();
+        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, {
@@ -169,10 +210,32 @@ program
             policyStatus: 'allowed',
         });
         newline();
-        console.log(success('Indexing complete!'));
+        if (isMinimalStyle()) {
+            console.log(success('Indexing complete. Cache written to .codehere-cache/'));
+        }
+        else {
+            console.log(success('Indexing complete!'));
+        }
+        process.exit(0);
     }
     catch (err) {
-        console.error(error('Error indexing repository:'), 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('Authentication failed: Invalid or missing API key'));
+            newline();
+            console.log(colors.bold('Troubleshooting:'));
+            console.log('  1. Verify your COHERE_API_KEY is set correctly:');
+            console.log(colors.cyan('     echo $COHERE_API_KEY'));
+            console.log('  2. Check if the key is valid at: https://dashboard.cohere.com/api-keys');
+            console.log('  3. If using a .env file, ensure it\'s loaded (e.g., use dotenv)');
+            console.log('  4. For testing, you can use: CODEHERE_FAKE_AI=1 codehere index');
+            newline();
+        }
+        else {
+            console.error(error('Error indexing repository:'), errorMessage);
+        }
         process.exit(1);
     }
 });
@@ -196,7 +259,7 @@ Make sure to run "codehere index" first!
   `)
     .action(async (question) => {
     initLogFile();
-    if (!process.env.COHERE_API_KEY) {
+    if (!process.env.COHERE_API_KEY && process.env.CODEHERE_FAKE_AI !== '1') {
         newline();
         console.error(error('COHERE_API_KEY not found in environment'));
         newline();
@@ -209,21 +272,7 @@ Make sure to run "codehere index" first!
         process.exit(1);
     }
     try {
-        console.log(createBanner('Ask Question', 'Semantic search + AI chat'));
-        newline();
-        // Display query
-        console.log(colors.bold('Query:'));
-        console.log(colors.cyan('  ' + question));
-        newline();
-        // Use clean architecture
-        const searchSpinner = createSpinner('Searching codebase...');
-        searchSpinner.start();
-        try {
-            await executeAskCommand(question);
-        }
-        finally {
-            searchSpinner.stop();
-        }
+        await executeAskCommand(question);
         logEntry({
             timestamp: new Date().toISOString(),
             command: 'ask',
@@ -232,7 +281,12 @@ Make sure to run "codehere index" first!
         });
     }
     catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : 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);
     }
 });
@@ -242,10 +296,11 @@ program
     .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 fix src/auth.ts "Add error handling for invalid tokens"
-  $ codehere fix utils/helpers.js "Rename function foo() to bar()"
+  $ codehere fix utils/helpers.js "Rename function foo() to bar()" --review
   $ codehere edit app.js "Add input validation"
 
 This command will:
@@ -254,12 +309,15 @@ This command will:
   • 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) => {
+    .action(async (file, instruction, options) => {
     initLogFile();
     if (!process.env.COHERE_API_KEY) {
         newline();
@@ -274,93 +332,31 @@ Safety policies:
         process.exit(1);
     }
     try {
-        console.log(createBanner('Edit File', 'AI-powered code editing'));
-        newline();
-        // Display edit info
-        console.log(colors.bold('File:') + ' ' + formatPath(file));
-        console.log(colors.bold('Instruction:') + ' ' + colors.cyan(instruction));
-        newline();
-        // Generate diff with spinner
-        const diffSpinner = createSpinner('Generating code changes...');
-        diffSpinner.start();
-        // Check if file exists
-        const { existsSync } = await import('fs');
-        const fullPath = join(process.cwd(), file);
-        if (!existsSync(fullPath)) {
-            diffSpinner.stop();
-            displayError(new Error(`File not found: ${file}`), {
-                operation: 'edit',
-                query: instruction,
-                filepath: file,
-                showSuggestions: true,
-            });
-            console.log(info(`Looking for: ${fullPath}`));
-            console.log(info('Tip: Use a relative path from your current directory'));
-            newline();
-            process.exit(1);
-        }
-        const result = await generateAndApplyEdit(file, instruction);
-        diffSpinner.stop();
-        if (result.success) {
-            newline();
-            // Policy check display
-            if (result.policyResult) {
-                sectionHeader('Policy Check');
-                const policyTable = createTable(['Check', 'Status'], [
-                    ['Line Limit (≤50)', result.policyResult.allowed ? statusIndicator('success') + ' Passed' : statusIndicator('error') + ' Failed'],
-                    ['Restricted Folders', result.policyResult.allowed ? statusIndicator('success') + ' Passed' : statusIndicator('error') + ' Failed'],
-                    ['Single File Only', result.policyResult.allowed ? statusIndicator('success') + ' Passed' : statusIndicator('error') + ' Failed'],
-                ]);
-                console.log(policyTable.toString());
+        // 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();
-            }
-            // Diff stats
-            if (result.diffStats) {
-                sectionHeader('Changes');
-                const statsTable = createTable(['Metric', 'Value'], [
-                    ['Lines Added', formatNumber(result.diffStats.linesAdded)],
-                    ['Lines Removed', formatNumber(result.diffStats.linesRemoved)],
-                    ['Total Changes', formatNumber(result.diffStats.linesAdded + result.diffStats.linesRemoved)],
-                    ['Files Changed', formatNumber(result.diffStats.filesChanged)],
-                ]);
-                console.log(statsTable.toString());
+                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);
             }
-            console.log(success('Edit applied successfully'));
-            logEntry({
-                timestamp: new Date().toISOString(),
-                command: 'fix',
-                query: instruction,
-                filepath: file,
-                diffStats: result.diffStats,
-                policyStatus: result.policyResult?.allowed ? 'allowed' : 'rejected',
-            });
-        }
-        else {
-            // Use centralized error display
-            const errorMessage = result.policyResult && !result.policyResult.allowed
-                ? result.policyResult.reason || 'Policy check failed'
-                : result.error || 'Edit failed';
-            const policyError = result.policyResult && !result.policyResult.allowed
-                ? new Error(`Policy check failed: ${result.policyResult.reason || 'Unknown reason'}`)
-                : new Error(`Edit failed: ${result.error || 'Unknown error'}`);
-            logEntry({
-                timestamp: new Date().toISOString(),
-                command: 'fix',
-                query: instruction,
-                filepath: file,
-                diffStats: result.diffStats,
-                policyStatus: 'rejected',
-                policyReason: result.error,
-            });
-            displayError(policyError, {
-                operation: 'edit',
-                query: instruction,
-                filepath: file,
-                showSuggestions: true,
-            });
-            process.exit(1);
         }
+        await executeFixCommand(file, instruction, { review: options?.review });
+        logEntry({
+            timestamp: new Date().toISOString(),
+            command: 'fix',
+            query: instruction,
+            filepath: file,
+            policyStatus: 'allowed',
+        });
     }
     catch (err) {
         displayError(err, {
@@ -403,8 +399,30 @@ This command will:
         process.exit(1);
     }
     try {
-        console.log(createBanner('Explain File', 'AI-powered code explanation'));
-        newline();
+        // 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');
@@ -454,9 +472,14 @@ program
     .option('-m, --metrics', 'Show detailed metrics')
     .action((options) => {
     const health = performHealthCheck();
-    newline();
-    console.log(createBanner('System Health', 'Enterprise monitoring'));
-    newline();
+    if (isMinimalStyle()) {
+        printMinimalHeader('health', '');
+    }
+    else {
+        newline();
+        console.log(createBanner('System Health', 'Enterprise monitoring'));
+        newline();
+    }
     console.log(formatHealthStatus(health));
     if (options.metrics) {
         newline();
@@ -557,13 +580,13 @@ program
     }
 });
 program
-    .command('review')
+    .command('git-review')
     .description('Review git changes and suggest improvements')
     .option('-f, --file <file>', 'Review specific file')
     .action((options) => {
     initLogFile();
     try {
-        console.log(createBanner('Code Review', 'Git-aware code analysis'));
+        console.log(createBanner('Git Review', 'Git-aware code analysis'));
         newline();
         const status = getGitStatus();
         if (!status.isRepo) {
@@ -612,6 +635,7 @@ program
     .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 (!process.env.COHERE_API_KEY) {
@@ -619,12 +643,17 @@ program
         process.exit(1);
     }
     try {
-        console.log(createBanner('Task Planning', 'Intelligent multi-step execution'));
-        newline();
-        console.log(colors.bold('Instruction:') + ' ' + colors.cyan(instruction));
+        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 });
+        await executePlanCommand(instruction, { execute: options.execute, review: options.review });
     }
     catch (err) {
         console.error(error('Error:'), err instanceof Error ? err.message : String(err));
@@ -703,24 +732,38 @@ program
         process.exit(1);
     }
     try {
-        console.log(createBanner('Code Review', 'Automated senior-level analysis'));
-        newline();
+        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();
-        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());
+        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));
@@ -809,44 +852,233 @@ program
         process.exit(1);
     }
 });
+// DocumentationAgent-based docs command
 program
     .command('docs')
-    .description('Generate and update documentation')
-    .argument('<file>', 'File to document')
-    .option('--readme', 'Generate README for entire project')
-    .option('--update', 'Update existing documentation')
-    .option('--save', 'Save documentation to file')
-    .action(async (file, options) => {
+    .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 (!process.env.COHERE_API_KEY) {
+        console.error(error('COHERE_API_KEY not found in environment'));
+        process.exit(1);
+    }
+    initLogFile();
+    await executeDocsCommand(type, {
+        target: options.target,
+        updateExisting: options.updateExisting,
+        outputPath: options.output,
+        review: Boolean(options.review),
+    });
+});
+// ProductRequirementsAgent-based product command
+program
+    .command('product')
+    .description('Generate product requirements documents using ProductRequirementsAgent')
+    .argument('<spec>', 'Command: spec')
+    .argument('<goal>', 'Product goal or feature description')
+    .option('--format <format>', 'Output format: markdown, json, or both', 'both')
+    .option('--output <path>', 'Output path for generated PRD (optional)')
+    .option('--detail <level>', 'Detail level: low, medium, or high', 'medium')
+    .option('--include-technical-spec', 'Include technical specification document')
+    .option('--review', 'Enable review & feedback capture (used for trust scoring and Validation Mode)')
+    .addHelpText('after', `
+Examples:
+  $ codehere product spec "Add team dashboards for executive reporting"
+  $ codehere product spec "Build user authentication system" --format markdown --output prd.md
+  $ codehere product spec "Implement payment gateway" --detail high --include-technical-spec --review
+
+Warning: This command may create new files if --output is specified.
+  `)
+    .action(async (cmd, goal, options) => {
+    if (cmd !== 'spec') {
+        console.error(error(`Unknown command: ${cmd}. Use 'spec' to generate product requirements.`));
+        process.exit(1);
+    }
+    if (!process.env.COHERE_API_KEY && process.env.CODEHERE_FAKE_AI !== '1') {
+        console.error(error('COHERE_API_KEY not found in environment'));
+        process.exit(1);
+    }
+    initLogFile();
+    // Note: --review flag is defined on parent 'product' command, not 'spec' subcommand
+    // In commander.js, parent command options may not be merged into subcommand options
+    // So we check both options.review (subcommand) and program.opts().review (parent command)
+    // This ensures --review works correctly for 'product spec' commands
+    const reviewValue = options.review !== undefined ? options.review : program.opts().review;
+    await executeProductCommand(goal, {
+        format: options.format,
+        output: options.output,
+        detail: options.detail,
+        includeTechnicalSpec: options.includeTechnicalSpec || false,
+        review: Boolean(reviewValue),
+    });
+});
+// Status command
+program
+    .command('status')
+    .description('Show system status and optionally list recent tasks')
+    .option('--json', 'Output machine-readable JSON summary instead of text')
+    .option('--tasks', 'Show recent tasks (experimental)')
+    .option('--env', 'Show environment details')
+    .option('--track', 'Show what works (success rates by command)')
+    .action(async (options) => {
+    await executeStatusCommand({
+        json: Boolean(options.json),
+        tasks: Boolean(options.tasks),
+        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('<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 (!process.env.COHERE_API_KEY) {
+        newline();
         console.error(error('COHERE_API_KEY not found in environment'));
         process.exit(1);
     }
     try {
-        console.log(createBanner('Documentation Generator', 'Auto-generate docs'));
-        newline();
-        const docsSpinner = createSpinner('Generating documentation...');
-        docsSpinner.start();
-        let docs;
-        if (options.readme) {
-            docs = await generateREADME();
-        }
-        else if (options.update) {
-            docs = await updateDocs(file);
-        }
-        else {
-            docs = await generateFileDocs(file);
+        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);
         }
-        docsSpinner.stop();
+        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 (!process.env.COHERE_API_KEY) {
         newline();
-        sectionHeader('Generated Documentation');
-        const formattedDocs = cleanResponse(docs);
-        console.log(formattedDocs);
-        if (options.save) {
-            const outputPath = options.readme ? 'README.md' : file.replace(/\.[^/.]+$/, '.md');
-            saveDocs(outputPath, docs);
-            console.log(success(`Documentation saved to ${outputPath}`));
-        }
+        console.error(error('COHERE_API_KEY not found in environment'));
+        process.exit(1);
+    }
+    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));
@@ -949,6 +1181,7 @@ program
     .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 (!process.env.COHERE_API_KEY) {
@@ -960,6 +1193,7 @@ program
         await executeOrchestrateCommand(goal, {
             mode: options.mode,
             planId: options.planId,
+            review: options.review,
         });
         logEntry({
             timestamp: new Date().toISOString(),