@taurgis/bonsai 1.0.4 → 1.0.5

package/dist/commands/config/unset.js

@@ -1,10 +1,10 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { writeUserConfig, writeProjectConfig } from '../../lib/config/index.js';
+import { writeUserConfig, writeProjectConfig, validKeysHint } from '../../lib/config/index.js';
 export default class ConfigUnset extends ConfigCommand {
     static id = 'config unset';
     static summary = 'Remove a research configuration key.';
-    static description = 'Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage.';
+    static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
             description: 'Remove the user-level storage setting',

package/dist/commands/fetch.d.ts

@@ -30,8 +30,13 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private executeCacheMiss;
     private buildResultData;
     private validateDurationFlags;
+    private emitFetchError;
     private resolveArtifact;
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
 }
+export declare function fetchFailureGuidance(message: string, url: string): {
+    suggestions: string[];
+    ref?: string;
+} | undefined;

package/dist/commands/fetch.js

@@ -6,7 +6,7 @@ import { BaseCommand } from '../base-command.js';
 import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
 import { writeArtifactSecurely } from '../lib/research/secure-write.js';
 import { loadSummaryLevel } from '../lib/config/index.js';
-import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
 import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
 import { fetchRenderedHtml } from '../lib/research/browser.js';
@@ -24,7 +24,7 @@ export default class FetchCommand extends BaseCommand {
     static id = 'fetch';
     static hidden = true;
     static summary = 'An advanced, locally cached web research tool optimized for LLM ingestion.';
-    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.';
+    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.\n\nUsually invoked via the shorthand `bonsai <url>` rather than `bonsai fetch <url>`.';
     static examples = [
         {
             description: 'Research a URL with detailed output, tagged with topic and tags',
@@ -64,7 +64,7 @@ export default class FetchCommand extends BaseCommand {
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan of the data (e.g., "2h", "7d", "3m").',
+            description: 'Predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m".',
         }),
         'max-age': Flags.string({
             description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
@@ -183,20 +183,22 @@ export default class FetchCommand extends BaseCommand {
     }
     // Validates the duration flags up front, exiting with code 2 on a malformed value.
     validateDurationFlags(ttl, maxAge) {
-        for (const [label, value] of [
-            ['TTL', ttl],
-            ['max-age', maxAge],
-        ]) {
-            if (!value)
-                continue;
-            try {
-                parseTtlToMs(value);
-            }
-            catch (err) {
-                this.error(`Invalid ${label}: ${err.message}`, { exit: 2 });
-            }
+        for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
+            if (msg)
+                this.error(msg, { exit: 2 });
         }
     }
+    // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
+    // Errors that otherwise reach the user as a bare "what broke" line with no "what to do"; this
+    // attaches recovery hints (e.g. import an auth-blocked page). Everything reaching here is a runtime
+    // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
+    // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
+    // the message (toErrorJson), so machine output is unchanged.
+    emitFetchError(err, url) {
+        const message = err instanceof Error ? err.message : String(err);
+        const guidance = fetchFailureGuidance(message, url);
+        this.error(message, { exit: 1, suggestions: guidance?.suggestions, ref: guidance?.ref });
+    }
     // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
     // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
     async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel) {
@@ -210,9 +212,12 @@ export default class FetchCommand extends BaseCommand {
         }
         const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel);
         const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
+        // No entry existed at lookup, so there is no prior freshness to report. 'none' (not
+        // 'stale_expired') keeps the field honest — nothing expired; the page was simply uncached and
+        // has now been fetched fresh. Mirrors the `status` command's miss reporting.
         return {
             cacheStatus: 'miss',
-            freshnessState: 'stale_expired',
+            freshnessState: 'none',
             artifact,
             storageDir: dir,
             redirectedToGlobal,
@@ -277,6 +282,13 @@ export default class FetchCommand extends BaseCommand {
             }
             return resultData;
         }
+        catch (err) {
+            // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
+            // path; only genuine fetch/extract failures land here and get classified guidance. Use the
+            // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
+            // unsanitized user input back to the terminal).
+            this.emitFetchError(err, normalizedUrl);
+        }
         finally {
             if (tmpDir) {
                 rmSync(tmpDir, { recursive: true, force: true });
@@ -284,6 +296,59 @@ export default class FetchCommand extends BaseCommand {
         }
     }
 }
+// Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
+// unrecognized failures, which then surface with their original message and no extra hint. The
+// patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
+// change. Resolutions mirror the published troubleshooting guide.
+export function fetchFailureGuidance(message, url) {
+    const ref = 'https://taurgis.github.io/bonsai/troubleshooting';
+    // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
+    // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
+    const importHint = `Open it in a browser, save the page, then import it: cat page.md | bonsai import ${url} --stdin`;
+    // 401/403: an auth wall or anti-scraping WAF. Bonsai has no authenticated-fetch path in v1.
+    if (/failed with status 40[13]\b/.test(message)) {
+        return {
+            suggestions: ['The page requires authentication or blocks automated requests.', importHint],
+            ref,
+        };
+    }
+    if (/failed with status 404\b/.test(message)) {
+        return { suggestions: ['Check the URL is correct and the page still exists.'] };
+    }
+    if (/failed with status 5\d\d\b/.test(message)) {
+        return {
+            suggestions: ['The server returned an error. Retry later or verify the host is healthy.'],
+        };
+    }
+    // Server returned a non-HTML body (JSON, binary, or no Content-Type at all). Scope the opener to
+    // the real failure: --rendered does produce HTML, so "only scrapes HTML" would read as misleading.
+    if (/Rejected content type|does not look like HTML/.test(message)) {
+        return {
+            suggestions: [
+                'The server returned a non-HTML response (e.g. JSON or binary).',
+                'If the page is rendered by client-side JavaScript, retry with --rendered.',
+                importHint,
+            ],
+            ref,
+        };
+    }
+    if (/DNS resolution failed/.test(message)) {
+        return {
+            suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
+        };
+    }
+    // A hostname that only resolves to a private/local IP at request time (literal private addresses
+    // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
+    if (/blocked local or private target/.test(message)) {
+        return {
+            suggestions: [
+                'The hostname resolves to a private or local address, which is blocked to prevent SSRF. Only public http(s) hosts can be fetched.',
+            ],
+            ref,
+        };
+    }
+    return undefined;
+}
 // Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
 function applyCaptureMetadata(artifact, capture) {
     const meta = artifact.metadata;

package/dist/commands/import.d.ts

@@ -23,6 +23,7 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected stdinIsInteractive(): boolean;
     private readStdin;
     private getSourceUrls;
     private validateSourceMode;

package/dist/commands/import.js

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Errors, Flags } from '@oclif/core';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -34,6 +34,10 @@ export default class ResearchImport extends BaseCommand {
     static args = {
         url: Args.string({
             required: false,
+            // oclif fills an omitted optional arg from piped stdin unless ignoreStdin is set. Without
+            // this, the Markdown piped for `--stdin` is swallowed into `url`, making multi-source import
+            // (`import --stdin --source-url ...`) wrongly look like it also got a positional URL.
+            ignoreStdin: true,
             description: 'The single source URL of the page (only for single-source import).',
         }),
     };
@@ -78,6 +82,11 @@ export default class ResearchImport extends BaseCommand {
         })(),
     };
     static stdoutIsPrimaryData = true;
+    // Isolated so tests can force the interactive branch; `isTTY` is `true` only on a real terminal and
+    // falsy (undefined) for pipes, files, and /dev/null. See https://nodejs.org/api/process.html#processstdin
+    stdinIsInteractive() {
+        return process.stdin.isTTY === true;
+    }
     async readStdin(limitBytes = 1024 * 1024) {
         return new Promise((resolve, reject) => {
             let data = '';
@@ -164,16 +173,34 @@ export default class ResearchImport extends BaseCommand {
     }
     async readAndValidateInput() {
         if (this.flags.stdin) {
+            // On an interactive terminal with nothing piped, reading stdin blocks forever waiting for EOF —
+            // a silent hang with no feedback. Fail fast with a usage error instead; piped/redirected input
+            // (the agent and CI path) has isTTY falsy and reads normally.
+            if (this.stdinIsInteractive()) {
+                this.error('No data piped to --stdin.', {
+                    exit: 2,
+                    suggestions: [
+                        'Pipe Markdown content, e.g. cat notes.md | bonsai import <url> --stdin',
+                        'Or read from a file: bonsai import <url> --file notes.md',
+                    ],
+                });
+            }
+            // Initialized so the post-catch read below never depends on this.error()'s `never` return type
+            // for definite assignment; the empty-content guard rejects '' as a usage error anyway.
+            let rawInput = '';
             try {
-                const rawInput = await this.readStdin();
-                if (!rawInput.trim()) {
-                    this.error('Empty stdin content provided.', { exit: 2 });
-                }
-                return rawInput;
+                rawInput = await this.readStdin();
             }
             catch (err) {
+                // Genuine stream/size failure reading stdin → I/O failure (exit 1).
                 this.error(err.message, { exit: 1 });
             }
+            // Empty input is a usage error (exit 2), not an I/O failure — keep it out of the
+            // catch above so its exit code is not clobbered to 1.
+            if (!rawInput.trim()) {
+                this.error('Empty stdin content provided.', { exit: 2 });
+            }
+            return rawInput;
         }
         if (this.flags.file) {
             const filePath = path.resolve(this.flags.file);
@@ -181,6 +208,11 @@ export default class ResearchImport extends BaseCommand {
                 return this.readAndValidateFile(filePath);
             }
             catch (err) {
+                // readAndValidateFile raises usage errors (missing/not-a-file/empty) via this.error,
+                // which throw CLIErrors carrying their own exit code and message — preserve those.
+                // Only an unexpected read failure becomes a wrapped I/O failure (exit 1).
+                if (err instanceof Errors.CLIError)
+                    throw err;
                 this.error(`Failed to read file: ${err.message}`, { exit: 1 });
             }
         }

package/dist/commands/list.js

@@ -3,6 +3,9 @@ import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
+import { resultListHeading, truncationNotice } from '../lib/text.js';
+// Listings are ordered newest-first, so the truncation word is "first"; --limit caps at 100.
+const LIST_LABELS = { noun: 'cached research', order: 'first', maxLimit: 100 };
 export default class ResearchList extends BaseCommand {
     static id = 'list';
     static summary = 'List cached research artifacts by metadata filters.';
@@ -82,6 +85,12 @@ export default class ResearchList extends BaseCommand {
         return scanCacheDirs(readRoots, (artifact, filePath) => {
             if (artifact.metadata.status !== 'active')
                 return null;
+            // Section children are sub-chunks of a page, not artifacts a user "has" — they would flood the
+            // listing (one page yields dozens) and aren't in the documented source/research_note contract.
+            // They stay discoverable through `search` (which ranks them) and `inspect` (which lists a
+            // page's sections). `list` answers "what pages/notes do I have?", so keep it page-level.
+            if (artifact.metadata.artifact_type === 'section')
+                return null;
             const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
             if (!this.matchesFilters(artifact.metadata, freshness))
                 return null;
@@ -101,14 +110,14 @@ export default class ResearchList extends BaseCommand {
             };
         });
     }
-    logListResults(finalResults) {
+    logListResults(finalResults, totalMatched) {
         if (this.jsonEnabled())
             return;
         if (finalResults.length === 0) {
             this.log('No cached research entries found matching filters.');
             return;
         }
-        this.log(`Found ${finalResults.length} cached research entries:\n`);
+        this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
             this.log(`${index + 1}. [${res.topic || 'No Topic'}] Key: ${res.cacheKey}`);
             this.log(`   Type: ${res.artifactType} | Freshness: ${res.freshness}`);
@@ -132,7 +141,13 @@ export default class ResearchList extends BaseCommand {
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
-        this.logListResults(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, LIST_LABELS);
+        if (notice && this.jsonEnabled())
+            this.warn(notice);
+        this.logListResults(finalResults, results.length);
         return finalResults;
     }
 }

package/dist/commands/prune.js

@@ -4,7 +4,8 @@ import { join } from 'node:path';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { parseTtlToMs } from '../lib/research/freshness.js';
+import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
+import { pluralize } from '../lib/text.js';
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
     static summary = 'Clean up old or inactive research cache entries.';
@@ -48,6 +49,15 @@ export default class ResearchPrune extends BaseCommand {
         if (!this.flags['dry-run'] && !this.flags.yes) {
             this.error('Safety check: Please specify --yes to confirm pruning, or --dry-run to list files that would be deleted.', { exit: 2 });
         }
+        // Validate durations up front: scanCacheDir swallows per-file errors, so a malformed
+        // --older-than/--inactive would otherwise be silently ignored and report "0 entries".
+        for (const msg of [
+            durationFlagError('--older-than', this.flags['older-than']),
+            durationFlagError('--inactive', this.flags.inactive),
+        ]) {
+            if (msg)
+                this.error(msg, { exit: 2 });
+        }
     }
     shouldPrune(meta, currentTime) {
         const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
@@ -109,24 +119,30 @@ export default class ResearchPrune extends BaseCommand {
         const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
         const dryRun = this.flags['dry-run'];
         const count = filesToPrune.length;
+        // Track deletions actually performed so the JSON envelope and human output agree even when an
+        // unlink fails (e.g. a permission error). Reporting candidate count as `prunedCount` would
+        // overstate success and mislead an agent branching on the result.
+        let prunedCount = 0;
         if (dryRun) {
             if (!this.jsonEnabled()) {
-                this.log(`[Dry Run] Found ${count} research cache entries that would be pruned:\n`);
+                const noun = pluralize(count, 'entry', 'entries');
+                this.log(`[Dry Run] Found ${count} research cache ${noun} that would be pruned:\n`);
                 filesToPrune.forEach((f) => {
                     this.log(`- [${f.topic || 'No Topic'}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
                 });
             }
         }
         else {
-            const prunedCount = this.deletePruneCandidates(filesToPrune);
+            prunedCount = this.deletePruneCandidates(filesToPrune);
             if (!this.jsonEnabled()) {
-                this.log(`Successfully pruned ${prunedCount} of ${count} research cache entries.`);
+                const noun = pluralize(count, 'entry', 'entries');
+                this.log(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`);
             }
         }
         return {
             dryRun,
-            prunedCount: dryRun ? 0 : filesToPrune.length,
-            candidateCount: filesToPrune.length,
+            prunedCount,
+            candidateCount: count,
             files: filesToPrune.map((f) => ({
                 cacheKey: f.cacheKey,
                 path: f.path,

package/dist/commands/search.js

@@ -1,11 +1,18 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.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;
@@ -182,10 +189,14 @@ export default class ResearchSearch extends BaseCommand {
         }
         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}`);
@@ -254,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;
     }
 }
@@ -305,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,6 +1,6 @@
 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, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.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.

package/dist/lib/config/index.js

@@ -1,6 +1,6 @@
 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, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, STORAGE_ENV_VAR, SUMMARY_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, resolveSummaryLevel } from './resolve.js';
 /**