@neurcode-ai/cli 0.9.21 → 0.9.23

package/dist/commands/ask.js

@@ -39,14 +39,21 @@ const STOP_WORDS = new Set([
     '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',
 ]);
 const LOW_SIGNAL_TERMS = new Set([
     'used', 'use', 'using', 'mentioned', 'mention', 'where', 'tell', 'read', 'check', 'find', 'search',
-    'workflow', 'repo', 'repository', 'codebase', 'anywhere',
+    'workflow', 'repo', 'repository', 'codebase', 'anywhere', 'can', 'type', 'types', 'list', 'show', 'like',
+    'neurcode', 'cli', 'file', 'files', 'path', 'filepath', 'header', 'added', 'add', 'request', 'requests',
 ]);
+const GENERIC_OUTPUT_TERMS = new Set(['file', 'files', 'path', 'filepath']);
 function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
     const files = [];
-    const ignoreDirs = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo', '.cache', 'coverage']);
+    const ignoreDirs = new Set([
+        'node_modules', '.git', '.next', 'dist', 'build', '.turbo', '.cache', 'coverage',
+        '.neurcode', '.vscode', '.pnpm-store', '.npm', '.yarn',
+    ]);
     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)
@@ -95,7 +102,9 @@ function scanFiles(dir, maxFiles = MAX_SCAN_FILES) {
 }
 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) {
@@ -105,6 +114,7 @@ function normalizeTerm(raw) {
     return raw
         .toLowerCase()
         .replace(/['"`]/g, '')
+        .replace(/[^a-z0-9_\-\s]/g, ' ')
         .replace(/\s+/g, ' ')
         .trim();
 }
@@ -178,6 +188,34 @@ function buildTermMatchers(term, weight) {
     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)
+            continue;
+        expanded.add(term);
+        if (term.includes(' ')) {
+            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));
+        }
+    }
+    return [...expanded];
+}
 function buildMatchers(question) {
     const comparisonTerms = extractComparisonTerms(question);
     if (comparisonTerms.length >= 2) {
@@ -192,10 +230,12 @@ function buildMatchers(question) {
         };
     }
     const quoted = extractQuotedTerms(question);
+    const identityTerms = extractIdentityTerms(question);
     const keywords = tokenizeQuestion(question).slice(0, 8);
     const quotedSet = new Set(quoted.map((term) => normalizeTerm(term)));
-    const terms = [...new Set([...quoted, ...keywords].map(normalizeTerm).filter(Boolean))]
-        .filter((term) => quotedSet.has(term) || !LOW_SIGNAL_TERMS.has(term));
+    const baseTerms = [...new Set([...quoted, ...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',
@@ -216,8 +256,29 @@ function derivePathHints(question) {
     }
     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/');
     }
@@ -230,533 +291,240 @@ function normalizeSnippet(line) {
         .trim()
         .slice(0, 220);
 }
-function lineNumberFromOffset(content, offset) {
-    if (offset <= 0)
-        return 1;
-    return content.slice(0, offset).split(/\r?\n/).length;
-}
-function stripMarkdown(value) {
-    return value
-        .replace(/[*_`~]/g, '')
-        .replace(/\[(.*?)\]\(.*?\)/g, '$1')
-        .replace(/\s+/g, ' ')
-        .trim();
-}
-function isCliCommandListQuestion(normalizedQuestion) {
-    const mentionsCli = /\bcli\b|\bneurcode\b|\bcommand\b|\bcmds?\b/.test(normalizedQuestion);
-    if (!mentionsCli)
-        return false;
-    return (/\blist\b/.test(normalizedQuestion) ||
-        /\bshow\b/.test(normalizedQuestion) ||
-        /\bavailable\b/.test(normalizedQuestion) ||
-        /\bwhat can i\b/.test(normalizedQuestion) ||
-        /\bwhich\b/.test(normalizedQuestion) ||
-        /\blike\b/.test(normalizedQuestion));
-}
-function isInstallCliQuestion(normalizedQuestion) {
-    const mentionsInstall = /\binstall\b|\bupgrade\b|\blatest\b|\bupdate\b/.test(normalizedQuestion);
-    const mentionsCli = /\bcli\b|\bneurcode\b/.test(normalizedQuestion);
-    const asksForCommand = /\bcmd\b|\bcommand\b|\bhow\b|\bwhat\b/.test(normalizedQuestion);
-    return mentionsInstall && mentionsCli && asksForCommand;
-}
-function isTenancyQuestion(normalizedQuestion) {
-    if (/\bmulti[- ]?tenant\b|\bsingle[- ]?tenant\b|\btenancy\b/.test(normalizedQuestion))
-        return true;
-    return /\borganization\b/.test(normalizedQuestion) && /\bsingle\b|\bmulti\b/.test(normalizedQuestion);
-}
-function isFeatureOverviewQuestion(normalizedQuestion) {
-    return (/\bfeature\b|\bfeatures\b|\bcapability\b|\bcapabilities\b/.test(normalizedQuestion) ||
-        /\bwhat all\b|\bwhat does\b|\bwhat can\b|\boffers?\b|\bplatform have\b/.test(normalizedQuestion));
+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',
+    ];
+    for (const path of pinned) {
+        if (!asSet.has(path))
+            continue;
+        candidateSet.add(path);
+        pathPriority.set(path, Math.max(pathPriority.get(path) || 0, 0.22));
+    }
+    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++;
+        }
+    }
 }
-function extractCliCommandCatalog(cwd) {
-    const indexPath = 'packages/cli/src/index.ts';
-    const fullPath = (0, path_1.join)(cwd, indexPath);
-    if (!(0, fs_1.existsSync)(fullPath))
+function readCliPackageName(cwd) {
+    const pkgPath = (0, path_1.join)(cwd, 'packages/cli/package.json');
+    if (!(0, fs_1.existsSync)(pkgPath))
         return null;
-    let content = '';
     try {
-        content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+        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 {
         return null;
     }
-    if (!content.trim())
-        return null;
-    const lines = content.split(/\r?\n/);
-    const topLevel = [];
-    const subcommands = [];
-    const citations = [];
+}
+function extractCommandsFromCliIndex(cwd) {
+    const indexPath = (0, path_1.join)(cwd, 'packages/cli/src/index.ts');
+    if (!(0, fs_1.existsSync)(indexPath))
+        return [];
+    let content = '';
+    try {
+        content = (0, fs_1.readFileSync)(indexPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const commandSet = new Set();
     const topByVar = new Map();
-    const seenTop = new Set();
-    const seenSub = new Set();
-    const topRegex = /(?:const\s+([A-Za-z_$][\w$]*)\s*=\s*)?program\s*\r?\n\s*\.command\('([^']+)'\)/g;
-    for (const match of content.matchAll(topRegex)) {
+    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 rawCommand = (match[2] || '').trim();
-        if (!rawCommand)
-            continue;
-        const commandName = rawCommand.split(/\s+/)[0];
-        if (!commandName)
+        const top = (match[2] || '').trim().split(/\s+/)[0];
+        if (!top)
             continue;
+        commandSet.add(`neurcode ${top}`);
         if (varName) {
-            topByVar.set(varName, commandName);
-        }
-        if (!seenTop.has(commandName)) {
-            seenTop.add(commandName);
-            topLevel.push(commandName);
-            const baseOffset = match.index ?? 0;
-            const commandInMatchOffset = match[0].indexOf(".command('");
-            const offset = commandInMatchOffset >= 0 ? baseOffset + commandInMatchOffset : baseOffset;
-            const line = lineNumberFromOffset(content, offset);
-            citations.push({
-                path: indexPath,
-                line,
-                snippet: normalizeSnippet(lines[line - 1] || `.command('${rawCommand}')`),
-                term: 'command',
-            });
+            topByVar.set(varName, top);
         }
     }
-    const subRegex = /([A-Za-z_$][\w$]*)\s*\r?\n\s*\.command\('([^']+)'\)/g;
-    for (const match of content.matchAll(subRegex)) {
+    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)
             continue;
-        const rawSubcommand = (match[2] || '').trim();
-        if (!rawSubcommand)
-            continue;
-        const subcommandName = rawSubcommand.split(/\s+/)[0];
-        if (!subcommandName)
+        const sub = (match[2] || '').trim().split(/\s+/)[0];
+        if (!sub)
             continue;
-        const combined = `${parent} ${subcommandName}`;
-        if (seenSub.has(combined))
-            continue;
-        seenSub.add(combined);
-        subcommands.push(combined);
-        const baseOffset = match.index ?? 0;
-        const commandInMatchOffset = match[0].indexOf(".command('");
-        const offset = commandInMatchOffset >= 0 ? baseOffset + commandInMatchOffset : baseOffset;
-        const line = lineNumberFromOffset(content, offset);
-        citations.push({
-            path: indexPath,
-            line,
-            snippet: normalizeSnippet(lines[line - 1] || `${parentVar}.command('${rawSubcommand}')`),
-            term: 'subcommand',
-        });
-    }
-    if (topLevel.length === 0)
-        return null;
-    return {
-        topLevelCommands: topLevel,
-        subcommands,
-        citations,
-    };
-}
-function extractInstallCommandInfo(cwd) {
-    const pkgPath = 'packages/cli/package.json';
-    const fullPath = (0, path_1.join)(cwd, pkgPath);
-    if (!(0, fs_1.existsSync)(fullPath))
-        return null;
-    let raw = '';
-    try {
-        raw = (0, fs_1.readFileSync)(fullPath, 'utf-8');
-    }
-    catch {
-        return null;
-    }
-    let packageName = '';
-    try {
-        const parsed = JSON.parse(raw);
-        packageName = typeof parsed.name === 'string' ? parsed.name.trim() : '';
-    }
-    catch {
-        return null;
-    }
-    if (!packageName)
-        return null;
-    const lines = raw.split(/\r?\n/);
-    const nameLine = lines.findIndex((line) => /"name"\s*:/.test(line));
-    const versionLine = lines.findIndex((line) => /"version"\s*:/.test(line));
-    const citations = [];
-    if (nameLine >= 0) {
-        citations.push({
-            path: pkgPath,
-            line: nameLine + 1,
-            snippet: normalizeSnippet(lines[nameLine]),
-            term: 'package name',
-        });
+        commandSet.add(`neurcode ${parent} ${sub}`);
     }
-    if (versionLine >= 0) {
-        citations.push({
-            path: pkgPath,
-            line: versionLine + 1,
-            snippet: normalizeSnippet(lines[versionLine]),
-            term: 'version',
-        });
-    }
-    return {
-        packageName,
-        citations,
-    };
+    return [...commandSet].slice(0, 40);
 }
-function buildInstallCommandAnswer(question, normalizedQuestion, installInfo, brainCandidates) {
-    const pkg = installInfo.packageName;
-    return {
-        question,
-        questionNormalized: normalizedQuestion,
-        mode: 'search',
-        answer: [
-            'Use this command to install the latest Neurcode CLI globally:',
-            `\`npm install -g ${pkg}@latest\``,
-            '',
-            `Optional (pnpm): \`pnpm add -g ${pkg}@latest\``,
-            'Then verify with: `neurcode --version`',
-        ].join('\n'),
-        findings: [
-            `CLI package detected: ${pkg}`,
-            'Source of truth: packages/cli/package.json',
-        ],
-        confidence: 'high',
-        truth: {
-            status: 'grounded',
-            score: 0.99,
-            reasons: [],
-            sourceCitations: installInfo.citations.length,
-            sourceFiles: 1,
-            minCitationsRequired: 1,
-            minFilesRequired: 1,
-        },
-        citations: installInfo.citations,
-        generatedAt: new Date().toISOString(),
-        stats: {
-            scannedFiles: 1,
-            matchedFiles: 1,
-            matchedLines: installInfo.citations.length,
-            brainCandidates,
-        },
-    };
-}
-function buildTenancyAnswer(cwd, question, normalizedQuestion, brainCandidates) {
-    const candidatePaths = [
-        'README.md',
-        'packages/cli/src/api-client.ts',
-        'packages/cli/src/utils/state.ts',
-        'services/api/src/lib/org-context.ts',
-        'services/api/src/routes/logs.ts',
-        'services/api/src/routes/metrics.ts',
-        'services/api/src/db/index.ts',
-        'services/api/src/services/architect-service.ts',
-        'services/api/src/lib/user-org.ts',
-    ];
-    const multiPatterns = [
-        { regex: /\bmulti[- ]tenant\b/i, weight: 3, term: 'multi-tenant' },
-        { regex: /\bx-org-id\b/i, weight: 2, term: 'x-org-id' },
-        { regex: /\borganization[_ -]?id\b/i, weight: 1, term: 'organization_id' },
-        { regex: /\bscoped by organization/i, weight: 3, term: 'org-scoped' },
-        { regex: /\bisolated workspaces?\b/i, weight: 2, term: 'isolated workspaces' },
-    ];
-    const singlePatterns = [
-        { regex: /\bsingle[- ]tenant\b/i, weight: 3, term: 'single-tenant' },
-        { regex: /\bsingle-user platform\b/i, weight: 2, term: 'single-user platform' },
-        { regex: /\bno organization management\b/i, weight: 2, term: 'no organization management' },
-    ];
-    const weighted = [];
-    let scannedFiles = 0;
-    let multiScore = 0;
-    let singleScore = 0;
-    for (const relPath of candidatePaths) {
-        const fullPath = (0, path_1.join)(cwd, relPath);
-        if (!(0, fs_1.existsSync)(fullPath))
-            continue;
-        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/);
-        for (let idx = 0; idx < lines.length; idx++) {
-            const line = lines[idx];
-            if (!line || line.trim().length === 0)
-                continue;
-            for (const pattern of multiPatterns) {
-                if (!pattern.regex.test(line))
-                    continue;
-                multiScore += pattern.weight;
-                weighted.push({
-                    path: relPath,
-                    line: idx + 1,
-                    snippet: normalizeSnippet(line),
-                    term: pattern.term,
-                    weight: pattern.weight,
-                    side: 'multi',
-                });
-            }
-            for (const pattern of singlePatterns) {
-                if (!pattern.regex.test(line))
-                    continue;
-                singleScore += pattern.weight;
-                weighted.push({
-                    path: relPath,
-                    line: idx + 1,
-                    snippet: normalizeSnippet(line),
-                    term: pattern.term,
-                    weight: pattern.weight,
-                    side: 'single',
-                });
-            }
-        }
-    }
-    if (weighted.length === 0)
-        return null;
-    const deduped = new Map();
-    for (const citation of weighted) {
-        const key = `${citation.path}:${citation.line}:${citation.term || ''}`;
-        const existing = deduped.get(key);
-        if (!existing || citation.weight > existing.weight) {
-            deduped.set(key, citation);
-        }
-    }
-    const citations = [...deduped.values()].sort((a, b) => b.weight - a.weight);
-    const matchedFiles = new Set(citations.map((citation) => citation.path)).size;
-    const totalSignals = multiScore + singleScore;
-    const delta = Math.abs(multiScore - singleScore);
-    let classification;
-    if (multiScore >= singleScore + 3)
-        classification = 'multi';
-    else if (singleScore >= multiScore + 3)
-        classification = 'single';
-    else
-        classification = 'mixed';
-    const reasons = [];
-    if (classification === 'mixed') {
-        reasons.push('Mixed indicators found: both multi-tenant and single-tenant signals are present.');
-    }
-    if (matchedFiles < 2) {
-        reasons.push('Evidence is concentrated in too few files for a strong architecture verdict.');
-    }
-    const scoreBase = totalSignals > 0 ? delta / totalSignals : 0;
-    const score = Math.max(0.45, Math.min(0.98, scoreBase * 0.6 + Math.min(citations.length, 12) / 20 + (matchedFiles >= 2 ? 0.15 : 0.05)));
-    const truthStatus = reasons.length > 0 && classification === 'mixed' ? 'insufficient' : 'grounded';
-    const truth = {
-        status: truthStatus,
-        score,
-        reasons,
-        sourceCitations: citations.length,
-        sourceFiles: matchedFiles,
-        minCitationsRequired: 2,
-        minFilesRequired: 1,
-    };
-    let answer;
-    if (classification === 'multi') {
-        answer = 'This codebase is multi-tenant. Core API/CLI flows are organization-scoped (org IDs and `x-org-id` context are enforced).';
-    }
-    else if (classification === 'single') {
-        answer = 'This codebase appears single-tenant based on current source signals.';
-    }
-    else if (multiScore >= singleScore) {
-        answer = 'The repo has mixed signals, but it currently leans multi-tenant. Most runtime paths are organization-scoped, with some legacy single-user wording.';
-    }
-    else {
-        answer = 'The repo has mixed tenancy signals and currently leans single-tenant in wording, though some organization-scoped logic exists.';
-    }
-    return {
-        question,
-        questionNormalized: normalizedQuestion,
-        mode: 'comparison',
-        answer,
-        findings: [
-            `Tenancy signals: multi=${multiScore}, single=${singleScore}`,
-            `Evidence files: ${matchedFiles}`,
-            'Key sources include API org-context/auth routes and CLI org-scoping headers.',
-        ],
-        confidence: calibrateConfidence(truth),
-        truth: {
-            status: truth.status,
-            score: Number(truth.score.toFixed(2)),
-            reasons: truth.reasons,
-            sourceCitations: truth.sourceCitations,
-            sourceFiles: truth.sourceFiles,
-            minCitationsRequired: truth.minCitationsRequired,
-            minFilesRequired: truth.minFilesRequired,
-        },
-        citations: citations.slice(0, 24).map(({ path, line, snippet, term }) => ({ path, line, snippet, term })),
-        generatedAt: new Date().toISOString(),
-        stats: {
-            scannedFiles,
-            matchedFiles,
-            matchedLines: citations.length,
-            brainCandidates,
-        },
-    };
-}
-function extractFeatureEntriesFromReadme(cwd) {
-    const readmePath = 'README.md';
-    const fullPath = (0, path_1.join)(cwd, readmePath);
-    if (!(0, fs_1.existsSync)(fullPath))
+function extractFeatureBulletsFromReadme(cwd, limit) {
+    const readmePath = (0, path_1.join)(cwd, 'README.md');
+    if (!(0, fs_1.existsSync)(readmePath))
         return [];
     let content = '';
     try {
-        content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+        content = (0, fs_1.readFileSync)(readmePath, 'utf-8');
     }
     catch {
         return [];
     }
     const lines = content.split(/\r?\n/);
     let start = lines.findIndex((line) => /^##\s+.*features/i.test(line));
-    if (start < 0) {
-        start = lines.findIndex((line) => /^###\s+the solution/i.test(line));
-    }
+    if (start < 0)
+        start = lines.findIndex((line) => /^###\s+.*features/i.test(line));
     if (start < 0)
         return [];
-    let end = lines.length;
+    const out = [];
+    const seen = new Set();
     for (let i = start + 1; i < lines.length; i++) {
-        if (/^##\s+/.test(lines[i])) {
-            end = 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])
+                continue;
+            const text = formatInsightSnippet(simple[1]);
+            const key = text.toLowerCase();
+            if (text && !seen.has(key)) {
+                seen.add(key);
+                out.push(text);
+            }
+        }
+        if (out.length >= limit)
+            break;
     }
-    const entries = [];
-    let currentCategory = 'Core Features';
-    for (let i = start + 1; i < end; i++) {
-        const line = lines[i];
-        if (!line)
-            continue;
-        const headingMatch = line.match(/^###\s+(.+)$/);
-        if (headingMatch?.[1]) {
-            currentCategory = stripMarkdown(headingMatch[1]);
-            continue;
+    return out;
+}
+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}`);
         }
-        const richBullet = line.match(/^- \*\*(.+?)\*\*\s*-\s*(.+)$/);
-        if (richBullet?.[1]) {
-            entries.push({
-                category: currentCategory,
-                title: stripMarkdown(richBullet[1]),
-                description: stripMarkdown(richBullet[2]),
-                line: i + 1,
-                snippet: normalizeSnippet(line),
-            });
-            continue;
+        for (const match of snippet.matchAll(/`neurcode\s+([^`]+)`/g)) {
+            const command = (match[1] || '').trim();
+            if (!command)
+                continue;
+            commandSet.add(`neurcode ${command}`);
         }
-        const simpleBullet = line.match(/^- (.+)$/);
-        if (simpleBullet?.[1]) {
-            const text = stripMarkdown(simpleBullet[1]);
-            if (!text)
+        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;
-            entries.push({
-                category: currentCategory,
-                title: text,
-                line: i + 1,
-                snippet: normalizeSnippet(line),
-            });
+            commandSet.add(`neurcode ${plainMatch[1].trim()}`);
         }
     }
-    return entries;
+    return [...commandSet].slice(0, 20);
 }
-function buildFeatureOverviewAnswer(question, normalizedQuestion, entries, brainCandidates) {
-    const grouped = new Map();
-    for (const entry of entries) {
-        const bucket = grouped.get(entry.category) || [];
-        const item = entry.description ? `${entry.title} - ${entry.description}` : entry.title;
-        if (!bucket.includes(item))
-            bucket.push(item);
-        grouped.set(entry.category, bucket);
-    }
-    const categoryLines = [];
-    for (const [category, items] of grouped.entries()) {
-        categoryLines.push(`• ${category}: ${items.slice(0, 3).join('; ')}`);
-        if (categoryLines.length >= 6)
+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());
+        }
+    }
+    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 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 citations = entries.slice(0, 24).map((entry) => ({
-        path: 'README.md',
-        line: entry.line,
-        snippet: entry.snippet,
-        term: 'feature',
-    }));
-    return {
-        question,
-        questionNormalized: normalizedQuestion,
-        mode: 'search',
-        answer: [
-            'Neurcode platform features in this repo include:',
-            ...categoryLines,
-            '',
-            'If you want, I can also list this as “feature + exact CLI command” pairs.',
-        ].join('\n'),
-        findings: [
-            `Feature entries found: ${entries.length}`,
-            `Feature categories found: ${grouped.size}`,
-            'Source of truth: README.md',
-        ],
-        confidence: 'high',
-        truth: {
-            status: 'grounded',
-            score: 0.93,
-            reasons: [],
-            sourceCitations: citations.length,
-            sourceFiles: 1,
-            minCitationsRequired: 2,
-            minFilesRequired: 1,
-        },
-        citations,
-        generatedAt: new Date().toISOString(),
-        stats: {
-            scannedFiles: 1,
-            matchedFiles: 1,
-            matchedLines: citations.length,
-            brainCandidates,
-        },
-    };
+    return out;
 }
-function buildCliCommandAnswer(question, normalizedQuestion, catalog, brainCandidates) {
-    const commandBullets = catalog.topLevelCommands.map((command) => `  • \`neurcode ${command}\``);
-    const nestedBullets = catalog.subcommands.slice(0, 8).map((command) => `  • \`neurcode ${command}\``);
-    const parts = ['Yes. These are the main CLI commands available in this repo:', ...commandBullets];
-    if (nestedBullets.length > 0) {
-        parts.push('\nCommon subcommands:', ...nestedBullets);
-    }
-    parts.push('\nTip: run `neurcode <command> --help` for options and examples.');
-    return {
-        question,
-        questionNormalized: normalizedQuestion,
-        mode: 'search',
-        answer: parts.join('\n'),
-        findings: [
-            `Top-level commands found: ${catalog.topLevelCommands.length}`,
-            catalog.subcommands.length > 0 ? `Nested subcommands found: ${catalog.subcommands.length}` : 'Nested subcommands found: 0',
-            'Source of truth: packages/cli/src/index.ts',
-        ],
-        confidence: 'high',
-        truth: {
-            status: 'grounded',
-            score: 0.99,
-            reasons: [],
-            sourceCitations: catalog.citations.length,
-            sourceFiles: 1,
-            minCitationsRequired: 1,
-            minFilesRequired: 1,
-        },
-        citations: catalog.citations,
-        generatedAt: new Date().toISOString(),
-        stats: {
-            scannedFiles: 1,
-            matchedFiles: 1,
-            matchedLines: catalog.citations.length,
-            brainCandidates,
-        },
-    };
+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/') ||
@@ -796,12 +564,13 @@ function evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceCitation
     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 = Math.max(minFilesRequired, 2);
+        minFilesRequired = hasStrongSingleFileEvidence ? minFilesRequired : Math.max(minFilesRequired, 2);
     }
     const reasons = [];
-    const sourceCitationCount = sourceCitations.length;
-    const sourceFileCount = sourcePerFileCounts.size;
     if (sourceCitationCount === 0) {
         reasons.push('No direct source-file evidence was found for the query terms.');
     }
@@ -831,7 +600,7 @@ function evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceCitation
         const highest = Math.max(...sourcePerFileCounts.values());
         dominantShare = highest / sourceCitationCount;
     }
-    if (broadQuestion && dominantShare > 0.85 && sourceFileCount < 3) {
+    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));
@@ -867,17 +636,28 @@ function evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceCitation
         minFilesRequired,
     };
 }
-function buildAnswer(mode, question, terms, citations, stats, termCounts, perFileCounts, truth) {
+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 = '';
-    if (truth.status === 'insufficient') {
-        answer = 'Insufficient grounded evidence to answer confidently from current source coverage.';
-        findings.push(...truth.reasons);
-        findings.push('Refine the query with specific file paths, modules, or identifiers for stronger grounding.');
-    }
-    else if (mode === 'comparison' && terms.length >= 2) {
+    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 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 asksHow = /\bhow\b/.test(normalizedQuestion);
+    const asksOrgRequestInjection = /\b(inject|injected|header|request|requests)\b/.test(normalizedQuestion) &&
+        /\b(org|organization)\b/.test(normalizedQuestion);
+    const commandMatches = [
+        ...extractNeurcodeCommandsFromCitations(citations),
+        ...(context.knownCommands || []),
+    ].filter((value, index, arr) => arr.indexOf(value) === index);
+    const installMatches = extractInstallCommandsFromCitations(citations);
+    const insightLines = extractInsightLines(citations, 5);
+    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;
@@ -897,14 +677,94 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
         findings.push(`Compared terms: "${left}" vs "${right}"`);
         findings.push(`Matches by term: ${left}=${leftCount}, ${right}=${rightCount}`);
     }
-    else {
-        if (citations.length > 0) {
-            answer = `Found ${citations.length} relevant evidence line(s) across ${stats.matchedFiles} file(s) for your question.`;
+    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".');
+    }
+    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 (asksCommandCatalog && commandMatches.length > 0) {
+        const normalizedCommands = 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];
+        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 locations = locationPool
+            .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}`);
+        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 = 'No direct evidence lines were found for this question in the scanned files.';
+            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');
+    }
+    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.');
+    }
+    if (asksInstall && installMatches.length === 0 && !context.cliPackageName) {
+        findings.push('Install question detected, but no package name could be resolved from packages/cli/package.json.');
+    }
     const topFiles = [...perFileCounts.entries()]
         .sort((a, b) => b[1] - a[1])
         .slice(0, 3)
@@ -913,6 +773,10 @@ function buildAnswer(mode, question, terms, citations, stats, termCounts, perFil
         findings.push(`Most relevant files: ${topFiles.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.');
+    }
     return {
         question,
         questionNormalized: normalizedQuestion,
@@ -1105,86 +969,13 @@ async function askCommand(question, options = {}) {
         const brainResults = orgId && projectId
             ? (0, brain_context_1.searchBrainContextEntries)(cwd, scope, normalizedQuestion, { limit: 48 })
             : { entries: [], totalIndexedFiles: 0 };
+        const cliPackageName = readCliPackageName(cwd);
+        const knownCliCommands = extractCommandsFromCliIndex(cwd);
+        const featureBullets = extractFeatureBulletsFromReadme(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 finalizeSpecialAnswer = (answer, note) => {
-            emitAskResult(answer, {
-                json: options.json,
-                maxCitations,
-                fromPlan: options.fromPlan,
-                verbose: options.verbose,
-            });
-            if (orgId && projectId) {
-                (0, brain_context_1.recordBrainProgressEvent)(cwd, scope, {
-                    type: 'ask',
-                    note,
-                });
-            }
-            if (shouldUseCache && orgId && projectId) {
-                const questionHash = (0, ask_cache_1.computeAskQuestionHash)({
-                    question: normalizedQuestion,
-                    contextHash: staticContext.hash,
-                });
-                const key = (0, ask_cache_1.computeAskCacheKey)({
-                    schemaVersion: 3,
-                    orgId,
-                    projectId,
-                    repo: repoFingerprint,
-                    questionHash,
-                    policyVersionHash,
-                    neurcodeVersion,
-                });
-                (0, ask_cache_1.writeCachedAsk)(cwd, {
-                    key,
-                    input: {
-                        schemaVersion: 3,
-                        orgId,
-                        projectId,
-                        repo: repoFingerprint,
-                        questionHash,
-                        policyVersionHash,
-                        neurcodeVersion,
-                        question: normalizedQuestion,
-                        contextHash: staticContext.hash,
-                    },
-                    output: answer,
-                    evidencePaths: answer.citations.map((citation) => citation.path),
-                });
-            }
-        };
-        if (isCliCommandListQuestion(normalizedQuestion)) {
-            const catalog = extractCliCommandCatalog(cwd);
-            if (catalog) {
-                const answer = buildCliCommandAnswer(question, normalizedQuestion, catalog, brainResults.entries.length);
-                finalizeSpecialAnswer(answer, `mode=cli_catalog;truth=${answer.truth.status};score=${answer.truth.score.toFixed(2)};commands=${catalog.topLevelCommands.length}`);
-                return;
-            }
-        }
-        if (isInstallCliQuestion(normalizedQuestion)) {
-            const installInfo = extractInstallCommandInfo(cwd);
-            if (installInfo) {
-                const answer = buildInstallCommandAnswer(question, normalizedQuestion, installInfo, brainResults.entries.length);
-                finalizeSpecialAnswer(answer, `mode=install_cli;truth=${answer.truth.status};score=${answer.truth.score.toFixed(2)};package=${installInfo.packageName}`);
-                return;
-            }
-        }
-        if (isTenancyQuestion(normalizedQuestion)) {
-            const answer = buildTenancyAnswer(cwd, question, normalizedQuestion, brainResults.entries.length);
-            if (answer) {
-                finalizeSpecialAnswer(answer, `mode=tenancy;truth=${answer.truth.status};score=${answer.truth.score.toFixed(2)};matched_files=${answer.stats.matchedFiles}`);
-                return;
-            }
-        }
-        if (isFeatureOverviewQuestion(normalizedQuestion)) {
-            const entries = extractFeatureEntriesFromReadme(cwd);
-            if (entries.length > 0) {
-                const answer = buildFeatureOverviewAnswer(question, normalizedQuestion, entries, brainResults.entries.length);
-                finalizeSpecialAnswer(answer, `mode=feature_overview;truth=${answer.truth.status};score=${answer.truth.score.toFixed(2)};entries=${entries.length}`);
-                return;
-            }
-        }
         const { mode, terms, matchers } = buildMatchers(question);
         const pathHints = derivePathHints(question);
         const mentionsAskCommand = /\bask\b/.test(normalizedQuestion);
@@ -1198,6 +989,7 @@ async function askCommand(question, options = {}) {
             candidateSet.add(entry.path);
             pathPriority.set(entry.path, (pathPriority.get(entry.path) || 0) + entry.score);
         }
+        addAnchorCandidates(fileTree, candidateSet, pathPriority, normalizedQuestion);
         const tokenHints = tokenizeQuestion(question);
         if (candidateSet.size < 80) {
             for (const filePath of fileTree) {
@@ -1207,6 +999,12 @@ async function askCommand(question, options = {}) {
                     if (normalizedPath.includes(token))
                         score += 0.2;
                 }
+                if (normalizedPath.startsWith('.github/')) {
+                    score -= 0.2;
+                }
+                if (normalizedPath.startsWith('scripts/')) {
+                    score -= 0.1;
+                }
                 if (!mentionsAskCommand && (filePath.endsWith('/commands/ask.ts') || filePath.endsWith('/utils/ask-cache.ts'))) {
                     score -= 0.45;
                 }
@@ -1222,8 +1020,8 @@ async function askCommand(question, options = {}) {
                 }
             }
         }
-        if (candidateSet.size < 20) {
-            for (const filePath of fileTree.slice(0, 160)) {
+        if (candidateSet.size < 40) {
+            for (const filePath of fileTree.slice(0, Math.min(fileTree.length, MAX_SCAN_FILES))) {
                 candidateSet.add(filePath);
             }
         }
@@ -1301,6 +1099,8 @@ async function askCommand(question, options = {}) {
             }
         }
         const selectedForOutput = [];
+        const wantsOrgRequestInjection = /\b(inject|injected|header|request|requests)\b/.test(normalizedQuestion) &&
+            /\b(org|organization)\b/.test(normalizedQuestion);
         if (mode === 'comparison' && terms.length >= 2) {
             for (const term of terms.slice(0, 2)) {
                 const firstForTerm = sourceEvidence.find((citation) => citation.term === term);
@@ -1309,6 +1109,38 @@ async function askCommand(question, options = {}) {
                 }
             }
         }
+        else if (mode === 'search' && terms.length > 0) {
+            const preferredTerms = 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;
+                if (selectedForOutput.some((existing) => existing.path === firstForTerm.path && existing.line === firstForTerm.line && existing.term === firstForTerm.term)) {
+                    continue;
+                }
+                selectedForOutput.push(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;
@@ -1330,7 +1162,11 @@ async function askCommand(question, options = {}) {
             brainCandidates: brainResults.entries.length,
         };
         const truth = evaluateTruthAssessment(mode, normalizedQuestion, terms, sourceEvidence, sourcePerFileCounts, sourceTermCounts);
-        const answer = buildAnswer(mode, question, terms, finalCitations, stats, sourceTermCounts, sourcePerFileCounts, truth);
+        const answer = buildAnswer(mode, question, terms, finalCitations, stats, sourceTermCounts, sourcePerFileCounts, truth, {
+            cliPackageName,
+            knownCommands: knownCliCommands,
+            featureBullets,
+        });
         emitAskResult(answer, {
             json: options.json,
             maxCitations,