@taurgis/bonsai 1.0.5 → 1.0.6

package/dist/commands/list.js

@@ -3,51 +3,55 @@ 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';
+import { ARTIFACT_TYPES, CAPTURE_METHODS } from '../lib/research/schema.js';
+import { NO_TOPIC_LABEL, 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 };
+// `list` answers "what pages/notes do I have?" and deliberately omits section children (see
+// scanCacheDirForList), so `section` is not an offered filter — every other artifact type can appear.
+const LISTABLE_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');
 export default class ResearchList extends BaseCommand {
     static id = 'list';
     static summary = 'List cached research artifacts by metadata filters.';
     static description = 'Lists cached research artifacts, including metadata details like path, source count, freshness, token estimates, and quality metrics without printing full content.';
     static examples = [
         {
-            description: 'List all cached entries',
+            description: 'list all cached entries',
             command: '<%= config.bin %> list',
         },
         {
-            description: 'List cached entries for a specific topic with JSON output',
+            description: 'list cached entries for a specific topic with JSON output',
             command: '<%= config.bin %> list --topic "React Suspense" --json',
         },
         {
-            description: 'List only fresh entries filtered by tags',
+            description: 'list only fresh entries filtered by tags',
             command: '<%= config.bin %> list --freshness fresh --tags node --tags url',
         },
     ];
     static flags = {
         topic: Flags.string({
             char: 't',
-            description: 'Filter by exact topic (case-insensitive).',
+            description: 'filter by exact topic (case-insensitive)',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Filter by tags (must match all tags specified).',
+            description: 'filter by tags (must match all tags specified)',
             multiple: true,
         }),
         freshness: Flags.option({
-            description: 'Filter by freshness state.',
+            description: 'filter by freshness state',
             options: ['fresh', 'stale_grace', 'stale_expired'],
         })(),
         'artifact-type': Flags.option({
-            description: 'Filter by artifact type.',
-            options: ['source', 'research_note'],
+            description: 'filter by artifact type',
+            options: LISTABLE_ARTIFACT_TYPES,
         })(),
         'capture-method': Flags.option({
-            description: 'Filter by capture method.',
-            options: ['static_fetch', 'browser_fallback', 'agent_supplied'],
+            description: 'filter by capture method',
+            options: CAPTURE_METHODS,
         })(),
         limit: Flags.integer({
-            description: 'Maximum number of results to return (default 50, max 100).',
+            description: 'maximum number of results to return (default 50, max 100)',
             default: 50,
         }),
     };
@@ -55,7 +59,7 @@ export default class ResearchList extends BaseCommand {
     validateListFlags() {
         const limit = this.flags.limit;
         if (limit !== undefined && (limit < 1 || limit > 100)) {
-            this.error('Limit must be between 1 and 100.', { exit: 2 });
+            this.error('Limit must be between 1 and 100.', { exit: 2, code: 'INVALID_LIMIT' });
         }
     }
     matchesFilters(meta, freshness) {
@@ -88,7 +92,10 @@ export default class ResearchList extends BaseCommand {
             // 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.
+            // page's sections). `list` answers "what pages/notes do I have?", so keep it page-level. This
+            // unconditional guard owns the exclusion (the default no-filter case relies on it);
+            // LISTABLE_ARTIFACT_TYPES just hides `section` from --artifact-type so no one filters for a
+            // type list can never return. Keep both in sync if section handling ever changes.
             if (artifact.metadata.artifact_type === 'section')
                 return null;
             const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
@@ -115,11 +122,12 @@ export default class ResearchList extends BaseCommand {
             return;
         if (finalResults.length === 0) {
             this.log('No cached research entries found matching filters.');
+            this.log(`\nTip: populate the cache first: ${this.config.bin} <url>`);
             return;
         }
         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(`${index + 1}. [${res.topic || NO_TOPIC_LABEL}] Key: ${res.cacheKey}`);
             this.log(`   Type: ${res.artifactType} | Freshness: ${res.freshness}`);
             this.log(`   Tokens: compressed=${res.tokenEstimate?.compressed || 0}, detailed=${res.tokenEstimate?.detailed || 0}`);
             this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);

package/dist/commands/prune.d.ts

@@ -10,7 +10,7 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
     static flags: {
         'older-than': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         inactive: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | "section" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/prune.js

@@ -5,49 +5,66 @@ import { BaseCommand } from '../base-command.js';
 import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
-import { pluralize } from '../lib/text.js';
+import { ARTIFACT_TYPES } from '../lib/research/schema.js';
+import { NO_TOPIC_LABEL, pluralize } from '../lib/text.js';
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
     static summary = 'Clean up old or inactive research cache entries.';
     static description = 'Prunes cached research entries based on age, inactivity, or artifact type to free up disk space.';
     static examples = [
         {
-            description: 'Perform a dry run of pruning entries older than 90 days',
+            description: 'perform a dry run of pruning entries older than 90 days',
             command: '<%= config.bin %> prune --older-than 90d --dry-run',
         },
         {
-            description: 'Actually prune entries older than 30 days that are source scrapes',
+            description: 'actually prune entries older than 30 days that are source scrapes',
             command: '<%= config.bin %> prune --older-than 30d --artifact-type source --yes',
         },
     ];
     static flags = {
         'older-than': Flags.string({
-            description: 'Prune entries older than duration (e.g. "30d", "90d").',
+            description: 'prune entries older than duration (e.g. "30d", "90d")',
         }),
         inactive: Flags.string({
-            description: 'Prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d").',
+            description: 'prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d")',
         }),
         'artifact-type': Flags.option({
-            description: 'Filter pruning to specific artifact type.',
-            options: ['source', 'research_note'],
+            // Prune operates on every cached file, so it can target any artifact type — including the
+            // `section`/`index` children a page generates (e.g. to clear orphans left after a source is
+            // pruned with `--artifact-type source`).
+            description: 'filter pruning to specific artifact type',
+            options: ARTIFACT_TYPES,
         })(),
         'dry-run': Flags.boolean({
-            description: 'List files that would be deleted without actually deleting them.',
+            description: 'list files that would be deleted without actually deleting them',
             default: false,
         }),
         yes: Flags.boolean({
             char: 'y',
-            description: 'Skip confirmation prompt and prune files.',
+            description: 'confirm deletion and prune matched entries (required unless --dry-run)',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
     validatePruneFlags() {
         if (!this.flags['older-than'] && !this.flags.inactive && !this.flags['artifact-type']) {
-            this.error('Must specify at least one pruning filter: --older-than, --inactive, or --artifact-type.', { exit: 2 });
+            this.error('Must specify at least one pruning filter: --older-than, --inactive, or --artifact-type.', {
+                exit: 2,
+                code: 'MISSING_FILTER',
+                suggestions: [
+                    `Preview age-based pruning: ${this.config.bin} prune --older-than 90d --dry-run`,
+                ],
+            });
         }
         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 });
+            const olderThanPart = this.flags['older-than']
+                ? ` --older-than ${this.flags['older-than']}`
+                : '';
+            this.error('Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.', {
+                exit: 2,
+                code: 'SAFETY_CHECK_REQUIRED',
+                suggestions: [`Preview first: ${this.config.bin} prune --dry-run${olderThanPart}`],
+            });
         }
         // Validate durations up front: scanCacheDir swallows per-file errors, so a malformed
         // --older-than/--inactive would otherwise be silently ignored and report "0 entries".
@@ -56,7 +73,7 @@ export default class ResearchPrune extends BaseCommand {
             durationFlagError('--inactive', this.flags.inactive),
         ]) {
             if (msg)
-                this.error(msg, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
     shouldPrune(meta, currentTime) {
@@ -128,7 +145,7 @@ export default class ResearchPrune extends BaseCommand {
                 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'})`);
+                    this.log(`- [${f.topic || NO_TOPIC_LABEL}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
                 });
             }
         }

package/dist/commands/search.d.ts

@@ -3,6 +3,10 @@ export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
     static args: {
         query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/commands/search.js

@@ -1,11 +1,13 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Flags, ux } 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 { levenshtein, NO_TOPIC_LABEL, resultListHeading, truncationNotice, } from '../lib/text.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
+import { ARTIFACT_TYPES } from '../lib/research/schema.js';
 import { detectSite } from '../sites/index.js';
 import { fetchStaticHtml, fetchText, postJson } from '../lib/research/fetcher.js';
+import { normalizeUrl } from '../lib/research/url.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 = {
@@ -29,52 +31,66 @@ export default class ResearchSearch extends BaseCommand {
     static id = 'search';
     static summary = 'Search locally cached research artifacts by keywords.';
     static description = 'Scans the local research cache database and ranks matching entries based on topic, tags, source URLs, summary, and content.';
+    static examples = [
+        {
+            description: 'search for cached notes containing specific keywords',
+            command: '<%= config.bin %> <%= command.id %> "authentication flow"',
+        },
+        {
+            description: 'search with remote docs fallback',
+            command: '<%= config.bin %> <%= command.id %> "router" --remote https://react.dev',
+        },
+        {
+            description: 'search local cache with tag filtering',
+            command: '<%= config.bin %> <%= command.id %> "setup" --tags node --tags tutorial',
+        },
+    ];
     static args = {
         query: Args.string({
             required: true,
-            description: 'The search query containing terms to match.',
+            description: 'the search query containing terms to match',
         }),
     };
     static flags = {
         topic: Flags.string({
             char: 't',
-            description: 'Filter results by exact topic (case-insensitive).',
+            description: 'filter results by exact topic (case-insensitive)',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Filter results by tags (must match all tags specified).',
+            description: 'filter results by tags (must match all tags specified)',
             multiple: true,
         }),
         'artifact-type': Flags.option({
-            description: 'Filter results by artifact type.',
-            options: ['source', 'research_note', 'index', 'section'],
+            description: 'filter results by artifact type',
+            options: ARTIFACT_TYPES,
         })(),
         limit: Flags.integer({
-            description: 'Maximum number of results to return (default 10, max 50).',
+            description: 'maximum number of results to return (default 10, max 50)',
             default: 10,
         }),
         'include-stale': Flags.boolean({
-            description: 'Include stale expired cache entries in the search results.',
+            description: 'include stale expired cache entries in the search results',
             default: false,
         }),
         domain: Flags.string({
-            description: 'Search a documentation site directly (e.g. help.salesforce.com) instead of the local cache. Requires a site module that implements search.',
+            description: 'search a documentation site directly (requires compatible site module)',
         }),
         remote: Flags.string({
-            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.',
+            description: 'discover uncached docs via public search or index (falls back to local cache)',
         }),
     };
     static stdoutIsPrimaryData = true;
     validateSearchFlags() {
         const limit = this.flags.limit;
         if (limit !== undefined && (limit < 1 || limit > 50)) {
-            this.error('Limit must be between 1 and 50.', { exit: 2 });
+            this.error('Limit must be between 1 and 50.', { exit: 2, code: 'INVALID_LIMIT' });
         }
     }
     getSearchQueryTerms(query) {
         const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
         if (terms.length === 0) {
-            this.error('Query string cannot be empty.', { exit: 2 });
+            this.error('Query string cannot be empty.', { exit: 2, code: 'EMPTY_QUERY' });
         }
         return terms;
     }
@@ -194,11 +210,12 @@ export default class ResearchSearch extends BaseCommand {
             return;
         if (finalResults.length === 0) {
             this.log('No matching cached research entries found.');
+            this.log(`\nTip: populate the cache first: ${this.config.bin} <url>`);
             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(`${index + 1}. [${res.topic || NO_TOPIC_LABEL}] Score: ${res.score}`);
             this.log(`   Cache Key: ${res.cacheKey}`);
             this.log(`   Snippet: ${res.snippet}`);
             this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);
@@ -220,24 +237,47 @@ export default class ResearchSearch extends BaseCommand {
     async executeSiteSearch(query, domain) {
         const siteModule = detectSite(`https://${domain}`);
         if (!siteModule) {
-            this.error(`No site module registered for domain: ${domain}`, { exit: 2 });
+            this.error(`No site module registered for domain: ${domain}`, {
+                exit: 2,
+                code: 'UNSUPPORTED_DOMAIN',
+            });
         }
         if (!siteModule.search) {
-            this.error(`Site module '${siteModule.id}' does not implement search.`, { exit: 2 });
+            this.error(`Site module '${siteModule.id}' does not implement search.`, {
+                exit: 2,
+                code: 'SEARCH_NOT_SUPPORTED',
+            });
+        }
+        try {
+            if (!this.jsonEnabled())
+                ux.action.start(`Searching ${domain}`);
+            const results = await siteModule.search(query);
+            if (!this.jsonEnabled())
+                ux.action.stop();
+            this.printResults(`Found ${results.length} results from ${siteModule.name}:\n`, results);
+            return results.map((r) => ({ ...r, site_module_id: siteModule.id }));
+        }
+        catch (err) {
+            if (!this.jsonEnabled())
+                ux.action.stop('failed');
+            throw err;
         }
-        const results = await siteModule.search(query);
-        this.printResults(`Found ${results.length} results from ${siteModule.name}:\n`, results);
-        return results.map((r) => ({ ...r, site_module_id: siteModule.id }));
     }
     // Remote docs discovery. On any connector failure, degrade to local cache search with a warning
     // (T-20). Returns discovery results tagged remote: true so callers can tell them from cache hits.
     async executeRemoteSearch(query, docsUrl) {
         try {
+            if (!this.jsonEnabled())
+                ux.action.start(`Searching ${docsUrl}`);
             const { provider, results } = await runRemoteDocsSearch(docsUrl, query, REMOTE_SEARCH_DEPS);
+            if (!this.jsonEnabled())
+                ux.action.stop();
             this.printResults(`Found ${results.length} remote results via ${provider}:\n`, results);
             return results.map((r) => ({ ...r, remote: true }));
         }
         catch (err) {
+            if (!this.jsonEnabled())
+                ux.action.stop('failed');
             this.warn(`Remote docs search unavailable, using local cache: ${err.message}`);
             return undefined;
         }
@@ -245,14 +285,36 @@ export default class ResearchSearch extends BaseCommand {
     async run() {
         const { query } = this.args;
         const { domain, remote } = this.flags;
+        // Reject whitespace-only queries on every path (local, --domain, --remote).
+        this.getSearchQueryTerms(query);
+        if (domain && remote) {
+            this.error('--domain and --remote are mutually exclusive. Use one discovery mode at a time.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+                suggestions: [
+                    `Local site API: ${this.config.bin} search "${query}" --domain ${domain}`,
+                    `Remote index: ${this.config.bin} search "${query}" --remote ${remote}`,
+                ],
+            });
+        }
         if (domain) {
             return this.executeSiteSearch(query, domain);
         }
         if (remote) {
-            const remoteResults = await this.executeRemoteSearch(query, remote);
+            let normalizedRemote;
+            try {
+                normalizedRemote = normalizeUrl(remote);
+            }
+            catch (err) {
+                this.error(`Invalid --remote URL: ${err.message}`, {
+                    exit: 2,
+                    code: 'INVALID_URL',
+                });
+            }
+            const remoteResults = await this.executeRemoteSearch(query, normalizedRemote);
             if (remoteResults !== undefined)
                 return remoteResults;
-            // else: fall through to local cache search
+            // else: fall through to local cache search (connector/network failure only)
         }
         this.validateSearchFlags();
         const queryTerms = this.getSearchQueryTerms(query);

package/dist/commands/status.d.ts

@@ -3,6 +3,10 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -12,5 +16,7 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
+    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
     run(): Promise<unknown>;
 }

package/dist/commands/status.js

@@ -1,8 +1,8 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
+import { formatErrorForJson } from '../lib/envelope.js';
 import { getArtifactPath } from '../lib/research/storage.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;
     return isMaxAgeExpired
@@ -22,27 +22,52 @@ export default class ResearchStatus extends BaseCommand {
     static id = 'status';
     static summary = 'Check the cache status of a URL without fetching or writing.';
     static description = 'Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.';
+    static examples = [
+        {
+            description: 'check if a URL is already in the cache',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'check status against a specific freshness tier and TTL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
+        },
+    ];
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to check.',
+            description: 'the URL to check',
         }),
     };
     static flags = {
         tier: Flags.option({
-            description: 'Freshness tier policy to evaluate against.',
+            description: 'freshness tier policy to evaluate against',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Custom TTL duration to evaluate against (e.g. "2h", "7d").',
+            description: 'custom TTL duration to evaluate against (e.g. "2h", "7d")',
         }),
         'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g. "1d", "30d").',
+            description: 'maximum age of cache to accept (e.g. "1d", "30d")',
         }),
     };
     static stdoutIsPrimaryData = true;
+    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
+    toSuccessJson(data) {
+        const envelope = super.toSuccessJson(data);
+        const d = data;
+        if (d?.status !== 'miss')
+            return envelope;
+        const normalizedUrl = d.normalizedUrl ?? '';
+        const suggestions = [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`];
+        const stderr = formatErrorForJson({
+            message: `Cache miss for ${normalizedUrl}`,
+            code: 'CACHE_MISS',
+            suggestions,
+        });
+        return { ...envelope, ok: false, exitCode: 1, stderr, code: 'CACHE_MISS', suggestions };
+    }
     async run() {
         const { url } = this.args;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
@@ -50,20 +75,9 @@ export default class ResearchStatus extends BaseCommand {
         // 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({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                url,
-            });
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
+        const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
         const currentTime = new Date();
@@ -72,16 +86,28 @@ export default class ResearchStatus extends BaseCommand {
         // 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()) {
-            this.log(`URL: ${normalizedUrl}`);
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
-            this.log(`Status: ${result.status}`);
-            this.log(`Freshness: ${result.freshness}`);
-            this.log(`Action: ${result.action}`);
+            this.log(`${'URL:'.padEnd(25)} ${normalizedUrl}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Cache Path:'.padEnd(25)} ${artifactPath}`);
+            this.log(`${'Status:'.padEnd(25)} ${result.status}`);
+            this.log(`${'Freshness:'.padEnd(25)} ${result.freshness}`);
+            this.log(`${'Action:'.padEnd(25)} ${result.action}`);
+        }
+        // Align with inspect's CACHE_MISS contract: a miss is actionable, not a usage error. Exit 1
+        // lets scripts branch on $? while JSON still returns the structured status payload. Unlike
+        // inspect, we do not throw here — status must always return structured data even on a miss.
+        if (result.status === 'miss') {
+            // Human mode: actionable hint on stderr. JSON mode: same info lives in the envelope (see
+            // toSuccessJson) so agents get code/suggestions without parsing warn() line wraps.
+            if (!this.jsonEnabled()) {
+                this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
+            }
+            process.exitCode = 1;
         }
         return {
             cacheKey,
             cachePath: artifactPath,
+            normalizedUrl,
             status: result.status,
             freshness: result.freshness,
             action: result.action,

package/dist/commands.d.ts

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
@@ -17,6 +18,7 @@ export declare const commands: {
     prune: typeof PruneCommand;
     search: typeof SearchCommand;
     status: typeof StatusCommand;
+    config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;
     'config:list': typeof ConfigList;
     'config:set': typeof ConfigSet;

package/dist/commands.js

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
@@ -17,6 +18,7 @@ export const commands = {
     prune: PruneCommand,
     search: SearchCommand,
     status: StatusCommand,
+    config: ConfigIndex,
     'config:get': ConfigGet,
     'config:list': ConfigList,
     'config:set': ConfigSet,