@taurgis/bonsai 3.2.2 → 4.1.0

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>;
+}

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/status.js

@@ -32,6 +32,10 @@ export default class ResearchStatus extends BaseCommand {
             description: 'evaluate status with a specific tier and TTL',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
         },
+        {
+            description: 'check multiple URLs in one batch (space-separated)',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api',
+        },
     ];
     static strict = false;
     static args = {
@@ -83,6 +87,12 @@ export default class ResearchStatus extends BaseCommand {
             if (result.status === 'miss') {
                 this.warn(cacheMissHint(this.config.bin, normalizedUrl));
             }
+            else if (result.action === 'would_revalidate') {
+                this.tip(`${this.config.bin} ${normalizedUrl} to revalidate.`);
+            }
+            else {
+                this.tip(`${this.config.bin} inspect ${normalizedUrl} for full metadata.`);
+            }
         }
         return {
             cacheKey,

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/hooks/command-not-found/suggest.d.ts

@@ -1,5 +1,5 @@
 import { type Hook, type Interfaces } from '@oclif/core';
-export declare function buildCommandNotFoundDetails(id: string, argv: string[] | undefined, config: Interfaces.Config): {
+export declare function buildCommandNotFoundDetails(rawId: string, argv: string[] | undefined, config: Interfaces.Config): {
     code: 'COMMAND_NOT_FOUND' | 'MISSING_URL_SCHEME' | 'UNEXPECTED_ARGUMENT';
     command: string;
     jsonMode: boolean;

package/dist/hooks/command-not-found/suggest.js

@@ -1,5 +1,5 @@
 import { toConfiguredId } from '@oclif/core';
-import { closestMatch, maxFuzzyDistance } from '../../lib/text.js';
+import { closestMatch, maxFuzzyDistance, sanitizeForTerminal } from '../../lib/text.js';
 import { writeCommandNotFoundJson } from '../../lib/cli-emit.js';
 import { looksLikeSchemelessUrl } from '../../lib/research/url.js';
 /**
@@ -97,7 +97,17 @@ function missingUrlSchemeDetails(urls, argv, config) {
         suggestions: [suggestion],
     };
 }
-export function buildCommandNotFoundDetails(id, argv, config) {
+export function buildCommandNotFoundDetails(rawId, argv, config) {
+    // The attempted id is raw user input echoed straight back into this error's message and
+    // suggestions — untrusted per the repo's trust-boundary rules, same reasoning as
+    // BaseCommand.error(). Sanitize once, up front, so every derived value below (segments, the
+    // display-only "attempted" string, a bare-URL correction) is already safe; a real command/topic id
+    // never contains control bytes, so this only affects input that could never have matched one
+    // anyway. Gate on jsonMode exactly like BaseCommand.error() does, so `--json` keeps
+    // byte-for-byte fidelity — this hook fires before a Command instance exists, so there's no
+    // `jsonEnabled()` to call, but the same boolean is cheap to compute directly from argv.
+    const jsonMode = isJsonMode(argv);
+    const id = jsonMode ? rawId : sanitizeForTerminal(rawId);
     // Match against every loaded command id — including hidden ones that stay invokable
     // (`fetch`, plugin internals). Root `--help` hides them; typo recovery should not.
     const commandIds = config.commandIDs;

package/dist/lib/argv.d.ts

@@ -16,6 +16,11 @@ export interface NormalizationResult {
 export interface ArgvNormalizeOptions {
     /** Tokens that consume the next argv value (`--topic`, `-t`, …). From cli-flag-manifest. */
     valueTakingFlags: ReadonlySet<string>;
+    /**
+     * Root segment of every registered command id (`config:get` → `config`). From cli-flag-manifest.
+     * A `word:` token whose root is in this set is a command (`config:get`), never a URL scheme.
+     */
+    knownCommandRoots: ReadonlySet<string>;
 }
 /**
  * Normalize raw process argv for oclif. `valueTakingFlags` must come from the composition root

package/dist/lib/argv.js

@@ -1,5 +1,6 @@
 import { EXIT_USAGE } from './cli-error-policy.js';
 import { buildCliErrorEnvelope } from './envelope.js';
+import { sanitizeForTerminal } from './text.js';
 /** Shared MISSING_COMMAND copy for flag-only argv preflight. */
 function missingCommandDetails(bin, swallowed) {
     if (swallowed) {
@@ -26,7 +27,7 @@ function missingCommandDetails(bin, swallowed) {
  * it picks a command, so `bonsai --read-only list` would otherwise treat `--read-only` as the
  * command id. Strip and re-append them after the command/URL, same pattern as `--json`.
  */
-const GLOBAL_BOOLEAN_FLAGS = new Set(['--read-only', '--plan']);
+const GLOBAL_BOOLEAN_FLAGS = new Set(['--read-only', '--plan', '--toon']);
 /**
  * When a value-taking flag is the only "command" and its value looks like a URL, the user almost
  * certainly put the URL where the flag value belongs (e.g. `bonsai --tags https://example.com`).
@@ -47,7 +48,13 @@ function findSwallowedUrlFlag(argv, valueTakingFlags) {
     return null;
 }
 function missingUsageExit(json, argv, valueTakingFlags) {
-    const details = missingCommandDetails('bonsai', findSwallowedUrlFlag(argv, valueTakingFlags));
+    const swallowed = findSwallowedUrlFlag(argv, valueTakingFlags);
+    // `swallowed.url` is raw user input echoed straight back into the MISSING_COMMAND message and its
+    // "pass the URL as the command" suggestion — untrusted per the repo's trust-boundary rules, same
+    // reasoning as BaseCommand.error(). This preflight path fires before oclif ever dispatches a
+    // command, so there is no `this.jsonEnabled()` to call — but `json` is already known here, so gate
+    // on it the same way: sanitize only the human-mode message, keep `--json` byte-for-byte.
+    const details = missingCommandDetails('bonsai', swallowed && !json ? { ...swallowed, url: sanitizeForTerminal(swallowed.url) } : swallowed);
     return {
         exitCode: EXIT_USAGE,
         json,
@@ -86,7 +93,18 @@ function hasCommandToken(argv, valueTakingFlags) {
  * (`cli-flag-manifest`) — this module stays free of command registry imports.
  */
 export function normalizeArgv(rawArgv, options) {
-    const { valueTakingFlags } = options;
+    const { valueTakingFlags, knownCommandRoots } = options;
+    // AXI "content first": a truly bare invocation (`bonsai`, no args/flags at all) shows live cache
+    // data instead of oclif's default root help — `bonsai help`, `--help`, and `-h` remain the
+    // 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', '--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
     // "--json". Collect every --json, append one copy after the command/URL, and
@@ -113,8 +131,15 @@ export function normalizeArgv(rawArgv, options) {
     // forms like `javascript:` or `data:` so fetch can reject unsupported protocols instead of oclif
     // reporting a misleading "command not found". If the invocation begins with a flag, allow common
     // flag-before-argument usage such as `bonsai --format detailed https://example.com`.
+    // Exclude tokens whose part before the first `:` names a real command (`config:get`) — oclif
+    // joins namespaced command ids with `:` regardless of the display-only topicSeparator, so those
+    // are commands, not URL schemes, and must reach normal command dispatch instead of a misleading
+    // "Invalid URL" error.
     const firstNonFlagArgIndex = firstPositionalIndex(core, valueTakingFlags);
-    const rootFetchShape = firstNonFlagArgIndex !== -1 && looksLikeUrl(core[firstNonFlagArgIndex]);
+    const firstArg = firstNonFlagArgIndex !== -1 ? core[firstNonFlagArgIndex] : undefined;
+    const rootFetchShape = firstArg !== undefined &&
+        looksLikeUrl(firstArg) &&
+        !knownCommandRoots.has(firstArg.split(':')[0]);
     if (rootFetchShape) {
         const url = core[firstNonFlagArgIndex];
         core = [
@@ -131,7 +156,7 @@ export function normalizeArgv(rawArgv, options) {
         core.push('--json');
     // Flag-only argv (`--json`, `--read-only`, `--tags https://…`) never resolves a command.
     // Exit here so command_not_found does not special-case dash-prefixed ids.
-    // Empty argv and `--help`/`--version` stay with oclif.
+    // Truly empty argv already returned above; `--help`/`--version` stay with oclif here.
     if (!helpRequested && core.length > 0 && !hasCommandToken(core, valueTakingFlags)) {
         return {
             argv: jsonMode ? ['--json'] : [],

package/dist/lib/cli-flag-manifest.d.ts

@@ -3,3 +3,10 @@
  * Built from command class metadata so argv normalization stays free of command imports.
  */
 export declare const VALUE_TAKING_FLAG_TOKENS: ReadonlySet<string>;
+/**
+ * Root segment of every registered command id (`config:get` → `config`). oclif joins namespaced
+ * command ids with `:` regardless of the display-only `topicSeparator` setting, so a token like
+ * `config:get` is a real command, not a URL — argv normalization checks this set before assuming
+ * `word:` is a URL scheme.
+ */
+export declare const KNOWN_COMMAND_ROOT_TOKENS: ReadonlySet<string>;

package/dist/lib/cli-flag-manifest.js

@@ -6,3 +6,10 @@ import { valueTakingFlagTokensFromCommands } from './value-flags.js';
  * Built from command class metadata so argv normalization stays free of command imports.
  */
 export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromCommands(commands, BaseCommand.baseFlags);
+/**
+ * Root segment of every registered command id (`config:get` → `config`). oclif joins namespaced
+ * command ids with `:` regardless of the display-only `topicSeparator` setting, so a token like
+ * `config:get` is a real command, not a URL — argv normalization checks this set before assuming
+ * `word:` is a URL scheme.
+ */
+export const KNOWN_COMMAND_ROOT_TOKENS = new Set(Object.keys(commands).map((id) => id.split(':')[0]));