@taurgis/bonsai 1.0.4 → 1.0.6

package/dist/commands/inspect.js

@@ -1,49 +1,54 @@
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
 export default class ResearchInspect extends BaseCommand {
     static id = 'inspect';
     static summary = 'Inspect cached research metadata for a URL.';
     static description = 'Inspects local storage and displays full frontmatter metadata for the URL (without printing the content body).';
+    static examples = [
+        {
+            description: 'inspect cached research metadata for a specific URL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'output the full metadata as JSON for use by other tools',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
+        },
+    ];
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to inspect.',
+            description: 'the URL to inspect',
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const { url } = this.args;
-        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 });
-        }
+        const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         if (!located) {
-            this.error(`No cached research found for URL: ${normalizedUrl}`, { exit: 1 });
+            // inspect makes no network call, so the bare message reads like the network-failure case the
+            // exit-1 contract describes. Point at the fix instead: fetch the page so it lands in the cache.
+            this.error(`No cached research found for URL: ${normalizedUrl}`, {
+                exit: 1,
+                code: 'CACHE_MISS',
+                suggestions: [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`],
+            });
         }
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Cache Path:'.padEnd(25)} ${artifactPath}`);
             this.log(`--- Metadata ---`);
             for (const [key, val] of Object.entries(cached.metadata)) {
+                const paddedKey = (key + ':').padEnd(Math.max(25, key.length + 2));
                 if (typeof val === 'object' && val !== null) {
-                    this.log(`${key}: ${JSON.stringify(val)}`);
+                    this.log(`${paddedKey} ${JSON.stringify(val)}`);
                 }
                 else {
-                    this.log(`${key}: ${val}`);
+                    this.log(`${paddedKey} ${val}`);
                 }
             }
             if (sections.length) {

package/dist/commands/list.d.ts

@@ -11,8 +11,8 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         freshness: import("@oclif/core/interfaces").OptionFlag<"fresh" | "stale_grace" | "stale_expired" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | "route_markdown" | "github_source" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;

package/dist/commands/list.js

@@ -3,48 +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 { 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,
         }),
     };
@@ -52,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) {
@@ -82,6 +89,15 @@ 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. 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);
             if (!this.matchesFilters(artifact.metadata, freshness))
                 return null;
@@ -101,16 +117,17 @@ 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.');
+            this.log(`\nTip: populate the cache first: ${this.config.bin} <url>`);
             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(`${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`);
@@ -132,7 +149,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.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

@@ -4,49 +4,76 @@ 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 { 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".
+        for (const msg of [
+            durationFlagError('--older-than', this.flags['older-than']),
+            durationFlagError('--inactive', this.flags.inactive),
+        ]) {
+            if (msg)
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
     shouldPrune(meta, currentTime) {
@@ -109,24 +136,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'})`);
+                    this.log(`- [${f.topic || NO_TOPIC_LABEL}] 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.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,20 @@
-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, 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 = {
+    noun: 'matching cached research',
+    order: 'top',
+    maxLimit: 50,
+};
 const REMOTE_SEARCH_DEPS = {
     fetchStatic: async (url) => {
         const res = await fetchStaticHtml(url);
@@ -22,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 (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 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;
     }
@@ -182,12 +205,17 @@ 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.');
+            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`);
@@ -209,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;
         }
@@ -234,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);
@@ -254,7 +327,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 +384,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.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>;
 }