@neurcode-ai/cli 0.9.23 → 0.9.24

package/dist/commands/ask.js

@@ -25,7 +25,12 @@ catch {
         white: (str) => str,
     };
 }
-const MAX_SCAN_FILES = 320;
+const MAX_SCAN_FILES = (() => {
+    const raw = Number(process.env.NEURCODE_ASK_MAX_SCAN_FILES || '900');
+    if (!Number.isFinite(raw))
+        return 900;
+    return Math.max(120, Math.min(Math.trunc(raw), 2000));
+})();
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_RAW_CITATIONS = 120;
 const PRIMARY_SOURCE_EXTENSIONS = new Set([
@@ -45,9 +50,29 @@ const STOP_WORDS = new Set([
 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', 'file', 'files', 'path', 'filepath', 'header', 'added', 'add', 'request', 'requests',
+    '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',
 ]);
 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 scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
     const files = [];
     const ignoreDirs = new Set([
@@ -111,12 +136,19 @@ function escapeRegExp(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function normalizeTerm(raw) {
-    return 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();
@@ -163,6 +195,25 @@ function extractComparisonTerms(question) {
         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)
@@ -179,6 +230,10 @@ function buildTermMatchers(term, 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_-]*');
@@ -213,6 +268,20 @@ function expandSearchTerms(terms) {
         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'));
+        }
     }
     return [...expanded];
 }
@@ -231,9 +300,10 @@ function buildMatchers(question) {
     }
     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, ...identityTerms, ...keywords].map(normalizeTerm).filter(Boolean))];
+    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));
@@ -284,6 +354,149 @@ function derivePathHints(question) {
     }
     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);
+    }
+    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,
+    };
+}
+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;
+        }
+    }
+    return hits;
+}
+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 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 tryBuildDeterministicAnswer(_cwd, question, normalizedQuestion) {
+    const scope = assessQuestionScope(normalizedQuestion);
+    if (scope.isOutOfScope) {
+        return {
+            payload: buildOutOfScopeAnswerPayload(question, normalizedQuestion, scope.reasons),
+            reason: 'out_of_scope',
+        };
+    }
+    return null;
+}
 function normalizeSnippet(line) {
     return line
         .replace(/\t/g, ' ')
@@ -444,6 +657,34 @@ function extractNeurcodeCommandsFromCitations(citations) {
     }
     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) {
@@ -466,6 +707,162 @@ function formatInsightSnippet(snippet) {
         .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;
+        }
+        const pattern = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`, 'i');
+        if (pattern.test(text)) {
+            hits += 1;
+            continue;
+        }
+        if (isCompactText) {
+            const compactTerm = normalized.replace(/[^a-z0-9]/g, '');
+            if (compactTerm.length >= 3 && compactText.includes(compactTerm)) {
+                hits += 1;
+            }
+        }
+    }
+    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 (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;
+        }
+        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);
+            }
+        }
+        for (const ch of line) {
+            if (ch === '{')
+                depth += 1;
+            if (ch === '}')
+                depth -= 1;
+        }
+        if (depth <= 0)
+            break;
+    }
+    if (fields.length === 0)
+        return null;
+    return { interfaceName, fields };
+}
+function splitIdentifierTokens(value) {
+    if (!value)
+        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;
+        }
+        seen.add(interfaceKey);
+        scored.push({
+            score: relevanceScore,
+            summary: `${parsed.interfaceName}: ${parsed.fields.slice(0, 12).join(', ')}`,
+        });
+    }
+    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();
@@ -498,8 +895,8 @@ function isCommandCatalogIntent(normalizedQuestion) {
         /\bshow\b/.test(normalizedQuestion) ||
         /\bavailable\b/.test(normalizedQuestion) ||
         /\ball commands?\b/.test(normalizedQuestion) ||
-        /\bwhich commands?\b/.test(normalizedQuestion) ||
-        /\bwhat 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);
@@ -644,17 +1041,110 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
     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)\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 = [
-        ...extractNeurcodeCommandsFromCitations(citations),
-        ...(context.knownCommands || []),
+        ...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) {
@@ -699,8 +1189,66 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
         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 (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.';
+            }
+        }
+    }
+    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 normalizedCommands = commandMatches
+        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}\``);
@@ -712,6 +1260,7 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
             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();
@@ -730,13 +1279,67 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
             };
             locationPool.sort((a, b) => score(b) - score(a));
         }
-        const locations = locationPool
+        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))
+            : [];
+        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 bullets = insightLines.map((line) => `  • ${line}`);
+        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))
+            : [];
+        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)) {
@@ -870,6 +1473,25 @@ async function askCommand(question, options = {}) {
         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}...`));
+            }
+            emitAskResult(deterministic.payload, {
+                json: options.json,
+                maxCitations,
+                fromPlan: options.fromPlan,
+                verbose: options.verbose,
+            });
+            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)}`,
+                });
+            }
+            return;
+        }
         if (process.stdout.isTTY && !process.env.CI) {
             (0, neurcode_context_1.ensureDefaultLocalContextFile)(cwd);
         }
@@ -979,6 +1601,7 @@ async function askCommand(question, options = {}) {
         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);
@@ -991,6 +1614,8 @@ async function askCommand(question, options = {}) {
         }
         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();
@@ -1005,7 +1630,12 @@ async function askCommand(question, options = {}) {
                 if (normalizedPath.startsWith('scripts/')) {
                     score -= 0.1;
                 }
-                if (!mentionsAskCommand && (filePath.endsWith('/commands/ask.ts') || filePath.endsWith('/utils/ask-cache.ts'))) {
+                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))) {
@@ -1040,11 +1670,15 @@ async function askCommand(question, options = {}) {
             ? prioritized.filter((filePath) => !pathHints.some((hint) => filePath.startsWith(hint)))
             : prioritized;
         const candidates = [...hinted, ...nonHinted].slice(0, MAX_SCAN_FILES);
-        const citations = [];
+        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) {
-            if (citations.length >= MAX_RAW_CITATIONS)
-                break;
             const fullPath = (0, path_1.join)(cwd, filePath);
             let content = '';
             try {
@@ -1058,34 +1692,165 @@ async function askCommand(question, options = {}) {
             }
             scannedFiles++;
             const lines = content.split(/\r?\n/);
+            const lineTerms = new Map();
+            const matchedTerms = new Set();
             for (let idx = 0; idx < lines.length; idx++) {
-                if (citations.length >= MAX_RAW_CITATIONS)
-                    break;
-                const line = lines[idx];
-                if (!line || line.trim().length === 0)
+                const rawLine = lines[idx];
+                if (!rawLine || rawLine.trim().length === 0)
                     continue;
                 for (const matcher of matchers) {
-                    if (!matcher.regex.test(line))
-                        continue;
-                    const snippet = normalizeSnippet(line);
-                    if (!snippet)
+                    if (!matcher.regex.test(rawLine))
                         continue;
-                    const evidence = {
-                        path: filePath,
-                        line: idx + 1,
-                        snippet,
-                        term: matcher.label,
-                        weight: matcher.weight +
-                            (pathPriority.get(filePath) || 0) +
-                            (pathHints.some((hint) => filePath.startsWith(hint)) ? 0.25 : 0),
-                    };
-                    const dedupeKey = `${evidence.path}:${evidence.line}:${evidence.term || ''}`;
-                    if (citations.some((item) => `${item.path}:${item.line}:${item.term || ''}` === dedupeKey)) {
+                    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;
                     }
-                    citations.push(evidence);
-                    break;
                 }
+                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);
@@ -1099,20 +1864,75 @@ async function askCommand(question, options = {}) {
             }
         }
         const selectedForOutput = [];
-        const wantsOrgRequestInjection = /\b(inject|injected|header|request|requests)\b/.test(normalizedQuestion) &&
-            /\b(org|organization)\b/.test(normalizedQuestion);
+        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);
+            }
+        }
         if (mode === 'comparison' && terms.length >= 2) {
             for (const term of terms.slice(0, 2)) {
                 const firstForTerm = sourceEvidence.find((citation) => citation.term === term);
                 if (firstForTerm) {
-                    selectedForOutput.push(firstForTerm);
+                    pushSelected(firstForTerm);
                 }
             }
         }
         else if (mode === 'search' && terms.length > 0) {
-            const preferredTerms = terms
-                .filter((term) => !LOW_SIGNAL_TERMS.has(term) && term.length >= 4)
-                .slice(0, 8);
+            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)
@@ -1122,32 +1942,22 @@ async function askCommand(question, options = {}) {
                 });
                 if (!firstForTerm)
                     continue;
-                if (selectedForOutput.some((existing) => existing.path === firstForTerm.path && existing.line === firstForTerm.line && existing.term === firstForTerm.term)) {
-                    continue;
-                }
-                selectedForOutput.push(firstForTerm);
+                pushSelected(firstForTerm);
                 if (selectedForOutput.length >= maxCitations)
                     break;
             }
         }
-        if (wantsOrgRequestInjection && selectedForOutput.length < maxCitations) {
-            const targeted = sourceEvidence.filter((citation) => /x-org-id|org[_ -]?id|headers?\[|auto-?inject|request/i.test(citation.snippet));
-            for (const citation of targeted) {
-                if (selectedForOutput.length >= maxCitations)
-                    break;
-                if (selectedForOutput.some((existing) => existing.path === citation.path && existing.line === citation.line && existing.term === citation.term)) {
-                    continue;
-                }
-                selectedForOutput.push(citation);
-            }
-        }
         for (const citation of sourceEvidence) {
             if (selectedForOutput.length >= maxCitations)
                 break;
-            if (selectedForOutput.some((existing) => existing.path === citation.path && existing.line === citation.line && existing.term === citation.term)) {
+            if (commandFocusQuery &&
+                (querySignals.asksLocation || querySignals.asksHow) &&
+                selectedForOutput.some((item) => item.path.includes(`/commands/${commandFocusQuery}.`)) &&
+                citation.path.includes('/commands/') &&
+                !citation.path.includes(`/commands/${commandFocusQuery}.`)) {
                 continue;
             }
-            selectedForOutput.push(citation);
+            pushSelected(citation);
         }
         const finalCitations = selectedForOutput.map(({ path, line, snippet, term }) => ({
             path,
@@ -1161,11 +1971,16 @@ async function askCommand(question, options = {}) {
             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, {
             json: options.json,