@taurgis/bonsai 4.0.0 → 4.1.0

package/dist/commands/context.js

@@ -0,0 +1,65 @@
+import { BaseCommand } from '../base-command.js';
+import { loadStoreRoots } from '../lib/research/store-roots.js';
+import { buildContextDashboard } from '../lib/research/context-dashboard.js';
+import { NO_TOPIC_LABEL, formatTip, pluralize, sanitizeForTerminal } from '../lib/text.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand {
+    static id = 'context';
+    static summary = 'Show a compact cache dashboard for ambient session context';
+    static description = 'Print a short summary of the current research cache: total entries, a freshness ' +
+        'breakdown, and the most recently touched pages. This is what `bonsai setup` wires into a ' +
+        "SessionStart hook, so a session starts with the cache's state already visible.";
+    static examples = [
+        {
+            description: 'preview what a SessionStart hook would show',
+            command: '<%= config.bin %> context',
+        },
+        {
+            description: 'get the dashboard as JSON',
+            command: '<%= config.bin %> context --json',
+        },
+    ];
+    static stdoutIsPrimaryData = true;
+    logDashboard(dashboard) {
+        if (this.jsonEnabled())
+            return;
+        if (dashboard.total === 0) {
+            this.log(`${this.config.bin} cache: 0 entries found.`);
+            this.log(formatTip(`populate the cache: ${colors.cyan(`${this.config.bin} <url>`)}`));
+            return;
+        }
+        const { fresh, stale_grace: staleGrace, stale_expired: staleExpired } = dashboard.byFreshness;
+        this.log(`${this.config.bin} cache: ${dashboard.total} ${pluralize(dashboard.total, 'entry', 'entries')} ` +
+            `(${fresh} fresh, ${staleGrace} stale_grace, ${staleExpired} stale_expired)`);
+        for (const entry of dashboard.entries) {
+            const topicStr = entry.topic
+                ? colors.cyan(sanitizeForTerminal(entry.topic))
+                : colors.gray(NO_TOPIC_LABEL);
+            const freshnessStr = FRESHNESS_COLOR[entry.freshness](entry.freshness);
+            const url = entry.sourceUrls[0] ?? '';
+            this.log(`- [${topicStr}] ${freshnessStr} — ${colors.gray(url)}`);
+        }
+        if (dashboard.total > dashboard.shown) {
+            this.log(formatTip(`see all ${dashboard.total} entries: ${colors.cyan(`${this.config.bin} list`)}`));
+        }
+        this.log(formatTip(`research a new page: ${colors.cyan(`${this.config.bin} <url>`)}`));
+    }
+    async run() {
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const dashboard = buildContextDashboard(roots.readRoots, new Date(), {
+            persistIndex: !this.readOnly,
+        });
+        this.logDashboard(dashboard);
+        return dashboard;
+    }
+}

package/dist/commands/list.d.ts

@@ -16,19 +16,28 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         command: string;
     }[];
     static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        identity: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;
         url: 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" | "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>;
-        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    private metadataFilterFlags;
     private matchesFilters;
     private scanCacheDirForList;
-    private hasActiveFilters;
+    /**
+     * Identity header for the AXI "home view" (bare `bonsai`, no args): the tool's own bin path and
+     * one-sentence description, shown before the live data so an agent orients on what it's looking
+     * at without a separate `--help` round trip. Human mode only — the hidden `--identity` flag is
+     * only ever set by the argv rewrite for a bare invocation; it is not documented for direct use.
+     */
+    private logIdentityHeader;
     private logListResults;
     /**
      * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with

package/dist/commands/list.js

@@ -1,24 +1,28 @@
 import { Flags } from '@oclif/core';
+import { homedir } from 'node:os';
 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, formatTip, resultListHeading, sanitizeForTerminal, } from '../lib/text.js';
+import { collapseHomeDir, formatTip, resultListHeading, } from '../lib/text.js';
 import { limitFlag } from '../lib/limit-flag.js';
-import { artifactMatchesUrlFilter, emptyUrlFilterError } from '../lib/research/url.js';
-import { matchesTopicFilter, matchesTagsFilter, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
-import { colors } from '../lib/color.js';
-import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+import { countByFreshness, toListRow } from '../lib/research/list-row.js';
+import { emptyUrlFilterError } from '../lib/research/url.js';
+import { matchesCommonMetadataFilters, hasActiveMetadataFilters, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
+import { commonMetadataFilterFlags } from '../lib/common-metadata-filter-flags.js';
+import { buildNextLimitCommand } from '../lib/next-command.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS, formatResultRowHeader, formatResultRowSourceUrls, formatResultRowTokens, } from '../lib/cli-presentation.js';
 // Listings are ordered newest-first, so the truncation word is "first"; --limit caps at this value.
 const LIST_DEFAULT_MAX_LIMIT = 100;
+// A small default keeps an unfiltered `list` from flooding an agent's context with everything ever
+// cached; `summary.truncated`/`nextCommand` (and the human-mode tip) make raising --limit an
+// explicit, deliberate next step rather than a silent, unbounded dump.
+const LIST_DEFAULT_LIMIT = 10;
 const LIST_LABELS = {
     noun: 'cached research',
     order: 'first',
 };
-// `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');
 /** Project a full row down to the default minimal shape (see {@link ListRowMinimal}). */
 function toMinimalListRow(row) {
     return {
@@ -28,13 +32,6 @@ function toMinimalListRow(row) {
         tokenEstimate: row.tokenEstimate,
     };
 }
-/** Count matched rows per freshness tier for the envelope's `summary.byFreshness`. */
-function countByFreshness(rows) {
-    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
-    for (const row of rows)
-        counts[row.freshness]++;
-    return counts;
-}
 /** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand {
     static id = 'list';
@@ -70,57 +67,30 @@ export default class ResearchList extends BaseCommand {
         },
     ];
     static flags = {
-        topic: Flags.string({
-            char: 't',
-            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: CLI_FLAG_DESCRIPTIONS.filterTags,
-            multiple: true,
-        }),
-        url: Flags.string({
-            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
-        }),
-        freshness: Flags.option({
-            description: 'freshness state',
-            options: ['fresh', 'stale_grace', 'stale_expired'],
-        })(),
-        'artifact-type': Flags.option({
-            description: CLI_FLAG_DESCRIPTIONS.listArtifactType,
-            options: LISTABLE_ARTIFACT_TYPES,
-        })(),
-        'capture-method': Flags.option({
-            description: 'capture method',
-            options: CAPTURE_METHODS,
-        })(),
-        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, 50, `result count (max ${LIST_DEFAULT_MAX_LIMIT})`),
+        ...commonMetadataFilterFlags(CLI_FLAG_DESCRIPTIONS.listArtifactType),
+        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, LIST_DEFAULT_LIMIT, `result count (max ${LIST_DEFAULT_MAX_LIMIT}, default ${LIST_DEFAULT_LIMIT})`),
         full: Flags.boolean({
             default: false,
             description: CLI_FLAG_DESCRIPTIONS.listFull,
         }),
+        // Only ever set by the argv rewrite for a truly bare `bonsai` invocation (see normalizeArgv);
+        // hidden because it is not documented or intended for direct use.
+        identity: Flags.boolean({ default: false, hidden: true }),
     };
     static stdoutIsPrimaryData = true;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    metadataFilterFlags() {
+        return {
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            url: this.flags.url,
+            artifactType: this.flags['artifact-type'],
+            captureMethod: this.flags['capture-method'],
+            freshness: this.flags.freshness,
+        };
+    }
     matchesFilters(meta, freshness) {
-        if (!matchesTopicFilter(meta, this.flags.topic)) {
-            return false;
-        }
-        if (!matchesTagsFilter(meta, this.flags.tags)) {
-            return false;
-        }
-        if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
-            return false;
-        }
-        if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
-            return false;
-        }
-        if (this.flags['capture-method'] && meta.capture_method !== this.flags['capture-method']) {
-            return false;
-        }
-        if (this.flags.freshness && freshness !== this.flags.freshness) {
-            return false;
-        }
-        return true;
+        return matchesCommonMetadataFilters(meta, freshness, this.metadataFilterFlags());
     }
     scanCacheDirForList(readRoots, currentTime) {
         // Honor effective read-only: listing must not persist the derived search-index sidecar.
@@ -131,38 +101,30 @@ export default class ResearchList extends BaseCommand {
             // listing (one page yields dozens) and aren't in the documented source/research_note contract.
             // They stay discoverable through `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
+            // PAGE_LEVEL_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;
-            return {
-                cacheKey: artifact.metadata.cache_key,
-                path: filePath,
-                artifactType: artifact.metadata.artifact_type,
-                sourceUrls: artifact.metadata.source_urls,
-                topic: artifact.metadata.topic,
-                tags: artifact.metadata.tags,
-                freshness,
-                captureMethod: artifact.metadata.capture_method,
-                tokenEstimate: artifact.metadata.token_estimate,
-                qualityNotes: artifact.metadata.quality_notes,
-                fetchedAt: artifact.metadata.fetched_at,
-                validatedAt: artifact.metadata.validated_at,
-            };
+            return toListRow(artifact, filePath, freshness);
         }, { persistIndex: !this.readOnly });
     }
-    hasActiveFilters() {
-        return Boolean(this.flags.topic ||
-            (this.flags.tags && this.flags.tags.length > 0) ||
-            this.flags.freshness ||
-            this.flags['artifact-type'] ||
-            this.flags['capture-method'] ||
-            this.flags.url);
+    /**
+     * Identity header for the AXI "home view" (bare `bonsai`, no args): the tool's own bin path and
+     * one-sentence description, shown before the live data so an agent orients on what it's looking
+     * at without a separate `--help` round trip. Human mode only — the hidden `--identity` flag is
+     * only ever set by the argv rewrite for a bare invocation; it is not documented for direct use.
+     */
+    logIdentityHeader() {
+        if (!this.flags.identity || this.jsonEnabled())
+            return;
+        const binPath = collapseHomeDir(process.argv[1] ?? this.config.bin, homedir());
+        this.log(`bin: ${binPath}`);
+        this.log(`description: ${this.config.pjson.description ?? this.config.bin}\n`);
     }
-    logListResults(finalResults, totalMatched) {
+    logListResults(finalResults, totalMatched, nextCommand) {
         if (finalResults.length === 0) {
             this.emitEmptyListGuidance();
             return;
@@ -171,22 +133,13 @@ export default class ResearchList extends BaseCommand {
             return;
         this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
-            const topicStr = res.topic
-                ? colors.cyan(sanitizeForTerminal(res.topic))
-                : colors.gray(NO_TOPIC_LABEL);
-            const keyStr = colors.bold(res.cacheKey);
-            this.log(`${index + 1}. [${topicStr}] Key: ${keyStr}`);
-            const freshnessColorMap = {
-                fresh: colors.green,
-                stale_grace: colors.yellow,
-                stale_expired: colors.red,
-            };
-            const freshnessColor = freshnessColorMap[res.freshness];
-            const freshnessStr = freshnessColor(res.freshness);
+            this.log(formatResultRowHeader(index, res.topic, res.cacheKey));
+            const freshnessStr = FRESHNESS_COLOR[res.freshness](res.freshness);
             this.log(`   Type: ${colors.bold(res.artifactType)} | Freshness: ${freshnessStr}`);
-            this.log(`   Tokens: compressed=${colors.bold(String(res.tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(res.tokenEstimate?.detailed || 0))}`);
-            this.log(`   Source URLs: ${colors.gray(res.sourceUrls.join(', '))}\n`);
+            this.log(formatResultRowTokens(res.tokenEstimate));
+            this.log(formatResultRowSourceUrls(res.sourceUrls));
         });
+        this.tipNextCommand(nextCommand);
     }
     /**
      * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
@@ -195,7 +148,7 @@ export default class ResearchList extends BaseCommand {
     emitEmptyListGuidance() {
         if (this.jsonEnabled())
             return;
-        const filtered = this.hasActiveFilters();
+        const filtered = hasActiveMetadataFilters(this.metadataFilterFlags());
         const headline = filtered
             ? 'No cached research entries match the given filters.'
             : 'No cached research entries found.';
@@ -217,6 +170,7 @@ export default class ResearchList extends BaseCommand {
             emptyTagsFilterError(this.flags.tags);
         if (flagErr)
             this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
+        this.logIdentityHeader();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -230,17 +184,24 @@ export default class ResearchList extends BaseCommand {
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
+        const truncated = results.length > finalResults.length;
+        // Suggest exactly enough to see every match, capped at the command's own max — a caller who
+        // truncated at the default can raise --limit once and be done, rather than guessing a value.
+        const nextCommand = truncated
+            ? buildNextLimitCommand(this.config.bin, 'list', this.argv, Math.min(results.length, LIST_DEFAULT_MAX_LIMIT))
+            : null;
         // Human heading carries truncation inline; --json/--toon get the same counts (plus a freshness
         // breakdown and an explicit `empty` flag) as an always-present envelope `summary` object.
         this.jsonSummary = {
             total: results.length,
             shown: finalResults.length,
             limit: this.flags.limit,
-            truncated: results.length > finalResults.length,
+            truncated,
             empty: results.length === 0,
             byFreshness: countByFreshness(results),
+            nextCommand,
         };
-        this.logListResults(finalResults, results.length);
+        this.logListResults(finalResults, results.length, nextCommand);
         return this.flags.full ? finalResults : finalResults.map(toMinimalListRow);
     }
     /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */

package/dist/commands/search.d.ts

@@ -0,0 +1,43 @@
+import { BaseCommand } from '../base-command.js';
+import type { SearchRow, SearchRowMinimal } from '../lib/cli-result-types.js';
+/** Search cached research artifacts by tag/content keywords and metadata filters. */
+export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    /** Aggregate counts (and an explicit empty/truncation signal); see `list.ts`'s equivalent. */
+    private jsonSummary;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
+        url: 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" | "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>;
+        query: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'match-any': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    private metadataFilterFlags;
+    private matchesMetadataFilters;
+    private scanCacheDirForSearch;
+    /** Newest-first (no query) or highest-score-first (query given), both tie-broken by cache key. */
+    private sortResults;
+    private hasActiveFilters;
+    private logSearchResults;
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    private emitEmptySearchGuidance;
+    run(): Promise<SearchRow[] | SearchRowMinimal[]>;
+    /** Attach the aggregate `summary` computed in `run()` (see {@link SearchSummary}). */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
+}

package/dist/commands/search.js

@@ -0,0 +1,233 @@
+import { Flags } from '@oclif/core';
+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 { formatTip, resultListHeading, sanitizeForTerminal, } from '../lib/text.js';
+import { limitFlag } from '../lib/limit-flag.js';
+import { countByFreshness, toListRow } from '../lib/research/list-row.js';
+import { emptyUrlFilterError } from '../lib/research/url.js';
+import { matchesCommonMetadataFilters, hasActiveMetadataFilters, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
+import { commonMetadataFilterFlags } from '../lib/common-metadata-filter-flags.js';
+import { buildNextLimitCommand } from '../lib/next-command.js';
+import { tokenizeSearchQuery, emptySearchQueryError, scoreSearchMatch, extractSearchSnippet, } from '../lib/research/search-match.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS, formatResultRowHeader, formatResultRowSourceUrls, formatResultRowTokens, } from '../lib/cli-presentation.js';
+const SEARCH_DEFAULT_MAX_LIMIT = 100;
+// A small default (matching `list`'s) keeps a broad query from flooding an agent's context;
+// `summary.truncated`/`nextCommand` (and the human-mode tip) make raising --limit an explicit,
+// deliberate next step rather than a silent, unbounded dump.
+const SEARCH_DEFAULT_LIMIT = 10;
+const NO_MATCH_SCORE = { score: 0, matchedFields: [] };
+/** Project a full row down to the default minimal shape (see {@link SearchRowMinimal}). */
+function toMinimalSearchRow(row) {
+    return {
+        sourceUrls: row.sourceUrls,
+        topic: row.topic,
+        freshness: row.freshness,
+        tokenEstimate: row.tokenEstimate,
+        score: row.score,
+        matchedFields: row.matchedFields,
+        snippet: row.snippet,
+    };
+}
+/** Search cached research artifacts by tag/content keywords and metadata filters. */
+export default class ResearchSearch extends BaseCommand {
+    static id = 'search';
+    static summary = 'Search cached research artifacts by tags and content';
+    static description = 'Rank cached page-level artifacts by a --query matched against topic, tags, summary, and ' +
+        'compressed content, plus the same metadata filters as `list` (topic, tags, URL, freshness, ' +
+        'artifact type, capture method). Reads only the token-cheap indexed summary/compressed text, ' +
+        'never the full detailed body, so ranking a large cache stays fast. Pass --full for every ' +
+        'metadata field.';
+    /** Aggregate counts (and an explicit empty/truncation signal); see `list.ts`'s equivalent. */
+    jsonSummary = null;
+    static examples = [
+        {
+            description: 'search content and tags for a keyword',
+            command: '<%= config.bin %> search --query "suspense boundary"',
+        },
+        {
+            description: 'match any of several terms instead of requiring all',
+            command: '<%= config.bin %> search --query "suspense streaming" --match-any',
+        },
+        {
+            description: 'combine a query with metadata filters',
+            command: '<%= config.bin %> search --query cache --tags react --freshness fresh',
+        },
+        {
+            description: 'filter by tags/topic alone, ranked like list (no --query)',
+            command: '<%= config.bin %> search --tags node --json',
+        },
+    ];
+    static flags = {
+        query: Flags.string({
+            char: 'q',
+            description: CLI_FLAG_DESCRIPTIONS.searchQuery,
+        }),
+        'match-any': Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.searchMatchAny,
+        }),
+        ...commonMetadataFilterFlags(CLI_FLAG_DESCRIPTIONS.searchArtifactType),
+        limit: limitFlag(SEARCH_DEFAULT_MAX_LIMIT, SEARCH_DEFAULT_LIMIT, `result count (max ${SEARCH_DEFAULT_MAX_LIMIT}, default ${SEARCH_DEFAULT_LIMIT})`),
+        full: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.searchFull,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    metadataFilterFlags() {
+        return {
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            url: this.flags.url,
+            artifactType: this.flags['artifact-type'],
+            captureMethod: this.flags['capture-method'],
+            freshness: this.flags.freshness,
+        };
+    }
+    matchesMetadataFilters(meta, freshness) {
+        return matchesCommonMetadataFilters(meta, freshness, this.metadataFilterFlags());
+    }
+    scanCacheDirForSearch(readRoots, currentTime, terms) {
+        const matchAny = this.flags['match-any'];
+        // Honor effective read-only: searching must not persist the derived search-index sidecar.
+        return scanCacheDirs(readRoots, (artifact, filePath) => {
+            if (artifact.metadata.status !== 'active')
+                return null;
+            // Page-level only, same reasoning as `list`: sections are sub-chunks of a page, not
+            // artifacts a user "has" — find them via `inspect` instead.
+            if (artifact.metadata.artifact_type === 'section')
+                return null;
+            const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
+            if (!this.matchesMetadataFilters(artifact.metadata, freshness))
+                return null;
+            let match = NO_MATCH_SCORE;
+            let snippet = null;
+            if (terms.length > 0) {
+                const scored = scoreSearchMatch({
+                    topic: artifact.metadata.topic,
+                    tags: artifact.metadata.tags,
+                    summary: artifact.summary,
+                    compressed: artifact.compressed,
+                }, terms, matchAny);
+                if (!scored)
+                    return null;
+                match = scored;
+                snippet = extractSearchSnippet({ summary: artifact.summary, compressed: artifact.compressed }, terms);
+            }
+            return {
+                ...toListRow(artifact, filePath, freshness),
+                score: match.score,
+                matchedFields: match.matchedFields,
+                snippet,
+            };
+        }, { persistIndex: !this.readOnly });
+    }
+    /** Newest-first (no query) or highest-score-first (query given), both tie-broken by cache key. */
+    sortResults(results, queried) {
+        results.sort((a, b) => {
+            if (queried && b.score !== a.score)
+                return b.score - a.score;
+            const timeA = new Date(a.validatedAt || a.fetchedAt || 0).getTime();
+            const timeB = new Date(b.validatedAt || b.fetchedAt || 0).getTime();
+            if (timeB !== timeA)
+                return timeB - timeA;
+            return a.cacheKey.localeCompare(b.cacheKey);
+        });
+    }
+    hasActiveFilters() {
+        return Boolean(this.flags.query) || hasActiveMetadataFilters(this.metadataFilterFlags());
+    }
+    logSearchResults(finalResults, totalMatched, queried, nextCommand) {
+        if (finalResults.length === 0) {
+            this.emitEmptySearchGuidance();
+            return;
+        }
+        if (this.jsonEnabled())
+            return;
+        const labels = queried
+            ? { noun: 'matching cached research', order: 'top' }
+            : { noun: 'cached research', order: 'first' };
+        this.log(`${resultListHeading(totalMatched, finalResults.length, labels)}\n`);
+        finalResults.forEach((res, index) => {
+            this.log(formatResultRowHeader(index, res.topic, res.cacheKey));
+            const freshnessStr = FRESHNESS_COLOR[res.freshness](res.freshness);
+            const scoreStr = queried ? ` | Score: ${colors.bold(String(res.score))}` : '';
+            this.log(`   Type: ${colors.bold(res.artifactType)} | Freshness: ${freshnessStr}${scoreStr}`);
+            if (queried && res.matchedFields.length > 0) {
+                this.log(`   Matched: ${colors.gray(res.matchedFields.join(', '))}`);
+            }
+            if (res.snippet) {
+                this.log(`   Snippet: ${colors.gray(sanitizeForTerminal(res.snippet))}`);
+            }
+            this.log(formatResultRowTokens(res.tokenEstimate));
+            this.log(formatResultRowSourceUrls(res.sourceUrls));
+        });
+        this.tipNextCommand(nextCommand);
+    }
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    emitEmptySearchGuidance() {
+        if (this.jsonEnabled())
+            return;
+        const filtered = this.hasActiveFilters();
+        const headline = filtered
+            ? 'No cached research entries match the given search.'
+            : 'No cached research entries found.';
+        const tipCmd = filtered ? `${this.config.bin} search` : `${this.config.bin} <url>`;
+        const tipLead = filtered
+            ? 'try a broader --query, --match-any, or relax other filters: '
+            : 'populate the cache first: ';
+        this.log(headline);
+        this.log(`\n${formatTip(`${tipLead}${colors.cyan(tipCmd)}`)}`);
+    }
+    async run() {
+        const flagErr = emptyUrlFilterError(this.flags.url) ??
+            emptyTopicFilterError(this.flags.topic) ??
+            emptyTagsFilterError(this.flags.tags) ??
+            emptySearchQueryError(this.flags.query);
+        if (flagErr)
+            this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const currentTime = new Date();
+        const terms = this.flags.query ? tokenizeSearchQuery(this.flags.query) : [];
+        const queried = terms.length > 0;
+        const results = this.scanCacheDirForSearch(roots.readRoots, currentTime, terms);
+        this.sortResults(results, queried);
+        const finalResults = results.slice(0, this.flags.limit);
+        const truncated = results.length > finalResults.length;
+        // Suggest exactly enough to see every match, capped at the command's own max — a caller who
+        // truncated at the default can raise --limit once and be done, rather than guessing a value.
+        const nextCommand = truncated
+            ? buildNextLimitCommand(this.config.bin, 'search', this.argv, Math.min(results.length, SEARCH_DEFAULT_MAX_LIMIT))
+            : null;
+        this.jsonSummary = {
+            total: results.length,
+            shown: finalResults.length,
+            limit: this.flags.limit,
+            truncated,
+            empty: results.length === 0,
+            byFreshness: countByFreshness(results),
+            queried,
+            nextCommand,
+        };
+        this.logSearchResults(finalResults, results.length, queried, nextCommand);
+        return this.flags.full ? finalResults : finalResults.map(toMinimalSearchRow);
+    }
+    /** Attach the aggregate `summary` computed in `run()` (see {@link SearchSummary}). */
+    toSuccessJson(data) {
+        const envelope = this.baseSuccessJson(data);
+        if (!this.jsonSummary)
+            return envelope;
+        return { ...envelope, summary: this.jsonSummary };
+    }
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../base-command.js';
+import type { SetupResult } from '../lib/cli-result-types.js';
+/**
+ * Installs (or repairs) a `SessionStart` hook that runs `bonsai context` at the start of every
+ * agent session, so the cache's current state is visible before the agent takes any action (AXI
+ * principle 7: ambient context via session integrations).
+ */
+export default class Setup extends BaseCommand<typeof Setup> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        agent: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    private assertKnownAgent;
+    run(): Promise<SetupResult>;
+}