@neurcode-ai/cli 0.9.26 → 0.9.27

package/dist/commands/ask.js

@@ -27,60 +27,269 @@ catch {
     };
 }
 const MAX_SCAN_FILES = (() => {
-    const raw = Number(process.env.NEURCODE_ASK_MAX_SCAN_FILES || '900');
+    const raw = Number(process.env.NEURCODE_ASK_MAX_SCAN_FILES || '2200');
     if (!Number.isFinite(raw))
-        return 900;
-    return Math.max(120, Math.min(Math.trunc(raw), 2000));
+        return 2200;
+    return Math.max(300, Math.min(Math.trunc(raw), 8000));
 })();
 const MAX_FILE_BYTES = 512 * 1024;
-const MAX_RAW_CITATIONS = 120;
-const PRIMARY_SOURCE_EXTENSIONS = new Set([
-    'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs',
-    'py', 'go', 'rs', 'java', 'kt', 'swift', 'rb', 'php', 'cs',
-    'json', 'yaml', 'yml', 'toml', 'md', 'sql', 'graphql', 'gql',
-    'sh', 'bash', 'zsh', 'ps1', 'env', 'html', 'css', 'scss', 'less', 'prisma',
+const MAX_RAW_CITATIONS = 220;
+const RG_MAX_MATCHES = 3500;
+const FETCH_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.NEURCODE_ASK_EXTERNAL_TIMEOUT_MS || '9000');
+    if (!Number.isFinite(raw))
+        return 9000;
+    return Math.max(3000, Math.min(Math.trunc(raw), 30000));
+})();
+const REPO_SCOPE_TERMS = new Set([
+    'repo', 'repository', 'codebase', 'file', 'files', 'path', 'paths', 'module', 'modules',
+    'function', 'class', 'interface', 'type', 'schema', 'command', 'commands', 'flag', 'option',
+    'middleware', 'route', 'service', 'api', 'org', 'organization', 'tenant', 'tenancy',
+    'plan', 'verify', 'ask', 'ship', 'apply', 'watch', 'session', 'cache', 'brain', 'diff',
+]);
+const EXTERNAL_WORLD_TERMS = new Set([
+    'capital', 'population', 'gdp', 'weather', 'temperature', 'forecast', 'stock', 'price',
+    'exchange', 'currency', 'president', 'prime minister', 'news', 'election', 'sports',
+    'bitcoin', 'btc', 'ethereum', 'eth', 'usd', 'eur', 'inr', 'jpy',
+    'fifa', 'world cup', 'olympics', 'cricket', 'nba', 'nfl',
 ]);
 const STOP_WORDS = new Set([
-    'the', 'and', 'for', 'with', 'that', 'this', 'what', 'where', 'when', 'which', 'into',
+    'the', 'and', 'for', 'with', 'that', 'this', 'what', 'where', 'when', 'which',
     'from', 'your', 'about', 'there', 'their', 'them', 'have', 'does', 'is', 'are', 'was',
-    'were', 'any', 'all', 'read', 'tell', 'me', 'its', 'it', 'instead', 'than', 'then',
-    'workflow', 'codebase', 'repo', 'repository', 'used', 'use', 'mentioned', 'mention', 'whether',
-    'list', 'show', 'like', 'can', 'type', 'types', 'using', 'etc', 'cmd', 'cmds', 'command', 'commands',
-    'system', 'platform', 'latest', 'package', 'packages',
+    'were', 'any', 'all', 'tell', 'me', 'its', 'it', 'than', 'then', 'workflow', 'codebase',
+    'repo', 'repository', 'used', 'use', 'using', 'list', 'show', 'like', 'can', 'type',
+    'types', 'package', 'packages', 'give', 'need', 'please', 'how', 'work', 'works', 'working',
 ]);
 const LOW_SIGNAL_TERMS = new Set([
-    'used', 'use', 'using', 'mentioned', 'mention', 'where', 'tell', 'read', 'check', 'find', 'search',
-    'workflow', 'repo', 'repository', 'codebase', 'anywhere', 'can', 'type', 'types', 'list', 'show', 'like',
-    'neurcode', 'cli', 'ask', 'file', 'files', 'path', 'filepath', 'header', 'added', 'add', 'request', 'requests',
-    'flag', 'flags', 'option', 'options',
-    'defined', 'define', 'implemented', 'implement', 'called', 'call', 'computed', 'compute', 'resolved', 'resolve',
-    'lookup', 'lookups', 'decide', 'decides',
+    'used', 'use', 'using', 'where', 'tell', 'read', 'check', 'find', 'search',
+    'workflow', 'repo', 'repository', 'codebase', 'anywhere', 'can', 'type', 'types',
+    'list', 'show', 'like', 'neurcode', 'cli', 'file', 'files', 'path', 'paths',
+    'resolved', 'resolve', 'defined', 'define', 'implemented', 'implement', 'called', 'call',
+    'how', 'work', 'works', 'working',
+]);
+const SUBCOMMAND_STOP_TERMS = new Set([
+    'command', 'commands', 'subcommand', 'subcommands',
+    'option', 'options', 'flag', 'flags',
+    'what', 'where', 'when', 'why', 'who', 'which', 'how',
+    'does', 'do', 'did', 'can', 'could', 'should', 'would', 'will',
+    'work', 'works', 'working', 'flow', 'trace', 'compute', 'computed',
+    'implementation', 'implement', 'internals', 'logic', 'behavior', 'behaviour',
 ]);
-const GENERIC_OUTPUT_TERMS = new Set(['file', 'files', 'path', 'filepath']);
-const REPO_SCOPE_TERMS = [
-    'repo', 'repository', 'codebase', 'neurcode', 'cli', 'command', 'commands', 'ship', 'plan', 'ask', 'verify',
-    'apply', 'watch', 'config', 'login', 'logout', 'whoami', 'doctor', 'module', 'file', 'files', 'path',
-    'middleware', 'api', 'service', 'services', 'branch', 'commit', 'cache', 'brain', 'org', 'organization',
-    'tenant', 'tenancy', 'x-org-id', 'readme', 'docs',
-];
-const EXTERNAL_WORLD_TERMS = [
-    'capital', 'exchange rate', 'stock price', 'weather', 'temperature', 'forecast', 'news', 'election',
-    'president', 'prime minister', 'population', 'gdp', 'sports score', 'match result', 'bitcoin price',
-    'usd', 'inr', 'eur', 'jpy', 'currency',
-];
-const REALTIME_WORLD_TERMS = ['right now', 'currently', 'today', 'tomorrow', 'yesterday', 'live', 'real time'];
 const CLI_COMMAND_NAMES = new Set([
     'check', 'refactor', 'security', 'brain', 'login', 'logout', 'init', 'doctor',
     'whoami', 'config', 'map', 'ask', 'plan', 'ship', 'apply', 'allow', 'watch',
     'session', 'verify', 'prompt', 'revert',
 ]);
+function normalizeFilePath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function isIgnoredSearchPath(path) {
+    const normalized = normalizeFilePath(path).toLowerCase();
+    if (!normalized)
+        return true;
+    if (normalized.startsWith('dist/') ||
+        normalized.includes('/dist/') ||
+        normalized.startsWith('build/') ||
+        normalized.includes('/build/') ||
+        normalized.startsWith('out/') ||
+        normalized.includes('/out/') ||
+        normalized.startsWith('.next/') ||
+        normalized.includes('/.next/')) {
+        return true;
+    }
+    if (normalized.includes('.pnpm-store/') ||
+        normalized.startsWith('node_modules/') ||
+        normalized.includes('/node_modules/') ||
+        normalized.startsWith('.git/') ||
+        normalized.includes('/.git/') ||
+        normalized.startsWith('.neurcode/') ||
+        normalized.includes('/.neurcode/') ||
+        normalized.includes('/coverage/') ||
+        normalized.includes('/.cache/') ||
+        normalized.endsWith('.min.js') ||
+        normalized.endsWith('.map')) {
+        return true;
+    }
+    return false;
+}
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizeSnippet(line) {
+    return line
+        .replace(/\t/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 260);
+}
+function buildQueryProfile(searchTerms) {
+    const normalizedQuestion = searchTerms.normalizedQuestion;
+    const commandFocus = detectCommandFocus(normalizedQuestion);
+    return {
+        asksLocation: /\b(where|which file|location|defined|implemented|called|computed|resolved)\b/.test(normalizedQuestion),
+        asksHow: /\b(how|flow|trace|explain|why)\b/.test(normalizedQuestion),
+        asksList: /\b(list|show|which|what)\b/.test(normalizedQuestion),
+        asksRegistration: /\b(register|registered|registration|mapped|wired|hooked)\b/.test(normalizedQuestion),
+        codeFocused: /\b(command|commands|flag|option|api|middleware|route|service|class|function|interface|type|schema|field|cache|tenant|org|auth|verify|plan|apply|ship)\b/.test(normalizedQuestion),
+        commandFocus,
+        subcommandFocus: detectSubcommandFocus(normalizedQuestion, commandFocus),
+        highSignalSet: new Set(searchTerms.highSignalTerms.map((term) => term.toLowerCase())),
+    };
+}
+function isLikelyDocumentationPath(path) {
+    const normalized = normalizeFilePath(path).toLowerCase();
+    if (!normalized)
+        return false;
+    if (normalized === 'readme.md' || normalized.endsWith('/readme.md'))
+        return true;
+    if (normalized.startsWith('docs/') || normalized.includes('/docs/'))
+        return true;
+    if (normalized.includes('/documentation/'))
+        return true;
+    if (normalized.includes('/sitemap'))
+        return true;
+    if (normalized.endsWith('.md') || normalized.endsWith('.mdx'))
+        return true;
+    return false;
+}
+function isLikelyCodeSnippet(snippet) {
+    const value = snippet.trim();
+    if (!value)
+        return false;
+    if (/^\s*\/[/*]/.test(value))
+        return true;
+    if (/[{}();=]/.test(value))
+        return true;
+    if (/\b(import|export|const|let|var|function|class|interface|type|enum|return|await|if|else|switch|case|try|catch|throw)\b/.test(value)) {
+        return true;
+    }
+    if (/\b[a-zA-Z_][a-zA-Z0-9_]*\s*\(/.test(value))
+        return true;
+    if (/\.\w+\(/.test(value))
+        return true;
+    if (/=>/.test(value))
+        return true;
+    return false;
+}
+function isLikelyDocSnippet(snippet) {
+    const value = snippet.trim();
+    if (!value)
+        return false;
+    if (/^<\w+/.test(value) || /<\/\w+>/.test(value))
+        return true;
+    if (/\b(className|href|to: ['"]\/docs\/|#ask-command)\b/.test(value))
+        return true;
+    if (/^#{1,6}\s/.test(value))
+        return true;
+    if (/^[-*]\s/.test(value))
+        return true;
+    return false;
+}
+function isPromptExampleSnippet(snippet, normalizedQuestion, highSignalTerms) {
+    const snippetLower = snippet.toLowerCase();
+    if (!snippetLower)
+        return false;
+    if (/\bneurcode\s+(ask|plan|verify|ship|apply)\s+["`]/i.test(snippet))
+        return true;
+    if (snippetLower.includes('?') && /\b(where|what|how|why|which)\b/.test(snippetLower)) {
+        const overlaps = highSignalTerms.filter((term) => term && snippetLower.includes(term.toLowerCase())).length;
+        if (overlaps >= Math.min(3, Math.max(2, highSignalTerms.length)))
+            return true;
+    }
+    const normalizedSnippet = (0, plan_cache_1.normalizeIntent)(snippetLower);
+    if (normalizedQuestion.length >= 24 && normalizedSnippet.includes(normalizedQuestion.slice(0, 28))) {
+        return true;
+    }
+    return false;
+}
+function tokenizeQuestion(question) {
+    return (0, plan_cache_1.normalizeIntent)(question)
+        .replace(/[^a-z0-9_\-\s]/g, ' ')
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3 && !STOP_WORDS.has(token));
+}
+function extractQuotedPhrases(question) {
+    const out = [];
+    const seen = new Set();
+    const re = /["'`](.{2,100}?)["'`]/g;
+    for (const match of question.matchAll(re)) {
+        const value = (0, plan_cache_1.normalizeIntent)(match[1] || '').trim();
+        if (!value || seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+function extractCodeIdentifiers(question) {
+    const matches = question.match(/[A-Za-z_][A-Za-z0-9_\-]{2,}/g) || [];
+    const out = [];
+    const seen = new Set();
+    for (const token of matches) {
+        const normalized = token.trim();
+        const key = normalized.toLowerCase();
+        if (!normalized || STOP_WORDS.has(key))
+            continue;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(normalized);
+    }
+    return out.slice(0, 16);
+}
+function buildSearchTerms(question) {
+    const normalizedQuestion = (0, plan_cache_1.normalizeIntent)(question);
+    const tokens = tokenizeQuestion(question);
+    const quotedPhrases = extractQuotedPhrases(question);
+    const identifiers = extractCodeIdentifiers(question);
+    const highSignalTerms = tokens
+        .filter((token) => !LOW_SIGNAL_TERMS.has(token))
+        .slice(0, 18);
+    const phraseTerms = [];
+    for (let i = 0; i < highSignalTerms.length - 1; i++) {
+        const phrase = `${highSignalTerms[i]} ${highSignalTerms[i + 1]}`;
+        if (phrase.length >= 7)
+            phraseTerms.push(phrase);
+        if (phraseTerms.length >= 8)
+            break;
+    }
+    const all = [
+        ...quotedPhrases,
+        ...identifiers,
+        ...highSignalTerms,
+        ...phraseTerms,
+    ];
+    const seen = new Set();
+    const rgTerms = [];
+    for (const term of all) {
+        const normalized = (0, plan_cache_1.normalizeIntent)(term).trim();
+        if (!normalized)
+            continue;
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        rgTerms.push(normalized);
+    }
+    return {
+        normalizedQuestion,
+        tokens,
+        highSignalTerms,
+        quotedPhrases,
+        identifiers,
+        rgTerms: rgTerms.slice(0, 22),
+    };
+}
 function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
     const files = [];
     const ignoreDirs = new Set([
-        'node_modules', '.git', '.next', 'dist', 'build', '.turbo', '.cache', 'coverage',
-        '.neurcode', '.vscode', '.pnpm-store', '.npm', '.yarn',
+        'node_modules', '.git', '.next', 'dist', 'build', '.turbo', '.cache',
+        'coverage', '.neurcode', '.vscode', '.pnpm-store', '.yarn', '.npm',
+    ]);
+    const ignoreExts = new Set([
+        'map', 'log', 'lock', 'png', 'jpg', 'jpeg', 'gif', 'ico', 'svg',
+        'woff', 'woff2', 'ttf', 'eot', 'pdf',
     ]);
-    const ignoreExts = new Set(['map', 'log', 'lock', 'png', 'jpg', 'jpeg', 'gif', 'ico', 'svg', 'woff', 'woff2', 'ttf', 'eot', 'pdf']);
     const walk = (current) => {
         if (files.length >= maxFiles)
             return;
@@ -94,10 +303,6 @@ function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
         for (const entry of entries) {
             if (files.length >= maxFiles)
                 break;
-            if (entry.startsWith('.') && !entry.startsWith('.env')) {
-                if (ignoreDirs.has(entry))
-                    continue;
-            }
             const fullPath = (0, path_1.join)(current, entry);
             let st;
             try {
@@ -109,6 +314,8 @@ function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
             if (st.isDirectory()) {
                 if (ignoreDirs.has(entry))
                     continue;
+                if (entry.startsWith('.') && entry !== '.env')
+                    continue;
                 walk(fullPath);
                 continue;
             }
@@ -119,374 +326,103 @@ function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
             const ext = entry.includes('.') ? entry.split('.').pop()?.toLowerCase() || '' : '';
             if (ext && ignoreExts.has(ext))
                 continue;
-            const rel = fullPath.slice(dir.length + 1).replace(/\\/g, '/');
+            const rel = normalizeFilePath(fullPath.slice(dir.length + 1));
             files.push(rel);
         }
     };
     walk(dir);
     return files.slice(0, maxFiles);
 }
-function tokenizeQuestion(question) {
-    return (0, plan_cache_1.normalizeIntent)(question)
-        .replace(/[^a-z0-9_\-\s]/g, ' ')
-        .split(/\s+/)
-        .map((token) => token.trim())
-        .filter((token) => token.length >= 3 && !STOP_WORDS.has(token));
-}
-function escapeRegExp(input) {
-    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function normalizeTerm(raw) {
-    const normalized = raw
-        .toLowerCase()
-        .replace(/['"`]/g, '')
-        .replace(/[^a-z0-9_\-\s]/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim();
-    if (!normalized)
-        return '';
-    return normalized
-        .split(' ')
-        .map((token) => token.replace(/^[-_]+|[-_]+$/g, ''))
-        .filter(Boolean)
-        .join(' ');
-}
-function extractQuotedTerms(question) {
-    const seen = new Set();
-    const terms = [];
-    const re = /["'`](.{2,80}?)["'`]/g;
-    for (const match of question.matchAll(re)) {
-        const term = normalizeTerm(match[1] || '');
-        if (!term || seen.has(term))
-            continue;
-        seen.add(term);
-        terms.push(term);
-    }
-    return terms;
-}
-function extractIdentityTerms(question) {
-    const normalized = (0, plan_cache_1.normalizeIntent)(question);
-    const matches = normalized.match(/(?:organization[\s_-]*id|org[\s_-]*id|orgid|organizationid|user[\s_-]*id|userid|userid)/g);
-    if (!matches)
-        return [];
-    const seen = new Set();
-    const ordered = [];
-    for (const raw of matches) {
-        const term = normalizeTerm(raw);
-        if (seen.has(term))
-            continue;
-        seen.add(term);
-        ordered.push(term);
-    }
-    return ordered;
-}
-function extractComparisonTerms(question) {
-    const quoted = extractQuotedTerms(question);
-    if (quoted.length >= 2)
-        return quoted.slice(0, 2);
-    const normalized = (0, plan_cache_1.normalizeIntent)(question);
-    const hasComparisonJoiner = normalized.includes('instead of') ||
-        normalized.includes(' versus ') ||
-        normalized.includes(' vs ') ||
-        normalized.includes(' compared to ');
-    if (!hasComparisonJoiner)
-        return [];
-    const identities = extractIdentityTerms(question);
-    if (identities.length >= 2)
-        return identities.slice(0, 2);
-    return [];
-}
-function extractPhraseTerms(question, maxTerms = 6) {
-    const tokens = (0, plan_cache_1.normalizeIntent)(question)
-        .replace(/[^a-z0-9_\-\s]/g, ' ')
-        .split(/\s+/)
-        .map((token) => token.trim())
-        .filter((token) => token.length >= 3 && !STOP_WORDS.has(token) && !LOW_SIGNAL_TERMS.has(token));
-    const phrases = [];
-    const seen = new Set();
-    for (let i = 0; i < tokens.length - 1; i++) {
-        const phrase = `${tokens[i]} ${tokens[i + 1]}`;
-        if (seen.has(phrase))
-            continue;
-        seen.add(phrase);
-        phrases.push(phrase);
-        if (phrases.length >= maxTerms)
-            break;
-    }
-    return phrases;
-}
-function buildTermMatchers(term, weight) {
-    const normalized = normalizeTerm(term);
-    if (!normalized)
-        return [];
-    const tokens = normalized.split(/\s+/).filter(Boolean);
-    const out = [];
-    const push = (label, regexSource) => {
-        out.push({
-            label,
-            regex: new RegExp(regexSource, 'i'),
-            weight,
-        });
-    };
-    if (tokens.length === 1) {
-        const token = escapeRegExp(tokens[0]);
-        push(normalized, `\\b${token}\\b`);
-        if (/^[a-z0-9_]+$/.test(tokens[0]) && tokens[0].length >= 5) {
-            push(normalized, `\\b${token}[a-z0-9_]*\\b`);
-            push(normalized, `\\b[a-z0-9_]*${token}[a-z0-9_]*\\b`);
-        }
-        return out;
-    }
-    const tokenChain = tokens.map((t) => escapeRegExp(t)).join('[\\s_-]*');
-    push(normalized, `\\b${tokenChain}\\b`);
-    push(normalized, `\\b${escapeRegExp(tokens.join(''))}\\b`);
-    push(normalized, `\\b${escapeRegExp(tokens.join('_'))}\\b`);
-    push(normalized, `\\b${escapeRegExp(tokens.join('-'))}\\b`);
-    return out;
-}
-function expandSearchTerms(terms) {
-    const expanded = new Set();
-    for (const rawTerm of terms) {
-        const term = normalizeTerm(rawTerm);
-        if (!term)
+function countTermHits(text, terms) {
+    if (!text || terms.length === 0)
+        return 0;
+    let hits = 0;
+    const lower = text.toLowerCase();
+    for (const term of terms) {
+        const normalized = term.toLowerCase().trim();
+        if (!normalized)
             continue;
-        expanded.add(term);
-        if (term.includes(' ')) {
+        if (normalized.includes(' ')) {
+            if (lower.includes(normalized))
+                hits += 1;
             continue;
         }
-        if (term.endsWith('ies') && term.length > 4) {
-            expanded.add(`${term.slice(0, -3)}y`);
-        }
-        if (term.endsWith('s') && term.length > 3) {
-            expanded.add(term.slice(0, -1));
-        }
-        else if (term.length > 3) {
-            expanded.add(`${term}s`);
-        }
-        if (term.endsWith('ing') && term.length > 5) {
-            expanded.add(term.slice(0, -3));
-        }
-        if (term.endsWith('ed') && term.length > 4) {
-            expanded.add(term.slice(0, -2));
-        }
-        if (term.includes('-')) {
-            expanded.add(term.replace(/-/g, ' '));
-            expanded.add(term.replace(/-/g, ''));
-        }
-        if (term.endsWith('cache')) {
-            expanded.add(`${term}d`);
-        }
-        if (term.endsWith('cached')) {
-            expanded.add(term.slice(0, -1)); // cached -> cache
-        }
-        if (term.includes('cache') && term.includes('-')) {
-            expanded.add(term.replace(/cache\b/, 'cached'));
-            expanded.add(term.replace(/cached\b/, 'cache'));
-        }
+        const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
+        if (pattern.test(lower))
+            hits += 1;
     }
-    return [...expanded];
+    return hits;
 }
-function buildMatchers(question) {
-    const comparisonTerms = extractComparisonTerms(question);
-    if (comparisonTerms.length >= 2) {
-        const matchers = [
-            ...buildTermMatchers(comparisonTerms[0], 1.0),
-            ...buildTermMatchers(comparisonTerms[1], 0.9),
-        ];
+function classifyQuestionScope(question, terms) {
+    const normalized = terms.normalizedQuestion;
+    const repoSignal = countTermHits(normalized, [...REPO_SCOPE_TERMS]);
+    const externalSignal = countTermHits(normalized, [...EXTERNAL_WORLD_TERMS]);
+    const hasCodeLikeSyntax = /[`][^`]+[`]/.test(question) ||
+        /\b[a-z0-9_\-/]+\.(ts|tsx|js|jsx|py|go|java|rb|php|cs|json|yml|yaml|toml|sql|md)\b/i.test(question) ||
+        /\b[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(question) ||
+        /--[a-z0-9-]+/i.test(question);
+    const mentionsKnownCommand = [...CLI_COMMAND_NAMES].some((cmd) => new RegExp(`\\b${escapeRegExp(cmd)}\\b`, 'i').test(normalized));
+    const asksGlobalFact = /\b(capital|population|gdp|weather|forecast|stock|currency|exchange rate|president|prime minister|who is|who was|who won|what is|where is|when did|world cup|olympics|fifa|nba|nfl|cricket)\b/.test(normalized);
+    if ((externalSignal >= 1 || asksGlobalFact) && repoSignal === 0 && !hasCodeLikeSyntax && !mentionsKnownCommand) {
         return {
-            mode: 'comparison',
-            terms: comparisonTerms.slice(0, 2),
-            matchers,
+            kind: 'external',
+            reasons: ['Question appears to be outside repository scope.'],
         };
     }
-    const quoted = extractQuotedTerms(question);
-    const identityTerms = extractIdentityTerms(question);
-    const phraseTerms = extractPhraseTerms(question);
-    const keywords = tokenizeQuestion(question).slice(0, 8);
-    const quotedSet = new Set(quoted.map((term) => normalizeTerm(term)));
-    const baseTerms = [...new Set([...quoted, ...phraseTerms, ...identityTerms, ...keywords].map(normalizeTerm).filter(Boolean))];
-    const filteredTerms = baseTerms.filter((term) => quotedSet.has(term) || !LOW_SIGNAL_TERMS.has(term));
-    const terms = expandSearchTerms(filteredTerms.length > 0 ? filteredTerms : baseTerms).filter(Boolean);
-    const matchers = terms.flatMap((term) => buildTermMatchers(term, quoted.includes(term) ? 0.9 : 0.55));
-    return {
-        mode: 'search',
-        terms,
-        matchers,
-    };
-}
-function derivePathHints(question) {
-    const normalized = (0, plan_cache_1.normalizeIntent)(question);
-    const hints = [];
-    if (/\bcli|command|terminal\b/.test(normalized)) {
-        hints.push('packages/cli/src/commands/');
-        hints.push('packages/cli/src/');
-        hints.push('packages/cli/');
-    }
-    if (/\bapi|backend|server|route|middleware\b/.test(normalized)) {
-        hints.push('services/api/');
-    }
-    if (/\bdashboard|landing|docs|frontend|ui|pricing\b/.test(normalized)) {
-        hints.push('web/dashboard/');
-        hints.push('docs/');
-        hints.push('README.md');
-    }
-    if (/\bfeature|capabilit|offer|platform\b/.test(normalized)) {
-        hints.push('docs/');
-        hints.push('README.md');
-    }
-    if (/\binstall|setup|upgrade|update\b/.test(normalized)) {
-        hints.push('README.md');
-        hints.push('docs/');
-        hints.push('packages/cli/');
-    }
-    if (/\btenant|tenancy|single|multi|organization|org\b/.test(normalized)) {
-        hints.push('services/api/src/lib/');
-        hints.push('services/api/src/routes/');
-        hints.push('packages/cli/src/');
-    }
-    if (/\brequest|requests|header|inject|injected\b/.test(normalized)) {
-        hints.push('packages/cli/src/api-client.ts');
-        hints.push('services/api/src/middleware/');
-    }
-    if (/(github action|\bci\b)/.test(normalized)) {
-        hints.push('.github/workflows/');
-        hints.push('packages/action/');
-        hints.push('actions/');
-    }
-    return [...new Set(hints)];
-}
-function extractCodeLikeIdentifiers(question) {
-    const quoted = extractQuotedTerms(question);
-    const tokens = question.match(/[A-Za-z_][A-Za-z0-9_]{2,}/g) || [];
-    const seen = new Set();
-    const output = [];
-    for (const raw of [...quoted, ...tokens]) {
-        const normalized = raw.trim();
-        if (!normalized)
-            continue;
-        const key = normalized.toLowerCase();
-        if (STOP_WORDS.has(key) || LOW_SIGNAL_TERMS.has(key))
-            continue;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        output.push(normalized);
+    if (repoSignal > 0 || hasCodeLikeSyntax || mentionsKnownCommand) {
+        return { kind: 'repo', reasons: [] };
     }
-    return output.slice(0, 8);
-}
-function deriveQuerySignals(question, normalizedQuestion, terms) {
-    const asksLocation = /\b(where|which file|in which file|filepath|file path|location)\b/.test(normalizedQuestion);
-    const asksHow = /\b(how|flow|trace|walk me through|explain)\b/.test(normalizedQuestion);
-    const asksCommandSurface = /\b(command|commands|subcommand|subcommands|flag|flags|option|options)\b/.test(normalizedQuestion);
-    const asksSchema = /\b(field|fields|key|keys|schema|interface|input|output|parameter|parameters)\b/.test(normalizedQuestion);
-    const asksList = /\b(list|show|which|available)\b/.test(normalizedQuestion) &&
-        /\b(command|commands|subcommand|subcommands|files|fields|features)\b/.test(normalizedQuestion);
-    const asksDefinition = /\b(defined|implemented|called|computed|resolved)\b/.test(normalizedQuestion);
-    const identifiers = extractCodeLikeIdentifiers(question);
-    const highSignalTerms = terms.filter((term) => !LOW_SIGNAL_TERMS.has(term) && term.length >= 3);
     return {
-        asksLocation,
-        asksHow,
-        asksList,
-        asksDefinition,
-        asksCommandSurface,
-        asksSchema,
-        identifiers,
-        highSignalTerms,
+        kind: 'ambiguous',
+        reasons: ['Question does not clearly reference repository context.'],
     };
 }
-function extractAnchorTerms(question) {
-    const quoted = extractQuotedTerms(question);
-    const special = (question.match(/[A-Za-z0-9_-]{4,}/g) || []).filter((token) => /[_-]/.test(token) || /[A-Z]/.test(token));
-    const normalized = [...new Set([...quoted, ...special].map(normalizeTerm).filter(Boolean))]
-        .filter((term) => !STOP_WORDS.has(term) && !LOW_SIGNAL_TERMS.has(term));
-    return expandSearchTerms(normalized).slice(0, 12);
-}
-function looksLikeImportLine(rawLine) {
-    const trimmed = rawLine.trim();
-    return /^import\s+/.test(trimmed) || /^export\s+\{/.test(trimmed);
-}
-function countQuestionTermHits(normalizedQuestion, terms) {
-    let hits = 0;
-    const seen = new Set();
-    for (const term of terms) {
-        const normalizedTerm = term.toLowerCase().trim();
-        if (!normalizedTerm || seen.has(normalizedTerm))
-            continue;
-        seen.add(normalizedTerm);
-        if (normalizedTerm.includes(' ')) {
-            if (!normalizedQuestion.includes(normalizedTerm))
-                continue;
-            hits += 1;
-            continue;
-        }
-        const boundaryPattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalizedTerm)}(?:$|[^a-z0-9])`);
-        if (boundaryPattern.test(normalizedQuestion)) {
-            hits += 1;
-        }
+function detectCommandFocus(normalizedQuestion) {
+    const compound = normalizedQuestion.match(/\b([a-z][a-z0-9-]*)\s+([a-z][a-z0-9-]*)\s+command\b/);
+    if (compound?.[1] && CLI_COMMAND_NAMES.has(compound[1])) {
+        return compound[1];
     }
-    return hits;
+    const direct = normalizedQuestion.match(/\bneurcode\s+([a-z][a-z0-9-]*)\b/);
+    if (direct?.[1] && CLI_COMMAND_NAMES.has(direct[1])) {
+        return direct[1];
+    }
+    const singular = normalizedQuestion.match(/\b([a-z][a-z0-9-]*)\s+command\b/);
+    if (singular?.[1] && CLI_COMMAND_NAMES.has(singular[1])) {
+        return singular[1];
+    }
+    const mentioned = [...CLI_COMMAND_NAMES].filter((cmd) => new RegExp(`\\b${escapeRegExp(cmd)}\\b`, 'i').test(normalizedQuestion));
+    if (mentioned.length === 1)
+        return mentioned[0];
+    return null;
 }
-function assessQuestionScope(normalizedQuestion) {
-    const repoHits = countQuestionTermHits(normalizedQuestion, REPO_SCOPE_TERMS);
-    const externalHits = countQuestionTermHits(normalizedQuestion, EXTERNAL_WORLD_TERMS);
-    const realtimeHits = countQuestionTermHits(normalizedQuestion, REALTIME_WORLD_TERMS);
-    const currencyPairPattern = /\b[a-z]{3}\s*(?:to|\/)\s*[a-z]{3}\b/;
-    const hasCurrencyPair = currencyPairPattern.test(normalizedQuestion);
-    const hasWorldEntity = /\b(france|india|usa|united states|china|germany|europe|asia|africa)\b/.test(normalizedQuestion);
-    const looksExternal = hasCurrencyPair ||
-        externalHits > 0 ||
-        (hasWorldEntity && /\bcapital|population|gdp|president|prime minister\b/.test(normalizedQuestion)) ||
-        (realtimeHits > 0 && /\bexchange rate|weather|stock|price|news|capital|population\b/.test(normalizedQuestion));
-    if (looksExternal && repoHits === 0) {
-        const reasons = ['This question appears to require external world knowledge rather than repository evidence.'];
-        if (hasCurrencyPair) {
-            reasons.push('Detected a currency/exchange-rate query, which is outside repo-grounded scope.');
-        }
-        if (realtimeHits > 0) {
-            reasons.push('Detected real-time wording (for example "right now"/"currently"), which is not answerable from local files.');
-        }
-        return { isOutOfScope: true, reasons };
-    }
-    return { isOutOfScope: false, reasons: [] };
+function isLikelySubcommandToken(value, options) {
+    const token = (0, plan_cache_1.normalizeIntent)(value).trim().toLowerCase();
+    if (!token || token.length < 3)
+        return false;
+    if (!/^[a-z][a-z0-9-]*$/.test(token))
+        return false;
+    if (!options?.allowKnownCommand && CLI_COMMAND_NAMES.has(token))
+        return false;
+    if (STOP_WORDS.has(token) || LOW_SIGNAL_TERMS.has(token) || SUBCOMMAND_STOP_TERMS.has(token))
+        return false;
+    return true;
 }
-function buildOutOfScopeAnswerPayload(question, normalizedQuestion, reasons) {
-    const truthReasons = [
-        'Neurcode Ask is repository-grounded and does not use web/external knowledge.',
-        ...reasons,
-    ];
-    return {
-        question,
-        questionNormalized: normalizedQuestion,
-        mode: 'search',
-        answer: [
-            'I can only answer from this repository.',
-            'This question looks external/realtime, so I cannot answer it from repo evidence.',
-            'Try a repo-scoped variant, for example: `Where is org id injected in CLI requests?`',
-        ].join('\n'),
-        findings: [
-            'Scope guard triggered: external/non-repo query.',
-            'No repo files were scanned to avoid returning misleading answers.',
-        ],
-        confidence: 'low',
-        truth: {
-            status: 'insufficient',
-            score: 0.05,
-            reasons: truthReasons,
-            sourceCitations: 0,
-            sourceFiles: 0,
-            minCitationsRequired: 2,
-            minFilesRequired: 1,
-        },
-        citations: [],
-        generatedAt: new Date().toISOString(),
-        stats: {
-            scannedFiles: 0,
-            matchedFiles: 0,
-            matchedLines: 0,
-            brainCandidates: 0,
-        },
-    };
+function detectSubcommandFocus(normalizedQuestion, commandFocus) {
+    if (!commandFocus)
+        return null;
+    const explicit = normalizedQuestion.match(new RegExp(`\\b${escapeRegExp(commandFocus)}\\s+([a-z][a-z0-9-]*)\\s+command\\b`));
+    if (explicit?.[1] && isLikelySubcommandToken(explicit[1], { allowKnownCommand: true })) {
+        return explicit[1].toLowerCase();
+    }
+    const directAfter = normalizedQuestion.match(new RegExp(`\\b${escapeRegExp(commandFocus)}\\s+([a-z][a-z0-9-]*)\\b`));
+    if (directAfter?.[1] && isLikelySubcommandToken(directAfter[1])) {
+        return directAfter[1].toLowerCase();
+    }
+    const explicitSubcommand = normalizedQuestion.match(new RegExp(`\\b([a-z][a-z0-9-]*)\\s+subcommand\\b.*\\b${escapeRegExp(commandFocus)}\\b`));
+    if (explicitSubcommand?.[1] && isLikelySubcommandToken(explicitSubcommand[1])) {
+        return explicitSubcommand[1].toLowerCase();
+    }
+    return null;
 }
 function parseOwnershipLookbackDays(normalizedQuestion) {
     if (/\bquarter\b/.test(normalizedQuestion))
@@ -511,10 +447,21 @@ function buildOwnershipDeterministicAnswer(cwd, question, normalizedQuestion) {
     const asksOwnership = /\b(who|owner|owners|authored|touched|touch)\b/.test(normalizedQuestion);
     if (!asksOwnership)
         return null;
+    const repoSignal = countTermHits(normalizedQuestion, [...REPO_SCOPE_TERMS]);
+    const externalSignal = countTermHits(normalizedQuestion, [...EXTERNAL_WORLD_TERMS]);
+    const hasCodeLikeSyntax = /[`][^`]+[`]/.test(question) ||
+        /\b[a-z0-9_\-/]+\.(ts|tsx|js|jsx|py|go|java|rb|php|cs|json|yml|yaml|toml|sql|md)\b/i.test(question) ||
+        /\b[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(question) ||
+        /--[a-z0-9-]+/i.test(question);
+    const ownershipExternalPattern = /\b(who won|who is|who was|world cup|olympics|fifa|nba|nfl|cricket)\b/.test(normalizedQuestion);
+    if ((repoSignal === 0 && !hasCodeLikeSyntax) || ownershipExternalPattern || externalSignal > 0) {
+        return null;
+    }
     const ignoreTerms = new Set([
-        'who', 'owner', 'owners', 'authored', 'touched', 'touch', 'last', 'quarter', 'recent', 'recently',
-        'file', 'files', 'module', 'modules', 'repo', 'repository', 'codebase', 'this', 'that', 'these', 'those',
-        'for', 'from', 'with', 'about', 'during', 'before', 'after', 'show', 'list', 'what', 'which', 'where',
+        'who', 'owner', 'owners', 'authored', 'touched', 'touch', 'last', 'quarter',
+        'recent', 'recently', 'file', 'files', 'module', 'modules', 'repo', 'repository',
+        'codebase', 'this', 'that', 'these', 'those', 'for', 'from', 'with', 'about',
+        'during', 'before', 'after', 'show', 'list', 'what', 'which', 'where',
     ]);
     const focusTerms = (0, plan_cache_1.normalizeIntent)(question)
         .split(/\s+/)
@@ -543,21 +490,20 @@ function buildOwnershipDeterministicAnswer(cwd, question, normalizedQuestion) {
         }
         if (!currentAuthor)
             continue;
-        const normalizedPath = line.replace(/\\/g, '/').replace(/^\.\//, '');
-        if (!normalizedPath || normalizedPath.startsWith('.git/') || normalizedPath.startsWith('node_modules/')) {
+        const normalizedPath = normalizeFilePath(line);
+        if (!normalizedPath || isIgnoredSearchPath(normalizedPath)) {
             continue;
         }
         if (focusTerms.length > 0 && !focusTerms.some((term) => (0, plan_cache_1.normalizeIntent)(normalizedPath).includes(term))) {
             continue;
         }
         authorTouches.set(currentAuthor, (authorTouches.get(currentAuthor) || 0) + 1);
-        const perFile = fileTouches.get(normalizedPath) || new Map();
-        perFile.set(currentAuthor, (perFile.get(currentAuthor) || 0) + 1);
-        fileTouches.set(normalizedPath, perFile);
+        const byFile = fileTouches.get(normalizedPath) || new Map();
+        byFile.set(currentAuthor, (byFile.get(currentAuthor) || 0) + 1);
+        fileTouches.set(normalizedPath, byFile);
     }
-    if (authorTouches.size === 0) {
+    if (authorTouches.size === 0)
         return null;
-    }
     const topContributors = [...authorTouches.entries()]
         .sort((a, b) => b[1] - a[1])
         .slice(0, 5)
@@ -570,10 +516,6 @@ function buildOwnershipDeterministicAnswer(cwd, question, normalizedQuestion) {
     })
         .slice(0, 6);
     const targetLabel = focusTerms.length > 0 ? `files matching "${focusTerms.slice(0, 4).join(', ')}"` : 'this repository';
-    const answer = [
-        `Top contributors for ${targetLabel} in the last ${sinceDays} day(s):`,
-        ...topContributors.map((entry) => `  • ${entry.author} (${entry.touches} touches)`),
-    ].join('\n');
     const citations = topFiles.map(([path, owners]) => {
         const summary = [...owners.entries()]
             .sort((a, b) => b[1] - a[1])
@@ -587,1050 +529,1330 @@ function buildOwnershipDeterministicAnswer(cwd, question, normalizedQuestion) {
             snippet: `Recent git touches (last ${sinceDays}d): ${summary}`,
         };
     });
-    const sourceFiles = new Set(citations.map((citation) => citation.path)).size;
-    const score = Math.min(0.98, 0.65 + Math.min(sourceFiles, 6) * 0.05);
+    const sourceFiles = new Set(citations.map((c) => c.path)).size;
     return {
-        reason: 'ownership_git_history',
-        payload: {
-            question,
-            questionNormalized: normalizedQuestion,
-            mode: 'search',
-            answer,
-            findings: [
-                `Derived from git history over the last ${sinceDays} day(s).`,
-                `Focus: ${targetLabel}.`,
-            ],
-            confidence: topContributors.length >= 2 ? 'high' : 'medium',
-            truth: {
-                status: 'grounded',
-                score,
-                reasons: ['Answer is grounded in local git history for this repository.'],
+        question,
+        questionNormalized: normalizedQuestion,
+        mode: 'search',
+        answer: [
+            `I checked local git history for the last ${sinceDays} day(s).`,
+            `Top contributors for ${targetLabel}:`,
+            ...topContributors.map((entry) => `  • ${entry.author} (${entry.touches} touches)`),
+        ].join('\n'),
+        findings: [
+            `Derived from git history over ${sinceDays} day(s).`,
+            `Focus: ${targetLabel}.`,
+        ],
+        confidence: topContributors.length >= 2 ? 'high' : 'medium',
+        proof: {
+            topFiles: [...new Set(citations.map((citation) => citation.path))].slice(0, 5),
+            evidenceCount: citations.length,
+            coverage: {
                 sourceCitations: citations.length,
                 sourceFiles,
-                minCitationsRequired: 1,
-                minFilesRequired: 1,
-            },
-            citations,
-            generatedAt: new Date().toISOString(),
-            stats: {
-                scannedFiles: 0,
                 matchedFiles: sourceFiles,
                 matchedLines: citations.length,
-                brainCandidates: 0,
             },
         },
-    };
-}
-function tryBuildDeterministicAnswer(cwd, question, normalizedQuestion) {
-    const scope = assessQuestionScope(normalizedQuestion);
-    if (scope.isOutOfScope) {
-        return {
-            payload: buildOutOfScopeAnswerPayload(question, normalizedQuestion, scope.reasons),
-            reason: 'out_of_scope',
-        };
-    }
-    const ownership = buildOwnershipDeterministicAnswer(cwd, question, normalizedQuestion);
-    if (ownership) {
-        return ownership;
-    }
-    return null;
-}
-function normalizeSnippet(line) {
-    return line
-        .replace(/\t/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .slice(0, 220);
+        truth: {
+            status: 'grounded',
+            score: Math.min(0.98, 0.66 + Math.min(sourceFiles, 6) * 0.05),
+            reasons: ['Answer is grounded in local git history.'],
+            sourceCitations: citations.length,
+            sourceFiles,
+            minCitationsRequired: 1,
+            minFilesRequired: 1,
+        },
+        citations,
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: sourceFiles,
+            matchedLines: citations.length,
+            brainCandidates: 0,
+        },
+    };
 }
-function addAnchorCandidates(fileTree, candidateSet, pathPriority, normalizedQuestion) {
-    const asSet = new Set(fileTree);
-    const pinned = [
-        'README.md',
-        'packages/cli/package.json',
-        'packages/cli/src/index.ts',
-        'packages/cli/src/api-client.ts',
-        'services/api/src/lib/org-context.ts',
-        'services/api/src/lib/user-org.ts',
-        'docs/cli-commands.md',
-        'docs/enterprise-setup.md',
+function buildCommandRegistrationDeterministicAnswer(cwd, question, searchTerms, maxCitations) {
+    const profile = buildQueryProfile(searchTerms);
+    if (!profile.asksRegistration || !profile.commandFocus)
+        return null;
+    const commandName = profile.commandFocus;
+    const handlerName = `${commandName}Command`;
+    const directPattern = `\\.command\\(['"\`]${escapeRegExp(commandName)}['"\`]\\)`;
+    const handlerPattern = `\\b${escapeRegExp(handlerName)}\\b`;
+    const handlerCallPattern = `\\b(?:await\\s+)?${escapeRegExp(handlerName)}\\s*\\(`;
+    const rawMatches = [
+        ...runRipgrepSearch(cwd, directPattern),
+        ...runRipgrepSearch(cwd, handlerCallPattern),
+        ...runRipgrepSearch(cwd, handlerPattern),
     ];
-    for (const path of pinned) {
-        if (!asSet.has(path))
+    if (rawMatches.length === 0)
+        return null;
+    const dedup = new Map();
+    const directRegex = new RegExp(directPattern, 'i');
+    const handlerRegex = new RegExp(handlerPattern, 'i');
+    const handlerCallRegex = new RegExp(handlerCallPattern, 'i');
+    for (const match of rawMatches) {
+        if (isIgnoredSearchPath(match.path))
             continue;
-        candidateSet.add(path);
-        pathPriority.set(path, Math.max(pathPriority.get(path) || 0, 0.22));
+        if (isLikelyDocumentationPath(match.path))
+            continue;
+        let score = 0.45;
+        if (directRegex.test(match.snippet))
+            score += 7.2;
+        if (handlerCallRegex.test(match.snippet))
+            score += 3.2;
+        if (handlerRegex.test(match.snippet))
+            score += 1.4;
+        const pathLower = match.path.toLowerCase();
+        if (pathLower === 'packages/cli/src/index.ts')
+            score += 4.6;
+        if (pathLower.includes(`/commands/${commandName}.`))
+            score += 2.8;
+        if (pathLower.includes('/commands/'))
+            score += 0.55;
+        if (/\.action\(/.test(match.snippet))
+            score += 1.1;
+        if (/^\s*import\s+/.test(match.snippet))
+            score += 0.7;
+        if (score <= 0)
+            continue;
+        const key = `${match.path}:${match.line}`;
+        const next = {
+            path: match.path,
+            line: match.line,
+            snippet: match.snippet,
+            term: commandName,
+            score,
+            matchedTerms: [commandName],
+        };
+        const existing = dedup.get(key);
+        if (!existing || next.score > existing.score) {
+            dedup.set(key, next);
+        }
     }
-    const docsLikelyUseful = /\b(feature|capabilit|offer|platform|install|setup|tenant|tenancy|architecture)\b/.test(normalizedQuestion);
-    if (!docsLikelyUseful)
-        return;
-    let addedDocs = 0;
-    for (const path of fileTree) {
-        if (addedDocs >= 24)
-            break;
-        if (path === 'README.md' || (path.startsWith('docs/') && path.endsWith('.md'))) {
-            candidateSet.add(path);
-            pathPriority.set(path, Math.max(pathPriority.get(path) || 0, 0.18));
-            addedDocs++;
+    const scored = [...dedup.values()].sort((a, b) => b.score - a.score);
+    if (scored.length === 0)
+        return null;
+    const citations = selectTopCitations(scored, Math.min(maxCitations, 10), searchTerms);
+    if (citations.length === 0)
+        return null;
+    const directCitations = citations.filter((citation) => directRegex.test(citation.snippet));
+    const sourceFiles = new Set(citations.map((citation) => citation.path)).size;
+    const topFiles = [...new Set(citations.map((citation) => citation.path))].slice(0, 5);
+    const answerLines = [];
+    if (directCitations.length > 0) {
+        const first = directCitations[0];
+        answerLines.push(`The \`${commandName}\` command is registered at ${first.path}:${first.line}.`);
+        answerLines.push('Supporting wiring references:');
+        for (const citation of citations.slice(0, 5)) {
+            answerLines.push(`  • ${citation.path}:${citation.line} — ${normalizeSnippet(citation.snippet)}`);
         }
     }
+    else {
+        answerLines.push(`I found related wiring for \`${commandName}\`, but no direct \`.command('${commandName}')\` line yet.`);
+        answerLines.push('Closest references:');
+        for (const citation of citations.slice(0, 5)) {
+            answerLines.push(`  • ${citation.path}:${citation.line} — ${normalizeSnippet(citation.snippet)}`);
+        }
+    }
+    const truthStatus = directCitations.length > 0 ? 'grounded' : 'insufficient';
+    const truthScore = directCitations.length > 0
+        ? Math.min(0.98, 0.74 + Math.min(citations.length, 6) * 0.03)
+        : 0.33;
+    return {
+        question,
+        questionNormalized: searchTerms.normalizedQuestion,
+        mode: 'search',
+        answer: answerLines.join('\n'),
+        findings: [
+            `Direct registration hits: ${directCitations.length}.`,
+            `Total wiring citations: ${citations.length} across ${sourceFiles} file(s).`,
+        ],
+        confidence: truthStatus === 'grounded' ? 'high' : 'low',
+        proof: {
+            topFiles,
+            evidenceCount: citations.length,
+            coverage: {
+                sourceCitations: citations.length,
+                sourceFiles,
+                matchedFiles: sourceFiles,
+                matchedLines: citations.length,
+            },
+        },
+        truth: {
+            status: truthStatus,
+            score: Number(truthScore.toFixed(2)),
+            reasons: truthStatus === 'grounded'
+                ? ['Command registration is grounded in direct command declaration evidence.']
+                : [`No direct \`.command('${commandName}')\` declaration was found.`],
+            sourceCitations: citations.length,
+            sourceFiles,
+            minCitationsRequired: 1,
+            minFilesRequired: 1,
+        },
+        citations,
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: sourceFiles,
+            matchedLines: citations.length,
+            brainCandidates: 0,
+        },
+    };
 }
-function readCliPackageName(cwd) {
-    const pkgPath = (0, path_1.join)(cwd, 'packages/cli/package.json');
-    if (!(0, fs_1.existsSync)(pkgPath))
+function buildCommandInventoryDeterministicAnswer(cwd, question, searchTerms, maxCitations) {
+    const normalized = searchTerms.normalizedQuestion;
+    const asksInventory = /\b(list|show|what|which)\b/.test(normalized) &&
+        /\bcommands?\b/.test(normalized) &&
+        /\b(neurcode|cli|available|all)\b/.test(normalized);
+    if (!asksInventory)
         return null;
-    try {
-        const parsed = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8'));
-        if (typeof parsed.name !== 'string' || !parsed.name.trim())
-            return null;
-        return parsed.name.trim();
-    }
-    catch {
+    const matches = runRipgrepSearch(cwd, `\\.command\\(['"\`][a-z][a-z0-9-]*['"\`]\\)`)
+        .filter((row) => !isIgnoredSearchPath(row.path))
+        .filter((row) => !isLikelyDocumentationPath(row.path))
+        .filter((row) => normalizeFilePath(row.path) === 'packages/cli/src/index.ts');
+    if (matches.length === 0)
         return null;
+    const byCommand = new Map();
+    for (const row of matches.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line)) {
+        const match = row.snippet.match(/\.command\(['"`]([a-z][a-z0-9-]*)['"`]\)/i);
+        if (!match?.[1])
+            continue;
+        const command = match[1].trim().toLowerCase();
+        if (!command || byCommand.has(command))
+            continue;
+        byCommand.set(command, {
+            path: row.path,
+            line: row.line,
+            term: command,
+            snippet: row.snippet,
+        });
     }
+    const commands = [...byCommand.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]));
+    if (commands.length === 0)
+        return null;
+    const citations = commands
+        .slice(0, Math.max(6, Math.min(maxCitations, 30)))
+        .map(([, citation]) => citation);
+    const sourceFiles = new Set(citations.map((citation) => citation.path)).size;
+    const topFiles = [...new Set(citations.map((citation) => citation.path))].slice(0, 5);
+    const answerLines = [
+        `I found ${commands.length} Neurcode CLI command registrations in this repository.`,
+        'Top commands and registration points:',
+        ...commands.slice(0, 14).map(([command, citation]) => `  • ${command} — ${citation.path}:${citation.line}`),
+        '',
+        'If you want, ask `where is <command> command registered` for wiring details.',
+    ];
+    return {
+        question,
+        questionNormalized: normalized,
+        mode: 'search',
+        answer: answerLines.join('\n'),
+        findings: [
+            `Detected ${commands.length} command registration(s).`,
+            `Evidence spans ${sourceFiles} file(s).`,
+        ],
+        confidence: 'high',
+        proof: {
+            topFiles,
+            evidenceCount: citations.length,
+            coverage: {
+                sourceCitations: citations.length,
+                sourceFiles,
+                matchedFiles: sourceFiles,
+                matchedLines: citations.length,
+            },
+        },
+        truth: {
+            status: 'grounded',
+            score: 0.93,
+            reasons: ['Command list is grounded in direct `.command(...)` declarations.'],
+            sourceCitations: citations.length,
+            sourceFiles,
+            minCitationsRequired: 1,
+            minFilesRequired: 1,
+        },
+        citations,
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: sourceFiles,
+            matchedLines: citations.length,
+            brainCandidates: 0,
+        },
+    };
 }
-function extractCommandsFromCliIndex(cwd) {
-    const indexPath = (0, path_1.join)(cwd, 'packages/cli/src/index.ts');
-    if (!(0, fs_1.existsSync)(indexPath))
-        return [];
+function collectCommandSubcommandBlockEvidence(cwd, commandPath, subcommand, searchTerms, maxCitations) {
+    const fullPath = (0, path_1.join)(cwd, commandPath);
+    if (!(0, fs_1.existsSync)(fullPath))
+        return null;
     let content = '';
     try {
-        content = (0, fs_1.readFileSync)(indexPath, 'utf-8');
+        content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
     }
     catch {
-        return [];
+        return null;
     }
-    const commandSet = new Set();
-    const topByVar = new Map();
-    for (const match of content.matchAll(/(?:const\s+([A-Za-z_$][\w$]*)\s*=\s*)?program\s*\r?\n\s*\.command\('([^']+)'\)/g)) {
-        const varName = match[1];
-        const top = (match[2] || '').trim().split(/\s+/)[0];
-        if (!top)
-            continue;
-        commandSet.add(`neurcode ${top}`);
-        if (varName) {
-            topByVar.set(varName, top);
+    const lines = content.split(/\r?\n/);
+    const subcommandDeclRegex = new RegExp(`\\.command\\(['"\`]${escapeRegExp(subcommand)}(?:\\s+\\[[^\\]]+\\])?['"\`]\\)`, 'i');
+    const anchorIdx = lines.findIndex((line) => subcommandDeclRegex.test(line));
+    if (anchorIdx < 0)
+        return null;
+    let endIdx = lines.length;
+    for (let i = anchorIdx + 1; i < lines.length; i++) {
+        if (/^\s*\.command\(['"`][a-z][a-z0-9-]*(?:\s+\[[^\]]+\])?['"`]\)/i.test(lines[i])) {
+            endIdx = i;
+            break;
         }
     }
-    for (const match of content.matchAll(/([A-Za-z_$][\w$]*)\s*\r?\n\s*\.command\('([^']+)'\)/g)) {
-        const parentVar = match[1];
-        const parent = topByVar.get(parentVar);
-        if (!parent)
+    const relevantTerms = [...searchTerms.highSignalTerms, ...searchTerms.identifiers]
+        .map((term) => (0, plan_cache_1.normalizeIntent)(term))
+        .filter((term) => term.length >= 3 && !LOW_SIGNAL_TERMS.has(term) && term !== subcommand)
+        .slice(0, 14);
+    let focusRegex = null;
+    const focusPattern = buildPatternFromTerms(relevantTerms);
+    if (focusPattern) {
+        try {
+            focusRegex = new RegExp(focusPattern, 'i');
+        }
+        catch {
+            focusRegex = null;
+        }
+    }
+    const citations = [];
+    const seen = new Set();
+    const pushLine = (lineIdx, term) => {
+        if (lineIdx < 0 || lineIdx >= lines.length)
+            return;
+        const snippet = normalizeSnippet(lines[lineIdx] || '');
+        if (!snippet)
+            return;
+        const key = `${commandPath}:${lineIdx + 1}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        citations.push({
+            path: commandPath,
+            line: lineIdx + 1,
+            term,
+            snippet,
+        });
+    };
+    pushLine(anchorIdx, subcommand);
+    for (let i = anchorIdx; i < endIdx; i++) {
+        if (citations.length >= maxCitations)
+            break;
+        const snippet = normalizeSnippet(lines[i] || '');
+        if (!snippet)
             continue;
-        const sub = (match[2] || '').trim().split(/\s+/)[0];
-        if (!sub)
+        const isAction = /\.action\(/.test(snippet);
+        const isDescription = /\.description\(/.test(snippet);
+        const hasFocus = focusRegex ? focusRegex.test(snippet) : false;
+        const hasFlowCall = /\b(?:get|load|read|list|compute|count|find|search|refresh|record|write|print|format|clear|delete|close|set)[A-Za-z0-9_]*\s*\(/.test(snippet);
+        const hasStateSignal = /\b(cache|memory|context|scope|stats|entries|bytes|payload|store|index)\b/i.test(snippet);
+        const hasOutputSignal = /\bJSON\.stringify\b|\bconsole\.(?:log|warn|error)\b|^\s*return\b/.test(snippet);
+        const hasOptionSignal = /\.option\(/.test(snippet);
+        if (!isAction && !isDescription && !hasFocus && !hasFlowCall && !hasStateSignal && !hasOutputSignal && !hasOptionSignal) {
             continue;
-        commandSet.add(`neurcode ${parent} ${sub}`);
+        }
+        pushLine(i, hasStateSignal ? 'state' : undefined);
+    }
+    if (!citations.some((citation) => /\.action\(/.test(citation.snippet))) {
+        for (let i = anchorIdx; i < endIdx; i++) {
+            if (/\.action\(/.test(lines[i] || '')) {
+                pushLine(i, 'action');
+                break;
+            }
+        }
     }
-    return [...commandSet].slice(0, 40);
+    if (citations.length === 0)
+        return null;
+    return {
+        anchorLine: anchorIdx + 1,
+        citations: citations.slice(0, maxCitations),
+    };
 }
-function extractFeatureBulletsFromMarkdown(markdown, limit, headingPattern) {
-    const lines = markdown.split(/\r?\n/);
-    let start = lines.findIndex((line) => headingPattern.test(line));
-    if (start < 0)
-        return [];
+function extractCommandOperationNames(citations) {
     const out = [];
     const seen = new Set();
-    for (let i = start + 1; i < lines.length; i++) {
-        const line = lines[i];
-        if (/^##\s+/.test(line))
-            break;
-        const rich = line.match(/^- \*\*(.+?)\*\*\s*-\s*(.+)$/);
-        if (rich?.[1]) {
-            const text = `${formatInsightSnippet(rich[1])} - ${formatInsightSnippet(rich[2])}`.trim();
-            const key = text.toLowerCase();
-            if (key && !seen.has(key)) {
-                seen.add(key);
-                out.push(text);
-            }
-        }
-        else {
-            const simple = line.match(/^- (.+)$/);
-            if (!simple?.[1])
+    const ignored = new Set([
+        'if', 'for', 'while', 'switch', 'catch', 'return',
+        'async', 'argument',
+        'console', 'log', 'warn', 'error', 'JSON', 'Promise',
+        'Map', 'Set', 'Array', 'Object', 'String', 'Number', 'Date',
+        'command', 'description', 'option', 'action',
+        'filter', 'map', 'slice', 'sort', 'join', 'push',
+    ]);
+    for (const citation of citations) {
+        for (const match of citation.snippet.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)) {
+            const operation = match[1];
+            if (!operation || ignored.has(operation))
                 continue;
-            const text = formatInsightSnippet(simple[1]);
-            if (!text)
+            if (operation.length < 3)
                 continue;
-            const key = text.toLowerCase();
-            if (!seen.has(key)) {
-                seen.add(key);
-                out.push(text);
-            }
+            const looksLikeCodeOperation = /[A-Z_]/.test(operation) ||
+                /^(get|load|read|list|compute|count|find|search|refresh|record|write|print|format|clear|delete|close|set|diagnose|resolve|build|create|update)/i.test(operation);
+            if (!looksLikeCodeOperation)
+                continue;
+            if (seen.has(operation))
+                continue;
+            seen.add(operation);
+            out.push(operation);
+            if (out.length >= 10)
+                return out;
         }
-        if (out.length >= limit)
-            break;
     }
     return out;
 }
-function extractFeatureBulletsFromReadme(cwd, limit) {
-    const readmePath = (0, path_1.join)(cwd, 'README.md');
-    if (!(0, fs_1.existsSync)(readmePath))
+function buildCommandSubcommandFlowDeterministicAnswer(cwd, question, searchTerms, maxCitations) {
+    const profile = buildQueryProfile(searchTerms);
+    if (!profile.commandFocus || !profile.subcommandFocus)
+        return null;
+    if (profile.asksRegistration || profile.asksList)
+        return null;
+    const asksFlowLike = profile.asksHow ||
+        /\b(flow|trace|internals?|compute|works?|working|steps?|logic|behavior|behaviour)\b/.test(searchTerms.normalizedQuestion);
+    if (!asksFlowLike)
+        return null;
+    const commandName = profile.commandFocus;
+    const subcommand = profile.subcommandFocus;
+    const commandPath = `packages/cli/src/commands/${commandName}.ts`;
+    const blockEvidence = collectCommandSubcommandBlockEvidence(cwd, commandPath, subcommand, searchTerms, Math.min(Math.max(maxCitations, 8), 16));
+    if (!blockEvidence || blockEvidence.citations.length === 0)
+        return null;
+    const registrationCitations = runRipgrepSearch(cwd, `\\.command\\(['"\`]${escapeRegExp(commandName)}['"\`]\\)`)
+        .filter((hit) => normalizeFilePath(hit.path) === 'packages/cli/src/index.ts')
+        .slice(0, 1)
+        .map((hit) => ({
+        path: hit.path,
+        line: hit.line,
+        term: commandName,
+        snippet: hit.snippet,
+    }));
+    const subcommandDeclRegex = new RegExp(`\\.command\\(['"\`]${escapeRegExp(subcommand)}(?:\\s+\\[[^\\]]+\\])?['"\`]\\)`, 'i');
+    const scored = new Map();
+    for (const citation of registrationCitations) {
+        const key = `${citation.path}:${citation.line}`;
+        scored.set(key, {
+            ...citation,
+            score: 7.2,
+            matchedTerms: [commandName],
+        });
+    }
+    for (const citation of blockEvidence.citations) {
+        const key = `${citation.path}:${citation.line}`;
+        let score = 3.8;
+        if (subcommandDeclRegex.test(citation.snippet))
+            score += 6.2;
+        if (/\.action\(/.test(citation.snippet))
+            score += 4.2;
+        if (/\.description\(/.test(citation.snippet))
+            score += 1.0;
+        if (/\b(cache|memory|context|scope|stats|entries|bytes|payload|store|index)\b/i.test(citation.snippet)) {
+            score += 2.4;
+        }
+        if (/\b(?:get|load|read|list|compute|count|find|search|refresh|record|write|print|format|clear|delete|close|set)[A-Za-z0-9_]*\s*\(/.test(citation.snippet)) {
+            score += 1.8;
+        }
+        if (/\bJSON\.stringify\b|\bconsole\.(?:log|warn|error)\b|^\s*return\b/.test(citation.snippet)) {
+            score += 0.9;
+        }
+        scored.set(key, {
+            ...citation,
+            score,
+            matchedTerms: [commandName, subcommand],
+        });
+    }
+    const citations = [...scored.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Math.min(Math.max(maxCitations, 8), 16))
+        .map(({ path, line, snippet, term }) => ({ path, line, snippet, term }));
+    if (citations.length === 0)
+        return null;
+    const hasSubcommandDeclaration = citations.some((citation) => subcommandDeclRegex.test(citation.snippet));
+    const hasActionBlock = citations.some((citation) => /\.action\(/.test(citation.snippet));
+    if (!hasSubcommandDeclaration)
+        return null;
+    const sourceFiles = new Set(citations.map((citation) => citation.path)).size;
+    const topFiles = [...new Set(citations.map((citation) => citation.path))].slice(0, 5);
+    const operations = extractCommandOperationNames(citations.filter((citation) => citation.path === commandPath));
+    const answerLines = [
+        `Short answer: \`${commandName} ${subcommand}\` is implemented in ${commandPath}:${blockEvidence.anchorLine}.`,
+        '',
+        'What I verified in code:',
+        ...citations.slice(0, 8).map((citation) => `  • ${explainEvidenceCitation(citation)}`),
+    ];
+    if (operations.length > 0) {
+        answerLines.push('');
+        answerLines.push('Key operations in this flow:');
+        for (const operation of operations.slice(0, 8)) {
+            answerLines.push(`  • ${operation}()`);
+        }
+    }
+    answerLines.push('');
+    answerLines.push(`If you want, I can trace control flow inside ${commandPath} line-by-line.`);
+    const truthScore = Math.min(0.97, 0.73 +
+        (hasSubcommandDeclaration ? 0.1 : 0) +
+        (hasActionBlock ? 0.08 : 0) +
+        Math.min(citations.length * 0.01, 0.06));
+    return {
+        question,
+        questionNormalized: searchTerms.normalizedQuestion,
+        mode: 'search',
+        answer: answerLines.join('\n'),
+        findings: [
+            `Command focus: ${commandName}, subcommand focus: ${subcommand}.`,
+            `Subcommand block anchor: ${commandPath}:${blockEvidence.anchorLine}.`,
+            `Evidence lines: ${citations.length} across ${sourceFiles} file(s).`,
+        ],
+        confidence: truthScore >= 0.9 ? 'high' : 'medium',
+        proof: {
+            topFiles,
+            evidenceCount: citations.length,
+            coverage: {
+                sourceCitations: citations.length,
+                sourceFiles,
+                matchedFiles: sourceFiles,
+                matchedLines: citations.length,
+            },
+        },
+        truth: {
+            status: hasActionBlock ? 'grounded' : 'insufficient',
+            score: Number(truthScore.toFixed(2)),
+            reasons: hasActionBlock
+                ? ['Command subcommand flow is grounded in direct command action block evidence.']
+                : ['Subcommand declaration found but action block evidence is limited.'],
+            sourceCitations: citations.length,
+            sourceFiles,
+            minCitationsRequired: 2,
+            minFilesRequired: 1,
+        },
+        citations,
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: sourceFiles,
+            matchedLines: citations.length,
+            brainCandidates: 0,
+        },
+    };
+}
+function buildAskCacheFlowDeterministicAnswer(cwd, question, searchTerms, maxCitations) {
+    const normalized = searchTerms.normalizedQuestion;
+    const asksAskCacheFlow = /\bask\b/.test(normalized) &&
+        /\bcache\b/.test(normalized) &&
+        /\b(how|flow|work|works|working|exact|steps|internals?|mechanism)\b/.test(normalized);
+    if (!asksAskCacheFlow)
+        return null;
+    const probes = [
+        { tag: 'hash', pattern: 'computeAskQuestionHash\\(' },
+        { tag: 'key', pattern: 'computeAskCacheKey\\(' },
+        { tag: 'exact', pattern: 'readCachedAsk\\(' },
+        { tag: 'near', pattern: 'findNearCachedAsk\\(' },
+        { tag: 'drift', pattern: 'getChangedWorkingTreePaths\\(' },
+        { tag: 'write', pattern: 'writeCachedAsk\\(' },
+    ];
+    const raw = [];
+    for (const probe of probes) {
+        const hits = runRipgrepSearch(cwd, probe.pattern);
+        for (const hit of hits) {
+            const normalizedPath = normalizeFilePath(hit.path);
+            if (normalizedPath !== 'packages/cli/src/commands/ask.ts' && normalizedPath !== 'packages/cli/src/utils/ask-cache.ts') {
+                continue;
+            }
+            raw.push({ ...hit, tag: probe.tag });
+        }
+    }
+    if (raw.length === 0)
+        return null;
+    const scoreByTag = {
+        hash: 2.3,
+        key: 2.0,
+        exact: 4.8,
+        near: 4.2,
+        drift: 2.6,
+        write: 4.6,
+    };
+    const dedup = new Map();
+    for (const hit of raw) {
+        const key = `${hit.path}:${hit.line}`;
+        const score = (scoreByTag[hit.tag] || 0) + (hit.path.endsWith('/commands/ask.ts') ? 1.1 : 0.35);
+        const next = {
+            path: hit.path,
+            line: hit.line,
+            snippet: hit.snippet,
+            term: hit.tag,
+            score,
+            matchedTerms: [hit.tag],
+        };
+        const existing = dedup.get(key);
+        if (!existing || existing.score < next.score) {
+            dedup.set(key, next);
+        }
+    }
+    const scored = [...dedup.values()].sort((a, b) => b.score - a.score);
+    if (scored.length === 0)
+        return null;
+    const citations = selectTopCitations(scored, Math.min(Math.max(maxCitations, 8), 16), searchTerms);
+    if (citations.length === 0)
+        return null;
+    const hasExact = citations.some((citation) => /readCachedAsk\s*\(/.test(citation.snippet));
+    const hasNear = citations.some((citation) => /findNearCachedAsk\s*\(/.test(citation.snippet));
+    const hasWrite = citations.some((citation) => /writeCachedAsk\s*\(/.test(citation.snippet));
+    const hasHash = citations.some((citation) => /computeAskQuestionHash\s*\(|computeAskCacheKey\s*\(/.test(citation.snippet));
+    const hasDrift = citations.some((citation) => /getChangedWorkingTreePaths\s*\(/.test(citation.snippet));
+    const verifiedSteps = [];
+    if (hasHash)
+        verifiedSteps.push('Normalize question + context into deterministic hash and cache key.');
+    if (hasExact)
+        verifiedSteps.push('Attempt exact cache hit first (`readCachedAsk`).');
+    if (hasNear)
+        verifiedSteps.push('On exact miss, attempt semantic near-hit reuse (`findNearCachedAsk`).');
+    if (hasDrift)
+        verifiedSteps.push('Near-hit safety checks include working-tree drift via changed paths.');
+    if (hasWrite)
+        verifiedSteps.push('On fresh retrieval, write the result back for future asks (`writeCachedAsk`).');
+    const sourceFiles = new Set(citations.map((citation) => citation.path)).size;
+    const topFiles = [...new Set(citations.map((citation) => citation.path))].slice(0, 5);
+    const answerLines = [
+        'Short answer: ask cache uses an exact-hit -> near-hit -> fresh-retrieval -> write-back flow.',
+        '',
+        'Verified implementation steps:',
+        ...verifiedSteps.map((step, idx) => `  ${idx + 1}. ${step}`),
+        '',
+        'Grounding evidence:',
+        ...citations.slice(0, 8).map((citation) => `  • ${citation.path}:${citation.line} — ${normalizeSnippet(citation.snippet)}`),
+    ];
+    const truthScore = (hasExact && hasNear && hasWrite) ? 0.94 : 0.66;
+    return {
+        question,
+        questionNormalized: normalized,
+        mode: 'search',
+        answer: answerLines.join('\n'),
+        findings: [
+            `Verified cache-flow steps: ${verifiedSteps.length}.`,
+            `Evidence spans ${sourceFiles} file(s).`,
+        ],
+        confidence: truthScore >= 0.9 ? 'high' : 'medium',
+        proof: {
+            topFiles,
+            evidenceCount: citations.length,
+            coverage: {
+                sourceCitations: citations.length,
+                sourceFiles,
+                matchedFiles: sourceFiles,
+                matchedLines: citations.length,
+            },
+        },
+        truth: {
+            status: 'grounded',
+            score: truthScore,
+            reasons: ['Ask cache flow is grounded in direct cache function calls in the CLI implementation.'],
+            sourceCitations: citations.length,
+            sourceFiles,
+            minCitationsRequired: 2,
+            minFilesRequired: 1,
+        },
+        citations,
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: sourceFiles,
+            matchedLines: citations.length,
+            brainCandidates: 0,
+        },
+    };
+}
+function buildPatternFromTerms(terms) {
+    const parts = terms
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2)
+        .sort((a, b) => b.length - a.length)
+        .slice(0, 16)
+        .map((term) => {
+        const escaped = escapeRegExp(term);
+        if (/^[a-z0-9_]+$/i.test(term)) {
+            return `\\b${escaped}\\b`;
+        }
+        if (term.includes(' ')) {
+            return escaped.replace(/\\\s+/g, '\\s+');
+        }
+        return escaped;
+    });
+    if (parts.length === 0)
+        return '';
+    return `(?:${parts.join('|')})`;
+}
+function parseRgLine(line) {
+    const match = line.match(/^(.*?):(\d+):(.*)$/);
+    if (!match)
+        return null;
+    const rawPath = normalizeFilePath(match[1]);
+    if (isIgnoredSearchPath(rawPath))
+        return null;
+    const lineNumber = Number(match[2]);
+    if (!rawPath || !Number.isFinite(lineNumber) || lineNumber <= 0)
+        return null;
+    return {
+        path: rawPath,
+        line: lineNumber,
+        snippet: normalizeSnippet(match[3] || ''),
+    };
+}
+function runRipgrepSearch(cwd, pattern) {
+    if (!pattern)
+        return [];
+    const args = [
+        '--line-number',
+        '--no-heading',
+        '--color', 'never',
+        '--max-count', String(RG_MAX_MATCHES),
+        '--max-columns', '400',
+        '--smart-case',
+        '--hidden',
+        '--glob', '!**/node_modules/**',
+        '--glob', '!**/.git/**',
+        '--glob', '!**/dist/**',
+        '--glob', '!**/build/**',
+        '--glob', '!**/out/**',
+        '--glob', '!**/.next/**',
+        '--glob', '!**/coverage/**',
+        '--glob', '!**/.neurcode/**',
+        '--glob', '!**/.pnpm-store/**',
+        '--glob', '!*.lock',
+        '--glob', '!*.map',
+        '--',
+        pattern,
+        '.',
+    ];
+    const result = (0, child_process_1.spawnSync)('rg', args, {
+        cwd,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 * 80,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const status = result.status ?? 1;
+    if (status !== 0 && status !== 1) {
         return [];
-    try {
-        const content = (0, fs_1.readFileSync)(readmePath, 'utf-8');
-        return extractFeatureBulletsFromMarkdown(content, limit, /^#{2,3}\s+.*(features|capabilities|what it does|highlights|offerings|product surface|platform surface|overview)/i);
     }
-    catch {
+    const stdout = result.stdout || '';
+    if (!stdout.trim())
         return [];
+    const out = [];
+    for (const raw of stdout.split(/\r?\n/)) {
+        const parsed = parseRgLine(raw.trim());
+        if (!parsed)
+            continue;
+        out.push(parsed);
+        if (out.length >= RG_MAX_MATCHES)
+            break;
     }
+    return out;
 }
-function extractFeatureBulletsFromDocs(cwd, limit) {
-    const docsDir = (0, path_1.join)(cwd, 'docs');
-    if (!(0, fs_1.existsSync)(docsDir))
-        return [];
+function fallbackScanMatches(cwd, fileTree, pattern, maxMatches = 1200) {
     const out = [];
-    const seen = new Set();
-    let files = [];
+    if (!pattern)
+        return out;
+    let regex;
     try {
-        files = (0, fs_1.readdirSync)(docsDir).filter((name) => name.toLowerCase().endsWith('.md')).slice(0, 40);
+        regex = new RegExp(pattern, 'i');
     }
     catch {
-        return [];
+        return out;
     }
-    for (const fileName of files) {
-        if (out.length >= limit)
+    for (const filePath of fileTree) {
+        if (out.length >= maxMatches)
             break;
-        const fullPath = (0, path_1.join)(docsDir, fileName);
+        if (isIgnoredSearchPath(filePath))
+            continue;
+        const fullPath = (0, path_1.join)(cwd, filePath);
         let content = '';
         try {
+            const st = (0, fs_1.statSync)(fullPath);
+            if (st.size > MAX_FILE_BYTES)
+                continue;
             content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
         }
         catch {
             continue;
         }
-        const extracted = extractFeatureBulletsFromMarkdown(content, limit, /^#{2,3}\s+.*(features|capabilities|what it does|highlights|offerings|product surface|platform surface|overview)/i);
-        for (const bullet of extracted) {
-            const key = bullet.toLowerCase();
-            if (seen.has(key))
+        const lines = content.split(/\r?\n/);
+        for (let idx = 0; idx < lines.length; idx++) {
+            const line = lines[idx];
+            if (!line)
                 continue;
-            seen.add(key);
-            out.push(bullet);
-            if (out.length >= limit)
+            if (!regex.test(line))
+                continue;
+            out.push({
+                path: filePath,
+                line: idx + 1,
+                snippet: normalizeSnippet(line),
+            });
+            if (out.length >= maxMatches)
                 break;
         }
     }
     return out;
 }
-function extractFeatureBulletsForRepo(cwd, limit) {
-    const readmeBullets = extractFeatureBulletsFromReadme(cwd, limit);
-    if (readmeBullets.length >= limit) {
-        return readmeBullets.slice(0, limit);
-    }
-    const docsBullets = extractFeatureBulletsFromDocs(cwd, limit);
-    return [...new Set([...readmeBullets, ...docsBullets])].slice(0, limit);
-}
-function extractNeurcodeCommandsFromCitations(citations) {
-    const commandSet = new Set();
-    for (const citation of citations) {
-        const snippet = citation.snippet || '';
-        for (const match of snippet.matchAll(/\.command\('([^']+)'\)/g)) {
-            const command = (match[1] || '').trim().split(/\s+/)[0];
-            if (!command)
-                continue;
-            commandSet.add(`neurcode ${command}`);
+function collectRepoEvidence(cwd, fileTree, searchTerms, pathBoostScores) {
+    const pattern = buildPatternFromTerms(searchTerms.rgTerms);
+    const fromRg = runRipgrepSearch(cwd, pattern);
+    const rawMatches = fromRg.length > 0 ? fromRg : fallbackScanMatches(cwd, fileTree, pattern);
+    const profile = buildQueryProfile(searchTerms);
+    const asksLocation = profile.asksLocation;
+    const asksHow = profile.asksHow;
+    const asksList = profile.asksList;
+    const asksRegistration = profile.asksRegistration;
+    const commandFocus = profile.commandFocus;
+    const subcommandFocus = profile.subcommandFocus;
+    const subcommandDeclRegex = subcommandFocus
+        ? new RegExp(`\\.command\\(['"\`]${escapeRegExp(subcommandFocus)}(?:\\s+\\[[^\\]]+\\])?['"\`]\\)`, 'i')
+        : null;
+    const codeFocused = profile.codeFocused;
+    const matchedTerms = new Set();
+    const dedup = new Map();
+    for (const match of rawMatches) {
+        if (isIgnoredSearchPath(match.path))
+            continue;
+        const pathLower = match.path.toLowerCase();
+        const snippetLower = (match.snippet || '').toLowerCase();
+        const isDocPath = isLikelyDocumentationPath(match.path);
+        const docSnippet = isLikelyDocSnippet(match.snippet);
+        const codeSnippet = isLikelyCodeSnippet(match.snippet);
+        const promptExample = isPromptExampleSnippet(match.snippet, searchTerms.normalizedQuestion, searchTerms.highSignalTerms);
+        if (asksLocation && codeFocused && (pathLower.endsWith('.md') || pathLower.endsWith('.txt'))) {
+            continue;
         }
-        for (const match of snippet.matchAll(/`neurcode\s+([^`]+)`/g)) {
-            const command = (match[1] || '').trim();
-            if (!command)
-                continue;
-            commandSet.add(`neurcode ${command}`);
+        const termHits = searchTerms.rgTerms.filter((term) => {
+            const normalized = term.toLowerCase();
+            if (normalized.includes(' '))
+                return snippetLower.includes(normalized);
+            const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
+            return pattern.test(snippetLower);
+        });
+        const highSignalHits = searchTerms.highSignalTerms.filter((term) => {
+            const normalized = term.toLowerCase();
+            if (normalized.includes(' '))
+                return snippetLower.includes(normalized);
+            const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
+            return pattern.test(snippetLower);
+        });
+        const identifierHits = searchTerms.identifiers.filter((identifier) => new RegExp(`\\b${escapeRegExp(identifier)}\\b`, 'i').test(match.snippet));
+        const pathHits = searchTerms.highSignalTerms.filter((term) => pathLower.includes(term)).length;
+        const quotedHits = searchTerms.quotedPhrases.filter((phrase) => snippetLower.includes(phrase.toLowerCase())).length;
+        let score = 0;
+        score += termHits.length * 1.15;
+        score += highSignalHits.length * 1.65;
+        score += identifierHits.length * 2.05;
+        score += pathHits * (asksLocation ? 1.95 : 1.1);
+        score += quotedHits * 2.1;
+        if (codeFocused && codeSnippet) {
+            score += 0.95;
         }
-        for (const plainMatch of snippet.matchAll(/\bneurcode\s+([a-z][a-z0-9-]*(?:\s+[a-z][a-z0-9-]*)?)\b/g)) {
-            if (!plainMatch?.[1])
-                continue;
-            commandSet.add(`neurcode ${plainMatch[1].trim()}`);
+        if (codeFocused && !codeSnippet) {
+            score -= 1.35;
         }
-    }
-    return [...commandSet].slice(0, 20);
-}
-function extractCommandFocus(normalizedQuestion) {
-    const toKnownCommand = (candidate) => {
-        if (!candidate)
-            return null;
-        const normalized = candidate.toLowerCase().trim();
-        return CLI_COMMAND_NAMES.has(normalized) ? normalized : null;
-    };
-    const direct = normalizedQuestion.match(/\bneurcode\s+([a-z][a-z0-9-]*)\b/);
-    const directCommand = toKnownCommand(direct?.[1] || null);
-    if (directCommand)
-        return directCommand;
-    const scoped = normalizedQuestion.match(/\b(?:under|for|within|inside|in)\s+(?:neurcode\s+)?([a-z][a-z0-9-]*)\b/);
-    const scopedCommand = toKnownCommand(scoped?.[1] || null);
-    if (scopedCommand)
-        return scopedCommand;
-    const commandPattern = normalizedQuestion.match(/\b([a-z][a-z0-9-]*)\s+command\b/);
-    const commandPhrase = toKnownCommand(commandPattern?.[1] || null);
-    if (commandPhrase)
-        return commandPhrase;
-    const mentionedCommands = [...CLI_COMMAND_NAMES].filter((command) => new RegExp(`\\b${escapeRegExp(command)}\\b`, 'i').test(normalizedQuestion));
-    if (mentionedCommands.length !== 1)
-        return null;
-    const hasImplementationSignals = /\b(where|how|defined|implemented|called|computed|resolved|lookup|cache|flag|option|verdict|pass|fail|schema|field|fields|key|keys)\b/.test(normalizedQuestion);
-    if (hasImplementationSignals) {
-        return mentionedCommands[0];
-    }
-    return null;
-}
-function extractInstallCommandsFromCitations(citations) {
-    const installSet = new Set();
-    for (const citation of citations) {
-        const snippet = citation.snippet || '';
-        const matches = snippet.match(/\b(?:npm|pnpm|yarn)\s+(?:install|add)\s+-g\s+[@a-z0-9_.\-/]+(?:@latest)?\b/gi) || [];
-        for (const match of matches) {
-            installSet.add(match.trim());
+        if (docSnippet) {
+            score -= codeFocused ? 1.9 : 0.6;
         }
-    }
-    return [...installSet].slice(0, 6);
-}
-function formatInsightSnippet(snippet) {
-    return snippet
-        .replace(/^[-*]\s+/, '')
-        .replace(/^\/\/\s?/, '')
-        .replace(/^\/\*\s?/, '')
-        .replace(/\*\/$/, '')
-        .replace(/^\*\s+/, '')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .slice(0, 180);
-}
-function countTermHitsInText(text, terms) {
-    if (!text || terms.length === 0)
-        return 0;
-    let hits = 0;
-    const isCompactText = !/\s/.test(text);
-    const compactText = isCompactText ? text.replace(/[^a-z0-9]/g, '') : '';
-    for (const term of terms) {
-        const normalized = term.toLowerCase().trim();
-        if (!normalized)
-            continue;
-        if (normalized.includes(' ')) {
-            if (text.includes(normalized))
-                hits += 1;
-            continue;
+        if (isDocPath && codeFocused) {
+            score -= asksLocation ? 3.7 : 2.2;
         }
-        const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
-        if (pattern.test(text)) {
-            hits += 1;
-            continue;
+        if (promptExample) {
+            score -= codeFocused ? 4.4 : 2.2;
         }
-        if (isCompactText) {
-            const compactTerm = normalized.replace(/[^a-z0-9]/g, '');
-            if (compactTerm.length >= 3 && compactText.includes(compactTerm)) {
-                hits += 1;
-            }
+        if (/\b(?:export\s+)?(?:function|class|const|interface|type|enum)\b/.test(match.snippet)) {
+            score += 0.85;
         }
-    }
-    return hits;
-}
-function findInterfaceFieldBlock(lines, startLine) {
-    const startIndex = Math.max(0, startLine - 1);
-    const lookbackStart = Math.max(0, startIndex - 14);
-    const lookaheadEnd = Math.min(lines.length - 1, startIndex + 10);
-    let headerIndex = -1;
-    let interfaceName = '';
-    for (let i = startIndex; i >= lookbackStart; i--) {
-        const match = lines[i].match(/^\s*(?:export\s+)?interface\s+([A-Za-z_][A-Za-z0-9_]*)\b/);
-        if (!match?.[1])
-            continue;
-        headerIndex = i;
-        interfaceName = match[1];
-        break;
-    }
-    if (headerIndex < 0) {
-        for (let i = startIndex; i <= lookaheadEnd; i++) {
-            const match = lines[i].match(/^\s*(?:export\s+)?interface\s+([A-Za-z_][A-Za-z0-9_]*)\b/);
-            if (!match?.[1])
-                continue;
-            headerIndex = i;
-            interfaceName = match[1];
-            break;
+        if (asksLocation && /\b(?:function|class|interface|type)\b/.test(match.snippet)) {
+            score += 0.75;
         }
-    }
-    if (headerIndex < 0 || !interfaceName)
-        return null;
-    let opened = false;
-    let depth = 0;
-    const fields = [];
-    const seen = new Set();
-    for (let i = headerIndex; i < Math.min(lines.length, headerIndex + 120); i++) {
-        const line = lines[i];
-        if (!opened) {
-            if (line.includes('{')) {
-                opened = true;
-                depth = 1;
-            }
-            continue;
+        if (asksHow && /\b(if|else|return|await|for|while|switch|try|catch)\b/.test(match.snippet)) {
+            score += 0.55;
+        }
+        if (asksList && /\.command\(|\.option\(|\bneurcode\s+[a-z]/i.test(match.snippet)) {
+            score += 0.7;
+        }
+        if (asksRegistration && /(?:^|[^a-z])(?:register|registered|registration)(?:$|[^a-z])/i.test(match.snippet)) {
+            score += 0.8;
         }
-        const fieldMatch = line.match(/^\s*([A-Za-z_][A-Za-z0-9_?]*)\s*:/);
-        if (fieldMatch?.[1]) {
-            const field = fieldMatch[1].replace(/\?$/, '');
-            if (!seen.has(field)) {
-                seen.add(field);
-                fields.push(field);
+        if (asksRegistration && /\.command\(|program\.command\(/i.test(match.snippet)) {
+            score += 2.3;
+        }
+        if (asksLocation && profile.highSignalSet.has('middleware') && pathLower.includes('/middleware/')) {
+            score += 1.9;
+        }
+        if (asksLocation && profile.highSignalSet.has('middleware') && !pathLower.includes('middleware')) {
+            score -= 1.7;
+        }
+        if (asksLocation && profile.highSignalSet.has('auth') && /(?:^|\/)auth(?:[-_.]|\/|\.|$)/.test(pathLower)) {
+            score += 1.25;
+        }
+        if (asksLocation && profile.highSignalSet.has('orgid') && /\borgid\b|organizationid/i.test(match.snippet)) {
+            score += 1.45;
+        }
+        if (commandFocus) {
+            if (new RegExp(`\\.command\\(['"\`]${escapeRegExp(commandFocus)}['"\`]\\)`, 'i').test(match.snippet)) {
+                score += 6.2;
+            }
+            if (asksRegistration && pathLower === 'packages/cli/src/index.ts') {
+                score += 2.8;
+            }
+            if (pathLower.includes(`/commands/${commandFocus}.`)) {
+                score += asksHow ? 3.2 : 1.8;
+                if (subcommandDeclRegex && subcommandDeclRegex.test(match.snippet)) {
+                    score += 4.1;
+                }
+            }
+            else if (pathLower.includes('/commands/')) {
+                score -= asksHow ? 1.85 : 0.45;
+            }
+            if (asksHow && pathLower.includes('/commands/') && !pathLower.includes(`/commands/${commandFocus}.`) && pathLower !== 'packages/cli/src/index.ts') {
+                score -= 1.05;
+            }
+            if (commandFocus !== 'ask' && pathLower.endsWith('/commands/ask.ts')) {
+                score -= 3.2;
             }
         }
-        for (const ch of line) {
-            if (ch === '{')
-                depth += 1;
-            if (ch === '}')
-                depth -= 1;
+        if (codeFocused && (pathLower.endsWith('.md') || pathLower.startsWith('docs/'))) {
+            score -= 1.35;
+        }
+        if (codeFocused && (pathLower.endsWith('.txt') || pathLower.includes('audit'))) {
+            score -= 1.8;
+        }
+        if (codeFocused && /(?:^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/i.test(pathLower)) {
+            score -= 4.5;
+        }
+        if (codeFocused && /\bneurcode\s+(ask|plan|verify|ship)\s+["`]/i.test(match.snippet)) {
+            score -= 2.4;
+        }
+        if (codeFocused && /\?/.test(match.snippet) && /\b(neurcode|ask|plan)\b/i.test(match.snippet)) {
+            score -= 1.1;
+        }
+        if (codeFocused && /\bnew Set\(\[/.test(match.snippet)) {
+            score -= 1.1;
+        }
+        if (codeFocused && /\\b\([^)]*\|[^)]*\)/.test(match.snippet) && /\.test\(/.test(match.snippet)) {
+            score -= 1.45;
+        }
+        if (pathLower.includes('/commands/')) {
+            score += 0.15;
+        }
+        if (asksRegistration && pathLower.endsWith('/commands/ask.ts')) {
+            score -= 2.4;
+        }
+        if (asksLocation && codeFocused && pathLower.endsWith('/commands/ask.ts')) {
+            score -= 2.9;
+        }
+        const boost = pathBoostScores.get(match.path) || 0;
+        if (boost > 0) {
+            const cappedBoost = codeFocused && isDocPath
+                ? Math.min(boost, 0.06)
+                : Math.min(boost, 0.45);
+            score += cappedBoost;
+        }
+        if (score <= 0)
+            continue;
+        for (const term of highSignalHits) {
+            matchedTerms.add(term);
+        }
+        const dominantTerm = highSignalHits[0] ||
+            identifierHits[0] ||
+            termHits[0] ||
+            '';
+        const key = `${match.path}:${match.line}`;
+        const next = {
+            path: match.path,
+            line: match.line,
+            snippet: match.snippet,
+            term: dominantTerm || undefined,
+            score,
+            matchedTerms: [...new Set([...highSignalHits, ...identifierHits, ...termHits])],
+        };
+        const existing = dedup.get(key);
+        if (!existing || existing.score < next.score) {
+            dedup.set(key, next);
         }
-        if (depth <= 0)
-            break;
     }
-    if (fields.length === 0)
-        return null;
-    return { interfaceName, fields };
+    const scoredCitations = [...dedup.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, MAX_RAW_CITATIONS);
+    return {
+        scoredCitations,
+        matchedTerms,
+        scannedFiles: fileTree.length,
+    };
 }
-function splitIdentifierTokens(value) {
-    if (!value)
+function selectTopCitations(scored, maxCitations, searchTerms) {
+    if (scored.length === 0)
         return [];
-    const tokens = value
-        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-        .replace(/[_\-\s]+/g, ' ')
-        .toLowerCase()
-        .split(/\s+/)
-        .map((token) => token.trim())
-        .filter((token) => token.length >= 2);
-    return [...new Set(tokens)];
-}
-function buildSchemaFieldSummaries(citations, lineCache, terms) {
-    const scored = [];
-    const seen = new Set();
-    const highSignalTerms = terms.filter((term) => !LOW_SIGNAL_TERMS.has(term));
-    const queryTermSet = new Set(highSignalTerms.map((term) => term.toLowerCase()));
-    for (const citation of citations) {
-        const lines = lineCache.get(citation.path);
-        if (!lines || lines.length === 0)
-            continue;
-        const parsed = findInterfaceFieldBlock(lines, citation.line);
-        if (!parsed)
-            continue;
-        const interfaceKey = `${citation.path}:${parsed.interfaceName}`;
-        if (seen.has(interfaceKey))
-            continue;
-        const ifaceLower = parsed.interfaceName.toLowerCase();
-        const ifaceTokens = splitIdentifierTokens(parsed.interfaceName);
-        const ifaceText = `${ifaceLower} ${ifaceTokens.join(' ')}`.trim();
-        const fieldText = parsed.fields.join(' ').toLowerCase();
-        const nameHits = countTermHitsInText(ifaceText, highSignalTerms);
-        const fieldHits = countTermHitsInText(fieldText, highSignalTerms);
-        let relevanceScore = nameHits * 2 + fieldHits;
-        if (queryTermSet.has('plan') && ifaceText.includes('plan'))
-            relevanceScore += 0.8;
-        if (queryTermSet.has('cache') && ifaceText.includes('cache'))
-            relevanceScore += 0.8;
-        if (queryTermSet.has('key') && ifaceText.includes('key'))
-            relevanceScore += 1.2;
-        if ((queryTermSet.has('field') || queryTermSet.has('fields')) && parsed.fields.length > 0) {
-            relevanceScore += Math.min(1, parsed.fields.length / 8);
-        }
-        if (highSignalTerms.length > 0 && relevanceScore === 0) {
-            continue;
+    const profile = buildQueryProfile(searchTerms);
+    const asksLocationCode = profile.asksLocation && profile.codeFocused;
+    const structuralTerms = new Set([
+        'middleware', 'route', 'routes', 'service', 'services', 'controller', 'controllers',
+        'command', 'commands', 'schema', 'model', 'models', 'db', 'database', 'api', 'auth',
+        'cache', 'plan', 'verify', 'ship', 'apply', 'watch',
+    ]);
+    const sorted = [...scored].sort((a, b) => b.score - a.score);
+    const topScore = sorted[0]?.score || 0;
+    const scoreFloor = asksLocationCode ? topScore * 0.45 : topScore * 0.18;
+    let candidates = sorted.filter((citation) => citation.score >= scoreFloor);
+    if (candidates.length === 0) {
+        candidates = sorted.slice(0, maxCitations * 3);
+    }
+    if (asksLocationCode) {
+        const anchorTerms = searchTerms.highSignalTerms.filter((term) => structuralTerms.has(term.toLowerCase()));
+        if (anchorTerms.length > 0) {
+            const anchored = candidates.filter((citation) => {
+                const pathLower = citation.path.toLowerCase();
+                return anchorTerms.some((term) => pathLower.includes(term.toLowerCase()));
+            });
+            if (anchored.length >= Math.min(2, maxCitations)) {
+                candidates = anchored;
+            }
+        }
+        const strict = candidates.filter((citation) => !isLikelyDocumentationPath(citation.path) &&
+            !isLikelyDocSnippet(citation.snippet) &&
+            !isPromptExampleSnippet(citation.snippet, searchTerms.normalizedQuestion, searchTerms.highSignalTerms) &&
+            isLikelyCodeSnippet(citation.snippet));
+        if (strict.length >= Math.min(maxCitations, 3)) {
+            candidates = strict;
+        }
+        else {
+            const merged = [];
+            const seen = new Set();
+            for (const citation of [...strict, ...candidates]) {
+                const key = `${citation.path}:${citation.line}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                merged.push(citation);
+            }
+            candidates = merged;
+        }
+    }
+    if (profile.codeFocused && !asksLocationCode) {
+        const identifierAnchors = searchTerms.identifiers
+            .map((term) => (0, plan_cache_1.normalizeIntent)(term))
+            .filter((term) => term.length >= 3);
+        const termAnchors = searchTerms.highSignalTerms
+            .map((term) => term.toLowerCase().trim())
+            .filter((term) => term.length >= 3 && !LOW_SIGNAL_TERMS.has(term));
+        const anchors = [...new Set([...identifierAnchors, ...termAnchors])].slice(0, 8);
+        if (anchors.length > 0) {
+            const anchored = candidates.filter((citation) => {
+                const pathLower = citation.path.toLowerCase();
+                const snippetLower = citation.snippet.toLowerCase();
+                return anchors.some((term) => {
+                    if (pathLower.includes(term))
+                        return true;
+                    const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(term)}(?:$|[^a-z0-9])`, 'i');
+                    return pattern.test(snippetLower);
+                });
+            });
+            if (anchored.length >= Math.min(maxCitations, 4)) {
+                candidates = anchored;
+            }
         }
-        seen.add(interfaceKey);
-        scored.push({
-            score: relevanceScore,
-            summary: `${parsed.interfaceName}: ${parsed.fields.slice(0, 12).join(', ')}`,
+    }
+    if (profile.commandFocus) {
+        const commandNeedle = `/commands/${profile.commandFocus}.`;
+        const commandAnchored = candidates.filter((citation) => {
+            const pathLower = citation.path.toLowerCase();
+            return pathLower.includes(commandNeedle) || pathLower === 'packages/cli/src/index.ts';
         });
+        if (commandAnchored.length >= Math.min(maxCitations, 3)) {
+            candidates = commandAnchored;
+        }
     }
-    const ranked = scored.sort((a, b) => b.score - a.score);
-    if (ranked.length === 0)
-        return [];
-    const topScore = ranked[0].score;
-    let minScore = topScore >= 2 ? topScore * 0.6 : 0;
-    const strictExactFieldRequest = queryTermSet.has('exact') &&
-        (queryTermSet.has('field') || queryTermSet.has('fields'));
-    if (strictExactFieldRequest) {
-        minScore = Math.max(minScore, topScore - 0.5);
-    }
-    return ranked
-        .filter((item) => item.score >= minScore)
-        .slice(0, 6)
-        .map((item) => item.summary);
-}
-function extractInsightLines(citations, limit) {
-    const out = [];
-    const seen = new Set();
-    for (const citation of citations) {
-        const line = formatInsightSnippet(citation.snippet || '');
-        if (!line || line.length < 10)
-            continue;
-        if (/^#+\s/.test(line))
-            continue;
-        if (/^name:\s+/i.test(line))
-            continue;
-        const tooNoisy = /[{}[\];=><]/.test(line) && !/\b(multi-tenant|single-tenant|organization|install|command|feature)\b/i.test(line);
-        if (tooNoisy)
-            continue;
-        const key = line.toLowerCase();
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(line);
-        if (out.length >= limit)
-            break;
+    const byFile = new Map();
+    for (const citation of candidates) {
+        const bucket = byFile.get(citation.path) || [];
+        bucket.push(citation);
+        byFile.set(citation.path, bucket);
     }
-    return out;
-}
-function isCommandCatalogIntent(normalizedQuestion) {
-    const mentionsCommandSurface = /\b(cli|cmd|cmds|command|commands|subcommand|subcommands)\b/.test(normalizedQuestion);
-    if (!mentionsCommandSurface)
-        return false;
-    const listIntent = /\blist\b/.test(normalizedQuestion) ||
-        /\bshow\b/.test(normalizedQuestion) ||
-        /\bavailable\b/.test(normalizedQuestion) ||
-        /\ball commands?\b/.test(normalizedQuestion) ||
-        /\bwhich commands\b/.test(normalizedQuestion) ||
-        /\bwhat commands\b/.test(normalizedQuestion) ||
-        /\bwhat can i (type|run)\b/.test(normalizedQuestion) ||
-        /\bcan i type\b/.test(normalizedQuestion) ||
-        /\bcmds\b/.test(normalizedQuestion);
-    if (!listIntent)
-        return false;
-    const specificIntent = /\bwhere\b/.test(normalizedQuestion) ||
-        /\bhow\b/.test(normalizedQuestion) ||
-        /\bwhy\b/.test(normalizedQuestion) ||
-        /\bwhen\b/.test(normalizedQuestion) ||
-        /\bwhich file\b/.test(normalizedQuestion) ||
-        /\bin which file\b/.test(normalizedQuestion) ||
-        /\bfilepath\b/.test(normalizedQuestion) ||
-        /\bfile path\b/.test(normalizedQuestion) ||
-        /\binject(?:ed)?\b/.test(normalizedQuestion) ||
-        /\bhandle(?:s|d)?\b/.test(normalizedQuestion) ||
-        /\bused?\b/.test(normalizedQuestion) ||
-        /\bflow\b/.test(normalizedQuestion);
-    return !specificIntent;
-}
-function isPrimarySourcePath(filePath) {
-    const normalized = filePath.trim().replace(/\\/g, '/').toLowerCase();
-    if (!normalized)
-        return false;
-    if (normalized.startsWith('.neurcode/') ||
-        normalized.startsWith('.github/') ||
-        normalized.startsWith('.git/') ||
-        normalized.startsWith('node_modules/') ||
-        normalized.startsWith('dist/') ||
-        normalized.startsWith('build/') ||
-        normalized.startsWith('coverage/')) {
-        return false;
+    for (const list of byFile.values()) {
+        list.sort((a, b) => b.score - a.score);
     }
-    if (normalized.includes('/dist/') || normalized.includes('/build/') || normalized.includes('/coverage/')) {
-        return false;
+    const selected = [];
+    // Pass 1: strongest line per file.
+    for (const [_, list] of [...byFile.entries()].sort((a, b) => b[1][0].score - a[1][0].score)) {
+        if (selected.length >= maxCitations)
+            break;
+        selected.push(list.shift());
     }
-    const ext = normalized.includes('.') ? normalized.split('.').pop() || '' : '';
-    if (!ext) {
-        // Allow extensionless source-like files (e.g. Dockerfile, Makefile).
-        return true;
+    // Pass 2: fill remaining by global score.
+    const remainder = [...byFile.values()].flat().sort((a, b) => b.score - a.score);
+    for (const citation of remainder) {
+        if (selected.length >= maxCitations)
+            break;
+        selected.push(citation);
     }
-    return PRIMARY_SOURCE_EXTENSIONS.has(ext);
+    return selected.map(({ path, line, snippet, term }) => ({ path, line, snippet, term }));
 }
-function isBroadQuestion(normalizedQuestion) {
-    return (/\banywhere\b/.test(normalizedQuestion) ||
-        /\bacross\b/.test(normalizedQuestion) ||
-        /\bworkflow\b/.test(normalizedQuestion) ||
-        /\bentire\b/.test(normalizedQuestion) ||
-        /\bwhole\b/.test(normalizedQuestion) ||
-        /\ball\b/.test(normalizedQuestion) ||
-        /\bin repo\b/.test(normalizedQuestion));
-}
-function calibrateConfidence(truth) {
-    if (truth.status === 'insufficient')
-        return 'low';
-    if (truth.score >= 0.78)
-        return 'high';
-    if (truth.score >= 0.52)
-        return 'medium';
-    return 'low';
-}
-function evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceCitations, sourcePerFileCounts, sourceTermCounts) {
-    const broadQuestion = isBroadQuestion(normalizedQuestion);
-    const minCitationsRequired = mode === 'comparison' ? 2 : 2;
-    let minFilesRequired = mode === 'comparison' ? 2 : 1;
-    const sourceCitationCount = sourceCitations.length;
-    const sourceFileCount = sourcePerFileCounts.size;
-    const hasStrongSingleFileEvidence = sourceFileCount === 1 && sourceCitationCount >= 6;
-    if (broadQuestion) {
-        minFilesRequired = hasStrongSingleFileEvidence ? minFilesRequired : Math.max(minFilesRequired, 2);
-    }
+function evaluateTruth(normalizedQuestion, highSignalTerms, citations) {
+    const sourceCitations = citations.length;
+    const sourceFiles = new Set(citations.map((c) => c.path)).size;
+    const asksLocation = /\b(where|which file|location|defined|implemented|called|computed|resolved)\b/.test(normalizedQuestion);
+    const asksList = /\b(list|all|available|commands|files|features)\b/.test(normalizedQuestion);
+    const commandFocus = detectCommandFocus(normalizedQuestion);
+    const subcommandFocus = detectSubcommandFocus(normalizedQuestion, commandFocus);
+    const minCitationsRequired = asksLocation ? 1 : asksList ? 3 : 2;
+    const minFilesRequired = asksLocation ? 1 : 2;
+    const matchedHighSignalTerms = highSignalTerms.filter((term) => {
+        const normalized = term.toLowerCase();
+        return citations.some((citation) => {
+            const haystack = `${citation.path} ${citation.snippet}`.toLowerCase();
+            if (normalized.includes(' '))
+                return haystack.includes(normalized);
+            const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
+            return pattern.test(haystack);
+        });
+    });
+    const coverage = highSignalTerms.length === 0
+        ? (sourceCitations > 0 ? 1 : 0)
+        : matchedHighSignalTerms.length / highSignalTerms.length;
+    const citationScore = Math.min(1, sourceCitations / Math.max(minCitationsRequired, 3));
+    const fileScore = Math.min(1, sourceFiles / Math.max(minFilesRequired, 2));
+    let score = Math.max(0, Math.min(1, citationScore * 0.45 + fileScore * 0.35 + coverage * 0.2));
     const reasons = [];
-    if (sourceCitationCount === 0) {
-        reasons.push('No direct source-file evidence was found for the query terms.');
-    }
-    if (sourceCitationCount < minCitationsRequired) {
-        reasons.push(`Only ${sourceCitationCount} source citation(s) found (minimum ${minCitationsRequired} required).`);
-    }
-    if (sourceFileCount < minFilesRequired) {
-        reasons.push(`Evidence spans ${sourceFileCount} file(s) (minimum ${minFilesRequired} required for this question).`);
-    }
-    if (mode === 'comparison' && terms.length >= 2) {
-        const missingTerms = terms.filter((term) => (sourceTermCounts.get(term) || 0) === 0);
-        if (missingTerms.length > 0) {
-            reasons.push(`Missing direct source evidence for term(s): ${missingTerms.join(', ')}.`);
-        }
-    }
-    if (mode === 'search') {
-        const highSignalTerms = terms.filter((term) => !LOW_SIGNAL_TERMS.has(term));
-        if (highSignalTerms.length > 0) {
-            const matchedHighSignalTerms = highSignalTerms.filter((term) => (sourceTermCounts.get(term) || 0) > 0);
-            if (matchedHighSignalTerms.length === 0) {
-                reasons.push('No high-signal query terms were grounded in source citations.');
+    if (sourceCitations < minCitationsRequired) {
+        reasons.push(`Only ${sourceCitations} citation(s) found (minimum ${minCitationsRequired} expected).`);
+    }
+    if (sourceFiles < minFilesRequired) {
+        reasons.push(`Evidence spans ${sourceFiles} file(s) (minimum ${minFilesRequired} expected).`);
+    }
+    if (highSignalTerms.length > 0 && coverage < 0.4) {
+        reasons.push('Important query terms were not well represented in matched evidence.');
+    }
+    if (commandFocus) {
+        const commandNeedle = `/commands/${commandFocus}.`;
+        const commandFileCitations = citations.filter((citation) => citation.path.toLowerCase().includes(commandNeedle));
+        const registrationHits = citations.filter((citation) => citation.path.toLowerCase() === 'packages/cli/src/index.ts' &&
+            new RegExp(`\\.command\\(['"\`]${escapeRegExp(commandFocus)}['"\`]\\)`, 'i').test(citation.snippet));
+        const anchoredCount = commandFileCitations.length + registrationHits.length;
+        const anchoredRatio = sourceCitations > 0 ? anchoredCount / sourceCitations : 0;
+        if (anchoredCount === 0) {
+            reasons.push(`No direct evidence found in ${commandNeedle} or command registration wiring.`);
+        }
+        else if (sourceCitations >= 2 && anchoredRatio < 0.35) {
+            reasons.push('Top evidence is weakly anchored to the referenced command implementation.');
+        }
+        if (subcommandFocus) {
+            const subcommandDeclRegex = new RegExp(`\\.command\\(['"\`]${escapeRegExp(subcommandFocus)}(?:\\s+\\[[^\\]]+\\])?['"\`]\\)`, 'i');
+            const hasSubcommandDeclaration = citations.some((citation) => citation.path.toLowerCase().includes(commandNeedle) &&
+                subcommandDeclRegex.test(citation.snippet));
+            if (!hasSubcommandDeclaration) {
+                reasons.push(`No direct \`${subcommandFocus}\` subcommand declaration found in ${commandNeedle}.`);
             }
         }
-    }
-    let dominantShare = 0;
-    if (sourceCitationCount > 0) {
-        const highest = Math.max(...sourcePerFileCounts.values());
-        dominantShare = highest / sourceCitationCount;
-    }
-    if (broadQuestion && dominantShare > 0.85 && sourceFileCount < 3 && !hasStrongSingleFileEvidence) {
-        reasons.push('Evidence is highly concentrated in one file; broader coverage is required for this query.');
-    }
-    const citationScore = Math.min(1, sourceCitationCount / Math.max(minCitationsRequired, 4));
-    const fileScore = Math.min(1, sourceFileCount / Math.max(minFilesRequired, 3));
-    let termCoverageScore = 0;
-    if (mode === 'comparison' && terms.length >= 2) {
-        termCoverageScore = terms.filter((term) => (sourceTermCounts.get(term) || 0) > 0).length / terms.length;
-    }
-    else if (mode === 'search') {
-        const highSignalTerms = terms.filter((term) => !LOW_SIGNAL_TERMS.has(term));
-        if (highSignalTerms.length === 0) {
-            termCoverageScore = sourceCitationCount > 0 ? 1 : 0;
+        if (anchoredRatio < 0.35) {
+            score *= 0.68;
         }
-        else {
-            termCoverageScore = highSignalTerms.filter((term) => (sourceTermCounts.get(term) || 0) > 0).length / highSignalTerms.length;
+        else if (anchoredRatio < 0.55) {
+            score *= 0.86;
         }
     }
-    const concentrationPenalty = dominantShare > 0.9 ? 0.08 : dominantShare > 0.75 ? 0.04 : 0;
-    let score = citationScore * 0.45 + fileScore * 0.35 + termCoverageScore * 0.2 - concentrationPenalty;
-    if (!Number.isFinite(score))
-        score = 0;
-    score = Math.max(0, Math.min(score, 1));
-    if (score < 0.42 && reasons.length === 0) {
-        reasons.push('Evidence quality score is below the confidence threshold.');
+    if (score < 0.4 && reasons.length === 0) {
+        reasons.push('Evidence quality is below the confidence threshold.');
     }
     return {
-        status: reasons.length > 0 ? 'insufficient' : 'grounded',
+        status: reasons.length === 0 ? 'grounded' : 'insufficient',
         score,
         reasons,
-        sourceCitations: sourceCitationCount,
-        sourceFiles: sourceFileCount,
+        sourceCitations,
+        sourceFiles,
         minCitationsRequired,
         minFilesRequired,
     };
 }
-function buildAnswer(mode, question, terms, citations, stats, termCounts, perFileCounts, truth, context = {}) {
-    const confidence = calibrateConfidence(truth);
-    const normalizedQuestion = (0, plan_cache_1.normalizeIntent)(question);
-    const findings = [];
-    let answer = '';
-    const asksCommandCatalog = isCommandCatalogIntent(normalizedQuestion);
-    const asksInstall = /\b(install|upgrade|update|latest)\b/.test(normalizedQuestion);
-    const asksFeatures = /\b(feature|features|capability|capabilities|offers?)\b/.test(normalizedQuestion);
-    const asksSchema = /\b(field|fields|key|keys|schema|interface|input|output|parameter|parameters)\b/.test(normalizedQuestion);
-    const asksTenancy = /\b(tenant|tenancy|single|multi|organization)\b/.test(normalizedQuestion);
-    const asksLocation = /\b(where|which file|in which file|filepath|file path|location|defined|implemented|called|computed|resolved)\b/.test(normalizedQuestion);
-    const asksHow = /\bhow\b/.test(normalizedQuestion);
-    const asksDecision = /\b(decide|decision|verdict|pass|fail)\b/.test(normalizedQuestion);
-    const asksCommandSurface = /\b(command|commands|subcommand|subcommands|flag|flags|option|options)\b/.test(normalizedQuestion);
-    const asksSingleCommandLookup = /\b(what|which)\s+command\b/.test(normalizedQuestion) &&
-        !/\b(commands|subcommands)\b/.test(normalizedQuestion);
-    const asksOrgRequestInjection = /\b(inject|injected|header|request|requests)\b/.test(normalizedQuestion) &&
-        /\b(org|organization)\b/.test(normalizedQuestion);
-    const extractedCommandMatches = extractNeurcodeCommandsFromCitations(citations);
-    const knownCommands = context.knownCommands || [];
-    const knownCommandSet = new Set(knownCommands);
-    const knownRoots = new Set(knownCommands.map((command) => command.split(/\s+/).slice(0, 2).join(' ')));
-    const filteredExtractedMatches = knownCommands.length > 0
-        ? extractedCommandMatches.filter((command) => {
-            if (knownCommandSet.has(command))
-                return true;
-            const root = command.split(/\s+/).slice(0, 2).join(' ');
-            return knownRoots.has(root);
-        })
-        : extractedCommandMatches;
-    const commandMatches = [
-        ...knownCommands,
-        ...filteredExtractedMatches,
-    ].filter((value, index, arr) => arr.indexOf(value) === index);
-    const commandFocus = extractCommandFocus(normalizedQuestion);
-    const installMatches = extractInstallCommandsFromCitations(citations);
-    const insightLines = extractInsightLines(citations, 5);
-    const highSignalAnswerTerms = terms.filter((term) => !LOW_SIGNAL_TERMS.has(term) && term.length >= 3).slice(0, 10);
-    const anchorTerms = extractAnchorTerms(question);
-    const queriedFlags = (question.match(/--[a-z0-9-]+/gi) || []).map((flag) => flag.toLowerCase());
-    const pathAnchorTerms = (0, plan_cache_1.normalizeIntent)(question)
-        .replace(/[^a-z0-9_\-\s]/g, ' ')
-        .split(/\s+/)
-        .map((token) => token.trim())
-        .filter((token) => token.length >= 3 &&
-        !STOP_WORDS.has(token) &&
-        ![
-            'where', 'which', 'file', 'files', 'path', 'paths', 'location',
-            'defined', 'implemented', 'called', 'computed', 'resolved',
-        ].includes(token))
-        .slice(0, 10);
-    const citationRelevanceScore = (citation) => {
-        const snippetLower = (citation.snippet || '').toLowerCase();
-        let score = countTermHitsInText(snippetLower, highSignalAnswerTerms);
-        score += countTermHitsInText(citation.path.toLowerCase(), highSignalAnswerTerms) * 0.5;
-        const pathAnchorHits = countTermHitsInText(citation.path.toLowerCase(), pathAnchorTerms);
-        score += pathAnchorHits * 0.9;
-        if (asksLocation && pathAnchorTerms.length > 0 && pathAnchorHits === 0) {
-            score -= 0.35;
-        }
-        const anchorHits = countTermHitsInText(snippetLower, anchorTerms);
-        score += anchorHits * 1.4;
-        if ((asksLocation || asksHow) && anchorTerms.length > 0 && anchorHits === 0) {
-            score -= 0.45;
-        }
-        if (queriedFlags.length > 0) {
-            const flagHits = queriedFlags.filter((flag) => snippetLower.includes(flag)).length;
-            score += flagHits * 2;
-            if (asksLocation && flagHits === 0)
-                score -= 0.4;
-            if (/\.option\(/i.test(snippetLower) && flagHits > 0)
-                score += 2.5;
-        }
-        if (asksCommandSurface) {
-            if (/\.command\(|\bcommand\(/i.test(snippetLower))
-                score += 2;
-            if (/\.option\(|--[a-z0-9-]+/i.test(snippetLower))
-                score += 1.4;
-            if (citation.path.includes('/commands/') || citation.path.endsWith('/index.ts'))
-                score += 0.6;
-        }
-        if (commandFocus) {
-            if (citation.path.includes(`/commands/${commandFocus}.`)) {
-                score += 2.1;
-            }
-            else if ((asksLocation || asksHow) && citation.path.includes('/commands/')) {
-                score -= 1.0;
-            }
-            if (citation.path.endsWith('/index.ts') &&
-                new RegExp(`\\.command\\('${escapeRegExp(commandFocus)}'\\)`, 'i').test(citation.snippet)) {
-                score += 1.4;
-            }
-        }
-        if ((asksLocation || asksHow) && looksLikeImportLine(citation.snippet)) {
-            score -= 0.8;
-        }
-        if ((asksLocation || asksHow) && /^\s*[?:]?\s*['"`].+['"`][,;]?\s*$/i.test(citation.snippet)) {
-            score -= 0.9;
-        }
-        if (asksLocation && /console\.log\(/i.test(citation.snippet)) {
-            score -= 1.0;
-        }
-        if (asksDecision) {
-            if (/\b(verdict|exitcode|policydecision)\b/i.test(snippetLower) || /\bif\s*\(|\?\s*'[^']+'\s*:\s*'[^']+'/i.test(citation.snippet)) {
-                score += 1.1;
-            }
-            if (/(log|roi|estimat|time saved|badge|banner)/i.test(snippetLower)) {
-                score -= 0.9;
-            }
-        }
-        return score;
-    };
-    const multiSignals = citations.filter((citation) => /\bmulti[- ]tenant|x-org-id|organization[_ -]?id|org-scoped\b/i.test(citation.snippet)).length;
-    const singleSignals = citations.filter((citation) => /\bsingle[- ]tenant|single-user\b/i.test(citation.snippet)).length;
-    if (mode === 'comparison' && terms.length >= 2) {
-        const left = terms[0];
-        const right = terms[1];
-        const leftCount = termCounts.get(left) || 0;
-        const rightCount = termCounts.get(right) || 0;
-        if (leftCount > 0 && rightCount > 0) {
-            answer = `Found both "${left}" (${leftCount}) and "${right}" (${rightCount}) references in the scanned scope.`;
-        }
-        else if (leftCount > 0) {
-            answer = `Found "${left}" references (${leftCount}) and no direct "${right}" references in the scanned scope.`;
-        }
-        else if (rightCount > 0) {
-            answer = `No direct "${left}" references found; "${right}" appears ${rightCount} time(s) in the scanned scope.`;
-        }
-        else {
-            answer = `No direct references to "${left}" or "${right}" were found in the scanned scope.`;
-        }
-        findings.push(`Compared terms: "${left}" vs "${right}"`);
-        findings.push(`Matches by term: ${left}=${leftCount}, ${right}=${rightCount}`);
+function calibrateConfidence(truth) {
+    if (truth.status === 'insufficient')
+        return 'low';
+    if (truth.score >= 0.78)
+        return 'high';
+    if (truth.score >= 0.55)
+        return 'medium';
+    return 'low';
+}
+function isPrimarySourcePath(path) {
+    const normalized = path.toLowerCase();
+    if (isIgnoredSearchPath(normalized))
+        return false;
+    if (isLikelyDocumentationPath(normalized))
+        return false;
+    if (normalized === 'license' || normalized.startsWith('license.'))
+        return false;
+    if (normalized.endsWith('/license') || normalized.includes('/license.'))
+        return false;
+    if (normalized.startsWith('changelog') || normalized.includes('/changelog'))
+        return false;
+    if (normalized.endsWith('pnpm-lock.yaml'))
+        return false;
+    if (normalized.endsWith('package-lock.json'))
+        return false;
+    if (normalized.endsWith('yarn.lock'))
+        return false;
+    if (normalized.endsWith('.md'))
+        return false;
+    if (normalized.endsWith('.txt'))
+        return false;
+    if (normalized === 'readme.md')
+        return false;
+    if (normalized.startsWith('docs/'))
+        return false;
+    if (normalized.includes('/__tests__/'))
+        return false;
+    if (normalized.includes('.test.') || normalized.includes('.spec.'))
+        return false;
+    return true;
+}
+function formatCitationLocation(citation) {
+    return `${citation.path}:${citation.line}`;
+}
+function explainEvidenceCitation(citation) {
+    const location = formatCitationLocation(citation);
+    const snippet = normalizeSnippet(citation.snippet);
+    if (!snippet)
+        return `${location}`;
+    if (/\.command\(/.test(snippet)) {
+        return `${location} registers CLI wiring: ${snippet}`;
     }
-    else if (citations.length === 0) {
-        answer = 'I could not find direct grounded evidence for that in the files I scanned.';
-        findings.push('Try adding a module/file hint, for example: "in packages/cli" or "in services/api auth middleware".');
+    if (/^\s*import\b/.test(snippet)) {
+        return `${location} connects module dependency: ${snippet}`;
     }
-    else if (asksInstall) {
-        const manifestInstall = context.cliPackageName ? `npm install -g ${context.cliPackageName}@latest` : null;
-        const primaryInstall = manifestInstall || installMatches[0];
-        if (!primaryInstall) {
-            answer = 'I found CLI references, but not an explicit install command in the matched evidence.';
-        }
-        else {
-            answer = [
-                'Here is the install command I found for the CLI:',
-                `\`${primaryInstall}\``,
-                installMatches.length > 1 ? `Also seen: ${installMatches.slice(1, 3).map((cmd) => `\`${cmd}\``).join(', ')}` : '',
-            ].filter(Boolean).join('\n');
-        }
-    }
-    else if (asksFeatures && (context.featureBullets || []).length > 0) {
-        const bullets = (context.featureBullets || []).slice(0, 6).map((line) => `  • ${line}`);
-        answer = ['Here are the main platform features I could verify from the repo:', ...bullets].join('\n');
-    }
-    else if (asksFeatures) {
-        const inferredFeatures = [];
-        const signalText = citations.map((citation) => `${citation.path} ${citation.snippet}`.toLowerCase());
-        const hasSignal = (patterns) => {
-            return signalText.some((line) => patterns.some((pattern) => pattern.test(line)));
-        };
-        const preferredCommands = [
-            'neurcode ask',
-            'neurcode plan',
-            'neurcode apply',
-            'neurcode verify',
-            'neurcode ship',
-            'neurcode watch',
-            'neurcode session',
-            'neurcode revert',
-            'neurcode check',
-            'neurcode login',
-            'neurcode config',
-            'neurcode init',
-        ];
-        const primaryCommands = [
-            ...preferredCommands.filter((command) => commandMatches.includes(command)),
-            ...commandMatches.filter((command) => !preferredCommands.includes(command)),
-        ]
-            .filter((command) => !command.startsWith('neurcode session ') && !command.startsWith('neurcode revert '))
-            .slice(0, 12);
-        if (primaryCommands.length > 0) {
-            inferredFeatures.push(`CLI workflows: ${primaryCommands.join(', ')}`);
-        }
-        if (hasSignal([/\bverify\b/, /\bpolicy\b/, /\bscope[_ -]?guard\b/, /\bgovernance\b/])) {
-            inferredFeatures.push('Governance and policy verification gates.');
-        }
-        if (hasSignal([/\bship\b/, /\bmerge confidence\b/, /\bauto-remediation\b/])) {
-            inferredFeatures.push('Ship workflow with automated remediation and merge confidence scoring.');
-        }
-        if (hasSignal([/\bask\b/, /\bcitation\b/, /\bgrounded\b/, /\bbrain\b/])) {
-            inferredFeatures.push('Repository-grounded Q&A with cached context retrieval.');
-        }
-        if (hasSignal([/\bsession\b/, /\brevert\b/, /\bhistory\b/, /\btime machine\b/])) {
-            inferredFeatures.push('Session/history tracking with revert support.');
-        }
-        if (hasSignal([/\bx-org-id\b/, /\bmulti[- ]tenant\b/, /\borganization[_ -]?id\b/])) {
-            inferredFeatures.push('Multi-tenant organization-scoped isolation and identity context.');
-        }
-        if (inferredFeatures.length > 0) {
-            answer = ['Based on repository evidence, these platform capabilities are available:', ...inferredFeatures.map((line) => `  • ${line}`)].join('\n');
-        }
-        else {
-            answer = 'I found code evidence, but not enough explicit feature documentation to give a precise feature list yet.';
-        }
+    if (/\b(orgid|organizationid|userid|token|auth)\b/i.test(snippet) && /=/.test(snippet)) {
+        return `${location} sets auth/org context: ${snippet}`;
     }
-    else if (asksSchema && citations.length > 0) {
-        const lineCache = context.lineCache || new Map();
-        const schemaFieldSummaries = buildSchemaFieldSummaries(citations, lineCache, terms);
-        if (schemaFieldSummaries.length > 0) {
-            const bullets = schemaFieldSummaries.map((line) => `  • ${line}`);
-            answer = ['From the matched code, these fields/signatures are relevant:', ...bullets].join('\n');
-        }
-        else {
-            const schemaLines = citations
-                .map((citation) => formatInsightSnippet(citation.snippet))
-                .filter((line) => /^export\s+interface\b/i.test(line) ||
-                /^export\s+type\b/i.test(line) ||
-                (/^[A-Za-z_][A-Za-z0-9_?]*\s*:\s*[^=,]+;?$/.test(line) &&
-                    !line.includes('{') &&
-                    !line.includes('=>')));
-            const selected = [...new Set(schemaLines)].slice(0, 8);
-            if (selected.length > 0) {
-                const bullets = selected.map((line) => `  • ${line}`);
-                answer = ['From the matched code, these fields/signatures are relevant:', ...bullets].join('\n');
-            }
-            else {
-                answer = 'I found cache/schema-related code, but not enough direct field declarations in the top evidence.';
-            }
-        }
+    if (/\breturn\b/.test(snippet)) {
+        return `${location} returns runtime behavior: ${snippet}`;
     }
-    else if (asksSingleCommandLookup && commandMatches.length > 0) {
-        const commandQueryTerms = [...new Set(tokenizeQuestion(question).flatMap((term) => {
-                const out = [term.toLowerCase()];
-                if (term.endsWith('s') && term.length > 4)
-                    out.push(term.slice(0, -1).toLowerCase());
-                if (term.endsWith('ing') && term.length > 5)
-                    out.push(term.slice(0, -3).toLowerCase());
-                if (term.endsWith('ed') && term.length > 4)
-                    out.push(term.slice(0, -2).toLowerCase());
-                return out;
-            }))];
-        const scored = commandMatches
-            .map((command) => {
-            const normalized = command.toLowerCase();
-            let score = countTermHitsInText(normalized, commandQueryTerms);
-            if (/\bend(s|ed|ing)?\b/.test(normalizedQuestion) && /\bend\b/.test(normalized))
-                score += 0.8;
-            if (commandFocus &&
-                (normalized === `neurcode ${commandFocus}` || normalized.startsWith(`neurcode ${commandFocus} `))) {
-                score += 1.2;
-            }
-            return { command, score };
-        })
-            .sort((a, b) => b.score - a.score);
-        const selected = (scored.filter((item) => item.score > 0).slice(0, 3).map((item) => item.command));
-        const top = selected.length > 0 ? selected : [scored[0].command];
-        answer = top.length === 1
-            ? `Use \`${top[0]}\`.`
-            : ['Most relevant commands:', ...top.map((command) => `  • \`${command}\``)].join('\n');
-    }
-    else if (asksCommandCatalog && commandMatches.length > 0) {
-        const scopedCommands = commandFocus
-            ? commandMatches.filter((command) => command === `neurcode ${commandFocus}` || command.startsWith(`neurcode ${commandFocus} `))
-            : commandMatches;
-        const normalizedCommands = (scopedCommands.length > 0 ? scopedCommands : commandMatches)
-            .filter((command) => /^neurcode\s+[a-z]/.test(command))
-            .slice(0, 22);
-        const commandBullets = normalizedCommands.map((command) => `  • \`${command}\``);
-        answer = ['Here are the CLI commands I could verify from the repo:', ...commandBullets].join('\n');
-    }
-    else if (asksLocation && citations.length > 0) {
-        const focusedCitations = citations.filter((citation) => {
-            const term = (citation.term || '').toLowerCase();
-            return term.length === 0 || !GENERIC_OUTPUT_TERMS.has(term);
-        });
-        const locationPool = focusedCitations.length > 0 ? [...focusedCitations] : [...citations];
-        locationPool.sort((a, b) => citationRelevanceScore(b) - citationRelevanceScore(a));
-        if (asksOrgRequestInjection) {
-            const score = (citation) => {
-                const snippet = citation.snippet.toLowerCase();
-                let value = 0;
-                if (snippet.includes('x-org-id'))
-                    value += 4;
-                if (snippet.includes('auto-inject') || snippet.includes('inject'))
-                    value += 2;
-                if (snippet.includes('headers[') || snippet.includes('header'))
-                    value += 2;
-                if (snippet.includes('request'))
-                    value += 1;
-                if (citation.path.includes('api-client.ts'))
-                    value += 2;
-                return value;
-            };
-            locationPool.sort((a, b) => score(b) - score(a));
-        }
-        const prefersImplementationLines = /\b(defined|implemented|called|computed|resolved|lookup)\b/.test(normalizedQuestion);
-        const queriedFlags = (question.match(/--[a-z0-9-]+/gi) || []).map((flag) => flag.toLowerCase());
-        const declarationLike = prefersImplementationLines
-            ? locationPool.filter((citation) => /\b(?:export\s+)?(?:function|const|let|var|class|interface|type)\b/i.test(citation.snippet))
+    if (/\bawait\b/.test(snippet)) {
+        return `${location} performs async flow step: ${snippet}`;
+    }
+    return `${location} — ${snippet}`;
+}
+function collectUniquePaths(citations, limit, skipFirst) {
+    const out = [];
+    const seen = new Set();
+    const start = skipFirst ? 1 : 0;
+    for (let i = start; i < citations.length; i++) {
+        const path = citations[i]?.path;
+        if (!path || seen.has(path))
+            continue;
+        seen.add(path);
+        out.push(path);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+function buildRepoAnswerPayload(question, searchTerms, citations, stats, truth) {
+    const profile = buildQueryProfile(searchTerms);
+    const asksLocation = profile.asksLocation;
+    const asksHow = profile.asksHow;
+    const asksList = profile.asksList;
+    const primary = citations[0];
+    const primaryLocation = primary ? formatCitationLocation(primary) : null;
+    const flowPaths = collectUniquePaths(citations, 4, false);
+    const relatedPaths = collectUniquePaths(citations, 4, true);
+    const evidenceLines = citations
+        .slice(0, 6)
+        .map((citation) => `  • ${explainEvidenceCitation(citation)}`);
+    let answer = '';
+    if (citations.length === 0) {
+        answer = [
+            'Short answer: I do not have enough direct repository evidence for this yet.',
+            '',
+            'What will improve accuracy:',
+            '  • Add a folder/file hint (for example: `in packages/cli/src/commands`).',
+            '  • Mention exact identifiers (function/class/flag names) if you have them.',
+        ].join('\n');
+    }
+    else if (asksLocation) {
+        const relatedContext = relatedPaths.length > 0
+            ? ['', 'Related context worth checking:', ...relatedPaths.map((path) => `  • ${path}`)]
             : [];
-        const orderedLocationPool = declarationLike.length >= 2
-            ? [...declarationLike, ...locationPool.filter((citation) => !declarationLike.includes(citation))]
-            : locationPool;
-        const commandFocusedLocationPool = commandFocus
-            ? [...orderedLocationPool].sort((a, b) => {
-                const score = (citation) => {
-                    let value = 0;
-                    if (citation.path.includes(`/commands/${commandFocus}.`))
-                        value += 3;
-                    if (citation.path.endsWith('/index.ts') &&
-                        new RegExp(`\\.command\\('${escapeRegExp(commandFocus)}'\\)`, 'i').test(citation.snippet)) {
-                        value += 2;
-                    }
-                    if (citation.path.includes('/commands/') && !citation.path.includes(`/commands/${commandFocus}.`)) {
-                        value -= 0.5;
-                    }
-                    if (queriedFlags.length > 0) {
-                        const snippetLower = citation.snippet.toLowerCase();
-                        const matchedFlagCount = queriedFlags.filter((flag) => snippetLower.includes(flag)).length;
-                        value += matchedFlagCount * 2;
-                        if (/\.option\(/i.test(citation.snippet) && matchedFlagCount > 0)
-                            value += 2;
-                    }
-                    return value;
-                };
-                return score(b) - score(a);
-            })
-            : orderedLocationPool;
-        const locations = commandFocusedLocationPool
-            .slice(0, 5)
-            .map((citation) => `  • ${citation.path}:${citation.line} — ${formatInsightSnippet(citation.snippet)}`);
-        answer = ['I found the relevant references here:', ...locations].join('\n');
-    }
-    else if (asksHow && insightLines.length > 0) {
-        const focusedInsights = [...citations]
-            .sort((a, b) => citationRelevanceScore(b) - citationRelevanceScore(a))
-            .filter((citation) => citationRelevanceScore(citation) >= 1)
-            .map((citation) => formatInsightSnippet(citation.snippet))
-            .filter((line) => !/^const\s+[A-Za-z_$][\w$]*\s*=\s*\/.+\/[a-z]*\.test\(/i.test(line))
-            .filter((line) => !/^[A-Za-z_$][\w$]*,\s*$/.test(line))
-            .filter((line) => !/^['"`].+['"`],?\s*$/.test(line));
-        const decisionFilteredInsights = asksDecision
-            ? focusedInsights.filter((line) => !/(log|roi|estimat|time saved|badge|banner|record[a-z]*event|telemetry|metric)/i.test(line))
-            : focusedInsights;
-        const decisionCoreInsights = asksDecision
-            ? decisionFilteredInsights.filter((line) => /\b(verdict|policydecision|exitcode|pass|fail|warn)\b/i.test(line) ||
-                /\?\s*'[^']+'\s*:\s*'[^']+'/.test(line))
+        answer = [
+            `Short answer: ${primaryLocation} is the strongest direct location match.`,
+            '',
+            'What I verified in code:',
+            ...evidenceLines,
+            ...relatedContext,
+            '',
+            `If you want, I can trace upstream callers and downstream usage from ${primaryLocation}.`,
+        ].join('\n');
+    }
+    else if (asksHow) {
+        const flowSummary = flowPaths.length > 1
+            ? flowPaths.join(' -> ')
+            : flowPaths[0] || (primaryLocation || 'the top match');
+        const relatedContext = relatedPaths.length > 0
+            ? ['', 'Related context:', ...relatedPaths.map((path) => `  • ${path}`)]
             : [];
-        const selectedInsights = decisionCoreInsights.length > 0
-            ? [...new Set(decisionCoreInsights)].slice(0, 5)
-            : decisionFilteredInsights.length > 0
-                ? [...new Set(decisionFilteredInsights)].slice(0, 5)
-                : focusedInsights.length > 0
-                    ? [...new Set(focusedInsights)].slice(0, 5)
-                    : insightLines;
-        const bullets = selectedInsights.map((line) => `  • ${line}`);
-        answer = ['From the matched code, this is how it works:', ...bullets].join('\n');
-    }
-    else if (asksTenancy && (multiSignals > 0 || singleSignals > 0)) {
-        if (multiSignals >= singleSignals + 2) {
-            answer = 'This codebase is multi-tenant, with organization-scoped flows (for example org IDs / `x-org-id` context).';
-        }
-        else if (singleSignals >= multiSignals + 2) {
-            answer = 'This codebase currently looks single-tenant from the scanned evidence.';
-        }
-        else {
-            answer = 'I see mixed tenancy signals, but it leans multi-tenant in current runtime paths.';
-        }
-    }
-    else if (insightLines.length > 0) {
-        const bullets = insightLines.map((line) => `  • ${line}`);
-        answer = truth.status === 'insufficient'
-            ? ['I found partial evidence, but not enough for a fully definitive answer yet.', 'What I can confirm so far:', ...bullets].join('\n')
-            : ['From this repo, here is what I found:', ...bullets].join('\n');
+        answer = [
+            `Short answer: the implementation flow is centered around ${flowSummary}.`,
+            '',
+            'Evidence-backed breakdown:',
+            ...evidenceLines,
+            ...relatedContext,
+        ].join('\n');
+    }
+    else if (asksList) {
+        answer = [
+            `Short answer: I verified ${truth.sourceCitations} evidence line(s) across ${truth.sourceFiles} file(s).`,
+            '',
+            'Most relevant items:',
+            ...evidenceLines,
+            '',
+            'If you want, I can rank these by execution order next.',
+        ].join('\n');
     }
     else {
-        answer = `I found grounded evidence in ${stats.matchedFiles} file(s), but it is mostly low-level implementation detail.`;
-    }
-    if (asksCommandCatalog && commandMatches.length === 0 && citations.length > 0) {
-        findings.push('Command-style question detected, but no command declarations were found in the matched lines.');
+        const corroborating = relatedPaths.slice(0, 2);
+        const corroboratingText = corroborating.length > 0 ? corroborating.join(', ') : 'nearby modules';
+        answer = [
+            `Short answer: ${primaryLocation} is the strongest anchor, corroborated by ${corroboratingText}.`,
+            '',
+            'What I can confirm directly from the codebase:',
+            ...evidenceLines,
+        ].join('\n');
+    }
+    const findings = [
+        `Matched ${stats.matchedLines} evidence line(s) across ${stats.matchedFiles} primary source file(s).`,
+    ];
+    if (primaryLocation) {
+        findings.push(`Primary evidence anchor: ${primaryLocation}`);
     }
-    if (asksInstall && installMatches.length === 0 && !context.cliPackageName) {
-        findings.push('Install question detected, but no package name could be resolved from packages/cli/package.json.');
+    if (flowPaths.length > 1) {
+        findings.push(`Inferred file flow: ${flowPaths.join(' -> ')}`);
     }
-    const topFiles = [...perFileCounts.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 3)
-        .map(([file, count]) => `${file} (${count})`);
-    if (topFiles.length > 0) {
-        findings.push(`Most relevant files: ${topFiles.join(', ')}`);
+    if (searchTerms.highSignalTerms.length > 0) {
+        findings.push(`High-signal terms used: ${searchTerms.highSignalTerms.slice(0, 8).join(', ')}`);
     }
-    findings.push(`Scanned ${stats.scannedFiles} file(s); matched ${stats.matchedFiles} file(s).`);
     if (truth.status === 'insufficient') {
         findings.push(...truth.reasons);
-        findings.push('Add scope hints (module/file/path) to improve precision and grounding coverage.');
+        findings.push('Add a tighter module/file hint to improve grounding precision.');
     }
+    const topFiles = [...citations.reduce((acc, citation) => {
+            acc.set(citation.path, (acc.get(citation.path) || 0) + 1);
+            return acc;
+        }, new Map())]
+        .sort((a, b) => b[1] - a[1])
+        .map(([path]) => path)
+        .slice(0, 5);
     return {
         question,
-        questionNormalized: normalizedQuestion,
-        mode,
+        questionNormalized: searchTerms.normalizedQuestion,
+        mode: 'search',
         answer,
         findings,
-        confidence,
+        confidence: calibrateConfidence(truth),
         proof: {
-            topFiles: [...citations.reduce((acc, citation) => {
-                    acc.set(citation.path, (acc.get(citation.path) || 0) + 1);
-                    return acc;
-                }, new Map()).entries()]
-                .sort((a, b) => b[1] - a[1])
-                .slice(0, 5)
-                .map(([path]) => path),
+            topFiles,
             evidenceCount: citations.length,
             coverage: {
                 sourceCitations: truth.sourceCitations,
@@ -1653,6 +1875,168 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
         stats,
     };
 }
+function stripHtml(value) {
+    return value
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const EXTERNAL_LLM_BASE_URL = (process.env.NEURCODE_ASK_EXTERNAL_BASE_URL || 'https://api.deepinfra.com/v1/openai').replace(/\/+$/, '');
+const EXTERNAL_LLM_MODEL = process.env.NEURCODE_ASK_EXTERNAL_MODEL || 'deepseek-ai/DeepSeek-V3.2';
+const EXTERNAL_LLM_KEY_ENV_NAMES = [
+    'DEEPINFRA_API_KEY',
+    'NEURCODE_DEEPINFRA_API_KEY',
+    'DEEPSEEK_API_KEY',
+    'NEURCODE_DEEPSEEK_API_KEY',
+];
+function resolveExternalLlmApiKey() {
+    for (const envName of EXTERNAL_LLM_KEY_ENV_NAMES) {
+        const value = process.env[envName];
+        if (value && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+function inferExternalAnswerConfidence(text) {
+    const normalized = (0, plan_cache_1.normalizeIntent)(text);
+    if (!normalized)
+        return 'low';
+    if (/\b(i am not sure|i'm not sure|unsure|unknown|cannot verify|can't verify|not certain|might|may|possibly|likely|probably)\b/.test(normalized)) {
+        return 'low';
+    }
+    if (text.split(/\s+/).length <= 28)
+        return 'high';
+    return 'medium';
+}
+async function fetchExternalLlmAnswer(question) {
+    if (process.env.NEURCODE_ASK_DISABLE_EXTERNAL_WEB === '1') {
+        return null;
+    }
+    const apiKey = resolveExternalLlmApiKey();
+    if (!apiKey)
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${EXTERNAL_LLM_BASE_URL}/chat/completions`, {
+            method: 'POST',
+            signal: controller.signal,
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model: EXTERNAL_LLM_MODEL,
+                messages: [
+                    {
+                        role: 'system',
+                        content: [
+                            'You answer non-codebase factual questions for a CLI assistant.',
+                            'Return a direct factual answer in at most 2 short sentences.',
+                            'If uncertain, explicitly say you are not sure instead of guessing.',
+                            'Do not include markdown or code fences.',
+                        ].join(' '),
+                    },
+                    {
+                        role: 'user',
+                        content: question,
+                    },
+                ],
+                temperature: 0.1,
+                max_tokens: 220,
+            }),
+        });
+        if (!response.ok)
+            return null;
+        const payload = await response.json();
+        const content = payload.choices?.[0]?.message?.content;
+        if (typeof content !== 'string')
+            return null;
+        const text = stripHtml(content).replace(/^short answer:\s*/i, '').trim();
+        if (!text)
+            return null;
+        return {
+            text,
+            source: `${EXTERNAL_LLM_MODEL} via DeepInfra`,
+            confidence: inferExternalAnswerConfidence(text),
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function buildExternalAnswerPayload(question, normalizedQuestion, reasons) {
+    const external = await fetchExternalLlmAnswer(question);
+    const hasExternalLlmKey = Boolean(resolveExternalLlmApiKey());
+    const shortAnswer = external?.text
+        ? `Short answer: ${external.text}`
+        : hasExternalLlmKey
+            ? 'Short answer: I could not get a reliable external response right now.'
+            : 'Short answer: I could not answer this external question because DeepSeek is not configured (set DEEPINFRA_API_KEY).';
+    const sourceNote = external?.source
+        ? `Source used: ${external.source}`
+        : hasExternalLlmKey
+            ? 'DeepSeek request failed or returned no answer.'
+            : 'DeepSeek not configured. Set DEEPINFRA_API_KEY to enable external free-flow answers.';
+    const truthScore = external
+        ? external.confidence === 'high'
+            ? 0.42
+            : external.confidence === 'medium'
+                ? 0.34
+                : 0.24
+        : 0.08;
+    return {
+        question,
+        questionNormalized: normalizedQuestion,
+        mode: 'search',
+        answer: [
+            shortAnswer,
+            '',
+            'I am strongest on repository questions. Come back with a codebase question and I will answer with file/line citations.',
+        ].join('\n'),
+        findings: [
+            'Question appears to be outside repository scope.',
+            sourceNote,
+        ],
+        confidence: external ? (external.confidence === 'high' ? 'medium' : 'low') : 'low',
+        proof: {
+            topFiles: [],
+            evidenceCount: 0,
+            coverage: {
+                sourceCitations: 0,
+                sourceFiles: 0,
+                matchedFiles: 0,
+                matchedLines: 0,
+            },
+        },
+        truth: {
+            status: 'insufficient',
+            score: Number(truthScore.toFixed(2)),
+            reasons: [
+                'Answer is not grounded in repository files.',
+                ...reasons,
+            ],
+            sourceCitations: 0,
+            sourceFiles: 0,
+            minCitationsRequired: 2,
+            minFilesRequired: 1,
+        },
+        citations: [],
+        generatedAt: new Date().toISOString(),
+        stats: {
+            scannedFiles: 0,
+            matchedFiles: 0,
+            matchedLines: 0,
+            brainCandidates: 0,
+        },
+    };
+}
 function emitAskResult(result, options) {
     if (options.json) {
         console.log(JSON.stringify({
@@ -1679,66 +2063,49 @@ function emitAskResult(result, options) {
         console.log(chalk.yellow(result.answer));
     }
     const showProof = options.proof === true;
-    if (!options.verbose && !showProof) {
+    const showVerbose = options.verbose === true;
+    if (!showProof && !showVerbose) {
         console.log(chalk.dim(`\nConfidence: ${result.confidence.toUpperCase()}`));
-        if (result.truth.status === 'insufficient' && result.citations.length === 0 && result.truth.reasons.length > 0) {
+        if (result.truth.status === 'insufficient' && result.truth.reasons.length > 0) {
             console.log(chalk.yellow('\nWhy confidence is limited:'));
             for (const reason of result.truth.reasons.slice(0, 2)) {
                 console.log(chalk.yellow(`  • ${reason}`));
             }
-            console.log(chalk.dim('\nTip: add `--proof` for quick evidence digest or `--verbose` for full detail.'));
+            console.log(chalk.dim('\nTip: add `--proof` for concise evidence or `--verbose` for full evidence output.'));
         }
         return;
     }
-    if (showProof && !options.verbose) {
-        const proof = result.proof;
-        if (proof) {
+    if (showProof) {
+        if (result.proof) {
             console.log(chalk.bold.white('\nProof:'));
-            const topFiles = proof.topFiles.slice(0, 4);
-            if (topFiles.length > 0) {
-                console.log(chalk.cyan(`  • Top files: ${topFiles.join(', ')}`));
-            }
-            console.log(chalk.cyan(`  • Evidence: citations=${proof.coverage.sourceCitations}, source_files=${proof.coverage.sourceFiles}, matched_lines=${proof.coverage.matchedLines}`));
-        }
-        const tenancyQuestion = /\b(tenant|tenancy|single|multi|organization|org)\b/.test(result.questionNormalized);
-        let citations = result.citations.slice(0, Math.min(options.maxCitations, 12));
-        if (tenancyQuestion) {
-            const focused = citations.filter((citation) => /\b(multi[- ]tenant|x-org-id|organization[_ -]?id|org[_ -]?id)\b/i.test(citation.snippet));
-            if (focused.length >= 3) {
-                citations = focused;
-            }
-            if (/multi-tenant/i.test(result.answer)) {
-                citations = citations.filter((citation) => !/\bsingle-user platform\b/i.test(citation.snippet));
+            if (result.proof.topFiles.length > 0) {
+                console.log(chalk.cyan(`  • Top files: ${result.proof.topFiles.slice(0, 5).join(', ')}`));
             }
+            console.log(chalk.cyan(`  • Coverage: citations=${result.proof.coverage.sourceCitations}, files=${result.proof.coverage.sourceFiles}, matched_lines=${result.proof.coverage.matchedLines}`));
         }
-        citations = citations.slice(0, Math.min(options.maxCitations, 6));
-        if (citations.length > 0) {
+        const proofCitations = result.citations.slice(0, Math.min(options.maxCitations, 6));
+        if (proofCitations.length > 0) {
             console.log(chalk.bold.white('\nKey Evidence:'));
-            citations.forEach((citation, idx) => {
+            proofCitations.forEach((citation, idx) => {
                 console.log(chalk.dim(`  ${idx + 1}. ${citation.path}:${citation.line} ${citation.snippet}`));
             });
         }
-        const truthLabel = result.truth.status === 'grounded' ? chalk.green('GROUNDED') : chalk.yellow('INSUFFICIENT');
-        console.log(chalk.dim(`\nTruth Mode: ${truthLabel} (score=${result.truth.score.toFixed(2)}, source_citations=${result.truth.sourceCitations}, source_files=${result.truth.sourceFiles})`));
-        console.log(chalk.dim(`Confidence: ${result.confidence.toUpperCase()} | scanned=${result.stats.scannedFiles} matched=${result.stats.matchedFiles}`));
-        return;
     }
-    if (result.findings.length > 0) {
-        console.log(chalk.bold.white('\nFindings:'));
-        for (const finding of result.findings) {
-            console.log(chalk.cyan(`  • ${finding}`));
+    if (showVerbose) {
+        if (result.findings.length > 0) {
+            console.log(chalk.bold.white('\nFindings:'));
+            for (const finding of result.findings) {
+                console.log(chalk.cyan(`  • ${finding}`));
+            }
+        }
+        const verboseCitations = result.citations.slice(0, options.maxCitations);
+        if (verboseCitations.length > 0) {
+            console.log(chalk.bold.white('\nEvidence:'));
+            verboseCitations.forEach((citation, idx) => {
+                const prefix = citation.term ? `${citation.term} ` : '';
+                console.log(chalk.dim(`  ${idx + 1}. ${citation.path}:${citation.line} ${prefix}${citation.snippet}`));
+            });
         }
-    }
-    const citations = result.citations.slice(0, options.maxCitations);
-    if (citations.length > 0) {
-        console.log(chalk.bold.white('\nEvidence:'));
-        citations.forEach((citation, idx) => {
-            const prefix = citation.term ? `${citation.term} ` : '';
-            console.log(chalk.dim(`  ${idx + 1}. ${citation.path}:${citation.line} ${prefix}${citation.snippet}`));
-        });
-    }
-    else {
-        console.log(chalk.yellow('\nEvidence: no direct matching lines found.'));
     }
     const truthLabel = result.truth.status === 'grounded' ? chalk.green('GROUNDED') : chalk.yellow('INSUFFICIENT');
     console.log(chalk.dim(`\nTruth Mode: ${truthLabel} (score=${result.truth.score.toFixed(2)}, source_citations=${result.truth.sourceCitations}, source_files=${result.truth.sourceFiles})`));
@@ -1759,13 +2126,96 @@ async function askCommand(question, options = {}) {
         const scope = { orgId: orgId || null, projectId: projectId || null };
         const maxCitations = Math.max(3, Math.min(options.maxCitations || 12, 30));
         const shouldUseCache = options.cache !== false && process.env.NEURCODE_ASK_NO_CACHE !== '1';
-        const normalizedQuestion = (0, plan_cache_1.normalizeIntent)(question);
-        const deterministic = tryBuildDeterministicAnswer(cwd, question, normalizedQuestion);
-        if (deterministic) {
-            if (!options.json) {
-                console.log(chalk.dim(`🧠 Asking repo context in ${cwd}...`));
+        const searchTerms = buildSearchTerms(question);
+        const ownershipAnswer = buildOwnershipDeterministicAnswer(cwd, question, searchTerms.normalizedQuestion);
+        if (ownershipAnswer) {
+            emitAskResult(ownershipAnswer, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+                proof: options.proof,
+            });
+            if (orgId && projectId) {
+                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
+                    type: 'ask',
+                    note: `mode=deterministic;reason=ownership_git_history;truth=${ownershipAnswer.truth.status};score=${ownershipAnswer.truth.score.toFixed(2)}`,
+                });
             }
-            emitAskResult(deterministic.payload, {
+            return;
+        }
+        const scopeAssessment = classifyQuestionScope(question, searchTerms);
+        if (scopeAssessment.kind === 'external') {
+            const externalPayload = await buildExternalAnswerPayload(question, searchTerms.normalizedQuestion, scopeAssessment.reasons);
+            emitAskResult(externalPayload, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+                proof: options.proof,
+            });
+            if (orgId && projectId) {
+                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
+                    type: 'ask',
+                    note: `mode=external;truth=${externalPayload.truth.status};score=${externalPayload.truth.score.toFixed(2)}`,
+                });
+            }
+            return;
+        }
+        const registrationAnswer = buildCommandRegistrationDeterministicAnswer(cwd, question, searchTerms, maxCitations);
+        if (registrationAnswer) {
+            emitAskResult(registrationAnswer, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+                proof: options.proof,
+            });
+            if (orgId && projectId) {
+                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
+                    type: 'ask',
+                    note: `mode=deterministic;reason=command_registration;truth=${registrationAnswer.truth.status};score=${registrationAnswer.truth.score.toFixed(2)}`,
+                });
+            }
+            return;
+        }
+        const commandInventoryAnswer = buildCommandInventoryDeterministicAnswer(cwd, question, searchTerms, maxCitations);
+        if (commandInventoryAnswer) {
+            emitAskResult(commandInventoryAnswer, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+                proof: options.proof,
+            });
+            if (orgId && projectId) {
+                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
+                    type: 'ask',
+                    note: `mode=deterministic;reason=command_inventory;truth=${commandInventoryAnswer.truth.status};score=${commandInventoryAnswer.truth.score.toFixed(2)}`,
+                });
+            }
+            return;
+        }
+        const commandSubcommandFlowAnswer = buildCommandSubcommandFlowDeterministicAnswer(cwd, question, searchTerms, maxCitations);
+        if (commandSubcommandFlowAnswer) {
+            emitAskResult(commandSubcommandFlowAnswer, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+                proof: options.proof,
+            });
+            if (orgId && projectId) {
+                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
+                    type: 'ask',
+                    note: `mode=deterministic;reason=command_subcommand_flow;truth=${commandSubcommandFlowAnswer.truth.status};score=${commandSubcommandFlowAnswer.truth.score.toFixed(2)}`,
+                });
+            }
+            return;
+        }
+        const askCacheFlowAnswer = buildAskCacheFlowDeterministicAnswer(cwd, question, searchTerms, maxCitations);
+        if (askCacheFlowAnswer) {
+            emitAskResult(askCacheFlowAnswer, {
                 json: options.json,
                 maxCitations,
                 fromPlan: options.fromPlan,
@@ -1775,7 +2225,7 @@ async function askCommand(question, options = {}) {
             if (orgId && projectId) {
                 (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
                     type: 'ask',
-                    note: `mode=deterministic;reason=${deterministic.reason};truth=${deterministic.payload.truth.status};score=${deterministic.payload.truth.score.toFixed(2)}`,
+                    note: `mode=deterministic;reason=ask_cache_flow;truth=${askCacheFlowAnswer.truth.status};score=${askCacheFlowAnswer.truth.score.toFixed(2)}`,
                 });
             }
             return;
@@ -1802,12 +2252,12 @@ async function askCommand(question, options = {}) {
                 });
             }
             catch {
-                // non-blocking
+                // Non-blocking.
             }
         }
         if (shouldUseCache && orgId && projectId) {
             const questionHash = (0, ask_cache_1.computeAskQuestionHash)({
-                question: normalizedQuestion,
+                question: searchTerms.normalizedQuestion,
                 contextHash: staticContext.hash,
             });
             const exactKey = (0, ask_cache_1.computeAskCacheKey)({
@@ -1824,7 +2274,7 @@ async function askCommand(question, options = {}) {
                 const exactOutput = {
                     ...exact.output,
                     question,
-                    questionNormalized: normalizedQuestion,
+                    questionNormalized: searchTerms.normalizedQuestion,
                 };
                 emitAskResult(exactOutput, {
                     json: options.json,
@@ -1844,18 +2294,18 @@ async function askCommand(question, options = {}) {
                 orgId,
                 projectId,
                 repo: repoFingerprint,
-                question: normalizedQuestion,
+                question: searchTerms.normalizedQuestion,
                 policyVersionHash,
                 neurcodeVersion,
                 contextHash: staticContext.hash,
                 changedPaths: (0, ask_cache_1.getChangedWorkingTreePaths)(cwd),
-                minSimilarity: 0.68,
+                minSimilarity: 0.72,
             });
             if (near) {
                 const nearOutput = {
                     ...near.entry.output,
                     question,
-                    questionNormalized: normalizedQuestion,
+                    questionNormalized: searchTerms.normalizedQuestion,
                 };
                 const reasonText = near.reason === 'safe_repo_drift_similar_question'
                     ? 'Using near-cached answer (safe repo drift)'
@@ -1879,408 +2329,24 @@ async function askCommand(question, options = {}) {
             console.log(chalk.dim(`🧠 Asking repo context in ${cwd}...`));
         }
         const brainResults = orgId && projectId
-            ? (0, brain_context_1.searchBrainContextEntries)(cwd, scope, normalizedQuestion, { limit: 48 })
+            ? (0, brain_context_1.searchBrainContextEntries)(cwd, scope, searchTerms.normalizedQuestion, { limit: 64 })
             : { entries: [], totalIndexedFiles: 0 };
-        const cliPackageName = readCliPackageName(cwd);
-        const knownCliCommands = extractCommandsFromCliIndex(cwd);
-        const featureBullets = extractFeatureBulletsForRepo(cwd, 10);
-        if (!options.json && brainResults.entries.length > 0) {
-            const top = brainResults.entries.filter((entry) => entry.score > 0).length;
-            console.log(chalk.dim(`🧠 Brain retrieval: ${top} relevant file summaries from ${brainResults.totalIndexedFiles} indexed files`));
-        }
-        const { mode, terms, matchers } = buildMatchers(question);
-        const pathHints = derivePathHints(question);
-        const mentionsAskCommand = /\bask\b/.test(normalizedQuestion);
-        const asksQuestionAnsweringInternals = /\b(question|questions|answer|answers|cache|brain|citation|grounded)\b/.test(normalizedQuestion);
-        if (matchers.length === 0) {
-            console.error(chalk.red('❌ Could not derive useful search terms from the question.'));
-            process.exit(1);
-        }
-        const candidateSet = new Set();
-        const pathPriority = new Map();
+        const pathBoostScores = new Map();
         for (const entry of brainResults.entries) {
-            candidateSet.add(entry.path);
-            pathPriority.set(entry.path, (pathPriority.get(entry.path) || 0) + entry.score);
-        }
-        addAnchorCandidates(fileTree, candidateSet, pathPriority, normalizedQuestion);
-        const tokenHints = tokenizeQuestion(question);
-        const codeFocusedQuestion = /\b(how|where|which file|defined|implemented|called|computed|resolved|function|class|api|command|flow|trace|why|field|fields|key|keys|schema|interface|parameter|parameters)\b/.test(normalizedQuestion) &&
-            !/\b(feature|features|install|setup|readme|docs|documentation)\b/.test(normalizedQuestion);
-        if (candidateSet.size < 80) {
-            for (const filePath of fileTree) {
-                const normalizedPath = filePath.toLowerCase();
-                let score = pathPriority.get(filePath) || 0;
-                for (const token of tokenHints) {
-                    if (normalizedPath.includes(token))
-                        score += 0.2;
-                }
-                if (normalizedPath.startsWith('.github/')) {
-                    score -= 0.2;
-                }
-                if (normalizedPath.startsWith('scripts/')) {
-                    score -= 0.1;
-                }
-                if (codeFocusedQuestion && (filePath === 'README.md' || normalizedPath.startsWith('docs/'))) {
-                    score -= 0.35;
-                }
-                if (!mentionsAskCommand &&
-                    !asksQuestionAnsweringInternals &&
-                    (filePath.endsWith('/commands/ask.ts') || filePath.endsWith('/utils/ask-cache.ts'))) {
-                    score -= 0.45;
-                }
-                if (pathHints.some((hint) => normalizedPath.startsWith(hint))) {
-                    score += 0.45;
-                }
-                else if (pathHints.length > 0) {
-                    score -= 0.08;
-                }
-                if (/\b(feature|features|capability|capabilities|offers?|platform)\b/.test(normalizedQuestion)) {
-                    if (filePath === 'README.md' || normalizedPath.startsWith('docs/')) {
-                        score += 0.55;
-                    }
-                    if (normalizedPath.startsWith('web/') || normalizedPath.startsWith('packages/dashboard/')) {
-                        score -= 0.25;
-                    }
-                }
-                if (score > 0) {
-                    candidateSet.add(filePath);
-                    pathPriority.set(filePath, score);
-                }
-            }
-        }
-        if (candidateSet.size < 40) {
-            for (const filePath of fileTree.slice(0, Math.min(fileTree.length, MAX_SCAN_FILES))) {
-                candidateSet.add(filePath);
-            }
-        }
-        const selfReferenceFiles = new Set([
-            'packages/cli/src/commands/ask.ts',
-            'packages/cli/src/utils/ask-cache.ts',
-        ]);
-        const prioritized = [...candidateSet]
-            .filter((filePath) => (0, fs_1.existsSync)((0, path_1.join)(cwd, filePath)))
-            .filter((filePath) => mentionsAskCommand || !selfReferenceFiles.has(filePath))
-            .sort((a, b) => (pathPriority.get(b) || 0) - (pathPriority.get(a) || 0));
-        const hinted = pathHints.length > 0
-            ? prioritized.filter((filePath) => pathHints.some((hint) => filePath.startsWith(hint)))
-            : [];
-        const nonHinted = pathHints.length > 0
-            ? prioritized.filter((filePath) => !pathHints.some((hint) => filePath.startsWith(hint)))
-            : prioritized;
-        const candidates = [...hinted, ...nonHinted].slice(0, MAX_SCAN_FILES);
-        const querySignals = deriveQuerySignals(question, normalizedQuestion, terms);
-        const commandFocusQuery = extractCommandFocus(normalizedQuestion);
-        const anchorTerms = extractAnchorTerms(question);
-        const hasTemporalIntent = /\b(before|after|during|when)\b/.test(normalizedQuestion);
-        const highSignalSet = new Set(querySignals.highSignalTerms);
-        const rawFileMatches = new Map();
-        const termFileHits = new Map();
-        let scannedFiles = 0;
-        for (const filePath of candidates) {
-            const fullPath = (0, path_1.join)(cwd, filePath);
-            let content = '';
-            try {
-                const st = (0, fs_1.statSync)(fullPath);
-                if (st.size > MAX_FILE_BYTES)
-                    continue;
-                content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
-            }
-            catch {
-                continue;
-            }
-            scannedFiles++;
-            const lines = content.split(/\r?\n/);
-            const lineTerms = new Map();
-            const matchedTerms = new Set();
-            for (let idx = 0; idx < lines.length; idx++) {
-                const rawLine = lines[idx];
-                if (!rawLine || rawLine.trim().length === 0)
-                    continue;
-                for (const matcher of matchers) {
-                    if (!matcher.regex.test(rawLine))
-                        continue;
-                    if (!lineTerms.has(idx))
-                        lineTerms.set(idx, new Set());
-                    lineTerms.get(idx).add(matcher.label);
-                    matchedTerms.add(matcher.label);
-                }
-            }
-            if (lineTerms.size === 0)
-                continue;
-            rawFileMatches.set(filePath, {
-                lines,
-                lineTerms,
-                pathScore: pathPriority.get(filePath) || 0,
-                hintBoost: pathHints.some((hint) => filePath.startsWith(hint)) ? 0.25 : 0,
-            });
-            for (const term of matchedTerms) {
-                termFileHits.set(term, (termFileHits.get(term) || 0) + 1);
-            }
-        }
-        const matchedFileTotal = Math.max(rawFileMatches.size, 1);
-        const termWeight = new Map();
-        for (const term of terms) {
-            const docFreq = termFileHits.get(term) || 0;
-            const idfWeight = Math.log((matchedFileTotal + 1) / (docFreq + 1)) + 0.25;
-            const highSignalBoost = highSignalSet.has(term) ? 0.35 : 0;
-            termWeight.set(term, Math.max(0.08, idfWeight + highSignalBoost));
-        }
-        const citations = [];
-        for (const [filePath, fileData] of rawFileMatches.entries()) {
-            const { lines, lineTerms, pathScore, hintBoost } = fileData;
-            for (const [lineIdx, directTerms] of lineTerms.entries()) {
-                if (citations.length >= MAX_RAW_CITATIONS)
-                    break;
-                const rawLine = lines[lineIdx] || '';
-                const snippet = normalizeSnippet(rawLine);
-                if (!snippet)
-                    continue;
-                const windowTerms = new Set();
-                const contextRadius = querySignals.asksLocation || querySignals.asksDefinition ? 6 : 2;
-                for (let i = Math.max(0, lineIdx - contextRadius); i <= Math.min(lines.length - 1, lineIdx + contextRadius); i++) {
-                    const termsAtLine = lineTerms.get(i);
-                    if (!termsAtLine)
-                        continue;
-                    for (const term of termsAtLine)
-                        windowTerms.add(term);
-                }
-                const highSignalWindow = [...windowTerms].filter((term) => highSignalSet.has(term));
-                let score = pathScore + hintBoost;
-                for (const term of windowTerms) {
-                    score += termWeight.get(term) || 0.1;
-                }
-                score += highSignalWindow.length * 0.7;
-                score += windowTerms.size * 0.12;
-                if (querySignals.highSignalTerms.length > 0 && highSignalWindow.length === 0) {
-                    score -= 0.65;
-                }
-                if ((querySignals.asksLocation || querySignals.asksDefinition) && querySignals.highSignalTerms.length >= 2 && highSignalWindow.length < 2) {
-                    score -= 0.9;
-                }
-                const anchorHits = countTermHitsInText(rawLine.toLowerCase(), anchorTerms);
-                score += anchorHits * 1.2;
-                if ((querySignals.asksLocation || querySignals.asksDefinition) && anchorTerms.length > 0 && anchorHits === 0) {
-                    score -= 0.6;
-                }
-                if (querySignals.asksLocation || querySignals.asksDefinition) {
-                    if (looksLikeImportLine(rawLine))
-                        score -= 0.75;
-                    if (/\b(?:export\s+)?(?:function|const|let|var|class|interface|type)\b/.test(rawLine) &&
-                        countTermHitsInText(rawLine.toLowerCase(), querySignals.highSignalTerms) >= 1) {
-                        score += 0.9;
-                    }
-                    if (querySignals.asksDefinition && /console\.log\(/.test(rawLine)) {
-                        score -= 0.6;
-                    }
-                    for (const identifier of querySignals.identifiers) {
-                        const escaped = escapeRegExp(identifier);
-                        if (new RegExp(`\\b${escaped}\\s*\\(`, 'i').test(rawLine)) {
-                            score += 0.95;
-                        }
-                        if (new RegExp(`\\b(?:function|const|let|var|class|interface|type)\\s+${escaped}\\b`, 'i').test(rawLine)) {
-                            score += 0.8;
-                        }
-                    }
-                    if (hasTemporalIntent) {
-                        if (/\b[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(rawLine))
-                            score += 0.75;
-                        if (/^\s*export\s+(interface|type)\b/.test(rawLine))
-                            score -= 0.9;
-                        if (/^\s*const\s+[A-Z0-9_]+\s*=/.test(rawLine))
-                            score -= 0.7;
-                    }
-                }
-                if (querySignals.asksHow && /\b(if|else|return|await|for|while|switch)\b/.test(rawLine)) {
-                    score += 0.2;
-                }
-                if (querySignals.asksHow) {
-                    const trimmed = rawLine.trim();
-                    if (trimmed.startsWith('//') || trimmed.startsWith('*'))
-                        score -= 0.45;
-                    if (/\.description\(/.test(rawLine))
-                        score -= 0.4;
-                }
-                if (querySignals.asksSchema) {
-                    if (/^\s*export\s+interface\s+/i.test(rawLine) || /^\s*export\s+type\s+/i.test(rawLine))
-                        score += 1.1;
-                    if (/^\s*[A-Za-z_][A-Za-z0-9_?]*\s*:\s*/.test(rawLine))
-                        score += 0.8;
-                    if (filePath.endsWith('.md'))
-                        score -= 0.5;
-                }
-                if (rawLine.length > 180 && rawLine.includes(',') && /['"`].*['"`].*['"`]/.test(rawLine)) {
-                    score -= 0.35;
-                }
-                if ((querySignals.asksLocation || querySignals.asksDefinition) && /Usage:\s*neurcode/i.test(rawLine)) {
-                    score -= 0.6;
-                }
-                if ((querySignals.asksLocation || querySignals.asksDefinition) && /^\s*type:\s*['"`][a-z0-9_-]+['"`],?\s*$/i.test(rawLine)) {
-                    score -= 0.7;
-                }
-                if (querySignals.asksCommandSurface) {
-                    if (/\.command\(|\bcommand\(/i.test(rawLine))
-                        score += 1.2;
-                    if (/\.option\(|--[a-z0-9-]+/i.test(rawLine))
-                        score += 0.8;
-                    if (filePath.endsWith('/index.ts') || filePath.includes('/commands/'))
-                        score += 0.35;
-                }
-                if (commandFocusQuery) {
-                    if (filePath.includes(`/commands/${commandFocusQuery}.`)) {
-                        score += 1.4;
-                    }
-                    else if ((querySignals.asksHow || querySignals.asksLocation) && filePath.includes('/commands/')) {
-                        score -= 1.2;
-                    }
-                    if (filePath.endsWith('/index.ts') &&
-                        new RegExp(`\\.command\\('${escapeRegExp(commandFocusQuery)}'\\)`, 'i').test(rawLine)) {
-                        score += 1.1;
-                    }
-                }
-                const dominantTerm = [...directTerms].sort((a, b) => (termWeight.get(b) || 0) - (termWeight.get(a) || 0))[0] ||
-                    [...windowTerms].sort((a, b) => (termWeight.get(b) || 0) - (termWeight.get(a) || 0))[0] ||
-                    '';
-                if (score <= 0)
-                    continue;
-                citations.push({
-                    path: filePath,
-                    line: lineIdx + 1,
-                    snippet,
-                    term: dominantTerm,
-                    weight: score,
-                });
-            }
-        }
-        citations.sort((a, b) => b.weight - a.weight);
-        const sourceEvidence = citations.filter((citation) => isPrimarySourcePath(citation.path));
-        const sourcePerFileCounts = new Map();
-        const sourceTermCounts = new Map();
-        for (const citation of sourceEvidence) {
-            sourcePerFileCounts.set(citation.path, (sourcePerFileCounts.get(citation.path) || 0) + 1);
-            if (citation.term) {
-                sourceTermCounts.set(citation.term, (sourceTermCounts.get(citation.term) || 0) + 1);
-            }
-        }
-        const selectedForOutput = [];
-        const selectedFileCounts = new Map();
-        const pushSelected = (citation) => {
-            if (selectedForOutput.length >= maxCitations)
-                return false;
-            if (selectedForOutput.some((existing) => existing.path === citation.path && existing.line === citation.line && existing.term === citation.term)) {
-                return false;
-            }
-            if (querySignals.asksLocation || querySignals.asksDefinition) {
-                const perFile = selectedFileCounts.get(citation.path) || 0;
-                const distinctFiles = selectedFileCounts.size;
-                const targetDistinct = Math.min(3, sourcePerFileCounts.size);
-                if (perFile >= 3 && distinctFiles < targetDistinct) {
-                    return false;
-                }
-            }
-            selectedForOutput.push(citation);
-            selectedFileCounts.set(citation.path, (selectedFileCounts.get(citation.path) || 0) + 1);
-            return true;
-        };
-        if (mode === 'search' && querySignals.asksSchema) {
-            const schemaAffinity = (citation) => {
-                const text = citation.snippet.toLowerCase();
-                let affinity = 0;
-                for (const term of querySignals.highSignalTerms) {
-                    const normalized = term.toLowerCase();
-                    const compact = normalized.replace(/\s+/g, '');
-                    if (text.includes(normalized))
-                        affinity += 1;
-                    else if (text.includes(compact))
-                        affinity += 0.85;
-                }
-                return affinity;
-            };
-            const schemaPreferred = sourceEvidence
-                .filter((citation) => /^export\s+interface\b/i.test(citation.snippet) ||
-                /^export\s+type\b/i.test(citation.snippet) ||
-                /^[A-Za-z_][A-Za-z0-9_?]*\s*:\s*[^=,]+;?$/.test(citation.snippet))
-                .sort((a, b) => {
-                const affinityDiff = schemaAffinity(b) - schemaAffinity(a);
-                if (affinityDiff !== 0)
-                    return affinityDiff;
-                return b.weight - a.weight;
-            });
-            for (const citation of schemaPreferred) {
-                if (selectedForOutput.length >= maxCitations)
-                    break;
-                pushSelected(citation);
-            }
+            pathBoostScores.set(entry.path, Math.max(pathBoostScores.get(entry.path) || 0, entry.score));
         }
-        if (mode === 'comparison' && terms.length >= 2) {
-            for (const term of terms.slice(0, 2)) {
-                const firstForTerm = sourceEvidence.find((citation) => citation.term === term);
-                if (firstForTerm) {
-                    pushSelected(firstForTerm);
-                }
-            }
-        }
-        else if (mode === 'search' && terms.length > 0) {
-            const discriminativeHighSignalTerms = querySignals.highSignalTerms.filter((term) => {
-                const docFreq = termFileHits.get(term) || 0;
-                return docFreq / matchedFileTotal <= 0.65;
-            });
-            const preferredTerms = discriminativeHighSignalTerms.length > 0
-                ? discriminativeHighSignalTerms.slice(0, 8)
-                : querySignals.highSignalTerms.length > 0
-                    ? querySignals.highSignalTerms.slice(0, 8)
-                    : terms
-                        .filter((term) => !LOW_SIGNAL_TERMS.has(term) && term.length >= 4)
-                        .slice(0, 8);
-            for (const term of preferredTerms) {
-                const firstForTerm = sourceEvidence.find((citation) => {
-                    if (citation.term !== term)
-                        return false;
-                    const normalized = (citation.term || '').toLowerCase();
-                    return !GENERIC_OUTPUT_TERMS.has(normalized);
-                });
-                if (!firstForTerm)
-                    continue;
-                pushSelected(firstForTerm);
-                if (selectedForOutput.length >= maxCitations)
-                    break;
-            }
-        }
-        for (const citation of sourceEvidence) {
-            if (selectedForOutput.length >= maxCitations)
-                break;
-            if (commandFocusQuery &&
-                (querySignals.asksLocation || querySignals.asksHow) &&
-                selectedForOutput.some((item) => item.path.includes(`/commands/${commandFocusQuery}.`)) &&
-                citation.path.includes('/commands/') &&
-                !citation.path.includes(`/commands/${commandFocusQuery}.`)) {
-                continue;
-            }
-            pushSelected(citation);
-        }
-        const finalCitations = selectedForOutput.map(({ path, line, snippet, term }) => ({
-            path,
-            line,
-            snippet,
-            term,
-        }));
+        const evidence = collectRepoEvidence(cwd, fileTree, searchTerms, pathBoostScores);
+        const sourceEvidence = evidence.scoredCitations.filter((citation) => isPrimarySourcePath(citation.path));
+        const finalCitations = selectTopCitations(sourceEvidence, maxCitations, searchTerms);
         const stats = {
-            scannedFiles,
-            matchedFiles: sourcePerFileCounts.size,
+            scannedFiles: evidence.scannedFiles,
+            matchedFiles: new Set(sourceEvidence.map((citation) => citation.path)).size,
             matchedLines: sourceEvidence.length,
             brainCandidates: brainResults.entries.length,
         };
-        const lineCacheForAnswer = new Map();
-        for (const [filePath, data] of rawFileMatches.entries()) {
-            lineCacheForAnswer.set(filePath, data.lines);
-        }
-        const truth = evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceEvidence, sourcePerFileCounts, sourceTermCounts);
-        const answer = buildAnswer(mode, question, terms, finalCitations, stats, sourceTermCounts, sourcePerFileCounts, truth, {
-            cliPackageName,
-            knownCommands: knownCliCommands,
-            featureBullets,
-            lineCache: lineCacheForAnswer,
-        });
-        emitAskResult(answer, {
+        const truth = evaluateTruth(searchTerms.normalizedQuestion, searchTerms.highSignalTerms, finalCitations);
+        const payload = buildRepoAnswerPayload(question, searchTerms, finalCitations, stats, truth);
+        emitAskResult(payload, {
             json: options.json,
             maxCitations,
             fromPlan: options.fromPlan,
@@ -2290,12 +2356,12 @@ async function askCommand(question, options = {}) {
         if (orgId && projectId) {
             (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
                 type: 'ask',
-                note: `mode=${mode};truth=${truth.status};score=${truth.score.toFixed(2)};matched_files=${stats.matchedFiles};matched_lines=${stats.matchedLines}`,
+                note: `mode=retrieval;truth=${truth.status};score=${truth.score.toFixed(2)};matched_files=${stats.matchedFiles};matched_lines=${stats.matchedLines}`,
             });
         }
         if (shouldUseCache && orgId && projectId) {
             const questionHash = (0, ask_cache_1.computeAskQuestionHash)({
-                question: normalizedQuestion,
+                question: searchTerms.normalizedQuestion,
                 contextHash: staticContext.hash,
             });
             const key = (0, ask_cache_1.computeAskCacheKey)({
@@ -2317,10 +2383,10 @@ async function askCommand(question, options = {}) {
                     questionHash,
                     policyVersionHash,
                     neurcodeVersion,
-                    question: normalizedQuestion,
+                    question: searchTerms.normalizedQuestion,
                     contextHash: staticContext.hash,
                 },
-                output: answer,
+                output: payload,
                 evidencePaths: finalCitations.map((citation) => citation.path),
             });
         }