@taurgis/bonsai 1.0.3 → 1.0.5

package/dist/commands/search.js

@@ -1,11 +1,18 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
-import { scanCacheDirs } from '../lib/research/storage.js';
+import { loadSearchableArtifacts } from '../lib/research/search-index.js';
+import { levenshtein, resultListHeading, truncationNotice, } from '../lib/text.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
 import { detectSite } from '../sites/index.js';
 import { fetchStaticHtml, fetchText, postJson } from '../lib/research/fetcher.js';
 import { runRemoteDocsSearch, } from '../lib/research/docs/remote-search-runner.js';
+// Results are ranked, so the truncation word is "top"; --limit caps at 50.
+const SEARCH_LABELS = {
+    noun: 'matching cached research',
+    order: 'top',
+    maxLimit: 50,
+};
 const REMOTE_SEARCH_DEPS = {
     fetchStatic: async (url) => {
         const res = await fetchStaticHtml(url);
@@ -54,7 +61,7 @@ export default class ResearchSearch extends BaseCommand {
             description: 'Search a documentation site directly (e.g. help.salesforce.com) instead of the local cache. Requires a site module that implements search.',
         }),
         remote: Flags.string({
-            description: 'Discover uncached docs via a site’s public search (Algolia DocSearch, MkDocs/Sphinx/Just-the-Docs index). Pass a docs page URL; falls back to local cache search if no connector applies.',
+            description: 'Discover uncached docs via a site’s public search or index (Algolia DocSearch, MkDocs/Sphinx/Just-the-Docs, llms.txt, sitemap.xml). Pass a docs page URL; falls back to local cache search if no connector applies.',
         }),
     };
     static stdoutIsPrimaryData = true;
@@ -150,21 +157,22 @@ export default class ResearchSearch extends BaseCommand {
         return snippet;
     }
     scanCacheDirForResults(readRoots, queryTerms, currentTime) {
-        return scanCacheDirs(readRoots, (artifact, filePath) => {
+        const results = [];
+        for (const { artifact, filePath } of loadSearchableArtifacts(readRoots)) {
             if (artifact.metadata.status !== 'active')
-                return null;
+                continue;
             const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
             if (!this.matchesFilters(artifact.metadata, freshness, this.flags.topic, this.flags.tags, this.flags['artifact-type'], Boolean(this.flags['include-stale'])))
-                return null;
+                continue;
             let score = this.calculateScore(artifact.metadata, artifact.summary, artifact.compressed, queryTerms, freshness);
             if (score <= 0)
-                return null;
+                continue;
             // Section children are more precise than the whole page, so rank a section hit slightly
             // above its parent for the same query (T-22).
             if (artifact.metadata.artifact_type === 'section')
                 score += 15;
             const snippetText = [artifact.summary, artifact.compressed].filter(Boolean).join('\n');
-            return {
+            results.push({
                 cacheKey: artifact.metadata.cache_key,
                 path: filePath,
                 artifactType: artifact.metadata.artifact_type,
@@ -177,13 +185,18 @@ export default class ResearchSearch extends BaseCommand {
                 snippet: this.makeSnippet(snippetText, queryTerms),
                 siteModuleId: artifact.metadata.site_module_id,
                 score,
-            };
-        });
+            });
+        }
+        return results;
     }
-    logSearchResults(finalResults) {
+    logSearchResults(finalResults, totalMatched) {
         if (this.jsonEnabled())
             return;
-        this.log(`Found ${finalResults.length} matching cached research entries:\n`);
+        if (finalResults.length === 0) {
+            this.log('No matching cached research entries found.');
+            return;
+        }
+        this.log(`${resultListHeading(totalMatched, finalResults.length, SEARCH_LABELS)}\n`);
         finalResults.forEach((res, index) => {
             this.log(`${index + 1}. [${res.topic || 'No Topic'}] Score: ${res.score}`);
             this.log(`   Cache Key: ${res.cacheKey}`);
@@ -252,7 +265,13 @@ export default class ResearchSearch extends BaseCommand {
         const results = this.scanCacheDirForResults(roots.readRoots, queryTerms, currentTime);
         results.sort((a, b) => b.score - a.score);
         const finalResults = results.slice(0, this.flags.limit);
-        this.logSearchResults(finalResults);
+        // Under --json the human heading is suppressed, so surface truncation on stderr instead (warn
+        // always emits, even in --json) without touching the stdout envelope. Human mode already shows
+        // it in the heading, so only warn under --json.
+        const notice = truncationNotice(results.length, finalResults.length, SEARCH_LABELS);
+        if (notice && this.jsonEnabled())
+            this.warn(notice);
+        this.logSearchResults(finalResults, results.length);
         return finalResults;
     }
 }
@@ -303,24 +322,6 @@ function scoreSingleTerm(term, topic, tags, sourceUrl, sourceUrls, summ, comp) {
     }
     return termScore;
 }
-function levenshtein(s1, s2) {
-    if (s1.length < s2.length)
-        return levenshtein(s2, s1);
-    if (s2.length === 0)
-        return s1.length;
-    let prevRow = Array.from({ length: s2.length + 1 }, (_, i) => i);
-    for (let i = 0; i < s1.length; i++) {
-        const currRow = [i + 1];
-        for (let j = 0; j < s2.length; j++) {
-            const deletions = prevRow[j + 1] + 1;
-            const insertions = currRow[j] + 1;
-            const substitutions = prevRow[j] + (s1[i] === s2[j] ? 0 : 1);
-            currRow.push(Math.min(deletions, insertions, substitutions));
-        }
-        prevRow = currRow;
-    }
-    return prevRow[s2.length];
-}
 function isFuzzyMatch(term, target) {
     if (term.length < 4 || target.length < 4)
         return false;

package/dist/commands/status.js

@@ -1,7 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { getArtifactPath } from '../lib/research/storage.js';
-import { evaluateFreshness, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 import { resolveResearchTarget } from '../lib/research/resolve-target.js';
 function resolveFreshness(cached, currentTime, ttl, maxAge) {
     const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
@@ -11,7 +11,7 @@ function resolveFreshness(cached, currentTime, ttl, maxAge) {
 }
 function describeCacheStatus(cached, currentTime, ttl, maxAge) {
     if (!cached) {
-        return { status: 'miss', freshness: 'stale_expired', action: 'would_fetch' };
+        return { status: 'miss', freshness: 'none', action: 'would_fetch' };
     }
     const freshness = resolveFreshness(cached, currentTime, ttl, maxAge);
     return freshness === 'fresh'
@@ -46,6 +46,12 @@ export default class ResearchStatus extends BaseCommand {
     async run() {
         const { url } = this.args;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
+        // Validate the duration flags up front so a malformed value reports the exact flag that is
+        // wrong, rather than later surfacing as a misattributed parse failure.
+        for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
+            if (msg)
+                this.error(msg, { exit: 2 });
+        }
         let target;
         try {
             target = resolveResearchTarget({
@@ -61,13 +67,8 @@ export default class ResearchStatus extends BaseCommand {
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
         const currentTime = new Date();
-        let result;
-        try {
-            result = describeCacheStatus(cached, currentTime, ttl, maxAge);
-        }
-        catch (err) {
-            this.error(`Invalid max-age: ${err.message}`, { exit: 2 });
-        }
+        // Both duration flags were validated above, so freshness resolution cannot throw on a parse error.
+        const result = describeCacheStatus(cached, currentTime, ttl, maxAge);
         // On a hit, report where it actually lives; on a miss, where a fetch would write it.
         const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
         if (!this.jsonEnabled()) {

package/dist/hooks/command-not-found/suggest.d.ts

@@ -0,0 +1,9 @@
+import { type Hook } from '@oclif/core';
+/**
+ * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
+ * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
+ * is offered only when the nearest command is a close match, and it is never auto-run — the user
+ * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
+ */
+declare const hook: Hook<'command_not_found'>;
+export default hook;

package/dist/hooks/command-not-found/suggest.js

@@ -0,0 +1,93 @@
+import { toConfiguredId } from '@oclif/core';
+import { closestMatch } from '../../lib/text.js';
+// Nearest command must be within this edit distance to be offered as a correction. Bonsai's command
+// ids are short, so 3 catches realistic typos ("statuss", "improt") without suggesting an unrelated
+// command for input that resembles nothing.
+const MAX_SUGGESTION_DISTANCE = 3;
+/**
+ * The nearest visible command to a typo, plus how many leading segments of the attempted id name
+ * the command. With `topicSeparator: ' '`, oclif folds every leading token of an unknown command
+ * into one colon-delimited id, so `bonsai serch hello` arrives as `serch:hello`. Matching that whole
+ * string never finds a short command, so walk prefixes longest→shortest and suggest off the closest:
+ * `serch:hello` resolves to nothing, but its prefix `serch` resolves to `search`. The matched prefix
+ * length doubles as the command-segment count, so a folded-in positional arg is dropped from display.
+ */
+function findSuggestion(segments, visibleIds) {
+    for (let n = segments.length; n >= 1; n--) {
+        const suggestion = closestMatch(segments.slice(0, n).join(':'), visibleIds, MAX_SUGGESTION_DISTANCE);
+        if (suggestion)
+            return { suggestion, commandSegments: n };
+    }
+    return { suggestion: null, commandSegments: 0 };
+}
+/**
+ * How many leading segments name the command when no suggestion exists: the known-topic chain plus
+ * the first unknown segment. Keeps `config frobnicate` from rendering as the misleading bare `config`
+ * (a real topic) while still dropping a positional arg from `frobnicate banana`.
+ */
+function topicChainLength(segments, config) {
+    let i = 0;
+    while (i < segments.length - 1 && config.findTopic(segments.slice(0, i + 1).join(':')))
+        i++;
+    return i + 1;
+}
+// Dot-separated, non-empty labels: a real domain (`docs.nestjs.com`) or IPv4 (`192.168.1.1`). The
+// URL parser also accepts a leading-dot filename (`.env`) or a relative path (`./x`) as a "host",
+// whose suggestion would be a nonsense `https://.env`; requiring well-formed labels rejects those.
+// Anchored with no overlapping quantifiers, so it is ReDoS-safe on the (already length-bounded) host.
+const DOMAIN_OR_IPV4 = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+/**
+ * The input as-typed when it looks like a URL missing its scheme (`example.com`,
+ * `docs.nestjs.com/guide`), else null. `bonsai <url>` is the headline command, but bin/cli.mjs only
+ * routes args carrying a `://` scheme to the fetch shorthand — so a scheme-less URL falls through to
+ * `command_not_found`. A domain-shaped host separates a forgotten-scheme URL from an ordinary command
+ * typo: `statuss` has no dot and never matches, while `config:frobnicate` fails to parse (the second
+ * segment becomes a non-numeric port), so neither is misread as a URL.
+ */
+function bareUrlInput(id) {
+    if (id.includes('://'))
+        return null;
+    let hostname;
+    try {
+        hostname = new URL(`https://${id}`).hostname;
+    }
+    catch {
+        return null;
+    }
+    return DOMAIN_OR_IPV4.test(hostname) ? id : null;
+}
+/**
+ * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
+ * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
+ * is offered only when the nearest command is a close match, and it is never auto-run — the user
+ * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
+ */
+const hook = async function (opts) {
+    const hiddenIds = new Set(opts.config.commands.filter((c) => c.hidden).map((c) => c.id));
+    const visibleIds = opts.config.commandIDs.filter((id) => !hiddenIds.has(id));
+    // A scheme-less URL is the most common "not a command" mistake for this CLI, so steer the user to
+    // the `bonsai <url>` shorthand with a scheme before falling back to nearest-command matching (which
+    // never finds a command for a hostname). The correction is shown, never auto-run (clig.dev).
+    const bareUrl = bareUrlInput(opts.id);
+    if (bareUrl) {
+        this.error([
+            `${bareUrl} is not a ${opts.config.bin} command.`,
+            `Run ${opts.config.bin} help for a list of available commands.`,
+            `Did you mean ${opts.config.bin} https://${bareUrl}? URLs need an http:// or https:// scheme.`,
+        ].join('\n'), { exit: 2 });
+    }
+    const segments = opts.id.split(':');
+    const { suggestion, commandSegments } = findSuggestion(segments, visibleIds);
+    // Show only the segments that name the command, never the positional args oclif folded into the id
+    // (which would otherwise glue the arg on and turn `://` into ` //`).
+    const displaySegments = commandSegments || topicChainLength(segments, opts.config);
+    const attempted = toConfiguredId(segments.slice(0, displaySegments).join(':'), opts.config);
+    // Order so the most actionable line lands last, where the eye rests (clig.dev): the help pointer
+    // is the floor, and a concrete "Did you mean …?" correction — when we have one — goes below it.
+    const lines = [`${attempted} is not a ${opts.config.bin} command.`];
+    lines.push(`Run ${opts.config.bin} help for a list of available commands.`);
+    if (suggestion)
+        lines.push(`Did you mean ${toConfiguredId(suggestion, opts.config)}?`);
+    this.error(lines.join('\n'), { exit: 2 });
+};
+export default hook;

package/dist/lib/config/index.d.ts

@@ -1,12 +1,17 @@
-export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
+export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
 export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
-export { resolveStorageMode, parseEnvStorage, STORAGE_ENV_VAR, type ResolveStorageInput, } from './resolve.js';
-import type { ConfigValues, ResolvedConfig, StorageMode } from './schema.js';
+export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.js';
+import type { ConfigValues, ResolvedConfig, StorageMode, SummaryLevel } from './schema.js';
 /**
  * Read both config files once and resolve the effective storage mode.
  * `flag` (a per-invocation `--storage` override) wins over everything else.
  */
 export declare function loadStorageMode(configDir: string | undefined, cwd: string, flag?: StorageMode, env?: Record<string, string | undefined>): StorageMode;
+/**
+ * Read both config files once and resolve the effective summary level.
+ * `flag` (a per-invocation override) wins over everything else.
+ */
+export declare function loadSummaryLevel(configDir: string | undefined, cwd: string, flag?: SummaryLevel, env?: Record<string, string | undefined>): SummaryLevel;
 /** The resolved value of every config key, factoring file + env layers. Extend as keys are added. */
 export declare function effectiveConfig(configDir: string | undefined, cwd: string): ResolvedConfig;
 export type ConfigScope = 'global' | 'local' | 'effective';

package/dist/lib/config/index.js

@@ -1,8 +1,8 @@
-export { SCHEMA_VERSION, STORAGE_MODES, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
+export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
 export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
-export { resolveStorageMode, parseEnvStorage, STORAGE_ENV_VAR, } from './resolve.js';
+export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
-import { resolveStorageMode } from './resolve.js';
+import { resolveStorageMode, resolveSummaryLevel } from './resolve.js';
 /**
  * Read both config files once and resolve the effective storage mode.
  * `flag` (a per-invocation `--storage` override) wins over everything else.
@@ -15,9 +15,24 @@ export function loadStorageMode(configDir, cwd, flag, env = process.env) {
         userConfig: readUserConfig(configDir),
     });
 }
+/**
+ * Read both config files once and resolve the effective summary level.
+ * `flag` (a per-invocation override) wins over everything else.
+ */
+export function loadSummaryLevel(configDir, cwd, flag, env = process.env) {
+    return resolveSummaryLevel({
+        flag,
+        env,
+        projectConfig: readProjectConfig(cwd),
+        userConfig: readUserConfig(configDir),
+    });
+}
 /** The resolved value of every config key, factoring file + env layers. Extend as keys are added. */
 export function effectiveConfig(configDir, cwd) {
-    return { storage: loadStorageMode(configDir, cwd) };
+    return {
+        storage: loadStorageMode(configDir, cwd),
+        summary: loadSummaryLevel(configDir, cwd),
+    };
 }
 /**
  * The config values for a requested scope: the user file (`global`), the project file (`local`),

package/dist/lib/config/resolve.d.ts

@@ -1,7 +1,16 @@
-import type { ConfigValues, StorageMode } from './schema.js';
+import type { ConfigValues, StorageMode, SummaryLevel } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export declare const STORAGE_ENV_VAR = "BONSAI_STORAGE";
+export declare const SUMMARY_ENV_VAR = "BONSAI_SUMMARY";
+/**
+ * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
+ * dropped during resolution (falling back to config/default), which would otherwise silently mask
+ * a typo like `BONSAI_SUMMARY=agressive`. Callers surface these on stderr so the misconfiguration
+ * is visible without breaking the run. Returns one message per offending variable, or empty.
+ */
+export declare function invalidEnvOverrideWarnings(env: Record<string, string | undefined>): string[];
 export declare function parseEnvStorage(env: Record<string, string | undefined>): StorageMode | undefined;
+export declare function parseEnvSummary(env: Record<string, string | undefined>): SummaryLevel | undefined;
 export interface ResolveStorageInput {
     flag?: StorageMode;
     env: Record<string, string | undefined>;
@@ -13,3 +22,14 @@ export interface ResolveStorageInput {
  * flag > env > project file > user file > built-in default.
  */
 export declare function resolveStorageMode(input: ResolveStorageInput): StorageMode;
+export interface ResolveSummaryInput {
+    flag?: SummaryLevel;
+    env: Record<string, string | undefined>;
+    projectConfig: Partial<ConfigValues>;
+    userConfig: Partial<ConfigValues>;
+}
+/**
+ * Resolve the effective summary level in precedence order:
+ * flag > env > project file > user file > built-in default.
+ */
+export declare function resolveSummaryLevel(input: ResolveSummaryInput): SummaryLevel;

package/dist/lib/config/resolve.js

@@ -1,12 +1,42 @@
-import { BUILT_IN_DEFAULTS, STORAGE_MODES } from './schema.js';
+import { BUILT_IN_DEFAULTS, STORAGE_MODES, SUMMARY_LEVELS } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export const STORAGE_ENV_VAR = 'BONSAI_STORAGE';
+export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
+/**
+ * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
+ * dropped during resolution (falling back to config/default), which would otherwise silently mask
+ * a typo like `BONSAI_SUMMARY=agressive`. Callers surface these on stderr so the misconfiguration
+ * is visible without breaking the run. Returns one message per offending variable, or empty.
+ */
+export function invalidEnvOverrideWarnings(env) {
+    const checks = [
+        [STORAGE_ENV_VAR, STORAGE_MODES],
+        [SUMMARY_ENV_VAR, SUMMARY_LEVELS],
+    ];
+    const warnings = [];
+    for (const [name, valid] of checks) {
+        // After trim, an empty/whitespace-only value is falsy and treated as "unset" (no warning),
+        // matching parseEnv*; matching is case-sensitive, so a wrong-case value is invalid and warns.
+        const raw = env[name]?.trim();
+        if (raw && !valid.includes(raw)) {
+            warnings.push(`Ignoring ${name}="${raw}": not one of ${valid.join(', ')}. ` +
+                `Using the configured value or default instead.`);
+        }
+    }
+    return warnings;
+}
 export function parseEnvStorage(env) {
     const raw = env[STORAGE_ENV_VAR]?.trim();
     return STORAGE_MODES.includes(raw ?? '')
         ? raw
         : undefined;
 }
+export function parseEnvSummary(env) {
+    const raw = env[SUMMARY_ENV_VAR]?.trim();
+    return SUMMARY_LEVELS.includes(raw ?? '')
+        ? raw
+        : undefined;
+}
 /**
  * Resolve the effective storage mode in precedence order:
  * flag > env > project file > user file > built-in default.
@@ -18,3 +48,14 @@ export function resolveStorageMode(input) {
         input.userConfig.storage ??
         BUILT_IN_DEFAULTS.storage);
 }
+/**
+ * Resolve the effective summary level in precedence order:
+ * flag > env > project file > user file > built-in default.
+ */
+export function resolveSummaryLevel(input) {
+    return (input.flag ??
+        parseEnvSummary(input.env) ??
+        input.projectConfig.summary ??
+        input.userConfig.summary ??
+        BUILT_IN_DEFAULTS.summary);
+}

package/dist/lib/config/schema.d.ts

@@ -4,13 +4,16 @@
  * where the research cache lives.
  */
 export type StorageMode = 'global' | 'project';
+export type SummaryLevel = 'conservative' | 'balanced' | 'aggressive';
 export interface ConfigValues {
     storage?: StorageMode;
+    summary?: SummaryLevel;
 }
 export type ResolvedConfig = Required<ConfigValues>;
 export type ConfigKey = keyof ConfigValues;
 export declare const SCHEMA_VERSION = 1;
 export declare const STORAGE_MODES: readonly StorageMode[];
+export declare const SUMMARY_LEVELS: readonly SummaryLevel[];
 export declare const ALL_KEYS: readonly ConfigKey[];
 export declare const BUILT_IN_DEFAULTS: ResolvedConfig;
 export interface KeyMeta {

package/dist/lib/config/schema.js

@@ -5,10 +5,13 @@
  */
 export const SCHEMA_VERSION = 1;
 export const STORAGE_MODES = ['global', 'project'];
-export const ALL_KEYS = ['storage'];
+export const SUMMARY_LEVELS = ['conservative', 'balanced', 'aggressive'];
+export const ALL_KEYS = ['storage', 'summary'];
 export const BUILT_IN_DEFAULTS = {
     // Default to global so existing installs keep using the OCLIF data dir unchanged.
     storage: 'global',
+    // Default to the gentlest summarization so cached content keeps the most detail out of the box.
+    summary: 'conservative',
 };
 export const KEY_META = {
     storage: {
@@ -18,6 +21,13 @@ export const KEY_META = {
         isValid: (v) => STORAGE_MODES.includes(String(v)),
         format: (v) => String(v),
     },
+    summary: {
+        description: `How aggressively the compressed format is summarized (${SUMMARY_LEVELS.join('|')}).`,
+        values: SUMMARY_LEVELS,
+        parseValue: (raw) => raw.trim(),
+        isValid: (v) => SUMMARY_LEVELS.includes(String(v)),
+        format: (v) => String(v),
+    },
 };
 export function isKnownKey(key) {
     return ALL_KEYS.includes(key);

package/dist/lib/research/artifact.d.ts

@@ -12,9 +12,20 @@ export declare function serializeArtifact(artifact: ResearchArtifact): string;
  */
 export declare function parseMetadata(lines: string[]): ResearchArtifactMetadata;
 /**
- * Extracts a named markdown section (e.g. ## Summary) from body text.
+ * Extracts a named markdown section (e.g. ## Summary) from body text. The section ends at the next
+ * known section header (`nextSection`), matched as the exact serialized separator `\n\n## <name>` —
+ * NOT at the next `## ` heading, because section bodies legitimately contain their own `##` headings
+ * (a compressed/detailed page often *starts* with one). Bounding on a generic heading would truncate
+ * such content to nothing. Omit `nextSection` for the final section to read to end-of-body.
  */
-export declare function extractSection(body: string, sectionName: string): string;
+export declare function extractSection(body: string, sectionName: string, nextSection?: string): string;
+/**
+ * Parses an artifact for search/listing without materializing the (often large) Detailed and
+ * Provenance bodies. Truncates at the Detailed section boundary before parsing so megabyte-scale
+ * detailed content is never split or sliced. `detailed` and `provenance` come back empty — callers
+ * that need them must use {@link parseArtifact}. Shares all parsing rules with parseArtifact.
+ */
+export declare function parseArtifactShallow(content: string): ResearchArtifact;
 /**
  * Parses full Markdown content into a structured ResearchArtifact.
  */

package/dist/lib/research/artifact.js

@@ -181,18 +181,38 @@ export function parseMetadata(lines) {
     return state.meta;
 }
 /**
- * Extracts a named markdown section (e.g. ## Summary) from body text.
+ * Extracts a named markdown section (e.g. ## Summary) from body text. The section ends at the next
+ * known section header (`nextSection`), matched as the exact serialized separator `\n\n## <name>` —
+ * NOT at the next `## ` heading, because section bodies legitimately contain their own `##` headings
+ * (a compressed/detailed page often *starts* with one). Bounding on a generic heading would truncate
+ * such content to nothing. Omit `nextSection` for the final section to read to end-of-body.
  */
-export function extractSection(body, sectionName) {
+export function extractSection(body, sectionName, nextSection) {
     const header = `## ${sectionName}`;
     const idx = body.indexOf(header);
     if (idx === -1)
         return '';
     const start = idx + header.length;
-    const nextHeadingIdx = body.indexOf('\n## ', start);
-    const rawText = nextHeadingIdx === -1 ? body.slice(start) : body.slice(start, nextHeadingIdx);
+    const endIdx = nextSection ? body.indexOf(`\n\n## ${nextSection}`, start) : -1;
+    const rawText = endIdx === -1 ? body.slice(start) : body.slice(start, endIdx);
     return rawText.trim();
 }
+/**
+ * Parses an artifact for search/listing without materializing the (often large) Detailed and
+ * Provenance bodies. Truncates at the Detailed section boundary before parsing so megabyte-scale
+ * detailed content is never split or sliced. `detailed` and `provenance` come back empty — callers
+ * that need them must use {@link parseArtifact}. Shares all parsing rules with parseArtifact.
+ */
+export function parseArtifactShallow(content) {
+    // Only look for the Detailed boundary in the body (after the closing frontmatter fence) and match
+    // the exact serialized separator `\n\n## Detailed`, so neither a frontmatter value nor an earlier
+    // body heading named "Detailed" can truncate the content prematurely.
+    const bodyStart = content.indexOf('\n---', 3);
+    const searchFrom = bodyStart === -1 ? 0 : bodyStart + 4;
+    const detailedIdx = content.indexOf('\n\n## Detailed', searchFrom);
+    const sliced = detailedIdx === -1 ? content : content.slice(0, detailedIdx);
+    return parseArtifact(sliced);
+}
 /**
  * Parses full Markdown content into a structured ResearchArtifact.
  */
@@ -209,9 +229,9 @@ export function parseArtifact(content) {
     const bodyLines = parts.slice(closingIdx + 1);
     const bodyText = bodyLines.join('\n');
     const metadata = parseMetadata(frontmatterLines);
-    const summary = extractSection(bodyText, 'Summary');
-    const compressed = extractSection(bodyText, 'Compressed');
-    const detailed = extractSection(bodyText, 'Detailed');
+    const summary = extractSection(bodyText, 'Summary', 'Compressed');
+    const compressed = extractSection(bodyText, 'Compressed', 'Detailed');
+    const detailed = extractSection(bodyText, 'Detailed', 'Provenance');
     const provenance = extractSection(bodyText, 'Provenance');
     return { metadata, summary, compressed, detailed, provenance };
 }

package/dist/lib/research/browser.d.ts

@@ -39,6 +39,18 @@ export interface CdpPage {
     sessionId: string;
     close: () => Promise<void>;
 }
+/** Status line of the main-frame document response, captured from Network.responseReceived. */
+export interface MainDocumentResponse {
+    status: number;
+    statusText: string;
+}
+/**
+ * Rejects a rendered page whose main document returned an HTTP error, mirroring the static
+ * fetcher's `assertOk`. Without this, `--rendered` on a 404/500 would capture the server's (or
+ * the browser's) error page as if it were real content and cache it. A missing response (no
+ * Document event seen — e.g. data: or about: targets) is left to the caller's content checks.
+ */
+export declare function assertRenderedHttpOk(mainDoc: MainDocumentResponse | undefined): void;
 /**
  * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network,
  * and Runtime domains. The caller drives navigation and must call close() when finished.

package/dist/lib/research/browser.js

@@ -90,7 +90,8 @@ export function findChromePath() {
         }
     }
     catch { }
-    throw new Error('Chrome executable not found. Please set CHROME_PATH environment variable.');
+    throw new Error('No Chrome or Chromium browser found for browser-based extraction. Install Chrome/Chromium or ' +
+        'set CHROME_PATH to the browser executable. Static (non-rendered) fetching does not require a browser.');
 }
 async function spawnChrome(chromePath) {
     const chromeProcess = spawn(chromePath, [
@@ -220,6 +221,17 @@ export const BLOCKED_ASSET_URLS = [
     '*.ico',
 ];
 const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+/**
+ * Rejects a rendered page whose main document returned an HTTP error, mirroring the static
+ * fetcher's `assertOk`. Without this, `--rendered` on a 404/500 would capture the server's (or
+ * the browser's) error page as if it were real content and cache it. A missing response (no
+ * Document event seen — e.g. data: or about: targets) is left to the caller's content checks.
+ */
+export function assertRenderedHttpOk(mainDoc) {
+    if (mainDoc && mainDoc.status >= 400) {
+        throw new Error(`Fetch failed with status ${mainDoc.status} ${mainDoc.statusText}`.trimEnd());
+    }
+}
 /**
  * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network,
  * and Runtime domains. The caller drives navigation and must call close() when finished.
@@ -332,8 +344,33 @@ export async function fetchRenderedHtml(url, options = {}) {
     const page = await openCdpPage();
     try {
         await page.client.send('Network.setBlockedURLs', { urls: BLOCKED_ASSET_URLS }, page.sessionId);
-        await page.client.send('Page.navigate', { url: currentUrl }, page.sessionId);
+        // Record the status of each frame's first Document response so we can reject HTTP errors after
+        // the page settles. Keyed by frameId; the navigated top frame is matched via the navigate result.
+        const documentResponses = new Map();
+        page.client.on(`${page.sessionId}:Network.responseReceived`, (params) => {
+            const { frameId } = params;
+            const status = params.response?.status;
+            // Only record real numeric statuses: a Document event without a usable status would
+            // otherwise store NaN, which silently slips past the `>= 400` guard and the `?? 200`
+            // fallback alike, leaking a NaN into BrowserFetchResult.status (declared `number`).
+            if (params.type !== 'Document' || !frameId || typeof status !== 'number')
+                return;
+            if (documentResponses.has(frameId))
+                return;
+            documentResponses.set(frameId, {
+                status,
+                statusText: params.response?.statusText ?? '',
+            });
+        });
+        const nav = await page.client.send('Page.navigate', { url: currentUrl }, page.sessionId);
+        // A network-level failure (DNS, refused/closed connection, TLS) never fires a load event, so
+        // fail fast here instead of waiting out the full navigation timeout on a dead page.
+        if (nav.errorText) {
+            throw new Error(`Navigation failed: ${nav.errorText}`);
+        }
         await waitForLoad(page.client, page.sessionId, timeout, options.settleMs ?? 1000);
+        const mainDoc = nav.frameId ? documentResponses.get(nav.frameId) : undefined;
+        assertRenderedHttpOk(mainDoc);
         const evalResult = await page.client.send('Runtime.evaluate', { expression: 'document.documentElement.outerHTML', returnByValue: true }, page.sessionId);
         const html = evalResult.result?.value;
         if (typeof html !== 'string') {
@@ -344,7 +381,7 @@ export async function fetchRenderedHtml(url, options = {}) {
             throw new Error(`Response body size limit exceeded. Rendered HTML is ${byteLength} bytes.`);
         }
         return {
-            status: 200,
+            status: mainDoc?.status ?? 200,
             contentType: 'text/html',
             etag: null,
             lastModified: null,