@taurgis/bonsai 1.0.5 → 3.0.0

package/README.md

@@ -20,7 +20,7 @@ The package is published as `@taurgis/bonsai` and installs a `bonsai` binary.
 | **Freshness tiers** | Supports `stable`, `standard`, `volatile`, custom TTLs, and stale revalidation | Handling standards differently from release notes or beta docs |
 | **Browser fallback** | Uses `--rendered` for pages that need client-side JavaScript | Capturing SPA documentation when static HTML is incomplete |
 | **Manual import** | Stores agent-supplied Markdown from stdin or files | Caching synthesized notes, private docs, or manually extracted pages |
-| **Search** | Ranks local cache entries by topic, tags, snippets, fuzzy terms, and phrases | Finding existing research before fetching again |
+| **List** | Filters cached entries by topic, tags, freshness, and metadata | Seeing what is already cached without reading full content |
 
 ---
 
@@ -82,10 +82,10 @@ echo "# My Custom Node API Notes" | npx @taurgis/bonsai import https://nodejs.or
 echo "# Synthesized React Cache Guide" | npx @taurgis/bonsai import --stdin --topic "React Suspense" --source-url https://react.dev/a --source-url https://react.dev/b
 ```
 
-### 5. Search before fetching
+### 5. List cached entries
 
 ```bash
-npx @taurgis/bonsai search "node api url"
+npx @taurgis/bonsai list --tags node
 ```
 
 ---
@@ -138,14 +138,6 @@ Display stored YAML frontmatter metadata for a URL.
 npx @taurgis/bonsai inspect <url>
 ```
 
-### `search <query>`
-
-Search cached research by metadata and content snippets.
-
-```bash
-npx @taurgis/bonsai search "<keywords>" [flags]
-```
-
 ### `list`
 
 List cached artifacts by metadata filters (`--topic`, `--tags`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content.
@@ -156,7 +148,7 @@ npx @taurgis/bonsai list [flags]
 
 ### `prune`
 
-Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, or `--artifact-type`) and either `--dry-run` or `--yes`.
+Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, or `--url`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error).
 
 ```bash
 npx @taurgis/bonsai prune --older-than 90d --dry-run
@@ -180,6 +172,35 @@ Both keys can also be overridden per-invocation via the `BONSAI_STORAGE` and `BO
 
 ---
 
+## Shell Autocomplete
+
+Bonsai ships with shell autocomplete via `@oclif/plugin-autocomplete`. After installing globally, set it up once for your shell:
+
+```bash
+# Bash — add to ~/.bashrc
+eval "$(bonsai autocomplete bash)"
+
+# Zsh — add to ~/.zshrc
+eval "$(bonsai autocomplete zsh)"
+
+# Fish
+bonsai autocomplete fish > ~/.config/fish/completions/bonsai.fish
+```
+
+To see full setup instructions including the copy-paste snippet for your shell:
+
+```bash
+bonsai autocomplete
+```
+
+Refresh cached completions after upgrading:
+
+```bash
+bonsai autocomplete --refresh-cache
+```
+
+---
+
 ## Freshness and Cache Rules
 
 Global cache files live in Bonsai's oclif data directory, typically:
@@ -246,6 +267,32 @@ When run with `--json`, commands return a stable envelope:
 
 ---
 
+## Environment Variables
+
+| Variable | Effect |
+| --- | --- |
+| `BONSAI_STORAGE` | Override the default storage location per-invocation (`global` or `project`). |
+| `BONSAI_SUMMARY` | Override the summary compression level per-invocation (`conservative`, `balanced`, or `aggressive`). |
+| `NO_COLOR` | Set to any non-empty value to disable all ANSI color output. An empty `NO_COLOR` is treated as unset. |
+| `FORCE_COLOR` | Set to any value other than an empty string, `0`, or `false` to force ANSI color on, even in non-TTY environments. |
+| `TERM=dumb` | Disables ANSI color output when the terminal cannot render escape sequences. |
+| `NO_UPDATE_NOTIFIER` | Suppress the "update available" notification. |
+| `CI` | Set to `1` or `true` to suppress the update notification in CI environments (detected automatically). |
+| `DEBUG` | Enable debug output for specific Bonsai namespaces, e.g. `DEBUG=bonsai:*`. |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Runtime failure (network error, fetch failed, file read error). |
+| `2` | Usage error (invalid flag, bad URL, missing required argument). |
+| `5` | Stale content served — the cache entry is past its grace window but `--allow-stale` is set. The returned content is still usable. |
+
+---
+
 ## Security and Limits
 
 * Fetched HTML is treated as untrusted input.

package/agents/agents/official-docs-researcher.agent.md

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What topic should I research in official docs?'
 metadata:
-  version: '3.0.0'
+  version: '4.0.0'
 ---
 
 # Official Docs Researcher Agent
@@ -18,45 +18,34 @@ Use this agent for technical changes, platform behavior, APIs, SDKs, standards,
 
 Do not research from memory alone. Training-data knowledge does not satisfy this workflow.
 
-## Default Workflow
+## Invocation
 
-1. Identify the product, version, edition, and source authority needed for the request.
-2. Search the Bonsai cache first:
+Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
 
-   ```bash
-   bonsai search "<topic or keywords>"
-   ```
+## Default Workflow
 
-3. If the cache misses or does not cover the question, locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes.
-4. Capture each source through Bonsai:
+1. Identify the product, version, edition, and source authority needed for the request.
+2. Locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes. Use your native web/search tools when you do not yet know the URL.
+3. Capture each source through Bonsai:
 
    ```bash
-   bonsai <official-url> --format detailed
+   npx @taurgis/bonsai <official-url> --format detailed
    ```
 
-5. Use `--rendered` for SPAs or pages where static extraction is incomplete:
+4. Use `--rendered` for SPAs or pages where static extraction is incomplete:
 
    ```bash
-   bonsai <official-url> --rendered --format detailed
+   npx @taurgis/bonsai <official-url> --rendered --format detailed
    ```
 
-6. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
+5. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
 
-Inside the Bonsai repository, use the development binary instead of an installed global command:
+For structured output:
 
 ```bash
-node bin/cli.mjs search "<topic or keywords>" --json
-node bin/cli.mjs <official-url> --format detailed --json
+npx @taurgis/bonsai <official-url> --format detailed --json
 ```
 
-For one-shot published usage outside this repo, use the scoped package name:
-
-```bash
-npx @taurgis/bonsai <official-url> --format detailed
-```
-
-Do not document or run bare `npx bonsai` unless an unscoped npm shim is actually published.
-
 ## Freshness Policy
 
 Choose the freshness tier based on the source:
@@ -72,13 +61,13 @@ Stale volatile sources must be revalidated before they are trusted. Never overwr
 If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
 
 ```bash
-bonsai import <url> --file <path>
+npx @taurgis/bonsai import <url> --file <path>
 ```
 
 For multi-source synthesis:
 
 ```bash
-bonsai import \
+npx @taurgis/bonsai import \
   --topic "<descriptive topic>" \
   --source-url <url1> \
   --source-url <url2> \

package/agents/agents/salesforce-docs-researcher.agent.md

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What Salesforce topic should I research in official docs?'
 metadata:
-  version: '1.0.0'
+  version: '2.0.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -18,61 +18,43 @@ Use this agent for technical changes, platform behavior, APIs, SDKs, standards,
 
 Do not research from memory alone. Training-data knowledge does not satisfy this workflow.
 
-## Default Workflow
+## Invocation
 
-1. Identify the product, version, edition, and source authority needed for the request.
-2. Search the Bonsai cache first:
+Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
 
-   ```bash
-   bonsai search "<topic or keywords>"
-   ```
+## Default Workflow
 
-3. If the cache misses or does not cover the question, locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes.
-4. Capture each source through Bonsai:
+1. Identify the product, version, edition, and source authority needed for the request.
+2. Locate official Salesforce source URLs. Use your native web/search tools when you do not yet know the URL.
+3. Capture each source through Bonsai:
 
    ```bash
-   bonsai <official-url> --format detailed
+   npx @taurgis/bonsai <official-url> --format detailed
    ```
 
-5. Use `--rendered` for SPAs or pages where static extraction is incomplete:
+4. Use `--rendered` for SPAs or pages where static extraction is incomplete:
 
    ```bash
-   bonsai <official-url> --rendered --format detailed
+   npx @taurgis/bonsai <official-url> --rendered --format detailed
    ```
 
-6. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
+5. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
 
-Inside the Bonsai repository, use the development binary instead of an installed global command:
+For structured output:
 
 ```bash
-node bin/cli.mjs search "<topic or keywords>" --json
-node bin/cli.mjs <official-url> --format detailed --json
+npx @taurgis/bonsai <official-url> --format detailed --json
 ```
 
-For one-shot published usage outside this repo, use the scoped package name:
-
-```bash
-npx @taurgis/bonsai <official-url> --format detailed
-```
-
-Do not document or run bare `npx bonsai` unless an unscoped npm shim is actually published.
-
 ## Working with Salesforce Sites
 
 Salesforce Help and Developer docs are Lightning Web Runtime (LWR) pages: the article text is rendered by JavaScript, so a plain fetch returns an almost-empty shell. Bonsai ships a per-host **site module** that forces browser rendering and runs Salesforce-specific extraction, so a normal Bonsai fetch already returns clean Markdown for these hosts — you do not need to add `--rendered` yourself.
 
 | Host | Module | Capabilities |
 | --- | --- | --- |
-| `help.salesforce.com` | `salesforce` (Salesforce Help) | Rendered fetch and live `--domain` search (Coveo backend) |
-| `developer.salesforce.com` | `salesforce-developer` (Salesforce Developer) | Rendered fetch only — no search |
-
-- **Search Help live.** For Help topics where you do not yet have a URL, search Salesforce's own backend instead of guessing:
-
-  ```bash
-  npx @taurgis/bonsai search "single sign-on" --domain help.salesforce.com
-  ```
+| `help.salesforce.com` | `salesforce` (Salesforce Help) | Rendered fetch |
+| `developer.salesforce.com` | `salesforce-developer` (Salesforce Developer) | Rendered fetch |
 
-  Results come straight from Coveo and are validated against an allow-list of Salesforce documentation hosts. There is no `--domain` search for `developer.salesforce.com`; passing it exits with an error, so find Developer URLs another way, then fetch them through Bonsai.
 - **Matching is by exact hostname.** `help.salesforce.com` matches; subdomains do not. Prefer canonical `/s/articleView?id=…` Help URLs; Bonsai normalizes legacy `/help_doccontent?id=…` links to them automatically.
 - **Revalidation re-fetches in full.** Module-fetched pages have no cheap `ETag`/`If-Modified-Since` shortcut, so refreshing a stale Salesforce page does a full re-render. `siteModuleId` in the JSON output confirms which module captured a page.
 
@@ -91,13 +73,13 @@ Stale volatile sources must be revalidated before they are trusted. Never overwr
 If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
 
 ```bash
-bonsai import <url> --file <path>
+npx @taurgis/bonsai import <url> --file <path>
 ```
 
 For multi-source synthesis:
 
 ```bash
-bonsai import \
+npx @taurgis/bonsai import \
   --topic "<descriptive topic>" \
   --source-url <url1> \
   --source-url <url2> \

package/agents/hooks/README.md

@@ -12,7 +12,7 @@ differs.
 The hooks deny native URL-fetch tools and return model-visible guidance like:
 
 ```bash
-bonsai https://example.com/docs --format detailed
+npx @taurgis/bonsai https://example.com/docs --format detailed
 ```
 
 Most hook systems cannot transparently replace a web-fetch tool call with a shell
@@ -48,15 +48,8 @@ that tells the agent to prefer Bonsai for URLs.
 
 ## Published Command
 
-The examples use `bonsai` on the assumption that the CLI is installed. For
-one-shot usage, tell agents to run:
+Run Bonsai through the published npm package:
 
 ```bash
 npx @taurgis/bonsai <url> --format detailed
 ```
-
-Inside the Bonsai repository, use the development binary:
-
-```bash
-node bin/cli.mjs <url> --format detailed
-```

package/agents/hooks/claude-code/hooks/bonsai-web-fetch.sh

@@ -9,7 +9,7 @@ const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
 const raw = JSON.stringify(input.tool_input ?? input);
 const match = raw.match(/https?:\/\/[^\s"'\''<>)}\]]+/);
 const url = match ? match[0] : "<url>";
-const command = `bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed`;
 const reason =
   `Use Bonsai instead of the native web fetch so the result is cached and reusable. Run: ${command}`;
 process.stdout.write(JSON.stringify({

package/agents/hooks/codex/hooks/bonsai-user-prompt-context.sh

@@ -12,7 +12,7 @@ process.stdout.write(JSON.stringify({
   hookSpecificOutput: {
     hookEventName: "UserPromptSubmit",
     additionalContext:
-      "When fetching documentation or URL content for this prompt, use Bonsai first: bonsai <url> --format detailed. Use --rendered only when static extraction is incomplete."
+      "When fetching documentation or URL content for this prompt, use Bonsai first: npx @taurgis/bonsai <url> --format detailed. Use --rendered only when static extraction is incomplete."
   }
 }) + "\n");
 ' <<< "$input"

package/agents/hooks/codex/hooks/bonsai-web-fetch.sh

@@ -9,7 +9,7 @@ const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
 const raw = JSON.stringify(input.tool_input ?? input);
 const match = raw.match(/https?:\/\/[^\s"'\''<>)}\]]+/);
 const url = match ? match[0] : "<url>";
-const command = `bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed`;
 const reason =
   `Use Bonsai instead of this URL-fetch tool so the result is cached and reusable. Run: ${command}`;
 process.stdout.write(JSON.stringify({

package/agents/hooks/cursor/hooks/bonsai-web-fetch.sh

@@ -9,7 +9,7 @@ const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
 const raw = JSON.stringify(input.tool_input ?? input.toolArgs ?? input);
 const match = raw.match(/https?:\/\/[^\s"'\''<>)}\]]+/);
 const url = match ? match[0] : "<url>";
-const command = `bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed`;
 const message =
   `Use Bonsai instead of the native URL fetch so the result is cached and reusable. Run: ${command}`;
 process.stdout.write(JSON.stringify({

package/agents/hooks/github-copilot/bonsai-web-fetch.sh

@@ -9,7 +9,7 @@ const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
 const raw = JSON.stringify(input.toolArgs ?? input.tool_input ?? input);
 const match = raw.match(/https?:\/\/[^\s"'\''<>)}\]]+/);
 const url = match ? match[0] : "<url>";
-const command = `bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed`;
 const reason =
   `Use Bonsai instead of web_fetch so the result is cached and reusable. Run: ${command}`;
 process.stdout.write(JSON.stringify({

package/agents/instructions/salesforce-research.instructions.md

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '1.0.1'
+  version: '2.0.0'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -24,7 +24,9 @@ metadata:
 
 ## Shared Cache
 
-- Both paths use the same freshness-tiered Bonsai cache (data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss.
+- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`.
+- **URL discovery**: When you do not yet know the official URL, discover it with your native web/search tools, then fetch the page through Bonsai so it is cached for future agents.
+- **Browse cached entries**: Use `npx @taurgis/bonsai list` when you need to see what is already cached by topic, tags, or freshness.
 - If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
 - Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
 
@@ -32,13 +34,12 @@ metadata:
 
 Salesforce Help and Developer docs are JavaScript-rendered (LWR), so Bonsai uses per-host **site modules** that render and extract them for you — a normal Bonsai fetch returns clean Markdown for these hosts without `--rendered`.
 
-- **Search Help live** when you do not have a URL yet — this hits Salesforce's own backend, not the local cache:
+- **Help and Developer fetch.** Once you have a URL, capture it through Bonsai:
 
   ```bash
-  npx @taurgis/bonsai search "single sign-on" --domain help.salesforce.com
+  npx @taurgis/bonsai <official-url> --format detailed
   ```
 
-- `developer.salesforce.com` has a rendered fetch but **no** `--domain` search (passing it errors); find Developer URLs another way, then fetch them through Bonsai.
 - Matching is by exact hostname; prefer canonical `/s/articleView?id=…` Help URLs (Bonsai normalizes legacy `/help_doccontent?id=…` links automatically).
 
 ## When Not to Use
@@ -50,7 +51,7 @@ Salesforce Help and Developer docs are JavaScript-rendered (LWR), so Bonsai uses
 ## Examples
 
 - ✅ Confirming one platform's current flag or frontmatter field before a small edit → run the web-research skill inline.
-- ✅ Finding a Salesforce Help article by topic → `npx @taurgis/bonsai search "<topic>" --domain help.salesforce.com`, then fetch the chosen URL through Bonsai.
+- ✅ Finding a Salesforce Help article by topic → discover the official URL with native web/search tools, then fetch it through Bonsai.
 - ✅ Comparing conventions across several platforms, or auditing/refactoring source broadly → delegate to the Salesforce Docs Researcher subagent.
 - ✅ Before editing instructions, prompts, agents, skills, workflows, or docs — reading source code does not replace checking current platform guidance.
 - ✅ Include official source URLs when the change references platform behavior or standards.

package/agents/instructions/web-research.instructions.md

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '3.1.1'
+  version: '4.0.0'
 ---
 
 # Web Research Requirement
@@ -24,7 +24,8 @@ metadata:
 
 ## Shared Cache
 
-- Both paths use the same freshness-tiered Bonsai cache (data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss.
+- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`.
+- **URL discovery**: When you do not yet know the official URL, discover it with your native web/search tools, then fetch the page through Bonsai so it is cached for future agents.
 - If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
 - Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
 

package/agents/skills/web-research/SKILL.md

@@ -1,47 +1,42 @@
 ---
 name: web-research
-description: 'Bonsai-backed official documentation and web research workflow. Use before technical changes that depend on platform behavior, when fetching documentation or web pages, when searching/listing/pruning the local research cache, or when importing manually gathered notes.'
+description: 'Bonsai-backed official documentation and web research workflow. Use before technical changes that depend on platform behavior, when fetching documentation or web pages, when listing/pruning the local research cache, or when importing manually gathered notes.'
 license: Forward Proprietary
 compatibility: VS Code 1.x+, GitHub Copilot
 metadata:
-  version: '2.1.0'
+  version: '3.0.0'
 ---
 
 # Web Research Skill
 
 Use Bonsai as the cache-first research path for official documentation and web content. Prefer current official sources, keep research reusable, and avoid direct one-off web fetches when Bonsai can capture the same page.
 
-## Required Pre-Step
-
-Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
+## Invocation
 
-Search the cache first:
+Always run Bonsai through the published npm package:
 
 ```bash
-bonsai search "<topic or keywords>"
+npx @taurgis/bonsai <command> [flags]
 ```
 
-If the cache misses or does not cover the question, fetch the source through Bonsai:
+Add `--json` when you need machine-readable output for agent callers.
 
-```bash
-bonsai <official-url> --format detailed
-```
+## Required Pre-Step
 
-Inside the Bonsai repository, use the development binary:
+Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
+
+When you do not yet know the official URL, discover it with your native web/search tools first. Once you have a URL, capture it through Bonsai:
 
 ```bash
-node bin/cli.mjs search "<topic or keywords>" --json
-node bin/cli.mjs <official-url> --format detailed --json
+npx @taurgis/bonsai <official-url> --format detailed
 ```
 
-For one-shot published usage outside this repo, use the scoped package name:
+For agent callers that need structured output:
 
 ```bash
-npx @taurgis/bonsai <official-url> --format detailed
+npx @taurgis/bonsai <official-url> --format detailed --json
 ```
 
-Do not document or run bare `npx bonsai` unless an unscoped npm shim is actually published.
-
 ## Source Rules
 
 - Prefer official vendor docs, standards, API references, SDK docs, release notes, changelogs, and security advisories.
@@ -57,13 +52,11 @@ Use `--format compressed` for context-budgeted reading and `--format detailed` f
 Use `--rendered` when static extraction is incomplete or the page is an SPA:
 
 ```bash
-bonsai <official-url> --rendered --format detailed
+npx @taurgis/bonsai <official-url> --rendered --format detailed
 ```
 
 Never reach for direct `WebFetch` or `WebSearch` to retrieve a specific page when Bonsai can fetch it. Bonsai returns reusable Markdown and keeps it cached for future agents.
 
-Pure discovery searches are allowed when you do not yet know which URL to fetch. Once a URL is selected, capture it with Bonsai.
-
 ## Manual Fallbacks
 
 If direct web access was unavoidable because of authentication, browser interaction, or a tool constraint, import the result into Bonsai before returning.
@@ -71,19 +64,19 @@ If direct web access was unavoidable because of authentication, browser interact
 Single-source import:
 
 ```bash
-bonsai import <url> --file path/to/notes.md
+npx @taurgis/bonsai import <url> --file path/to/notes.md
 ```
 
 Stdin import:
 
 ```bash
-echo "# My Synthesis Note" | bonsai import <url> --stdin
+echo "# My Synthesis Note" | npx @taurgis/bonsai import <url> --stdin
 ```
 
 Multi-source synthesis:
 
 ```bash
-bonsai import \
+npx @taurgis/bonsai import \
   --topic "<descriptive topic>" \
   --source-url <url1> \
   --source-url <url2> \
@@ -95,27 +88,26 @@ bonsai import \
 Check status without fetching:
 
 ```bash
-bonsai status <url>
+npx @taurgis/bonsai status <url>
 ```
 
 Inspect stored metadata:
 
 ```bash
-bonsai inspect <url>
+npx @taurgis/bonsai inspect <url>
 ```
 
-List or search cached entries:
+List cached entries by metadata:
 
 ```bash
-bonsai list --tags node
-bonsai search "react suspense"
+npx @taurgis/bonsai list --tags node
 ```
 
 Preview pruning before deleting:
 
 ```bash
-bonsai prune --older-than 90d --dry-run
-bonsai prune --older-than 90d --yes
+npx @taurgis/bonsai prune --older-than 90d --dry-run
+npx @taurgis/bonsai prune --older-than 90d --yes
 ```
 
 ## When This Does Not Apply
@@ -123,4 +115,4 @@ bonsai prune --older-than 90d --yes
 - No technical content or web content is involved.
 - You already fetched and applied current official docs in the current task.
 - The request is a trivial typo or formatting fix that does not involve platform behavior.
-- Bonsai is not installed and `npx @taurgis/bonsai ...` is not available; use the best available official-source workflow and import notes later.
+- `npx @taurgis/bonsai` is unavailable in the environment; use the best available official-source workflow and import notes later.

package/bin/cli.mjs

@@ -3,6 +3,15 @@
 import { execute } from '@oclif/core';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import updateNotifier from 'update-notifier';
+import { createRequire } from 'node:module';
+
+import { normalizeArgv } from '../dist/lib/argv.js';
+import { tryUnknownHelpOutput } from '../dist/lib/help-preflight.js';
+import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
+
+const req = createRequire(import.meta.url);
+const pkg = req('../package.json');
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -12,21 +21,42 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
 // process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
-const [firstArg, ...restArgv] = rawArgv;
-// Treat any first arg that looks like a URL (carries a scheme) as the `fetch` shorthand.
-// Routing wrong-scheme URLs (ftp://, file://) here too means fetch can answer with a clear
-// "only http/https" error instead of oclif's cryptic "command not found".
-const looksLikeUrl = firstArg?.includes('://') ?? false;
-const normalizedArgv =
-  firstArg === 'help'
-    ? [...restArgv, '--help']
-    : looksLikeUrl
-      ? ['fetch', ...rawArgv]
-      : rawArgv;
-
-process.argv = [process.argv[0], process.argv[1], ...normalizedArgv];
+const result = normalizeArgv(rawArgv);
+const root = __dirname + '/../';
+
+if (result.exitWithJson) {
+  process.exitCode = result.exitWithJson.exitCode;
+  console.log(JSON.stringify(result.exitWithJson.envelope, null, 2));
+  process.exit();
+}
+
+const unknownHelp = await tryUnknownHelpOutput(result.argv, root);
+if (unknownHelp) {
+  process.exitCode = unknownHelp.exitCode;
+  if (unknownHelp.kind === 'json') {
+    console.log(JSON.stringify(unknownHelp.envelope, null, 2));
+  } else {
+    console.error(` ›   Error: ${unknownHelp.message.replaceAll('\n', '\n ›   ')}`);
+  }
+  process.exit();
+}
+
+const jsonMeta = await tryJsonMetaOutput(result.argv, root);
+if (jsonMeta) {
+  process.exitCode = jsonMeta.exitCode;
+  console.log(JSON.stringify(jsonMeta.envelope, null, 2));
+  process.exit();
+}
+
+// Only notify after the exitWithJson fast-path so the notifier never fires before
+// a JSON envelope exits. Also skip under --json so agent callers never see stderr noise.
+if (!process.argv.includes('--json')) {
+  updateNotifier({ pkg }).notify();
+}
+
+process.argv = [process.argv[0], process.argv[1], ...result.argv];
 
 await execute({
   development: false,
-  dir: __dirname + '/../',
+  dir: root,
 });