@aaronsb/kg-cli 0.6.1

package/dist/cli/search.js

@@ -0,0 +1,829 @@
+"use strict";
+/**
+ * Search and Query Commands
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchCommand = void 0;
+const commander_1 = require("commander");
+const client_1 = require("../api/client");
+const colors = __importStar(require("./colors"));
+const colors_1 = require("./colors");
+const help_formatter_1 = require("./help-formatter");
+const config_1 = require("../lib/config");
+const terminal_images_1 = require("../lib/terminal-images");
+const nodePath = __importStar(require("path"));
+/**
+ * Format grounding strength for display (ADR-044)
+ * This is the fallback when grounding_display is not available.
+ */
+function formatGroundingStrength(grounding) {
+    const groundingValue = grounding.toFixed(3);
+    const percentValue = grounding * 100;
+    // Use ≈ symbol when value is very close to zero but not exactly zero
+    const groundingPercent = (Math.abs(percentValue) < 0.1 && percentValue !== 0)
+        ? `≈${percentValue >= 0 ? '0' : '-0'}`
+        : percentValue.toFixed(0);
+    if (grounding >= 0.7) {
+        return colors.status.success(`✓ Strong (${groundingValue}, ${groundingPercent}%)`);
+    }
+    else if (grounding >= 0.3) {
+        return colors.status.warning(`⚡ Moderate (${groundingValue}, ${groundingPercent}%)`);
+    }
+    else if (grounding >= 0) {
+        return colors.status.dim(`◯ Weak (${groundingValue}, ${groundingPercent}%)`);
+    }
+    else if (grounding >= -0.3) {
+        return colors.status.warning(`⚠ Negative (${groundingValue}, ${groundingPercent}%)`);
+    }
+    else {
+        return colors.status.error(`✗ Contradicted (${groundingValue}, ${groundingPercent}%)`);
+    }
+}
+/**
+ * Format grounding with confidence-awareness (grounding × confidence two-dimensional model)
+ *
+ * Uses grounding_display when available (categorical label from API).
+ * Includes numeric confidence_score alongside the label for quantitative insight.
+ * Falls back to raw grounding score display for backwards compatibility.
+ *
+ * The grounding_display labels come from a 3×3 matrix:
+ * | Grounding × Confidence | Display |
+ * |------------------------|---------|
+ * | Positive + Confident   | "Well-supported" |
+ * | Positive + Tentative   | "Some support (limited data)" |
+ * | Positive + Insufficient| "Possibly supported (needs exploration)" |
+ * | Neutral + Confident    | "Balanced perspectives" |
+ * | Neutral + Tentative    | "Unclear" |
+ * | Neutral + Insufficient | "Unexplored" |
+ * | Negative + Confident   | "Contested" |
+ * | Negative + Tentative   | "Possibly contested" |
+ * | Negative + Insufficient| "Unknown (needs exploration)" |
+ */
+function formatGroundingWithConfidence(grounding, groundingDisplay, confidenceLevel, confidenceScore = null) {
+    // Format confidence score as percentage if available
+    const confScoreStr = confidenceScore !== undefined && confidenceScore !== null
+        ? ` [${(confidenceScore * 100).toFixed(0)}% conf]`
+        : '';
+    // If we have a grounding_display label from the API, use it with appropriate styling
+    if (groundingDisplay) {
+        // Style based on the label content
+        if (groundingDisplay.includes('Well-supported')) {
+            return colors.status.success(`✓ ${groundingDisplay}`) + colors.status.dim(confScoreStr);
+        }
+        else if (groundingDisplay.includes('Contested')) {
+            return colors.status.error(`✗ ${groundingDisplay}`) + colors.status.dim(confScoreStr);
+        }
+        else if (groundingDisplay.includes('Unexplored') || groundingDisplay.includes('Unknown')) {
+            return colors.status.dim(`◯ ${groundingDisplay}${confScoreStr}`);
+        }
+        else if (groundingDisplay.includes('limited data') || groundingDisplay.includes('needs exploration')) {
+            return colors.status.warning(`⚡ ${groundingDisplay}`) + colors.status.dim(confScoreStr);
+        }
+        else if (groundingDisplay.includes('Balanced')) {
+            return colors.status.dim(`◐ ${groundingDisplay}${confScoreStr}`);
+        }
+        else {
+            // Default styling for other labels
+            return colors.status.dim(`◯ ${groundingDisplay}${confScoreStr}`);
+        }
+    }
+    // Fall back to raw grounding score display if available
+    if (grounding !== undefined && grounding !== null) {
+        return formatGroundingStrength(grounding);
+    }
+    // No grounding information available
+    return colors.status.dim('◯ Unexplored');
+}
+/**
+ * Format diversity score for display (ADR-063)
+ */
+function formatDiversity(diversity, relatedCount) {
+    const diversityPercent = (diversity * 100).toFixed(1);
+    if (diversity > 0.6) {
+        return colors.status.success(`🌐 Very High (${diversityPercent}%, ${relatedCount} concepts)`);
+    }
+    else if (diversity > 0.4) {
+        return colors.status.success(`🌐 High (${diversityPercent}%, ${relatedCount} concepts)`);
+    }
+    else if (diversity > 0.2) {
+        return colors.status.warning(`◐ Moderate (${diversityPercent}%, ${relatedCount} concepts)`);
+    }
+    else if (diversity > 0.1) {
+        return colors.status.dim(`◑ Low (${diversityPercent}%, ${relatedCount} concepts)`);
+    }
+    else {
+        return colors.status.error(`◯ Very Low (${diversityPercent}%, ${relatedCount} concepts)`);
+    }
+}
+/**
+ * Format authenticated diversity for display (ADR-044 + ADR-063)
+ */
+function formatAuthenticatedDiversity(authDiv) {
+    const percent = (Math.abs(authDiv) * 100).toFixed(1);
+    if (authDiv > 0.3) {
+        return colors.status.success(`✅ +${percent}% (diverse support)`);
+    }
+    else if (authDiv > 0) {
+        return colors.status.dim(`✓ +${percent}% (some support)`);
+    }
+    else if (authDiv > -0.3) {
+        return colors.status.warning(`⚠ ${percent}% (weak contradiction)`);
+    }
+    else {
+        return colors.status.error(`❌ ${percent}% (diverse contradiction)`);
+    }
+}
+const queryCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('query'), 'Search concepts by semantic similarity', 'Search for concepts using vector similarity (embeddings) - use specific phrases for best results')
+    .showHelpAfterError()
+    .argument('<query>', 'Natural language search query (2-3 words work best)')
+    .option('-l, --limit <number>', 'Maximum number of results to return', '10')
+    .option('--min-similarity <number>', 'Minimum similarity score (0.0-1.0, default 0.7=70%, lower to 0.5 for broader matches)', '0.7')
+    .option('--no-evidence', 'Hide evidence quotes (shown by default)')
+    .option('--no-images', 'Hide inline image display (shown by default if chafa installed)')
+    .option('--no-grounding', 'Disable grounding strength calculation (ADR-044 probabilistic truth convergence) for faster results')
+    .option('--no-diversity', 'Disable semantic diversity calculation (ADR-063 authenticity signal) for faster results')
+    .option('--diversity-hops <number>', 'Maximum traversal depth for diversity (1-3, default 2)', '2')
+    .option('--download <directory>', 'Download images to specified directory instead of displaying inline')
+    .option('--json', 'Output raw JSON instead of formatted text for scripting')
+    .option('--save-artifact', 'Save result as persistent artifact (ADR-083)')
+    .action(async (query, options) => {
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const config = (0, config_1.getConfig)();
+        // Use config defaults, allow CLI flags to override
+        // Commander.js --no-evidence flag sets options.evidence to false
+        const includeEvidence = options.evidence !== undefined ? options.evidence : config.getSearchShowEvidence();
+        const shouldShowImages = options.images !== undefined ? options.images : config.getSearchShowImages();
+        const includeGrounding = options.grounding !== false; // Default: true
+        const includeDiversity = options.diversity !== false; // Default: true
+        const result = await client.searchConcepts({
+            query,
+            limit: parseInt(options.limit),
+            min_similarity: parseFloat(options.minSimilarity),
+            include_evidence: includeEvidence,
+            include_grounding: includeGrounding,
+            include_diversity: includeDiversity,
+            diversity_max_hops: parseInt(options.diversityHops)
+        });
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title(`🔍 Searching for: ${query}`));
+        console.log((0, colors_1.separator)());
+        console.log(colors.status.success(`\n✓ Found ${result.count} concepts:\n`));
+        for (const [i, concept] of result.results.entries()) {
+            const scoreColor = (0, colors_1.getConceptColor)(concept.score);
+            console.log(colors.ui.bullet('●') + ' ' + colors.concept.label(`${i + 1}. ${concept.label}`));
+            if (concept.description) {
+                console.log(`   ${colors.status.dim(concept.description)}`);
+            }
+            console.log(`   ${colors.ui.key('ID:')} ${colors.concept.id(concept.concept_id)}`);
+            console.log(`   ${colors.ui.key('Similarity:')} ${(0, colors_1.coloredPercentage)(concept.score)}`);
+            console.log(`   ${colors.ui.key('Documents:')} ${colors.evidence.document(concept.documents.join(', '))}`);
+            console.log(`   ${colors.ui.key('Evidence:')} ${colors.evidence.count(String(concept.evidence_count))} instances`);
+            // Display grounding with confidence-awareness (ADR-044 + grounding × confidence model)
+            if (concept.grounding_strength !== undefined || concept.grounding_display) {
+                console.log(`   ${colors.ui.key('Grounding:')} ${formatGroundingWithConfidence(concept.grounding_strength, concept.grounding_display, concept.confidence_level, concept.confidence_score)}`);
+            }
+            // Display diversity if available (ADR-063)
+            if (concept.diversity_score !== undefined && concept.diversity_score !== null && concept.diversity_related_count !== undefined) {
+                console.log(`   ${colors.ui.key('Diversity:')} ${formatDiversity(concept.diversity_score, concept.diversity_related_count)}`);
+            }
+            // Display authenticated diversity if available (ADR-044 + ADR-063)
+            if (concept.authenticated_diversity !== undefined && concept.authenticated_diversity !== null) {
+                console.log(`   ${colors.ui.key('Authenticated:')} ${formatAuthenticatedDiversity(concept.authenticated_diversity)}`);
+            }
+            // Display sample evidence if requested
+            if (includeEvidence && concept.sample_evidence && concept.sample_evidence.length > 0) {
+                console.log(`   ${colors.ui.key('Sample Evidence:')}`);
+                for (const [idx, inst] of concept.sample_evidence.entries()) {
+                    const truncatedQuote = inst.quote.length > 100
+                        ? inst.quote.substring(0, 100) + '...'
+                        : inst.quote;
+                    console.log(`      ${colors.ui.bullet(`${idx + 1}.`)} ${colors.evidence.document(inst.document)} ${colors.evidence.paragraph(`(para ${inst.paragraph})`)}`);
+                    console.log(`         ${colors.evidence.quote(`"${truncatedQuote}"`)}`);
+                    // ADR-057: Handle images if available
+                    if (inst.has_image && inst.source_id) {
+                        const downloadDir = options.download;
+                        if (downloadDir) {
+                            // Download mode
+                            try {
+                                console.log(colors.status.dim(`         📥 Downloading image from ${inst.source_id}...`));
+                                const imageBuffer = await client.getSourceImage(inst.source_id);
+                                const extension = (0, terminal_images_1.detectImageFormat)(imageBuffer);
+                                const filename = `${inst.source_id}${extension}`;
+                                const outputPath = nodePath.join(downloadDir, filename);
+                                if ((0, terminal_images_1.saveImageToFile)(imageBuffer, outputPath)) {
+                                    console.log(colors.status.success(`         ✓ Saved to ${outputPath}`));
+                                }
+                            }
+                            catch (error) {
+                                console.log(colors.status.error(`         ✗ Failed to download image: ${error.message}`));
+                            }
+                        }
+                        else if (shouldShowImages && config.isChafaEnabled()) {
+                            // Display mode
+                            if ((0, terminal_images_1.isChafaAvailable)()) {
+                                try {
+                                    console.log(colors.status.dim(`         🖼️  Displaying image from ${inst.source_id}...`));
+                                    const imageBuffer = await client.getSourceImage(inst.source_id);
+                                    const extension = (0, terminal_images_1.detectImageFormat)(imageBuffer);
+                                    await (0, terminal_images_1.displayImageBufferWithChafa)(imageBuffer, extension, {
+                                        width: config.getChafaWidth(),
+                                        scale: config.getChafaScale(),
+                                        align: config.getChafaAlign(),
+                                        colors: config.getChafaColors()
+                                    });
+                                }
+                                catch (error) {
+                                    console.log(colors.status.error(`         ✗ Failed to display image: ${error.message}`));
+                                }
+                            }
+                            else {
+                                console.log(colors.status.warning(`         🖼️  Image available (source: ${inst.source_id})`));
+                                (0, terminal_images_1.printChafaInstallInstructions)();
+                            }
+                        }
+                        else {
+                            // Just indicate image is available
+                            console.log(colors.status.dim(`         🖼️  Image available (use --show-images to display or --download <dir> to save)`));
+                        }
+                    }
+                }
+            }
+            console.log();
+        }
+        // Show hint if additional results available below threshold
+        if (result.below_threshold_count && result.below_threshold_count > 0 && result.suggested_threshold) {
+            const thresholdPercent = (result.suggested_threshold * 100).toFixed(0);
+            console.log(colors.status.warning(`💡 ${result.below_threshold_count} additional concept${result.below_threshold_count > 1 ? 's' : ''} available at ${thresholdPercent}% threshold`));
+            console.log(colors.status.dim(`   Try: kg search query "${query}" --min-similarity ${result.suggested_threshold}\n`));
+        }
+        // ADR-083: Save result as artifact if requested
+        if (options.saveArtifact && result.count > 0) {
+            try {
+                const artifactResult = await client.createArtifact({
+                    artifact_type: 'search_result',
+                    representation: 'cli',
+                    name: `Search: "${query}" (${result.count} results)`,
+                    parameters: {
+                        query,
+                        limit: parseInt(options.limit),
+                        min_similarity: parseFloat(options.minSimilarity),
+                        include_evidence: includeEvidence,
+                        include_grounding: includeGrounding,
+                        include_diversity: includeDiversity,
+                        diversity_max_hops: parseInt(options.diversityHops)
+                    },
+                    payload: result
+                });
+                console.log(colors.status.success(`✓ Artifact saved: ${artifactResult.id}`));
+                console.log(colors.status.dim(`  View: kg artifact show ${artifactResult.id}`));
+            }
+            catch (artifactError) {
+                console.error(colors.status.error(`✗ Failed to save artifact: ${artifactError.message}`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(colors.status.error('✗ Search failed'));
+        console.error(colors.status.error(error.response?.data?.detail || error.message));
+        process.exit(1);
+    }
+});
+const showCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('show'), 'Get full details for a concept', 'Get comprehensive details for a concept: all evidence, relationships, sources, and grounding strength')
+    .alias('details') // backwards compatibility
+    .showHelpAfterError()
+    .argument('<concept-id>', 'Concept ID to retrieve (from search results)')
+    .option('--no-grounding', 'Disable grounding strength calculation (ADR-044 probabilistic truth convergence) for faster results')
+    .option('--json', 'Output raw JSON instead of formatted text for scripting')
+    .action(async (conceptId, options) => {
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const includeGrounding = options.grounding !== false; // Default: true
+        const concept = await client.getConceptDetails(conceptId, includeGrounding);
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(concept, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title(`📊 Concept Details: ${concept.label}`));
+        console.log((0, colors_1.separator)());
+        console.log(`\n${colors.ui.key('ID:')} ${colors.concept.id(concept.concept_id)}`);
+        if (concept.description) {
+            console.log(`${colors.ui.key('Description:')} ${colors.status.dim(concept.description)}`);
+        }
+        console.log(`${colors.ui.key('Search Terms:')} ${colors.concept.searchTerms(concept.search_terms.join(', '))}`);
+        console.log(`${colors.ui.key('Documents:')} ${colors.evidence.document(concept.documents.join(', '))}`);
+        // Display grounding with confidence-awareness (ADR-044 + grounding × confidence model)
+        if (concept.grounding_strength !== undefined || concept.grounding_display) {
+            console.log(`${colors.ui.key('Grounding:')} ${formatGroundingWithConfidence(concept.grounding_strength, concept.grounding_display, concept.confidence_level, concept.confidence_score)}`);
+        }
+        console.log('\n' + colors.ui.header(`Evidence (${concept.instances.length} instances)`));
+        console.log((0, colors_1.separator)(80, '─'));
+        concept.instances.forEach((inst, i) => {
+            console.log(`\n${colors.ui.bullet(`${i + 1}.`)} ${colors.evidence.document(inst.document)} ${colors.evidence.paragraph(`(para ${inst.paragraph})`)}`);
+            console.log(`   ${colors.evidence.quote(`"${inst.quote}"`)}`);
+        });
+        if (concept.relationships.length > 0) {
+            console.log('\n' + colors.ui.header(`Relationships (${concept.relationships.length})`));
+            console.log((0, colors_1.separator)(80, '─'));
+            concept.relationships.forEach(rel => {
+                const relColor = (0, colors_1.getRelationshipColor)(rel.rel_type);
+                const confidence = rel.confidence ? ` ${colors.status.dim(`[${(rel.confidence * 100).toFixed(0)}%]`)}` : '';
+                console.log(`  ${colors.path.arrow('→')} ${relColor(rel.rel_type)} ${colors.path.arrow('→')} ${colors.concept.label(rel.to_label)} ${colors.concept.id(`(${rel.to_id})`)}${confidence}`);
+            });
+        }
+        else {
+            console.log('\n' + colors.status.warning('⚠ No outgoing relationships'));
+        }
+        console.log();
+    }
+    catch (error) {
+        console.error(colors.status.error('✗ Failed to get concept details'));
+        console.error(colors.status.error(error.response?.data?.detail || error.message));
+        process.exit(1);
+    }
+});
+const relatedCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('related'), 'Find related concepts by graph traversal', 'Find concepts related through graph traversal (breadth-first search) - groups results by distance')
+    .showHelpAfterError()
+    .argument('<concept-id>', 'Starting concept ID for traversal')
+    .option('-d, --depth <number>', 'Maximum traversal depth in hops (1-2 fast, 3-4 moderate, 5 slow)', '2')
+    .option('-t, --types <types...>', 'Filter by relationship types (IMPLIES, ENABLES, SUPPORTS, etc. - see kg vocab list)')
+    .option('--include-epistemic <statuses...>', 'Only include relationships with these epistemic statuses (ADR-065): AFFIRMATIVE, CONTESTED, CONTRADICTORY, HISTORICAL')
+    .option('--exclude-epistemic <statuses...>', 'Exclude relationships with these epistemic statuses (ADR-065)')
+    .option('--json', 'Output raw JSON instead of formatted text for scripting')
+    .action(async (conceptId, options) => {
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const result = await client.findRelatedConcepts({
+            concept_id: conceptId,
+            max_depth: parseInt(options.depth),
+            relationship_types: options.types,
+            // ADR-065: Epistemic status filtering
+            include_epistemic_status: options.includeEpistemic,
+            exclude_epistemic_status: options.excludeEpistemic
+        });
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title(`🔗 Related Concepts from: ${conceptId}`));
+        console.log(`${colors.ui.key('Max depth:')} ${colors.path.distance(String(result.max_depth))}`);
+        console.log((0, colors_1.separator)());
+        console.log(colors.status.success(`\n✓ Found ${result.count} related concepts:\n`));
+        let currentDistance = -1;
+        result.results.forEach(concept => {
+            if (concept.distance !== currentDistance) {
+                currentDistance = concept.distance;
+                console.log('\n' + colors.path.distance(`Distance ${currentDistance}:`));
+            }
+            console.log(`  ${colors.ui.bullet('●')} ${colors.concept.label(concept.label)} ${colors.concept.id(`(${concept.concept_id})`)}`);
+            // Color-code the path by relationship types
+            const coloredPath = concept.path_types.map(type => (0, colors_1.getRelationshipColor)(type)(type)).join(colors.path.arrow(' → '));
+            console.log(`    ${colors.ui.key('Path:')} ${coloredPath}`);
+        });
+        console.log();
+    }
+    catch (error) {
+        console.error(colors.status.error('✗ Failed to find related concepts'));
+        console.error(colors.status.error(error.response?.data?.detail || error.message));
+        process.exit(1);
+    }
+});
+const connectCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('connect'), 'Find paths between two concepts', 'Find shortest path between two concepts using IDs or semantic phrase matching')
+    .showHelpAfterError()
+    .argument('<from>', 'Starting concept (exact ID or descriptive phrase - e.g., "licensing issues" not "licensing")')
+    .argument('<to>', 'Target concept (exact ID or descriptive phrase - use 2-3 word phrases for best results)')
+    .option('--max-hops <number>', 'Maximum path length', '5')
+    .option('--min-similarity <number>', 'Semantic similarity threshold for phrase matching (default 50% - lower for broader matches)', '0.5')
+    .option('--no-evidence', 'Hide evidence quotes (shown by default)')
+    .option('--no-images', 'Hide inline image display (shown by default if chafa installed)')
+    .option('--no-grounding', 'Disable grounding strength calculation (faster)')
+    .option('--download <directory>', 'Download images to specified directory instead of displaying inline')
+    .option('--json', 'Output raw JSON instead of formatted text')
+    .option('--include-epistemic <statuses...>', 'Only include relationships with these epistemic statuses (ADR-065): AFFIRMATIVE, CONTESTED, CONTRADICTORY, HISTORICAL')
+    .option('--exclude-epistemic <statuses...>', 'Exclude relationships with these epistemic statuses (ADR-065)')
+    .addHelpText('after', `
+Examples:
+  $ kg search connect concept-id-123 concept-id-456
+  $ kg search connect "licensing issues" "AGE benefits"
+  $ kg search connect "Apache AGE" "graph database" --min-similarity 0.3
+  $ kg search connect "my concept" "another concept" --show-evidence
+  $ kg search connect "concept-a" "concept-b" --include-epistemic AFFIRMATIVE
+  $ kg search connect "concept-a" "concept-b" --exclude-epistemic HISTORICAL INSUFFICIENT_DATA
+
+Notes:
+  - Generic single words ("features", "issues") may not match well
+  - Use specific 2-3 word phrases for better semantic matching
+  - Lower --min-similarity (e.g., 0.3) to find weaker concept matches
+  - Error messages suggest threshold adjustments when near-misses exist
+  - Use --include-epistemic to filter by relationship confidence level (ADR-065)
+      `)
+    .action(async (from, to, options) => {
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const config = (0, config_1.getConfig)();
+        // Use config defaults, allow CLI flags to override
+        const includeEvidence = options.evidence !== undefined ? options.evidence : config.getSearchShowEvidence();
+        const shouldShowImages = options.images !== undefined ? options.images : config.getSearchShowImages();
+        const includeGrounding = options.grounding !== false; // Default: true
+        // Auto-detect if using concept IDs (contain hyphens/underscores) or natural language
+        const isFromId = from.includes('-') || from.includes('_');
+        const isToId = to.includes('-') || to.includes('_');
+        let result;
+        let fromLabel = from;
+        let toLabel = to;
+        if (isFromId && isToId) {
+            // Both are concept IDs - use ID-based search
+            result = await client.findConnection({
+                from_id: from,
+                to_id: to,
+                max_hops: parseInt(options.maxHops),
+                include_evidence: includeEvidence,
+                include_grounding: includeGrounding,
+                // ADR-065: Epistemic status filtering
+                include_epistemic_status: options.includeEpistemic,
+                exclude_epistemic_status: options.excludeEpistemic
+            });
+        }
+        else {
+            // At least one is a natural language query - use search-based
+            result = await client.findConnectionBySearch({
+                from_query: from,
+                to_query: to,
+                max_hops: parseInt(options.maxHops),
+                threshold: parseFloat(options.minSimilarity),
+                include_evidence: includeEvidence,
+                include_grounding: includeGrounding,
+                // ADR-065: Epistemic status filtering
+                include_epistemic_status: options.includeEpistemic,
+                exclude_epistemic_status: options.excludeEpistemic
+            });
+            // Update labels with matched concepts
+            if (result.from_concept) {
+                fromLabel = `${result.from_concept.label} (matched: "${from}")`;
+            }
+            if (result.to_concept) {
+                toLabel = `${result.to_concept.label} (matched: "${to}")`;
+            }
+        }
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title('🌉 Finding Connection'));
+        console.log((0, colors_1.separator)());
+        console.log(`  ${colors.ui.key('From:')} ${colors.concept.label(fromLabel)}`);
+        if ('from_similarity' in result && result.from_similarity) {
+            console.log(`        ${colors.ui.key('Match:')} ${(0, colors_1.coloredPercentage)(result.from_similarity)}`);
+        }
+        console.log(`  ${colors.ui.key('To:')} ${colors.concept.label(toLabel)}`);
+        if ('to_similarity' in result && result.to_similarity) {
+            console.log(`        ${colors.ui.key('Match:')} ${(0, colors_1.coloredPercentage)(result.to_similarity)}`);
+        }
+        console.log(`  ${colors.ui.key('Max hops:')} ${colors.path.hop(String(result.max_hops))}\n`);
+        if (result.count === 0) {
+            console.log(colors.status.warning(`⚠ No connection found within ${result.max_hops} hops`));
+        }
+        else {
+            console.log(colors.status.success(`✓ Found ${result.count} path(s):\n`));
+            for (const [i, path] of result.paths.entries()) {
+                console.log(colors.path.distance(`Path ${i + 1}`) + colors.status.dim(` (${path.hops} hops):`));
+                for (const [j, node] of path.nodes.entries()) {
+                    console.log(`  ${colors.path.node(node.label)} ${colors.concept.id(`(${node.id})`)}`);
+                    if (node.description) {
+                        console.log(`     ${colors.status.dim(node.description)}`);
+                    }
+                    // Display grounding with confidence-awareness (ADR-044 + grounding × confidence model)
+                    if (includeGrounding && (node.grounding_strength !== undefined || node.grounding_display)) {
+                        console.log(`     ${colors.ui.key('Grounding:')} ${formatGroundingWithConfidence(node.grounding_strength, node.grounding_display, node.confidence_level, node.confidence_score)}`);
+                    }
+                    // Display sample evidence if requested
+                    if (includeEvidence && node.sample_evidence && node.sample_evidence.length > 0) {
+                        console.log(`     ${colors.ui.key('Evidence:')}`);
+                        for (const [idx, inst] of node.sample_evidence.entries()) {
+                            const truncatedQuote = inst.quote.length > 80
+                                ? inst.quote.substring(0, 80) + '...'
+                                : inst.quote;
+                            console.log(`        ${colors.ui.bullet(`${idx + 1}.`)} ${colors.evidence.document(inst.document)} ${colors.evidence.paragraph(`(para ${inst.paragraph})`)}`);
+                            console.log(`           ${colors.evidence.quote(`"${truncatedQuote}"`)}`);
+                            // ADR-057: Handle images if available
+                            if (inst.has_image && inst.source_id) {
+                                const downloadDir = options.download;
+                                if (downloadDir) {
+                                    // Download mode
+                                    try {
+                                        console.log(colors.status.dim(`           📥 Downloading image from ${inst.source_id}...`));
+                                        const imageBuffer = await client.getSourceImage(inst.source_id);
+                                        const extension = (0, terminal_images_1.detectImageFormat)(imageBuffer);
+                                        const filename = `${inst.source_id}${extension}`;
+                                        const outputPath = nodePath.join(downloadDir, filename);
+                                        if ((0, terminal_images_1.saveImageToFile)(imageBuffer, outputPath)) {
+                                            console.log(colors.status.success(`           ✓ Saved to ${outputPath}`));
+                                        }
+                                    }
+                                    catch (error) {
+                                        console.log(colors.status.error(`           ✗ Failed to download image: ${error.message}`));
+                                    }
+                                }
+                                else if (shouldShowImages && config.isChafaEnabled()) {
+                                    // Display mode
+                                    if ((0, terminal_images_1.isChafaAvailable)()) {
+                                        try {
+                                            console.log(colors.status.dim(`           🖼️  Displaying image from ${inst.source_id}...`));
+                                            const imageBuffer = await client.getSourceImage(inst.source_id);
+                                            const extension = (0, terminal_images_1.detectImageFormat)(imageBuffer);
+                                            await (0, terminal_images_1.displayImageBufferWithChafa)(imageBuffer, extension, {
+                                                width: config.getChafaWidth(),
+                                                scale: config.getChafaScale(),
+                                                align: config.getChafaAlign(),
+                                                colors: config.getChafaColors()
+                                            });
+                                        }
+                                        catch (error) {
+                                            console.log(colors.status.error(`           ✗ Failed to display image: ${error.message}`));
+                                        }
+                                    }
+                                    else {
+                                        console.log(colors.status.warning(`           🖼️  Image available (source: ${inst.source_id})`));
+                                        (0, terminal_images_1.printChafaInstallInstructions)();
+                                    }
+                                }
+                                else {
+                                    // Just indicate image is available
+                                    console.log(colors.status.dim(`           🖼️  Image available (use --show-images to display or --download <dir> to save)`));
+                                }
+                            }
+                        }
+                    }
+                    if (j < path.relationships.length) {
+                        const relType = path.relationships[j];
+                        const relColor = (0, colors_1.getRelationshipColor)(relType);
+                        console.log(`    ${colors.path.arrow('↓')} ${relColor(relType)}`);
+                    }
+                }
+                console.log();
+            }
+        }
+        console.log((0, colors_1.separator)());
+    }
+    catch (error) {
+        console.error(colors.status.error('✗ Failed to find connection'));
+        console.error(colors.status.error(error.response?.data?.detail || error.message));
+        process.exit(1);
+    }
+});
+const sourcesCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('sources'), 'Search source text by semantic similarity', 'Search source documents directly using embeddings - returns matched text with related concepts (ADR-068)')
+    .showHelpAfterError()
+    .argument('<query>', 'Search query text (searches source embeddings, not concept embeddings)')
+    .option('-l, --limit <number>', 'Maximum number of sources to return', '10')
+    .option('--min-similarity <number>', 'Minimum similarity score (0.0-1.0, default 0.7)', '0.7')
+    .option('-o, --ontology <name>', 'Filter by ontology/document name')
+    .option('--no-concepts', 'Hide concepts extracted from matched sources (shown by default)')
+    .option('--no-full-text', 'Hide full source text (shown by default)')
+    .option('--json', 'Output raw JSON instead of formatted text for scripting')
+    .action(async (query, options) => {
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const includeConcepts = options.concepts !== false; // Default: true
+        const includeFullText = options.fullText !== false; // Default: true
+        const result = await client.searchSources({
+            query,
+            limit: parseInt(options.limit),
+            min_similarity: parseFloat(options.minSimilarity),
+            ontology: options.ontology,
+            include_concepts: includeConcepts,
+            include_full_text: includeFullText
+        });
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title(`📄 Source Search: ${query}`));
+        console.log((0, colors_1.separator)());
+        console.log(colors.status.success(`\n✓ Found ${result.count} source(s):\n`));
+        for (const [i, source] of result.results.entries()) {
+            console.log(colors.ui.bullet('●') + ' ' + colors.concept.label(`${i + 1}. ${source.document} (para ${source.paragraph})`));
+            console.log(`   ${colors.ui.key('Source ID:')} ${colors.concept.id(source.source_id)}`);
+            console.log(`   ${colors.ui.key('Similarity:')} ${(0, colors_1.coloredPercentage)(source.similarity)}`);
+            if (source.is_stale) {
+                console.log(`   ${colors.status.warning('⚠ Stale embedding (source text changed)')}`);
+            }
+            // Display matched chunk
+            console.log(`   ${colors.ui.key('Matched chunk:')} ${colors.evidence.paragraph(`[${source.matched_chunk.start_offset}:${source.matched_chunk.end_offset}]`)}`);
+            const truncatedChunk = source.matched_chunk.chunk_text.length > 150
+                ? source.matched_chunk.chunk_text.substring(0, 150) + '...'
+                : source.matched_chunk.chunk_text;
+            console.log(`   ${colors.evidence.quote(`"${truncatedChunk}"`)}`);
+            // Display full text if requested
+            if (includeFullText && source.full_text) {
+                console.log(`   ${colors.ui.key('Full text:')}`);
+                const truncatedText = source.full_text.length > 200
+                    ? source.full_text.substring(0, 200) + '...'
+                    : source.full_text;
+                console.log(`      ${colors.status.dim(truncatedText)}`);
+            }
+            // Display concepts extracted from this source
+            if (includeConcepts && source.concepts && source.concepts.length > 0) {
+                console.log(`   ${colors.ui.key('Concepts:')} ${colors.status.dim(`(${source.concepts.length} extracted)`)}`);
+                for (const concept of source.concepts.slice(0, 5)) { // Show max 5 concepts
+                    console.log(`      ${colors.ui.bullet('→')} ${colors.concept.label(concept.label)} ${colors.concept.id(`(${concept.concept_id})`)}`);
+                    if (concept.description) {
+                        console.log(`         ${colors.status.dim(concept.description)}`);
+                    }
+                }
+                if (source.concepts.length > 5) {
+                    console.log(`      ${colors.status.dim(`... and ${source.concepts.length - 5} more`)}`);
+                }
+            }
+            console.log();
+        }
+    }
+    catch (error) {
+        console.error(colors.status.error('\n✗ Source search failed'));
+        if (error.response) {
+            // API returned error response
+            const status = error.response.status;
+            const detail = error.response.data?.detail || 'Unknown error';
+            console.error(colors.status.warning(`\nAPI Error (${status}): ${detail}`));
+            if (status === 500 && detail.includes('embedding')) {
+                console.error(colors.status.dim('\n💡 Suggestion: Check embedding provider configuration:'));
+                console.error(colors.status.dim('   kg admin embedding list'));
+            }
+            else if (status === 404) {
+                console.error(colors.status.dim('\n💡 Suggestion: Verify API endpoint exists (may need to update CLI)'));
+            }
+            else if (status === 401 || status === 403) {
+                console.error(colors.status.dim('\n💡 Suggestion: Check authentication:'));
+                console.error(colors.status.dim('   kg login'));
+            }
+        }
+        else if (error.request) {
+            // No response received
+            console.error(colors.status.warning('\nNo response from API server'));
+            console.error(colors.status.dim('\n💡 Suggestion: Check API is running:'));
+            console.error(colors.status.dim('   kg health'));
+        }
+        else {
+            // Request setup error
+            console.error(colors.status.warning(`\n${error.message}`));
+        }
+        process.exit(1);
+    }
+});
+// Configure colored help for all search subcommands
+[queryCommand, showCommand, relatedCommand, connectCommand, sourcesCommand].forEach(help_formatter_1.configureColoredHelp);
+exports.searchCommand = (0, help_formatter_1.setCommandHelp)(new commander_1.Command('search'), 'Search and explore the knowledge graph', 'Search and explore the knowledge graph using vector similarity, graph traversal, and path finding')
+    .showHelpAfterError('(add --help for additional information)')
+    .showSuggestionAfterError()
+    // Allow direct search: kg search <term> (shortcut for kg search query <term>)
+    .argument('[query]', 'Search query (shortcut for: kg search query <term>)')
+    .option('-l, --limit <number>', 'Maximum number of results to return', '10')
+    .option('--min-similarity <number>', 'Minimum similarity score (0.0-1.0)', '0.7')
+    .option('--json', 'Output raw JSON instead of formatted text')
+    .option('--save-artifact', 'Save result as persistent artifact (ADR-083)')
+    .action(async (query, options, command) => {
+    // If no query provided and no subcommand matched, show help
+    if (!query) {
+        command.help();
+        return;
+    }
+    // Check if query matches a subcommand name - if so, Commander already handled it
+    const subcommandNames = ['query', 'details', 'related', 'connect', 'sources'];
+    if (subcommandNames.includes(query)) {
+        // This shouldn't happen as Commander routes subcommands, but safety check
+        return;
+    }
+    // Delegate to query action for direct search shortcut
+    try {
+        const client = (0, client_1.createClientFromEnv)();
+        const config = (0, config_1.getConfig)();
+        const result = await client.searchConcepts({
+            query,
+            limit: parseInt(options.limit),
+            min_similarity: parseFloat(options.minSimilarity),
+            include_evidence: config.getSearchShowEvidence(),
+            include_grounding: true,
+            include_diversity: true,
+            diversity_max_hops: 2
+        });
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\n' + (0, colors_1.separator)());
+        console.log(colors.ui.title(`🔍 Searching for: ${query}`));
+        console.log((0, colors_1.separator)());
+        console.log(colors.status.success(`\n✓ Found ${result.count} concepts:\n`));
+        for (const [i, concept] of result.results.entries()) {
+            console.log(colors.ui.bullet('●') + ' ' + colors.concept.label(`${i + 1}. ${concept.label}`));
+            if (concept.description) {
+                console.log(`   ${colors.status.dim(concept.description)}`);
+            }
+            console.log(`   ${colors.ui.key('ID:')} ${colors.concept.id(concept.concept_id)}`);
+            console.log(`   ${colors.ui.key('Similarity:')} ${(0, colors_1.coloredPercentage)(concept.score)}`);
+            console.log(`   ${colors.ui.key('Documents:')} ${colors.evidence.document(concept.documents.join(', '))}`);
+            console.log(`   ${colors.ui.key('Evidence:')} ${colors.evidence.count(String(concept.evidence_count))} instances`);
+            // Display grounding with confidence-awareness
+            if (concept.grounding_strength !== undefined || concept.grounding_display) {
+                console.log(`   ${colors.ui.key('Grounding:')} ${formatGroundingWithConfidence(concept.grounding_strength, concept.grounding_display, concept.confidence_level, concept.confidence_score)}`);
+            }
+            // Display diversity if available
+            if (concept.diversity_score !== undefined && concept.diversity_score !== null && concept.diversity_related_count !== undefined) {
+                console.log(`   ${colors.ui.key('Diversity:')} ${formatDiversity(concept.diversity_score, concept.diversity_related_count)}`);
+            }
+            // Display authenticated diversity if available
+            if (concept.authenticated_diversity !== undefined && concept.authenticated_diversity !== null) {
+                console.log(`   ${colors.ui.key('Authenticated:')} ${formatAuthenticatedDiversity(concept.authenticated_diversity)}`);
+            }
+            console.log();
+        }
+        // Show hint if additional results available below threshold
+        if (result.below_threshold_count && result.below_threshold_count > 0 && result.suggested_threshold) {
+            const thresholdPercent = (result.suggested_threshold * 100).toFixed(0);
+            console.log(colors.status.warning(`💡 ${result.below_threshold_count} additional concept${result.below_threshold_count > 1 ? 's' : ''} available at ${thresholdPercent}% threshold`));
+            console.log(colors.status.dim(`   Try: kg search "${query}" --min-similarity ${result.suggested_threshold}\n`));
+        }
+        // ADR-083: Save result as artifact if requested
+        if (options.saveArtifact && result.count > 0) {
+            try {
+                const artifactResult = await client.createArtifact({
+                    artifact_type: 'search_result',
+                    representation: 'cli',
+                    name: `Search: "${query}" (${result.count} results)`,
+                    parameters: {
+                        query,
+                        limit: parseInt(options.limit),
+                        min_similarity: parseFloat(options.minSimilarity),
+                        include_evidence: config.getSearchShowEvidence(),
+                        include_grounding: true,
+                        include_diversity: true,
+                        diversity_max_hops: 2
+                    },
+                    payload: result
+                });
+                console.log(colors.status.success(`✓ Artifact saved: ${artifactResult.id}`));
+                console.log(colors.status.dim(`  View: kg artifact show ${artifactResult.id}`));
+            }
+            catch (artifactError) {
+                console.error(colors.status.error(`✗ Failed to save artifact: ${artifactError.message}`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(colors.status.error('✗ Search failed'));
+        console.error(colors.status.error(error.response?.data?.detail || error.message));
+        process.exit(1);
+    }
+})
+    .addCommand(queryCommand)
+    .addCommand(showCommand)
+    .addCommand(relatedCommand)
+    .addCommand(connectCommand)
+    .addCommand(sourcesCommand);
+//# sourceMappingURL=search.js.map