@taurgis/bonsai 4.0.0 → 4.1.0

package/dist/commands/setup.js

@@ -0,0 +1,148 @@
+import { Args, Flags } from '@oclif/core';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { BaseCommand } from '../base-command.js';
+import { atomicWriteFile } from '../lib/atomic-write.js';
+import { resolveBinCommand } from '../lib/setup/bin-command.js';
+import { SETUP_AGENTS, SETUP_AGENT_TARGETS, SETUP_HOOK_COMMAND_SUFFIX, SETUP_HOOK_MANAGED_BY, } from '../lib/setup/agents.js';
+import { InvalidHookFileError, planSessionStartHookInstall, } from '../lib/setup/hook-file-io.js';
+import { closestMatch, maxFuzzyDistance } from '../lib/text.js';
+import { assertScopeFlagsExclusive, scopeFlags } from '../lib/scope-flags.js';
+function isSetupAgent(value) {
+    return SETUP_AGENTS.includes(value);
+}
+/**
+ * Nearest known agent for a typo'd `agentArg`, or `null` if nothing plausible matches. Checks a
+ * prefix relationship first (either direction) so a short, valid-looking typo like `claude` for
+ * `claude-code` is caught even though its edit distance to the full name exceeds the general
+ * Levenshtein threshold; falls back to edit distance for closer misspellings like `codexx`.
+ */
+function suggestAgent(agentArg) {
+    const prefixMatch = SETUP_AGENTS.find((agent) => agent.startsWith(agentArg) || agentArg.startsWith(agent));
+    if (prefixMatch)
+        return prefixMatch;
+    // closestMatch's candidates are exactly SETUP_AGENTS, so any non-null result is a SetupAgent.
+    return closestMatch(agentArg, SETUP_AGENTS, maxFuzzyDistance(agentArg));
+}
+/** Maps a plan outcome to the reported status, remapping write outcomes to `would_*` under dry-run. */
+function reportSetupStatus(planStatus, dryRun) {
+    if (!dryRun)
+        return planStatus;
+    if (planStatus === 'unchanged')
+        return 'unchanged';
+    return planStatus === 'repaired' ? 'would_repair' : 'would_install';
+}
+const SETUP_STATUS_LABEL = {
+    installed: 'Installed',
+    repaired: 'Repaired',
+    unchanged: 'Already up to date:',
+    would_install: '[dry-run] Would install',
+    would_repair: '[dry-run] Would repair',
+};
+/**
+ * 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 {
+    static id = 'setup';
+    static summary = 'Install a SessionStart hook that shows live cache context';
+    static description = 'Writes (or repairs) a SessionStart hook entry that runs `bonsai context` at the start of ' +
+        'every session, so the agent sees the cache state before doing anything. Project-scoped by ' +
+        'default (shareable via version control); pass --global for a user-level, machine-only install. ' +
+        'Re-running is idempotent: an unchanged install is a no-op, and a stale executable path is repaired.';
+    static examples = [
+        {
+            description: 'install the hook for this project (Claude Code)',
+            command: '<%= config.bin %> setup claude-code',
+        },
+        {
+            description: 'install the hook for this project (Codex)',
+            command: '<%= config.bin %> setup codex',
+        },
+        {
+            description: 'preview a user-level install without writing anything',
+            command: '<%= config.bin %> setup claude-code --global --dry-run --json',
+        },
+    ];
+    static args = {
+        agent: Args.string({
+            required: true,
+            description: `agent to install the hook for (${SETUP_AGENTS.join(', ')})`,
+        }),
+    };
+    static flags = {
+        ...scopeFlags({
+            global: 'install to the user-level config instead of the project (default: project)',
+            local: 'install to the project config (default; explicit form of the default)',
+        }),
+        'dry-run': Flags.boolean({
+            description: 'preview the install without writing anything',
+            default: false,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    assertKnownAgent(agentArg) {
+        if (isSetupAgent(agentArg))
+            return;
+        if (agentArg === 'opencode') {
+            this.error('OpenCode is not supported by `setup` yet: its plugin hook signature for injecting ' +
+                "session-start context isn't confirmed in official docs, so Bonsai won't guess at one. " +
+                'See the "Ambient session context" docs for status.', { exit: 2, code: 'UNKNOWN_AGENT', suggestions: [`Use one of: ${SETUP_AGENTS.join(', ')}`] });
+        }
+        const suggestion = suggestAgent(agentArg);
+        const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+        this.error(`Unknown agent: "${agentArg}".${hint} Supported agents: ${SETUP_AGENTS.join(', ')}.`, {
+            exit: 2,
+            code: 'UNKNOWN_AGENT',
+            suggestions: suggestion
+                ? [`Use "${suggestion}": ${this.config.bin} setup ${suggestion}`]
+                : [`Use one of: ${SETUP_AGENTS.join(', ')}`],
+        });
+    }
+    async run() {
+        const agentArg = this.args.agent;
+        this.assertKnownAgent(agentArg);
+        assertScopeFlagsExclusive(this.error.bind(this), this.flags.global, this.flags.local);
+        const target = SETUP_AGENT_TARGETS[agentArg];
+        const scope = this.flags.global ? 'user' : 'project';
+        const root = scope === 'user' ? homedir() : process.cwd();
+        const path = join(root, target.relativePath);
+        const binCommand = resolveBinCommand(process.argv[1] ?? this.config.bin);
+        const command = `${binCommand} ${SETUP_HOOK_COMMAND_SUFFIX}`;
+        const existingContent = existsSync(path) ? readFileSync(path, 'utf-8') : null;
+        let plan;
+        try {
+            plan = planSessionStartHookInstall(existingContent, {
+                eventName: target.eventName,
+                matcher: target.matcher,
+                command,
+                timeout: target.timeout,
+                managedBy: SETUP_HOOK_MANAGED_BY,
+            });
+        }
+        catch (err) {
+            if (err instanceof InvalidHookFileError) {
+                this.error(`Cannot install into ${path}: ${err.message}.`, {
+                    exit: 1,
+                    code: 'INVALID_HOOK_FILE',
+                    suggestions: [
+                        'Fix or remove the existing file so it contains a single JSON object, then re-run setup.',
+                    ],
+                });
+            }
+            throw err;
+        }
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        const status = reportSetupStatus(plan.status, dryRun);
+        if (!dryRun && plan.status !== 'unchanged') {
+            mkdirSync(dirname(path), { recursive: true });
+            atomicWriteFile(path, plan.content);
+        }
+        if (!this.jsonEnabled()) {
+            this.log(`${SETUP_STATUS_LABEL[status]} ${agentArg} SessionStart hook at ${path} (${scope})`);
+        }
+        return { agent: agentArg, scope, path, binCommand, status, dryRun };
+    }
+}

package/dist/commands.d.ts

@@ -3,18 +3,24 @@ 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';
+import ContextCommand from './commands/context.js';
 import FetchCommand from './commands/fetch.js';
 import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import SetupCommand from './commands/setup.js';
 import StatusCommand from './commands/status.js';
 export declare const commands: {
+    context: typeof ContextCommand;
     fetch: typeof FetchCommand;
     import: typeof ImportCommand;
     inspect: typeof InspectCommand;
     list: typeof ListCommand;
     prune: typeof PruneCommand;
+    search: typeof SearchCommand;
+    setup: typeof SetupCommand;
     status: typeof StatusCommand;
     config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;

package/dist/commands.js

@@ -3,18 +3,24 @@ 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';
+import ContextCommand from './commands/context.js';
 import FetchCommand from './commands/fetch.js';
 import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import SetupCommand from './commands/setup.js';
 import StatusCommand from './commands/status.js';
 export const commands = {
+    context: ContextCommand,
     fetch: FetchCommand,
     import: ImportCommand,
     inspect: InspectCommand,
     list: ListCommand,
     prune: PruneCommand,
+    search: SearchCommand,
+    setup: SetupCommand,
     status: StatusCommand,
     config: ConfigIndex,
     'config:get': ConfigGet,

package/dist/lib/argv.js

@@ -99,8 +99,11 @@ export function normalizeArgv(rawArgv, options) {
     // explicit path to the command reference (all of them are non-empty argv and skip this branch).
     // oclif has no built-in "default command" concept for empty argv (see oclif/oclif#277), so this
     // is a one-line argv rewrite, the same technique the URL-shorthand rewrite below already uses.
+    // The hidden `--identity` flag (AXI principle 10) tells `list` to also identify the tool (bin
+    // path, one-sentence description) before the live data — only the true bare invocation gets it,
+    // not an explicit `bonsai list`.
     if (rawArgv.length === 0) {
-        return { argv: ['list'] };
+        return { argv: ['list', '--identity'] };
     }
     // oclif's JSON flag is command-scoped, so `bonsai list --json` works but
     // `bonsai --json list` is otherwise parsed as an unknown command named

package/dist/lib/cli-presentation.d.ts

@@ -1,3 +1,4 @@
+import type { TokenEstimate } from './research/schema.js';
 /** Shared flag/help copy so identical flags read identically across commands. */
 export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly freshnessTierPolicy: "freshness tier policy";
@@ -21,6 +22,10 @@ export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly listArtifactType: "artifact type; section children are omitted from list - use inspect to see them";
     readonly pruneArtifactType: "artifact type to prune, including section children";
     readonly listFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)";
+    readonly searchQuery: "keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set";
+    readonly searchMatchAny: "match any query term instead of requiring all of them (OR instead of AND)";
+    readonly searchArtifactType: "artifact type; section children are omitted from search - use inspect to see them";
+    readonly searchFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)";
 };
 /** One human-readable label/value pair for CLI stdout. */
 export type HumanField = readonly [label: string, value: string];
@@ -39,3 +44,17 @@ export declare function formatHumanField(label: string, value: string): string;
  * @returns Formatted lines in the same order.
  */
 export declare function formatHumanFields(fields: readonly HumanField[]): string[];
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export declare function formatResultRowHeader(index: number, topic: string | null, cacheKey: string): string;
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowTokens(tokenEstimate: TokenEstimate): string;
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowSourceUrls(sourceUrls: readonly string[]): string;

package/dist/lib/cli-presentation.js

@@ -1,5 +1,6 @@
 import { colors } from './color.js';
 import { MAX_TAG_LENGTH, MAX_TOPIC_LENGTH } from './research/metadata-flags.js';
+import { NO_TOPIC_LABEL, sanitizeForTerminal } from './text.js';
 const HUMAN_LABEL_WIDTH = 25;
 // Repeated verbatim across several flag descriptions; single-use wording lives inline below.
 const DURATION_EXAMPLES = 'e.g. "2h", "7d", "6m"';
@@ -27,6 +28,10 @@ export const CLI_FLAG_DESCRIPTIONS = {
     listArtifactType: 'artifact type; section children are omitted from list - use inspect to see them',
     pruneArtifactType: 'artifact type to prune, including section children',
     listFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)',
+    searchQuery: 'keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set',
+    searchMatchAny: 'match any query term instead of requiring all of them (OR instead of AND)',
+    searchArtifactType: 'artifact type; section children are omitted from search - use inspect to see them',
+    searchFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)',
 };
 function formatHumanLabel(label) {
     const text = `${label}:`;
@@ -51,3 +56,25 @@ export function formatHumanField(label, value) {
 export function formatHumanFields(fields) {
     return fields.map(([label, value]) => formatHumanField(label, value));
 }
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export function formatResultRowHeader(index, topic, cacheKey) {
+    const topicStr = topic ? colors.cyan(sanitizeForTerminal(topic)) : colors.gray(NO_TOPIC_LABEL);
+    const keyStr = colors.bold(cacheKey);
+    return `${index + 1}. [${topicStr}] Key: ${keyStr}`;
+}
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowTokens(tokenEstimate) {
+    return `   Tokens: compressed=${colors.bold(String(tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(tokenEstimate?.detailed || 0))}`;
+}
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowSourceUrls(sourceUrls) {
+    return `   Source URLs: ${colors.gray(sourceUrls.join(', '))}\n`;
+}

package/dist/lib/cli-result-types.d.ts

@@ -1,5 +1,6 @@
 /** Shared machine-facing write/result shapes for CLI JSON envelopes. */
 import type { ArtifactType, CaptureMethod, ResearchArtifactMetadata, TokenEstimate } from './research/schema.js';
+import type { SearchMatchField } from './research/search-match.js';
 /** Result of `config set` / `config unset` for the JSON envelope. */
 export interface ConfigWriteResult {
     key: string;
@@ -71,6 +72,36 @@ export interface ListSummary {
     /** Explicit signal for `total === 0`, so an empty `data: []` is never ambiguous. */
     empty: boolean;
     byFreshness: Record<ListFreshness, number>;
+    /**
+     * A copy-pasteable next invocation that reproduces the caller's own filters with a raised
+     * `--limit`, so a truncated result never leaves an agent to guess the syntax for "show me more."
+     * `null` when `truncated` is false.
+     */
+    nextCommand: string | null;
+}
+/** One row in `search --json` output when `--full` is passed. */
+export interface SearchRow extends ListRow {
+    /** Relevance score (0 when `--query` was omitted); see `search-match.ts` for the weighting. */
+    score: number;
+    /** Fields the query matched against; empty when `--query` was omitted. */
+    matchedFields: SearchMatchField[];
+    /** Excerpt around the first content match, or `null` when only topic/tags matched (or no query). */
+    snippet: string | null;
+}
+/**
+ * Default `search --json`/`--toon` row: enough to judge relevance (score, which fields matched, a
+ * short content excerpt) without the full metadata dump. Pass `--full` for every field on
+ * {@link SearchRow}.
+ */
+export interface SearchRowMinimal extends ListRowMinimal {
+    score: number;
+    matchedFields: SearchMatchField[];
+    snippet: string | null;
+}
+/** Aggregate counts attached to `search`'s envelope so agents skip extra round trips. */
+export interface SearchSummary extends ListSummary {
+    /** Whether `--query` was passed; when false every row scores 0 and results are recency-sorted. */
+    queried: boolean;
 }
 /** Section child summary nested under an inspect hit. */
 export interface InspectSectionRow {
@@ -110,3 +141,31 @@ export interface StatusRow {
     freshness: FreshnessState;
     action: 'would_fetch' | 'would_revalidate' | 'would_return_cached';
 }
+/** One entry in the `context` dashboard's recency-ordered preview. */
+export interface ContextDashboardEntry {
+    topic: string | null;
+    sourceUrls: string[];
+    freshness: ListFreshness;
+}
+/**
+ * Directory-scoped cache summary for `context` (AXI principle 7: ambient session-start context).
+ * `entries` is capped to a small preview; `total`/`byFreshness` always cover every matched
+ * artifact so the cap never hides the true count.
+ */
+export interface ContextDashboard {
+    total: number;
+    byFreshness: Record<ListFreshness, number>;
+    shown: number;
+    entries: ContextDashboardEntry[];
+}
+/** Agents `setup` knows how to install a SessionStart hook for. */
+export type SetupAgent = 'claude-code' | 'codex';
+/** Result of `setup <agent>` for the JSON envelope. */
+export interface SetupResult {
+    agent: SetupAgent;
+    scope: 'user' | 'project';
+    path: string;
+    binCommand: string;
+    status: 'installed' | 'repaired' | 'unchanged' | 'would_install' | 'would_repair';
+    dryRun: boolean;
+}

package/dist/lib/color.d.ts

@@ -18,3 +18,5 @@ export declare const colors: {
     gray: (t: string) => string;
     magenta: (t: string) => string;
 };
+/** Shared fresh/stale_grace/stale_expired → color mapping for `list` and `context`'s human output. */
+export declare const FRESHNESS_COLOR: Record<'fresh' | 'stale_grace' | 'stale_expired', (t: string) => string>;

package/dist/lib/color.js

@@ -34,3 +34,9 @@ export const colors = {
     gray: (t) => color(t, '\x1b[90m'),
     magenta: (t) => color(t, '\x1b[35m'),
 };
+/** Shared fresh/stale_grace/stale_expired → color mapping for `list` and `context`'s human output. */
+export const FRESHNESS_COLOR = {
+    fresh: colors.green,
+    stale_grace: colors.yellow,
+    stale_expired: colors.red,
+};

package/dist/lib/common-metadata-filter-flags.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Metadata filter flags shared by `list` and `search` (topic/tags/url/freshness/artifact
+ * type/capture method) — single source of truth so the two commands' flag definitions can never
+ * drift apart. `artifactTypeDescription` is the one piece that differs: each command names itself
+ * in its own `--artifact-type` help text (`list`/`search` currently, via `CLI_FLAG_DESCRIPTIONS`).
+ */
+export declare function commonMetadataFilterFlags(artifactTypeDescription: string): {
+    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>;
+};

package/dist/lib/common-metadata-filter-flags.js

@@ -0,0 +1,37 @@
+import { Flags } from '@oclif/core';
+import { CLI_FLAG_DESCRIPTIONS } from './cli-presentation.js';
+import { CAPTURE_METHODS, PAGE_LEVEL_ARTIFACT_TYPES } from './research/schema.js';
+/**
+ * Metadata filter flags shared by `list` and `search` (topic/tags/url/freshness/artifact
+ * type/capture method) — single source of truth so the two commands' flag definitions can never
+ * drift apart. `artifactTypeDescription` is the one piece that differs: each command names itself
+ * in its own `--artifact-type` help text (`list`/`search` currently, via `CLI_FLAG_DESCRIPTIONS`).
+ */
+export function commonMetadataFilterFlags(artifactTypeDescription) {
+    return {
+        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: artifactTypeDescription,
+            options: PAGE_LEVEL_ARTIFACT_TYPES,
+        })(),
+        'capture-method': Flags.option({
+            description: 'capture method',
+            options: CAPTURE_METHODS,
+        })(),
+    };
+}

package/dist/lib/next-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds a suggested next CLI invocation for a truncated `list`/`search` result — a copy-pasteable
+ * command that reproduces the caller's own filters with a raised `--limit`, so the caller never has
+ * to guess the syntax for "show me more." Surfaced as `summary.nextCommand` in the JSON/TOON
+ * envelope and as a human-mode tip.
+ */
+/**
+ * @param bin - The CLI's own binary name (`this.config.bin`).
+ * @param commandId - The command to suggest (`list` or `search`).
+ * @param argv - The current invocation's raw argv (`this.argv`), reused as-is so the suggestion can
+ *   never drift from whatever filters/flags the caller actually passed.
+ * @param newLimit - The `--limit` value to suggest.
+ * @returns A copy-pasteable shell command string.
+ */
+export declare function buildNextLimitCommand(bin: string, commandId: string, argv: readonly string[], newLimit: number): string;

package/dist/lib/next-command.js

@@ -0,0 +1,40 @@
+/**
+ * Builds a suggested next CLI invocation for a truncated `list`/`search` result — a copy-pasteable
+ * command that reproduces the caller's own filters with a raised `--limit`, so the caller never has
+ * to guess the syntax for "show me more." Surfaced as `summary.nextCommand` in the JSON/TOON
+ * envelope and as a human-mode tip.
+ */
+// Never valid to suggest back to a caller: `--limit` is being replaced by the new value, and
+// `--identity` is a hidden, undocumented flag only ever injected by the bare-invocation argv
+// rewrite (see argv.ts) — carrying it into a suggested command would leak an internal detail.
+const DROPPED_FLAGS = new Set(['--limit', '--identity']);
+// Tokens made only of these characters are safe to print bare in a shell command; anything else
+// (spaces, quotes, glob patterns like `*`) is double-quoted so the suggestion stays copy-pasteable.
+const SAFE_BARE_TOKEN = /^[A-Za-z0-9_@%+.:,/-]+$/;
+function quoteShellArgIfNeeded(token) {
+    if (SAFE_BARE_TOKEN.test(token))
+        return token;
+    return `"${token.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+/**
+ * @param bin - The CLI's own binary name (`this.config.bin`).
+ * @param commandId - The command to suggest (`list` or `search`).
+ * @param argv - The current invocation's raw argv (`this.argv`), reused as-is so the suggestion can
+ *   never drift from whatever filters/flags the caller actually passed.
+ * @param newLimit - The `--limit` value to suggest.
+ * @returns A copy-pasteable shell command string.
+ */
+export function buildNextLimitCommand(bin, commandId, argv, newLimit) {
+    const kept = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--limit') {
+            i++; // also drop its value
+            continue;
+        }
+        if (token.startsWith('--limit=') || DROPPED_FLAGS.has(token))
+            continue;
+        kept.push(quoteShellArgIfNeeded(token));
+    }
+    return [bin, commandId, ...kept, '--limit', String(newLimit)].join(' ');
+}

package/dist/lib/research/context-dashboard.d.ts

@@ -0,0 +1,19 @@
+import type { ContextDashboard } from '../cli-result-types.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export declare const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export declare function buildContextDashboard(readRoots: string[], currentTime: Date, options?: {
+    limit?: number;
+    persistIndex?: boolean;
+}): ContextDashboard;

package/dist/lib/research/context-dashboard.js

@@ -0,0 +1,43 @@
+import { scanCacheDirs } from './storage.js';
+import { evaluateFreshness } from './freshness.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export function buildContextDashboard(readRoots, currentTime, options = {}) {
+    const limit = options.limit ?? CONTEXT_DASHBOARD_DEFAULT_LIMIT;
+    const rows = scanCacheDirs(readRoots, (artifact) => {
+        if (artifact.metadata.status !== 'active')
+            return null;
+        // Section children are sub-chunks of a page, not something a dashboard should list on its
+        // own — same exclusion `list` applies (see list.ts's scanCacheDirForList).
+        if (artifact.metadata.artifact_type === 'section')
+            return null;
+        return {
+            topic: artifact.metadata.topic,
+            sourceUrls: artifact.metadata.source_urls,
+            freshness: evaluateFreshness(artifact.metadata, currentTime, null),
+            recencyKey: artifact.metadata.validated_at ?? artifact.metadata.fetched_at ?? null,
+        };
+    }, { persistIndex: options.persistIndex ?? true });
+    rows.sort((a, b) => new Date(b.recencyKey ?? 0).getTime() - new Date(a.recencyKey ?? 0).getTime());
+    const byFreshness = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        byFreshness[row.freshness]++;
+    const entries = rows.slice(0, limit).map((row) => ({
+        topic: row.topic,
+        sourceUrls: row.sourceUrls,
+        freshness: row.freshness,
+    }));
+    return { total: rows.length, byFreshness, shown: entries.length, entries };
+}

package/dist/lib/research/fetch-command-service.js

@@ -343,6 +343,16 @@ function logHumanFetchResult(input) {
         io.warn(`${normalizedUrl}: ${warning}`);
     }
     io.log(resultData.content);
+    // AXI content-truncation: only nudge toward the escape hatch when something was actually
+    // condensed — `detailedTokenEstimate` equals `tokenEstimate` whenever `format` is already
+    // `detailed`, or when compression happened to produce no smaller result.
+    if (resultData.format === 'compressed' &&
+        typeof resultData.tokenEstimate === 'number' &&
+        typeof resultData.detailedTokenEstimate === 'number' &&
+        resultData.detailedTokenEstimate > resultData.tokenEstimate) {
+        io.warn(formatTip(`${io.bin} ${normalizedUrl} --format detailed for the full ${resultData.detailedTokenEstimate}-token ` +
+            `version (currently showing ${resultData.tokenEstimate}).`));
+    }
     if (!dryRun) {
         io.warn(formatTip(`${io.bin} inspect ${normalizedUrl} for cached metadata.`));
     }

package/dist/lib/research/fetch-result.d.ts

@@ -57,6 +57,7 @@ export declare function buildFetchResultData(input: FetchResultInput): {
     searchProvider: string | null;
     format: "compressed" | "detailed";
     tokenEstimate: number | null;
+    detailedTokenEstimate: number | null;
     content: string;
 };
 export interface FetchFailureGuidance {

package/dist/lib/research/fetch-result.js

@@ -75,6 +75,10 @@ export function buildFetchResultData(input) {
         tokenEstimate: format === 'compressed'
             ? artifact.metadata.token_estimate.compressed
             : artifact.metadata.token_estimate.detailed,
+        // Always the true detailed count, even when `format` is `compressed` (AXI content-truncation
+        // principle: show the total size so the agent knows how much a `--format detailed` re-fetch
+        // would add, without a second round trip). Equals `tokenEstimate` when nothing was truncated.
+        detailedTokenEstimate: artifact.metadata.token_estimate.detailed,
         content,
     };
 }

package/dist/lib/research/list-row.d.ts

@@ -0,0 +1,15 @@
+import type { ListFreshness, ListRow } from '../cli-result-types.js';
+import type { ResearchArtifact } from './schema.js';
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export declare function toListRow(artifact: ResearchArtifact, filePath: string, freshness: ListRow['freshness']): ListRow;
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export declare function countByFreshness(rows: readonly {
+    freshness: ListFreshness;
+}[]): Record<ListFreshness, number>;

package/dist/lib/research/list-row.js

@@ -0,0 +1,31 @@
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export function toListRow(artifact, filePath, freshness) {
+    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,
+    };
+}
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export function countByFreshness(rows) {
+    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        counts[row.freshness]++;
+    return counts;
+}