@taurgis/bonsai 4.0.0 → 4.1.0

package/README.md

@@ -21,6 +21,7 @@ The package is published as `@taurgis/bonsai` and installs a `bonsai` binary.
 | **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 |
 | **List** | Filters cached entries by topic, tags, freshness, and metadata | Seeing what is already cached without reading full content |
+| **Search** | Ranks cached entries by keyword across tags, summary, and compressed content | Finding what's already cached on a topic without an exact topic/tag match |
 
 ---
 
@@ -88,6 +89,12 @@ echo "# Synthesized React Cache Guide" | npx @taurgis/bonsai import --stdin --to
 npx @taurgis/bonsai list --tags node
 ```
 
+### 6. Search cached entries by keyword
+
+```bash
+npx @taurgis/bonsai search --query "url parsing"
+```
+
 ---
 
 ## Command Reference
@@ -141,12 +148,28 @@ npx @taurgis/bonsai inspect <url>
 
 ### `list`
 
-List cached artifacts by metadata filters (`--topic`, `--tags`, `--url`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content. The default `--json`/`--toon` row is a minimal 4-field shape (`sourceUrls`, `topic`, `freshness`, `tokenEstimate`); pass `--full` for every metadata field. Running `bonsai` with no arguments at all is shorthand for `bonsai list`.
+List cached artifacts by metadata filters (`--topic`, `--tags`, `--url`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content. The default `--json`/`--toon` row is a minimal 4-field shape (`sourceUrls`, `topic`, `freshness`, `tokenEstimate`); pass `--full` for every metadata field. `--limit` defaults to 10 so an unfiltered call never floods the caller's context; a truncated result's `summary.nextCommand` gives a ready-to-run command with `--limit` raised. Running `bonsai` with no arguments at all is shorthand for `bonsai list`, preceded by a `bin:`/`description:` identity header (human mode only, that bare invocation only).
 
 ```bash
 npx @taurgis/bonsai list [flags]
 ```
 
+### `search`
+
+Rank cached artifacts by keyword — the content/tag search `list` doesn't do. `--query` matches
+(case-insensitive) against topic, tags, `summary`, and `compressed` content; every term must match
+somewhere unless `--match-any` is set. Every other filter (`--topic`, `--tags`, `--url`,
+`--freshness`, `--artifact-type`, `--capture-method`) works exactly like `list`'s. Each row adds a
+relevance `score`, which fields matched (`matchedFields`), and a short excerpt around the first
+content match (`snippet`) — reading only the token-cheap indexed `summary`/`compressed` text, never
+the full `detailed` body, so ranking a large cache stays fast and never balloons context. Omitting
+`--query` behaves like `list`: every row scores `0`, sorted newest-first. `--limit` defaults to 10,
+same as `list`.
+
+```bash
+npx @taurgis/bonsai search --query "suspense boundary" --tags react
+```
+
 ### `prune`
 
 Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, `--url`, `--topic`, or `--tags`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.

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

@@ -0,0 +1,102 @@
+---
+name: 'Official Docs Researcher'
+description: 'Researches official documentation through Bonsai and returns source-cited findings'
+model: 'Auto'
+tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
+argument-hint: 'What topic should I research in official docs?'
+metadata:
+  version: '4.5.0'
+---
+
+# Official 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.
+
+## Scope
+
+Use this agent for technical changes, platform behavior, APIs, SDKs, standards, release notes, changelogs, beta docs, security advisories, and other documentation-sensitive work.
+
+Do not research from memory alone. Training-data knowledge does not satisfy this workflow.
+
+## Invocation
+
+Run Bonsai as `npx @taurgis/bonsai ...`. Default to `--toon` for structured output — the same envelope as `--json`, at a lower token cost — as every example below does. Reach for `--json` only when a caller specifically needs real JSON (mutually exclusive with `--toon`).
+
+If you are operating in a read-only/plan mode (no filesystem writes allowed), add `--read-only` (alias `--plan`) to every Bonsai call, or export `BONSAI_READ_ONLY=1` (or `BONSAI_PLAN_MODE=1`) once for the session — fetches still run, but nothing is persisted to the local cache or config. See "Read-only / Plan Mode" below.
+
+## Default Workflow
+
+1. Identify the product, version, edition, and source authority needed for the request.
+2. Check whether relevant research is already cached before starting new fetches:
+
+   ```bash
+   npx @taurgis/bonsai search --query "<topic keywords>" --toon
+   ```
+
+   A hit still needs a freshness check (see below) before you trust it as current.
+3. Locate official source URLs for anything not already cached. 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.
+4. Capture each source through Bonsai:
+
+   ```bash
+   npx @taurgis/bonsai <official-url> --format detailed --toon
+   ```
+
+5. Use `--rendered` for SPAs or pages where static extraction is incomplete:
+
+   ```bash
+   npx @taurgis/bonsai <official-url> --rendered --format detailed --toon
+   ```
+
+6. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
+
+## 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.
+
+## Read-only / Plan Mode
+
+Bonsai supports a global `--read-only` flag (alias `--plan`), also honored via the `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` environment variables, that blocks all filesystem writes and deletes (cache persistence, config writes, `prune` deletions) while still allowing network fetches to run. Use it whenever you are invoked under a read-only/plan-mode harness so this research workflow stays non-destructive:
+
+- Research fetches (`npx @taurgis/bonsai <url>`) still hit the network and return content normally; they just skip writing the result to the local cache.
+- `import` previews the write and reports `dryRun: true` instead of persisting.
+- `config set` / `config unset` preview the write and report `would_set` / `would_unset`.
+- `prune` treats `--read-only` like an implicit dry run; combining it with `--yes` is rejected.
+
+Composition is OR: once read-only mode is active (flag or either env var), there is no per-call way to force writes back on.
+
+## Fallbacks
+
+If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
+
+```bash
+npx @taurgis/bonsai import <url> --file <path> --toon
+```
+
+For multi-source synthesis:
+
+```bash
+npx @taurgis/bonsai import \
+  --topic "<descriptive topic>" \
+  --source-url <url1> \
+  --source-url <url2> \
+  --file <path> \
+  --toon
+```
+
+## 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 `--toon`/`--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.

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: '2.2.0'
+  version: '2.5.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -20,33 +20,34 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 
 ## Invocation
 
-Run Bonsai as `npx @taurgis/bonsai ...`. Add `--toon` when you need structured output at a lower token cost; `--json` is also available if you specifically need JSON (mutually exclusive with `--toon`).
+Run Bonsai as `npx @taurgis/bonsai ...`. Default to `--toon` for structured output — the same envelope as `--json`, at a lower token cost — as every example below does. Reach for `--json` only when a caller specifically needs real JSON (mutually exclusive with `--toon`).
 
 If you are operating in a read-only/plan mode (no filesystem writes allowed), add `--read-only` (alias `--plan`) to every Bonsai call, or export `BONSAI_READ_ONLY=1` (or `BONSAI_PLAN_MODE=1`) once for the session — fetches still run, but nothing is persisted to the local cache or config. See "Read-only / Plan Mode" below.
 
 ## Default Workflow
 
 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:
+2. Check whether relevant research is already cached before starting new fetches:
 
    ```bash
-   npx @taurgis/bonsai <official-url> --format detailed
+   npx @taurgis/bonsai search --query "<topic keywords>" --toon
    ```
 
-4. Use `--rendered` for SPAs or pages where static extraction is incomplete:
+   A hit still needs a freshness check (see below) before you trust it as current.
+3. Locate official Salesforce source URLs for anything not already cached. Use your native web/search tools when you do not yet know the URL.
+4. Capture each source through Bonsai:
 
    ```bash
-   npx @taurgis/bonsai <official-url> --rendered --format detailed
+   npx @taurgis/bonsai <official-url> --format detailed --toon
    ```
 
-5. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
+5. Use `--rendered` for SPAs or pages where static extraction is incomplete:
 
-For structured output:
+   ```bash
+   npx @taurgis/bonsai <official-url> --rendered --format detailed --toon
+   ```
 
-```bash
-npx @taurgis/bonsai <official-url> --format detailed --toon
-```
+6. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
 
 ## Working with Salesforce Sites
 
@@ -86,7 +87,7 @@ Composition is OR: once read-only mode is active (flag or either env var), there
 If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
 
 ```bash
-npx @taurgis/bonsai import <url> --file <path>
+npx @taurgis/bonsai import <url> --file <path> --toon
 ```
 
 For multi-source synthesis:
@@ -96,7 +97,8 @@ npx @taurgis/bonsai import \
   --topic "<descriptive topic>" \
   --source-url <url1> \
   --source-url <url2> \
-  --file <path>
+  --file <path> \
+  --toon
 ```
 
 ## Response Contract

package/agents/hooks/README.md

@@ -7,12 +7,28 @@ 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.
 
+## Ambient session context (`bonsai setup`)
+
+The examples below only cover the *redirect-away-from-web-fetch* half of hook
+integration. For the complementary half — showing an agent the cache's current
+state before it does anything — run `bonsai setup <agent>` instead of copying
+files by hand. It installs (and repairs) a `SessionStart` hook that runs
+`bonsai context` at the start of every session, supporting `claude-code` and
+`codex` today. See [Ambient session
+context](https://bonsai.rhino-inquisitor.com/how-to/agent-integration#ambient-session-context)
+for the full workflow.
+
+OpenCode is not supported by `setup` yet: its plugin docs don't document a
+confirmed hook signature for injecting session-start context (closest is
+`session.created`, unconfirmed shape), so `setup` won't guess at one rather than
+ship an integration that might not work.
+
 ## What The Hooks Do
 
 The hooks deny native URL-fetch tools and return model-visible guidance like:
 
 ```bash
-npx @taurgis/bonsai https://example.com/docs --format detailed
+npx @taurgis/bonsai https://example.com/docs --format detailed --toon
 ```
 
 Most hook systems cannot transparently replace a web-fetch tool call with a shell
@@ -51,5 +67,5 @@ that tells the agent to prefer Bonsai for URLs.
 Run Bonsai through the published npm package:
 
 ```bash
-npx @taurgis/bonsai <url> --format detailed
+npx @taurgis/bonsai <url> --format detailed --toon
 ```

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 = `npx @taurgis/bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed --toon`;
 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: npx @taurgis/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 --toon. 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 = `npx @taurgis/bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed --toon`;
 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 = `npx @taurgis/bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed --toon`;
 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 = `npx @taurgis/bonsai ${url} --format detailed`;
+const command = `npx @taurgis/bonsai ${url} --format detailed --toon`;
 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: '2.1.0'
+  version: '2.4.0'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -24,9 +24,10 @@ metadata:
 
 ## Shared Cache
 
-- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`.
+- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`. Default to `--toon` for structured output (same envelope as `--json`, fewer tokens); use `--json` only when a caller specifically needs real JSON.
 - **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.
+- **Browse cached entries**: Use `npx @taurgis/bonsai list --toon` when you need to see what is already cached by topic, tags, or freshness. Prefer `--toon` over `--json` for lower token cost.
+- **Search cached entries**: Use `npx @taurgis/bonsai search --query "<keywords>" --toon` when you don't know the exact topic/tag to filter on — it ranks cached entries by a query matched against topic, tags, and page content. Both commands default `--limit` to 10; a truncated result's `summary.nextCommand` gives you the exact command to raise it.
 - 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.
 - If you are operating under a read-only/plan-mode harness, add `--read-only` (alias `--plan`) to Bonsai calls, or rely on `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` if the harness sets it — fetches still run, but nothing is persisted to the local cache or config; `config set` / `config unset` preview with `would_set` / `would_unset`.
@@ -38,7 +39,7 @@ Salesforce Help and Developer docs are JavaScript-rendered (LWR), so Bonsai uses
 - **Help and Developer fetch.** Once you have a URL, capture it through Bonsai:
 
   ```bash
-  npx @taurgis/bonsai <official-url> --format detailed
+  npx @taurgis/bonsai <official-url> --format detailed --toon
   ```
 
 - Matching is by exact hostname; prefer canonical `/s/articleView?id=…` Help URLs (Bonsai normalizes legacy `/help_doccontent?id=…` links automatically).

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

@@ -0,0 +1,45 @@
+---
+description: 'Verify current official docs before technical repo changes — inline via the web-research skill for minor research, via the Official Docs Researcher subagent for extensive research.'
+applyTo: '**'
+skills:
+  - web-research
+metadata:
+  version: '4.2.0'
+---
+
+# Web Research Requirement
+
+## 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 **Official 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
+
+- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`. Default to `--toon` for structured output (same envelope as `--json`, fewer tokens); use `--json` only when a caller specifically needs real JSON.
+- **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.
+- If you are operating under a read-only/plan-mode harness, add `--read-only` (alias `--plan`) to Bonsai calls, or rely on `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` if the harness sets it — fetches still run, but nothing is persisted to the local cache or config; `config set` / `config unset` preview with `would_set` / `would_unset`.
+
+## 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.
+- ✅ Comparing conventions across several platforms, or auditing/refactoring source broadly → delegate to the Official 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/skills/web-research/SKILL.md

@@ -0,0 +1,139 @@
+---
+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 listing/searching/pruning the local research cache, or when importing manually gathered notes.'
+license: Forward Proprietary
+compatibility: VS Code 1.x+, GitHub Copilot
+metadata:
+  version: '3.5.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.
+
+## Invocation
+
+Always run Bonsai through the published npm package:
+
+```bash
+npx @taurgis/bonsai <command> [flags]
+```
+
+Default to `--toon` for structured output — the same envelope as `--json`, at a lower token cost — as every example below does. Reach for `--json` only when a caller specifically needs real JSON (mutually exclusive with `--toon`).
+
+If you are operating under a read-only/plan-mode harness, add `--read-only` (alias `--plan`) to every Bonsai call, or export `BONSAI_READ_ONLY=1` (or `BONSAI_PLAN_MODE=1`) once for the session. Fetches still run and return content normally; nothing is written to the local cache or config until the harness leaves plan mode. `import`, `config set`/`unset`, and `prune` all honor it too — see "Read-only / Plan Mode" below.
+
+## Required Pre-Step
+
+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
+npx @taurgis/bonsai <official-url> --format detailed --toon
+```
+
+## Source Rules
+
+- Prefer official vendor docs, standards, API references, SDK docs, release notes, changelogs, and security advisories.
+- Include official source URLs when the change relies on platform behavior or standards.
+- Use `--tier stable`, `--tier standard`, or `--tier volatile` when the source class is clear.
+- Treat volatile sources as needing fresh validation before trusting them.
+- Do not use the retired manual `artifacts/online-research/` protocol for new research.
+
+## Fetch Rules
+
+Use `--format compressed` for context-budgeted reading and `--format detailed` for exact technical details, links, tables, and code examples.
+
+Use `--rendered` when static extraction is incomplete or the page is an SPA:
+
+```bash
+npx @taurgis/bonsai <official-url> --rendered --format detailed --toon
+```
+
+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.
+
+## Manual Fallbacks
+
+If direct web access was unavoidable because of authentication, browser interaction, or a tool constraint, import the result into Bonsai before returning.
+
+Single-source import:
+
+```bash
+npx @taurgis/bonsai import <url> --file path/to/notes.md --toon
+```
+
+Stdin import:
+
+```bash
+echo "# My Synthesis Note" | npx @taurgis/bonsai import <url> --stdin --toon
+```
+
+Multi-source synthesis:
+
+```bash
+npx @taurgis/bonsai import \
+  --topic "<descriptive topic>" \
+  --source-url <url1> \
+  --source-url <url2> \
+  --file path/to/synthesized-notes.md \
+  --toon
+```
+
+## Cache Operations
+
+Check status without fetching:
+
+```bash
+npx @taurgis/bonsai status <url> --toon
+```
+
+Inspect stored metadata:
+
+```bash
+npx @taurgis/bonsai inspect <url> --toon
+```
+
+List cached entries by metadata. Prefer `--toon` for agent callers — same data as `--json`, fewer
+tokens:
+
+```bash
+npx @taurgis/bonsai list --tags node --toon
+```
+
+Search cached entries by tag or content keyword when you don't know the exact topic/tag to filter
+on — ranks page-level entries by a query matched against topic, tags, summary, and compressed
+content:
+
+```bash
+npx @taurgis/bonsai search --query "suspense boundary" --toon
+```
+
+Both default `--limit` to 10 so a broad query never floods your context. A truncated result's
+envelope carries `summary.truncated` and `summary.nextCommand` — a ready-to-run command that
+reproduces your filters with a raised `--limit` — so raise it deliberately only when you actually
+need more, instead of requesting a large `--limit` up front.
+
+Preview pruning before deleting:
+
+```bash
+npx @taurgis/bonsai prune --older-than 90d --dry-run --toon
+npx @taurgis/bonsai prune --older-than 90d --yes --toon
+```
+
+## Read-only / Plan Mode
+
+Bonsai supports a global `--read-only` flag (alias `--plan`), also honored via the `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` environment variables, that blocks all filesystem writes and deletes (cache persistence, config writes, `prune` deletions) while still allowing network fetches to run:
+
+- Research fetches still hit the network and return content normally; they just skip writing the result to the local cache.
+- `import` previews the write and reports `dryRun: true` instead of persisting.
+- `prune` treats `--read-only` like an implicit dry run; combining it with `--yes` is rejected.
+
+Composition is OR: once read-only mode is active (flag or either env var), there is no per-call way to force writes back on. Use this whenever the calling agent itself is confined to a read-only/plan mode, so research stays possible without violating that constraint.
+
+## When This Does Not Apply
+
+- 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.
+- `npx @taurgis/bonsai` is unavailable in the environment; use the best available official-source workflow and import notes later.

package/dist/base-command.d.ts

@@ -66,6 +66,11 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * `data` is self-describing, so machine callers get no prose.
      */
     protected tip(message: string): void;
+    /**
+     * Human-mode tip for a truncated `list`/`search` result: the copy-pasteable command that raises
+     * `--limit` (see `next-command.ts`). A no-op when nothing was truncated (`nextCommand` is `null`).
+     */
+    protected tipNextCommand(nextCommand: string | null): void;
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     protected get readOnly(): boolean;
     /**

package/dist/base-command.js

@@ -2,6 +2,7 @@ import { Command, Errors, Flags, toConfiguredId, ux } from '@oclif/core';
 import { encode } from '@toon-format/toon';
 import { invalidConfigFileWarnings, invalidEnvOverrideWarnings, resolveReadOnly, } from './lib/config/index.js';
 import { CLI_FLAG_DESCRIPTIONS } from './lib/cli-presentation.js';
+import { colors } from './lib/color.js';
 import { formatTip, sanitizeForTerminal } from './lib/text.js';
 import { enrichErrorForDisplay, resolveExitCode, prepareCliError, EXIT_OK, EXIT_STALE_SERVED, } from './lib/cli-error-policy.js';
 import { buildEnvelope, enrichCacheMissEnvelope, enrichRowErrorEnvelope } from './lib/envelope.js';
@@ -145,6 +146,14 @@ export class BaseCommand extends Command {
             return;
         this.warn(formatTip(message));
     }
+    /**
+     * Human-mode tip for a truncated `list`/`search` result: the copy-pasteable command that raises
+     * `--limit` (see `next-command.ts`). A no-op when nothing was truncated (`nextCommand` is `null`).
+     */
+    tipNextCommand(nextCommand) {
+        if (nextCommand)
+            this.tip(`see the rest: ${colors.cyan(nextCommand)}`);
+    }
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     get readOnly() {
         return resolveReadOnly({ flag: Boolean(this.flags?.['read-only']), env: process.env });

package/dist/commands/config/base.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import type { ConfigKey, ConfigScope } from '../../lib/config/index.js';
+import { scopeFlags } from '../../lib/scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
@@ -16,10 +17,4 @@ export declare abstract class ConfigCommand<T extends typeof Command> extends Ba
     protected validateConfigKeyAndScope(key: string | undefined, global?: boolean, local?: boolean): asserts key is ConfigKey;
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
-export declare function configScopeFlags(descriptions: {
-    global: string;
-    local: string;
-}): {
-    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-};
+export declare const configScopeFlags: typeof scopeFlags;

package/dist/commands/config/base.js

@@ -1,19 +1,14 @@
-import { Flags, toConfiguredId } from '@oclif/core';
+import { toConfiguredId } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
+import { assertScopeFlagsExclusive, scopeFlags } from '../../lib/scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
  */
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {
-        if (global && local) {
-            this.error('--global and --local are mutually exclusive.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-                suggestions: ['Pass --global or --local, not both.'],
-            });
-        }
+        assertScopeFlagsExclusive(this.error.bind(this), global, local);
     }
     /** `--local` writes/reads the project file; otherwise the user-level file. */
     writeScope(local) {
@@ -58,13 +53,4 @@ export class ConfigCommand extends BaseCommand {
     }
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
-export function configScopeFlags(descriptions) {
-    return {
-        global: Flags.boolean({ char: 'g', description: descriptions.global }),
-        local: Flags.boolean({
-            description: descriptions.local,
-            aliases: ['project'],
-            charAliases: ['p'],
-        }),
-    };
-}
+export const configScopeFlags = scopeFlags;

package/dist/commands/context.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../base-command.js';
+import type { ContextDashboard } from '../lib/cli-result-types.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand<typeof Context> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static stdoutIsPrimaryData: boolean;
+    private logDashboard;
+    run(): Promise<ContextDashboard>;
+}