@taurgis/bonsai 1.0.4 → 1.0.6

package/README.md

@@ -4,6 +4,8 @@ Bonsai is a standalone local research cache CLI for AI agents. It turns official
 
 The package is published as `@taurgis/bonsai` and installs a `bonsai` binary.
 
+📚 **Full documentation: [bonsai.rhino-inquisitor.com](https://bonsai.rhino-inquisitor.com/)**
+
 > Because the npm package is scoped, the correct one-shot command is `npx @taurgis/bonsai ...`. The unscoped `npx bonsai` name resolves to the separate `bonsai` package on npm unless an unscoped shim is published later.
 
 ---
@@ -144,6 +146,22 @@ Search cached research by metadata and content snippets.
 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.
+
+```bash
+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`.
+
+```bash
+npx @taurgis/bonsai prune --older-than 90d --dry-run
+```
+
 ### `config`
 
 Two keys are configurable:
@@ -162,6 +180,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:
@@ -228,6 +275,30 @@ 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` | Disable all ANSI color output (also respected via `TERM=dumb`). |
+| `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.
@@ -240,6 +311,14 @@ When run with `--json`, commands return a stable envelope:
 
 ## Reference Documentation
 
-* [Command Reference](docs/commands.md)
-* [Caching Protocol Specification](docs/cache-protocol.md)
+The full documentation site lives at
+**[bonsai.rhino-inquisitor.com](https://bonsai.rhino-inquisitor.com/)** (built with
+VitePress from the [`docs/`](docs/) folder). Key pages:
+
+* [Getting Started](docs/guide/getting-started.md)
+* [Caching & Freshness](docs/concepts/caching-and-freshness.md)
+* [Compression & Token Budgeting](docs/concepts/compression.md)
+* [Agent Integration](docs/how-to/agent-integration.md)
+* [Command Reference](docs/reference/commands.md)
+* [Caching Protocol Specification](docs/reference/cache-protocol.md)
 * [Troubleshooting and Limitations](docs/troubleshooting.md)

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: '3.0.1'
 ---
 
 # Official Docs Researcher Agent
@@ -24,7 +24,16 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 2. Search the Bonsai cache first:
 
    ```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
    ```
 
 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.

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

@@ -0,0 +1,126 @@
+---
+name: 'Salesforce Docs Researcher'
+description: 'Researches official documentation through Bonsai and returns source-cited findings, specialized for Salesforce Help and Developer docs'
+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'
+---
+
+# Salesforce Docs Researcher Agent
+
+You are a Forward documentation research specialist. Your job is to find current official documentation, cache it through Bonsai, and return concise source-cited findings that another agent can apply safely. This is the Official Docs Researcher specialized for Salesforce: the same workflow, plus the Salesforce site-module notes in "Working with Salesforce Sites" below.
+
+## Scope
+
+Use this agent for technical changes, platform behavior, APIs, SDKs, standards, release notes, changelogs, beta docs, security advisories, and other documentation-sensitive work. For Salesforce that includes Apex, SOQL, Flows, permissions, Setup, packaging, and the REST, Bulk, and Metadata APIs, plus Lightning and LWC references.
+
+Do not research from memory alone. Training-data knowledge does not satisfy this workflow.
+
+## Default Workflow
+
+1. Identify the product, version, edition, and source authority needed for the request.
+2. Search the Bonsai cache first:
+
+   ```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
+   ```
+
+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:
+
+   ```bash
+   bonsai <official-url> --format detailed
+   ```
+
+5. Use `--rendered` for SPAs or pages where static extraction is incomplete:
+
+   ```bash
+   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.
+
+Inside the Bonsai repository, use the development binary instead of an installed global command:
+
+```bash
+node bin/cli.mjs search "<topic or keywords>" --json
+node bin/cli.mjs <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
+  ```
+
+  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.
+
+## Freshness Policy
+
+Choose the freshness tier based on the source:
+
+- `stable`: standards, specs, MDN reference pages, pinned major-version docs.
+- `standard`: vendor API docs, SDK docs, normal technical references.
+- `volatile`: release notes, changelogs, latest pages, security advisories, beta docs.
+
+Stale volatile sources must be revalidated before they are trusted. Never overwrite a good cache entry with an error response.
+
+## Fallbacks
+
+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>
+```
+
+For multi-source synthesis:
+
+```bash
+bonsai import \
+  --topic "<descriptive topic>" \
+  --source-url <url1> \
+  --source-url <url2> \
+  --file <path>
+```
+
+## Response Contract
+
+Return:
+
+- Answer summary.
+- Official source URLs used.
+- Version, edition, or date constraints.
+- Cache status or validation timestamp when Bonsai output provides it.
+- Gaps or uncertainty where official docs do not answer the question.
+
+Keep stdout clean when using `--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.

package/agents/hooks/README.md

@@ -0,0 +1,62 @@
+# Bonsai Hook Examples
+
+These examples show how to steer agents away from one-off web fetch tools and
+toward Bonsai's reusable research cache.
+
+They are examples, not an installer contract. Copy the relevant folder contents
+into the agent's native hook location and adjust paths if your repository layout
+differs.
+
+## What The Hooks Do
+
+The hooks deny native URL-fetch tools and return model-visible guidance like:
+
+```bash
+bonsai https://example.com/docs --format detailed
+```
+
+Most hook systems cannot transparently replace a web-fetch tool call with a shell
+command. Blocking the native fetch and giving the agent the exact Bonsai command
+is the reliable cross-agent pattern.
+
+## Use With Caution
+
+These hooks are intentionally intrusive. If Bonsai fails because of network,
+installation, permissions, or extraction issues, the agent may have no fallback
+path to its native web-fetch tool. That can block valid research instead of
+making it better.
+
+Start with one repository, watch how the agent behaves, and remove or narrow the
+hook if it blocks work you still need the native tool to handle.
+
+## Supported Examples
+
+| Agent          | Native hook file        | Example           |
+| -------------- | ----------------------- | ----------------- |
+| Claude Code    | `.claude/settings.json` | `claude-code/`    |
+| GitHub Copilot | `.github/hooks/*.json`  | `github-copilot/` |
+| Cursor         | `.cursor/hooks.json`    | `cursor/`         |
+| Codex          | `.codex/hooks.json`     | `codex/`          |
+
+Antigravity is intentionally omitted: no current official hook configuration
+surface was found for replacing `read_url_content` or similar URL-fetch tools.
+
+Codex has one important limitation: `PreToolUse` hooks cover shell, patch, and
+MCP tool calls, but not every built-in web/search tool. The Codex example blocks
+MCP-style URL fetch tools when they are available and adds prompt-time context
+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:
+
+```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

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+
+node -e '
+const fs = require("node:fs");
+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 reason =
+  `Use Bonsai instead of the native web fetch so the result is cached and reusable. Run: ${command}`;
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: reason
+  }
+}) + "\n");
+' <<< "$input"

package/agents/hooks/claude-code/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebFetch|WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/bonsai-web-fetch.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+
+node -e '
+const fs = require("node:fs");
+const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+const prompt = String(input.prompt ?? "");
+if (!/https?:\/\/\S+/.test(prompt)) process.exit(0);
+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."
+  }
+}) + "\n");
+' <<< "$input"

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

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+
+node -e '
+const fs = require("node:fs");
+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 reason =
+  `Use Bonsai instead of this URL-fetch tool so the result is cached and reusable. Run: ${command}`;
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: reason
+  }
+}) + "\n");
+' <<< "$input"

package/agents/hooks/codex/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__.*(web|fetch|get_url_content|read_url_content).*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/bonsai-web-fetch.sh",
+            "timeout": 10,
+            "statusMessage": "Routing URL fetch through Bonsai"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/bonsai-user-prompt-context.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+
+node -e '
+const fs = require("node:fs");
+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 message =
+  `Use Bonsai instead of the native URL fetch so the result is cached and reusable. Run: ${command}`;
+process.stdout.write(JSON.stringify({
+  continue: true,
+  permission: "deny",
+  user_message: "Native web fetch blocked. Use Bonsai for reusable research cache entries.",
+  agent_message: message
+}) + "\n");
+' <<< "$input"

package/agents/hooks/cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "bash .cursor/hooks/bonsai-web-fetch.sh",
+        "matcher": "web_fetch|WebFetch|read_url_content|get_url_content",
+        "timeout": 10
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "matcher": "web_fetch",
+        "bash": "bash .github/hooks/bonsai-web-fetch.sh",
+        "powershell": "bash .github/hooks/bonsai-web-fetch.sh",
+        "timeoutSec": 10
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "matcher": "WebFetch",
+        "bash": "bash .github/hooks/bonsai-web-fetch.sh",
+        "powershell": "bash .github/hooks/bonsai-web-fetch.sh",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+
+node -e '
+const fs = require("node:fs");
+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 reason =
+  `Use Bonsai instead of web_fetch so the result is cached and reusable. Run: ${command}`;
+process.stdout.write(JSON.stringify({
+  permissionDecision: "deny",
+  permissionDecisionReason: reason
+}) + "\n");
+' <<< "$input"

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

@@ -0,0 +1,59 @@
+---
+description: 'Verify current official docs before technical repo changes — inline via the web-research skill for minor research, via the Salesforce Docs Researcher subagent for extensive research. Specialized for Salesforce Help and Developer docs.'
+applyTo: '**'
+skills:
+  - web-research
+metadata:
+  version: '1.0.2'
+---
+
+# Web Research Requirement (Salesforce)
+
+## Mandatory Pre-Step
+
+- Verify the relevant current official documentation **in the same task** before creating, updating, refactoring, scaffolding, or deleting technical content.
+- Apply what you find — cite official source URLs when the change relies on platform behavior or standards.
+- Research is the requirement; how you run it scales with scope (below). Training-data knowledge never satisfies this — only docs fetched in the current task do.
+
+## Choose How to Research by Scope
+
+- **Minor research — run it inline.** For a single known page, one platform, or a quick flag/API/version check, the main agent invokes the **web-research** skill directly. A separate subagent is not required.
+- **Extensive research — delegate to a subagent.** For multiple sources or platforms, unfamiliar territory, broad audits, or anything that produces verbose output you do not want in the main context, run the **Salesforce Docs Researcher** subagent and apply its findings.
+- The main agent may always use the **web-research** skill directly — choose the subagent to isolate large research, not because inline research is disallowed.
+- When unsure, start inline and escalate to the subagent once the work spans several sources.
+
+## 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.
+- 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:
+
+  ```bash
+  npx @taurgis/bonsai search "single sign-on" --domain help.salesforce.com
+  ```
+
+- `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
+
+- No technical content is being modified (purely editorial changes).
+- You already fetched and applied official docs **in the current task**. Training-data knowledge does not satisfy this — only docs fetched in the same task do.
+- The request is too simple to warrant research (typo, lint fix not involving platform behavior).
+
+## 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.
+- ✅ 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.
+- ❌ Don't modify technical content without researching first, and don't treat cached or training knowledge as equivalent — official guidance evolves and must be verified per task.

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

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '3.1.0'
+  version: '3.1.2'
 ---
 
 # Web Research Requirement
@@ -24,8 +24,11 @@ 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.
+- **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.
+- 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

@@ -4,7 +4,7 @@ description: 'Bonsai-backed official documentation and web research workflow. Us
 license: Forward Proprietary
 compatibility: VS Code 1.x+, GitHub Copilot
 metadata:
-  version: '2.1.0'
+  version: '2.1.1'
 ---
 
 # Web Research Skill
@@ -15,10 +15,15 @@ Use Bonsai as the cache-first research path for official documentation and web c
 
 Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
 
-Search the cache first:
-
 ```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
 ```
 
 If the cache misses or does not cover the question, fetch the source through Bonsai: