@taurgis/bonsai 1.0.6 → 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
@@ -281,7 +273,9 @@ When run with `--json`, commands return a stable envelope:
 | --- | --- |
 | `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` | Disable all ANSI color output (also respected via `TERM=dumb`). |
+| `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:*`. |

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.1'
+  version: '4.0.0'
 ---
 
 # Official Docs Researcher Agent
@@ -18,54 +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
-   # 1. Default search: Checks the local cache across EVERYTHING you've researched, 
-   # including domains that do not support online search APIs.
-   bonsai search "<topic or keywords>"
-   
-   # 2. Remote API search: Use this to quickly find URLs for documentation pages online
-   # ONLY if you don't find any information in the local cache.
-   bonsai search "<topic or keywords>" --domain <domain>
-   # Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org,
-   # jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org,
-   # vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
-   ```
+## 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:
@@ -81,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.1'
+  version: '2.0.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -18,70 +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
-   # 1. Default search: Checks the local cache across EVERYTHING you've researched, 
-   # including domains that do not support online search APIs.
-   bonsai search "<topic or keywords>"
-   
-   # 2. Remote API search: Use this to quickly find URLs for documentation pages online
-   # ONLY if you don't find any information in the local cache.
-   bonsai search "<topic or keywords>" --domain <domain>
-   # Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org,
-   # jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org,
-   # vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
-   ```
+## 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.
 
@@ -100,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.2'
+  version: '2.0.0'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -24,23 +24,22 @@ metadata:
 
 ## Shared Cache
 
-- **Local Cache Search (Default)**: Always search the local cache first using `bonsai search "<query>"`. This checks everything you've researched across all domains, even ones that don't support online search APIs.
-- **Online URL Discovery (Fallback)**: If the local cache comes up empty, use `--domain <domain>` or `--remote <docs-url>` to quickly hit a site's search API and find the official URLs you need to fetch. This is specifically for online URL discovery when local cache fails.
+- **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.
-- Supported remote API domains: `help.salesforce.com`, `react.dev`, `vuejs.org`, `tailwindcss.com`, `nextjs.org`, `jestjs.io`, `cypress.io`, `vitest.dev`, `vitepress.dev`, `angular.dev`, `redux.js.org`, `vitejs.dev`, `fastify.dev`, `rollupjs.org`, `vueuse.org`.
 
 ## Working with Salesforce Sites
 
 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
@@ -52,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.2'
+  version: '4.0.0'
 ---
 
 # Web Research Requirement
@@ -24,11 +24,10 @@ metadata:
 
 ## Shared Cache
 
-- **Local Cache Search (Default)**: Always search the local cache first using `bonsai search "<query>"`. This checks everything you've researched across all domains, even ones that don't support online search APIs.
-- **Online URL Discovery (Fallback)**: If the local cache comes up empty, use `--domain <domain>` or `--remote <docs-url>` to quickly hit a site's search API and find the official URLs you need to fetch. This is specifically for online URL discovery when local cache fails.
+- **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.
-- Supported remote API domains: `help.salesforce.com`, `react.dev`, `vuejs.org`, `tailwindcss.com`, `nextjs.org`, `jestjs.io`, `cypress.io`, `vitest.dev`, `vitepress.dev`, `angular.dev`, `redux.js.org`, `vitejs.dev`, `fastify.dev`, `rollupjs.org`, `vueuse.org`.
 
 ## When Not to Use
 

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

@@ -1,52 +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.1'
+  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
+## Invocation
 
-Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
+Always run Bonsai through the published npm package:
 
 ```bash
-# 1. Default search: Checks the local cache across EVERYTHING you've researched, 
-# including domains that do not support online search APIs.
-bonsai search "<topic or keywords>"
-
-# 2. Remote API search: Use this to quickly find URLs for documentation pages online
-# ONLY if you don't find any information in the local cache.
-bonsai search "<topic or keywords>" --domain <domain>
-# Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org, jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org, vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
+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.
@@ -62,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.
@@ -76,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> \
@@ -100,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
@@ -128,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

@@ -7,6 +7,7 @@ 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);
@@ -21,6 +22,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
 const result = normalizeArgv(rawArgv);
+const root = __dirname + '/../';
 
 if (result.exitWithJson) {
   process.exitCode = result.exitWithJson.exitCode;
@@ -28,7 +30,18 @@ if (result.exitWithJson) {
   process.exit();
 }
 
-const jsonMeta = await tryJsonMetaOutput(result.argv, __dirname + '/../');
+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));
@@ -45,5 +58,5 @@ process.argv = [process.argv[0], process.argv[1], ...result.argv];
 
 await execute({
   development: false,
-  dir: __dirname + '/../',
+  dir: root,
 });

package/dist/base-command.d.ts

@@ -10,10 +10,11 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     static enableJsonFlag: boolean;
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
+    parsedArgv: string[];
     init(): Promise<void>;
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
-     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * but our warnings (secret-redirect, stale-serve, prune failures) are
      * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
      * JSON envelope, so machine output stays clean.
      */
@@ -37,11 +38,23 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
             exit?: number;
         };
         exitCode?: number;
+        code?: string;
     }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
-    /** Resolve a URL against the research cache, exiting with INVALID_URL on normalization failure. */
+    /**
+     * Resolve a URL against the research cache, exiting on a normalization failure. A scheme-less but
+     * domain-shaped input reports MISSING_URL_SCHEME — the same code the root `bonsai <url>` shorthand
+     * uses — so an agent sees one stable code for "forgot https://" everywhere; truly unparseable input
+     * stays INVALID_URL.
+     */
     protected resolveResearchTargetOrFail(url: string, extra?: Pick<ResolveResearchTargetOptions, 'flagOverride' | 'lookup'>): ResolvedResearchTarget;
+    /**
+     * Single exit point for a URL that failed normalization, shared by every URL-accepting command.
+     * The scheme-less message is already self-contained and actionable, so it is surfaced as-is;
+     * other parse failures keep the "Invalid URL:" prefix for context.
+     */
+    protected failInvalidUrl(url: string, message: string): never;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     private envelope;
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */