llm-checker 3.5.15 → 3.7.0

package/bin/enhanced_cli.js

@@ -58,9 +58,12 @@ const calibrationManager = new CalibrationManager();
 
 const COMMAND_HEADER_LABELS = {
     'hw-detect': 'Hardware Detection',
-    'smart-recommend': 'Smart Recommend',
+    'smart-recommend': 'Smart Recommend (Experimental)',
     search: 'Model Search',
     sync: 'Database Sync',
+    'registry-sync': 'Model Registry Sync',
+    'registry-search': 'Model Registry Search',
+    'registry-recommend': 'Registry Recommendations',
     'mcp-setup': 'Claude MCP Setup',
     check: 'Compatibility Check',
     installed: 'Installed Models',
@@ -79,6 +82,19 @@ function showAsciiArt(command) {
     renderCommandHeader(label);
 }
 
+const RECOMMENDATION_COMMAND_NOTES = {
+    check: 'Compatibility report: shows hardware fit first. Use `llm-checker recommend` for canonical ranked model picks.',
+    recommend: 'Canonical recommendations: deterministic hardware-aware selector by category.',
+    'smart-recommend': 'Experimental scoring engine: results can differ from `recommend` while this path is being unified.'
+};
+
+function displayRecommendationCommandNote(command) {
+    const note = RECOMMENDATION_COMMAND_NOTES[command];
+    if (!note) return;
+    console.log(chalk.gray(`Recommendation mode: ${note}`));
+    console.log('');
+}
+
 // Function to search Ollama models by use case
 function getOllamaCacheFile(filename) {
     try {
@@ -388,6 +404,41 @@ function getRealSizeFromOllamaCache(model) {
     }
 }
 
+function parsePositiveNumberOption(value, fallback = null) {
+    if (value === undefined || value === null || value === '') return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function truncateMiddle(value, maxLength = 48) {
+    const text = String(value || '');
+    if (text.length <= maxLength) return text;
+    if (maxLength <= 4) return text.slice(0, maxLength);
+    const head = Math.ceil((maxLength - 3) / 2);
+    const tail = Math.floor((maxLength - 3) / 2);
+    return `${text.slice(0, head)}...${text.slice(text.length - tail)}`;
+}
+
+function formatRegistryNumber(value, suffix = '') {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) return '?';
+    const rounded = parsed >= 100 ? Math.round(parsed) : Math.round(parsed * 10) / 10;
+    return `${rounded}${suffix}`;
+}
+
+function formatRegistrySize(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) return '?';
+    return `${Math.round(parsed * 100) / 100}GB`;
+}
+
+function formatRegistryList(value, maxItems = 3) {
+    const items = Array.isArray(value) ? value : [];
+    if (items.length === 0) return '-';
+    const shown = items.slice(0, maxItems).join(', ');
+    return items.length > maxItems ? `${shown}, +${items.length - maxItems}` : shown;
+}
+
 const program = new Command();
 
 program
@@ -1272,12 +1323,17 @@ function displayIntelligentRecommendations(intelligentData, hardware = null) {
     const { summary, recommendations } = intelligentData;
     const tier = summary.hardware_tier.replace('_', ' ').toUpperCase();
     const optimizeProfile = (summary.optimize_for || intelligentData.optimizeFor || 'balanced').toUpperCase();
+    const runtimeLabel = (intelligentData.runtime || summary.best_overall?.runtime || 'auto').toUpperCase();
+    const sourceLabel = intelligentData.recommendationSource === 'registry'
+        ? 'Multi-source registry'
+        : 'Ollama catalog';
     const tierColor = tier.includes('HIGH') ? chalk.green : tier.includes('MEDIUM') ? chalk.yellow : chalk.red;
 
     console.log('\n' + chalk.bgRed.white.bold(' INTELLIGENT RECOMMENDATIONS BY CATEGORY '));
     console.log(chalk.red('╭' + '─'.repeat(65)));
     console.log(chalk.red('│') + ` Hardware Tier: ${tierColor.bold(tier)} | Models Analyzed: ${chalk.cyan.bold(intelligentData.totalModelsAnalyzed)}`);
-    console.log(chalk.red('│') + ` Optimization: ${chalk.magenta.bold(optimizeProfile)}`);
+    console.log(chalk.red('│') + ` Optimization: ${chalk.magenta.bold(optimizeProfile)} | Runtime: ${chalk.cyan.bold(runtimeLabel)}`);
+    console.log(chalk.red('│') + ` Source: ${chalk.white.bold(sourceLabel)}`);
     console.log(chalk.red('│'));
 
     // Mostrar mejor modelo general
@@ -1288,6 +1344,7 @@ function displayIntelligentRecommendations(intelligentData, hardware = null) {
         console.log(chalk.red('│') + `    Command: ${chalk.cyan.bold(best.command)}`);
         console.log(chalk.red('│') + `    Score: ${chalk.yellow.bold(best.score)}/100 | Category: ${chalk.magenta(best.category)}`);
         console.log(chalk.red('│') + `    Quantization: ${chalk.white.bold(best.quantization || 'Q4_K_M')}`);
+        console.log(chalk.red('│') + `    Runtime: ${chalk.cyan.bold(best.runtime || intelligentData.runtime || 'ollama')} | Source: ${chalk.gray(best.source || 'unknown')}`);
         console.log(chalk.red('│') + `    Fine-tuning: ${chalk.blue.bold(bestFineTuning.shortLabel)}`);
         console.log(chalk.red('│'));
     }
@@ -1313,6 +1370,7 @@ function displayIntelligentRecommendations(intelligentData, hardware = null) {
         console.log(chalk.red('│') + `    ${chalk.green(model.name)} (${model.size})`);
         console.log(chalk.red('│') + `    Score: ${scoreColor.bold(model.score)}/100 | Pulls: ${chalk.gray(model.pulls?.toLocaleString() || 'N/A')}`);
         console.log(chalk.red('│') + `    Quantization: ${chalk.white.bold(model.quantization || 'Q4_K_M')}`);
+        console.log(chalk.red('│') + `    Runtime: ${chalk.cyan(model.runtime || intelligentData.runtime || 'ollama')} | Source: ${chalk.gray(model.source || 'unknown')}`);
         console.log(chalk.red('│') + `    Fine-tuning: ${chalk.blue.bold(fineTuningSupport.shortLabel)}`);
         console.log(chalk.red('│') + `    Command: ${chalk.cyan.bold(model.command)}`);
         console.log(chalk.red('│'));
@@ -3004,7 +3062,7 @@ auditCommand
     .option('-u, --use-case <case>', 'Use case when --command check is selected', 'general')
     .option('-c, --category <category>', 'Category hint when --command recommend is selected')
     .option('--optimize <profile>', 'Optimization profile for recommend mode (balanced|speed|quality|context|coding)', 'balanced')
-    .option('--runtime <runtime>', `Runtime for check mode (${SUPPORTED_RUNTIMES.join('|')})`, 'ollama')
+    .option('--runtime <runtime>', 'Runtime for check/recommend mode (auto|ollama|vllm|mlx|llama.cpp|transformers)', 'auto')
     .option('--include-cloud', 'Include cloud models in check-mode analysis')
     .option('--max-size <size>', 'Maximum model size for check mode (e.g., "24B" or "12GB")')
     .option('--min-size <size>', 'Minimum model size for check mode (e.g., "3B" or "2GB")')
@@ -3058,13 +3116,14 @@ auditCommand
                 policyCandidates = collectCandidatesFromAnalysis(analysisResult);
             } else {
                 recommendationResult = await checker.generateIntelligentRecommendations(hardware, {
-                    optimizeFor: options.optimize
+                    optimizeFor: options.optimize,
+                    runtime: options.runtime
                 });
                 if (!recommendationResult) {
                     throw new Error('Unable to generate recommendation data for policy audit export.');
                 }
 
-                runtimeBackend = normalizeRuntime(options.runtime || 'ollama');
+                runtimeBackend = recommendationResult.runtime || options.runtime || 'auto';
                 policyCandidates = collectCandidatesFromRecommendationData(recommendationResult);
             }
 
@@ -3295,6 +3354,7 @@ Policy scope:
     )
     .action(async (options) => {
         showAsciiArt('check');
+        displayRecommendationCommandNote('check');
         try {
             // Use verbose progress unless explicitly disabled
             const verboseEnabled = options.verbose !== false;
@@ -3462,11 +3522,8 @@ Policy scope:
 
 program
     .command('ollama')
-    .description('Manage Ollama integration with hardware compatibility')
-    .option('-l, --list', 'List installed models with compatibility scores')
-    .option('-r, --running', 'Show running models with performance data')
-    .option('-c, --compatible', 'Show only hardware-compatible installed models')
-    .option('--recommendations', 'Show installation recommendations')
+    .description('Check Ollama integration status (use `installed` to rank installed models)')
+    .option('-l, --list', 'List installed models ranked by compatibility (runs `installed`)')
     .action(async (options) => {
         showAsciiArt('ollama');
         const spinner = ora('Checking Ollama integration...').start();
@@ -3492,7 +3549,9 @@ program
             spinner.succeed(`Ollama integration active`);
 
             if (options.list) {
-                console.log('Ollama models list feature coming soon...');
+                console.log(chalk.cyan('\nRun `llm-checker installed` to rank your installed models by compatibility and use-case.'));
+            } else {
+                console.log(chalk.gray('\nTip: `llm-checker installed` ranks installed models; `llm-checker recommend` suggests models for your hardware.'));
             }
 
         } catch (error) {
@@ -3520,10 +3579,18 @@ program
             const availability = await ollamaClient.checkOllamaAvailability();
             if (!availability.available) {
                 spinner.fail('Ollama not available');
-                console.log(chalk.red('\n' + availability.error));
-                if (availability.hint) {
-                    console.log(chalk.yellow('Hint: ' + availability.hint));
+                if (options.json) {
+                    // --json must always emit parseable JSON on stdout (the success
+                    // path prints an array); previously these branches printed
+                    // ANSI-colored prose and broke `installed --json | jq`.
+                    console.log(JSON.stringify([], null, 2));
+                } else {
+                    console.log(chalk.red('\n' + availability.error));
+                    if (availability.hint) {
+                        console.log(chalk.yellow('Hint: ' + availability.hint));
+                    }
                 }
+                process.exitCode = 1;
                 return;
             }
 
@@ -3531,8 +3598,12 @@ program
             const installedModels = await ollamaClient.getLocalModels();
             if (!installedModels || installedModels.length === 0) {
                 spinner.fail('No models installed');
-                console.log(chalk.yellow('\nNo Ollama models found. Install one with:'));
-                console.log(chalk.cyan('  ollama pull llama3.2:3b'));
+                if (options.json) {
+                    console.log(JSON.stringify([], null, 2));
+                } else {
+                    console.log(chalk.yellow('\nNo Ollama models found. Install one with:'));
+                    console.log(chalk.cyan('  ollama pull llama3.2:3b'));
+                }
                 return;
             }
 
@@ -3819,6 +3890,8 @@ program
     .description('Get intelligent model recommendations for your hardware')
     .option('-c, --category <category>', 'Get recommendations for specific category (coding, talking, reading, etc.)')
     .option('--optimize <profile>', 'Optimization profile (balanced|speed|quality|context|coding)', 'balanced')
+    .option('--runtime <runtime>', 'Runtime target for registry recommendations (auto|ollama|vllm|mlx|llama.cpp|transformers)', 'auto')
+    .option('--no-registry', 'Use the legacy Ollama catalog recommendation path')
     .option('--no-verbose', 'Disable step-by-step progress display')
     .option('--policy <file>', 'Evaluate recommendations against a policy file')
     .option('--simulate <profile>', 'Simulate a hardware profile instead of detecting real hardware (use "list" to see profiles)')
@@ -3843,6 +3916,11 @@ Hardware simulation:
   $ llm-checker recommend --simulate m4pro24 --category coding
   $ llm-checker recommend --gpu "RTX 5060" --ram 32 --cpu "AMD Ryzen 7 5700X"
 
+Registry/runtime examples:
+  $ llm-checker recommend --runtime auto --category coding
+  $ llm-checker recommend --runtime vllm --category coding
+  $ llm-checker recommend --runtime mlx --category general
+
 Calibrated routing examples:
   $ llm-checker recommend --calibrated --category coding
   $ llm-checker recommend --calibrated ./calibration-policy.yaml --category reasoning
@@ -3851,6 +3929,7 @@ Calibrated routing examples:
     )
     .action(async (options) => {
         showAsciiArt('recommend');
+        displayRecommendationCommandNote('recommend');
         try {
             const verboseEnabled = options.verbose !== false;
             const checker = new (getLLMChecker())({ verbose: verboseEnabled });
@@ -3919,7 +3998,9 @@ Calibrated routing examples:
 
             const hardware = await checker.getSystemInfo();
             const intelligentRecommendations = await checker.generateIntelligentRecommendations(hardware, {
-                optimizeFor: options.optimize
+                optimizeFor: options.optimize,
+                runtime: options.runtime,
+                registry: options.registry
             });
 
             if (!intelligentRecommendations) {
@@ -4365,6 +4446,7 @@ program
     .option('--ctx <number>', 'Target context length', '8192')
     .option('-e, --evaluator <model>', 'Evaluator model (auto for best available)', 'auto')
     .option('-w, --weight <number>', 'AI weight (0.0-1.0, default 0.3)', '0.3')
+    .option('-m, --models <list>', 'Restrict evaluation to these models (comma-separated)')
     .action(async (options) => {
         showAsciiArt('ai-check');
         // Check if Ollama is installed first
@@ -4377,14 +4459,33 @@ program
             
             const aiCheckSelector = new AICheckSelector();
             
+            // Validate numeric options up front: bad input (e.g. --weight abc, --top
+            // foo) used to flow through as NaN, which survived the downstream clamp
+            // and made the displayed AI weight and every weighted score NaN.
+            const weight = Number.parseFloat(options.weight);
+            const top = Number.parseInt(options.top, 10);
+            const ctx = options.ctx ? Number.parseInt(options.ctx, 10) : undefined;
+            const invalidNumeric =
+                (!Number.isFinite(weight) || weight < 0 || weight > 1) ? `--weight ${options.weight} (use a number from 0.0 to 1.0)`
+                : (!Number.isInteger(top) || top <= 0) ? `--top ${options.top} (use a positive integer)`
+                : (ctx !== undefined && (!Number.isInteger(ctx) || ctx <= 0)) ? `--ctx ${options.ctx} (use a positive integer)`
+                : null;
+            if (invalidNumeric) {
+                spinner.stop();
+                console.error(chalk.red(`Invalid ${invalidNumeric}`));
+                process.exitCode = 1;
+                return;
+            }
+
             const checkOptions = {
                 category: options.category,
-                top: parseInt(options.top),
-                ctx: options.ctx ? parseInt(options.ctx) : undefined,
+                top,
+                ctx,
                 evaluator: options.evaluator,
-                weight: parseFloat(options.weight)
+                weight,
+                models: options.models || process.env.LLM_CHECKER_AI_CHECK_MODELS || undefined
             };
-            
+
             spinner.stop();
             
             const result = await aiCheckSelector.aiCheck(checkOptions);
@@ -4683,6 +4784,307 @@ program
         }
     });
 
+program
+    .command('registry-sync')
+    .description('Sync the multi-source model registry (Ollama, Hugging Face, GPT4All)')
+    .option('-s, --sources <list>', 'Comma-separated sources: ollama,huggingface,gpt4all', 'ollama,huggingface,gpt4all')
+    .option('-l, --limit <n>', 'Fallback maximum records per source')
+    .option('--hf-limit <n>', 'Maximum Hugging Face repos to ingest', '3000')
+    .option('--ollama-limit <n>', 'Maximum Ollama artifacts to ingest', '10000')
+    .option('--gpt4all-limit <n>', 'Maximum GPT4All entries to ingest', '1000')
+    .option('--query <text>', 'Hugging Face search query')
+    .option('--task <task>', 'Hugging Face task/filter, for example text-generation or text-embeddings-inference')
+    .option('--dry-run', 'Fetch and normalize without writing to the database')
+    .option('-q, --quiet', 'Suppress progress output')
+    .option('-j, --json', 'Output as JSON')
+    .action(async (options) => {
+        const quiet = Boolean(options.quiet || options.json);
+        if (!quiet) showAsciiArt('registry-sync');
+
+        const ModelDatabase = require('../src/data/model-database');
+        const { RegistryIngestor } = require('../src/data/registry-ingestors');
+        const database = new ModelDatabase();
+        const spinner = quiet ? null : ora('Preparing model registry sync...').start();
+
+        try {
+            await database.initialize();
+
+            const ingestor = new RegistryIngestor({
+                database,
+                onProgress: (info) => {
+                    if (spinner && info.message) {
+                        spinner.text = info.message;
+                    }
+                }
+            });
+
+            const summary = await ingestor.ingest({
+                sources: options.sources,
+                limit: parsePositiveNumberOption(options.limit),
+                hfLimit: parsePositiveNumberOption(options.hfLimit, 3000),
+                ollamaLimit: parsePositiveNumberOption(options.ollamaLimit, 10000),
+                gpt4allLimit: parsePositiveNumberOption(options.gpt4allLimit, 1000),
+                query: options.query,
+                task: options.task,
+                dryRun: Boolean(options.dryRun)
+            });
+            const stats = options.dryRun ? null : database.getRegistryStats();
+
+            if (options.json) {
+                console.log(JSON.stringify({ summary, stats }, null, 2));
+                return;
+            }
+
+            if (spinner) {
+                const action = options.dryRun ? 'normalized' : 'synced';
+                spinner.succeed(`Registry ${action}: ${summary.repos} repos, ${summary.artifacts} artifacts`);
+            }
+
+            console.log(chalk.green('\n[OK] Registry sync complete'));
+            console.log(chalk.gray(`  Sources touched: ${summary.sources}`));
+            console.log(chalk.gray(`  Collections: ${summary.collections}`));
+            console.log(chalk.gray(`  Repositories: ${summary.repos}`));
+            console.log(chalk.gray(`  Artifacts: ${summary.artifacts}`));
+
+            if (stats) {
+                console.log(chalk.blue.bold('\nRegistry totals:'));
+                console.log(chalk.gray(`  Sources: ${stats.sources}`));
+                console.log(chalk.gray(`  Repositories: ${stats.repos}`));
+                console.log(chalk.gray(`  Artifacts: ${stats.artifacts}`));
+
+                if (stats.bySource.length > 0) {
+                    const rows = [['Source', 'Artifacts']];
+                    for (const item of stats.bySource) {
+                        rows.push([item.source_id, String(item.artifact_count)]);
+                    }
+                    console.log('\n' + table(rows));
+                }
+            }
+
+            console.log(chalk.cyan('Try: llm-checker registry-search llama --runtime auto --limit 10'));
+        } catch (error) {
+            if (spinner) spinner.fail('Registry sync failed');
+            console.error(chalk.red('Error:'), error.message);
+            if (process.env.DEBUG) console.error(error.stack);
+            process.exitCode = 1;
+        } finally {
+            database.close();
+        }
+    });
+
+program
+    .command('registry-search [query]')
+    .description('Search exact downloadable/installable artifacts in the multi-source model registry')
+    .option('-s, --source <source>', 'Filter by source: ollama, huggingface, gpt4all')
+    .option('--format <format>', 'Filter by artifact format: gguf, safetensors, mlx, ollama')
+    .option('--runtime <runtime>', 'Filter by runtime support: auto, ollama, llama.cpp, transformers, vllm, mlx')
+    .option('--quant <type>', 'Filter by quantization, for example Q4_K_M or Q8_0')
+    .option('--max-size <gb>', 'Maximum artifact size in GB')
+    .option('--min-params <billion>', 'Minimum parameter count in billions')
+    .option('--max-params <billion>', 'Maximum parameter count in billions')
+    .option('--local-only', 'Exclude gated/auth-required artifacts')
+    .option('-l, --limit <n>', 'Maximum number of results', '20')
+    .option('-j, --json', 'Output as JSON')
+    .action(async (query = '', options) => {
+        if (!options.json) showAsciiArt('registry-search');
+
+        const ModelDatabase = require('../src/data/model-database');
+        const database = new ModelDatabase();
+
+        try {
+            await database.initialize();
+
+            const filters = {
+                source: options.source,
+                format: options.format ? String(options.format).toLowerCase() : undefined,
+                runtime: options.runtime,
+                quantization: options.quant,
+                maxSizeGB: parsePositiveNumberOption(options.maxSize),
+                minParamsB: parsePositiveNumberOption(options.minParams),
+                maxParamsB: parsePositiveNumberOption(options.maxParams),
+                localOnly: Boolean(options.localOnly),
+                limit: parsePositiveNumberOption(options.limit, 20)
+            };
+            const results = database.searchModelArtifacts(query, filters);
+            const stats = database.getRegistryStats();
+
+            if (options.json) {
+                console.log(JSON.stringify({
+                    query,
+                    filters,
+                    count: results.length,
+                    stats,
+                    results
+                }, null, 2));
+                return;
+            }
+
+            if (results.length === 0) {
+                console.log(chalk.yellow('No registry artifacts found.'));
+                if (stats.artifacts === 0) {
+                    console.log(chalk.gray('Populate the registry first with: llm-checker registry-sync'));
+                }
+                return;
+            }
+
+            console.log(chalk.blue.bold('\nRegistry Results'));
+            console.log(chalk.gray(`Stored registry: ${stats.artifacts} artifacts across ${stats.sources} sources`));
+            console.log('');
+
+            const rows = [[
+                'Source',
+                'Model',
+                'Artifact',
+                'Params',
+                'Size',
+                'Format',
+                'Runtime',
+                'Install'
+            ]];
+
+            for (const item of results) {
+                rows.push([
+                    item.source_id,
+                    truncateMiddle(item.canonical_model_id, 34),
+                    truncateMiddle(item.artifact_name || item.filename, 34),
+                    formatRegistryNumber(item.parameter_count_b, 'B'),
+                    formatRegistrySize(item.size_gb),
+                    item.quantization ? `${item.format}/${item.quantization}` : item.format,
+                    formatRegistryList(item.runtime_support, 2),
+                    truncateMiddle(item.install_command || item.download_url, 46)
+                ]);
+            }
+
+            console.log(table(rows));
+
+            const links = results
+                .filter((item) => item.download_url)
+                .slice(0, 5);
+            if (links.length > 0) {
+                console.log(chalk.blue.bold('Exact download links:'));
+                links.forEach((item, index) => {
+                    console.log(chalk.gray(`  ${index + 1}. ${item.canonical_model_id} -> ${item.download_url}`));
+                });
+            }
+        } catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            if (process.env.DEBUG) console.error(error.stack);
+            process.exitCode = 1;
+        } finally {
+            database.close();
+        }
+    });
+
+program
+    .command('registry-recommend [query]')
+    .description('Recommend the best exact model artifacts from the multi-source registry for this hardware')
+    .option('-c, --category <category>', 'Task category (general, coding, reasoning, embeddings, multimodal)', 'general')
+    .option('--optimize <profile>', 'Optimization profile (balanced|speed|quality|context|coding)', 'balanced')
+    .option('--runtime <runtime>', 'Runtime target: auto, ollama, llama.cpp, vllm, mlx, transformers', 'auto')
+    .option('-s, --source <source>', 'Filter by source: ollama, huggingface, gpt4all')
+    .option('--format <format>', 'Filter by artifact format: gguf, safetensors, mlx, ollama')
+    .option('--quant <type>', 'Filter by quantization, for example Q4_K_M or Q8_0')
+    .option('--max-size <gb>', 'Maximum artifact size in GB')
+    .option('--min-params <billion>', 'Minimum parameter count in billions')
+    .option('--max-params <billion>', 'Maximum parameter count in billions')
+    .option('--target-context <tokens>', 'Target context window for scoring')
+    .option('--include-gated', 'Include gated/auth-required artifacts')
+    .option('--pool-limit <n>', 'Maximum registry artifacts to score before ranking', '20000')
+    .option('-l, --limit <n>', 'Maximum number of recommendations', '10')
+    .option('-j, --json', 'Output as JSON')
+    .action(async (query = '', options) => {
+        if (!options.json) showAsciiArt('registry-recommend');
+
+        const UnifiedDetector = require('../src/hardware/unified-detector');
+        const { RegistryRecommender } = require('../src/data/registry-recommender');
+        const recommender = new RegistryRecommender();
+        const spinner = options.json ? null : ora('Scoring registry artifacts...').start();
+
+        try {
+            await recommender.initialize();
+
+            const detector = new UnifiedDetector();
+            const hardware = await detector.detect();
+            const category = normalizeTaskName(options.category || 'general');
+            const result = await recommender.recommend({
+                query,
+                category,
+                optimizeFor: options.optimize,
+                runtime: options.runtime,
+                source: options.source,
+                format: options.format ? String(options.format).toLowerCase() : undefined,
+                quantization: options.quant,
+                maxSizeGB: parsePositiveNumberOption(options.maxSize),
+                minParamsB: parsePositiveNumberOption(options.minParams),
+                maxParamsB: parsePositiveNumberOption(options.maxParams),
+                targetContext: parsePositiveNumberOption(options.targetContext),
+                localOnly: !options.includeGated,
+                poolLimit: parsePositiveNumberOption(options.poolLimit, 20000),
+                limit: parsePositiveNumberOption(options.limit, 10),
+                hardware
+            });
+
+            if (options.json) {
+                console.log(JSON.stringify({
+                    query,
+                    hardware: hardware.summary || hardware,
+                    ...result
+                }, null, 2));
+                return;
+            }
+
+            if (spinner) {
+                spinner.succeed(
+                    `Scored ${result.total_evaluated} candidates from ${result.total_artifacts} registry artifacts`
+                );
+            }
+
+            if (result.recommendations.length === 0) {
+                console.log(chalk.yellow('No registry recommendations found for those filters.'));
+                if (result.registry.artifacts === 0) {
+                    console.log(chalk.gray('Populate the registry first with: llm-checker registry-sync'));
+                }
+                return;
+            }
+
+            console.log(chalk.blue.bold('\nRegistry Recommendations'));
+            console.log(chalk.gray(`Registry: ${result.registry.repos} repos, ${result.registry.artifacts} artifacts`));
+            console.log(chalk.gray(`Runtime: ${result.runtime} | Category: ${result.category} | Optimize: ${result.optimizeFor}`));
+            console.log('');
+
+            const rows = [['#', 'Score', 'Source', 'Model', 'Artifact', 'Params', 'Size', 'Install']];
+            result.recommendations.forEach((item, index) => {
+                rows.push([
+                    String(index + 1),
+                    String(item.score),
+                    item.source,
+                    truncateMiddle(item.model, 30),
+                    truncateMiddle(item.artifact, 32),
+                    formatRegistryNumber(item.params_b, 'B'),
+                    formatRegistrySize(item.size_gb),
+                    truncateMiddle(item.install_command || item.download_url, 44)
+                ]);
+            });
+
+            console.log(table(rows));
+
+            console.log(chalk.blue.bold('Top pick:'));
+            const best = result.recommendations[0];
+            console.log(chalk.white.bold(`  ${best.model}`));
+            console.log(chalk.gray(`  Artifact: ${best.artifact}`));
+            console.log(chalk.gray(`  Why: ${best.rationale}`));
+            if (best.install_command) console.log(chalk.cyan(`  ${best.install_command}`));
+            if (best.download_url) console.log(chalk.gray(`  ${best.download_url}`));
+        } catch (error) {
+            if (spinner) spinner.fail('Registry recommendation failed');
+            console.error(chalk.red('Error:'), error.message);
+            if (process.env.DEBUG) console.error(error.stack);
+            process.exitCode = 1;
+        } finally {
+            recommender.close();
+        }
+    });
+
 program
     .command('search <query>')
     .description('Search models in the database with intelligent scoring')
@@ -4731,8 +5133,20 @@ program
             });
 
             if (searchResults.length === 0) {
-                if (spinner) spinner.info('No models found matching your query');
                 syncManager.close();
+                if (options.json) {
+                    // --json must always emit parseable JSON, even on zero matches
+                    // (previously it printed nothing and broke `search ... --json | jq`).
+                    console.log(JSON.stringify({
+                        query,
+                        all: [],
+                        recommendations: [],
+                        insights: [],
+                        meta: { afterFiltering: 0, totalMatches: 0 }
+                    }, null, 2));
+                } else if (spinner) {
+                    spinner.info('No models found matching your query');
+                }
                 return;
             }
 
@@ -4806,7 +5220,7 @@ program
 
 program
     .command('smart-recommend')
-    .description('Get intelligent model recommendations using the new scoring engine')
+    .description('Experimental recommendations using the alternate scoring engine')
     .option('-u, --use-case <case>', 'Optimize for use case', 'general')
     .option('-l, --limit <n>', 'Maximum number of recommendations', '5')
     .option('--target-tps <n>', 'Target tokens per second', '20')
@@ -4814,8 +5228,19 @@ program
     .option('--include-vision', 'Include vision/multimodal models')
     .option('--include-embeddings', 'Include embedding models')
     .option('-j, --json', 'Output as JSON')
+    .addHelpText(
+        'after',
+        `
+Recommendation engine note:
+  smart-recommend is experimental and may intentionally differ from recommend.
+  Use "llm-checker recommend" for canonical package recommendations.
+`
+    )
     .action(async (options) => {
-        if (!options.json) showAsciiArt('smart-recommend');
+        if (!options.json) {
+            showAsciiArt('smart-recommend');
+            displayRecommendationCommandNote('smart-recommend');
+        }
         const SyncManager = require('../src/data/sync-manager');
         const IntelligentSelector = require('../src/models/intelligent-selector');
         const UnifiedDetector = require('../src/hardware/unified-detector');