@taurgis/bonsai 1.0.3 → 1.0.5

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.
 
 ---
@@ -101,7 +103,7 @@ npx @taurgis/bonsai <url> [flags]
 Common flags:
 
 * `--topic`, `-t`: Primary category/topic for metadata tagging.
-* `--tags`, `-g`: Searchable tags. Can be repeated.
+* `--tags`, `-g`: Searchable tags. Can be repeated. When omitted, tags are auto-generated from the content by keyword detection (recorded with an `auto-generated tags via keyword extraction` quality note); passing `--tags` always takes precedence.
 * `--format`, `-f`: Output density: `compressed` or `detailed`.
 * `--tier`: Freshness tier: `stable`, `standard`, or `volatile`.
 * `--ttl`, `-l`: Custom predicted lifespan, such as `2h`, `7d`, or `30d`.
@@ -114,7 +116,7 @@ Common flags:
 
 ### `import [url]`
 
-Save custom Markdown notes directly to the cache.
+Save custom Markdown notes directly to the cache. As with `fetch`, when `--tags` is omitted the tags are auto-generated from the note content by keyword detection.
 
 ```bash
 npx @taurgis/bonsai import [url] --stdin [flags]
@@ -144,15 +146,37 @@ 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`
 
-Choose global or project-local cache storage.
+Two keys are configurable:
+
+| Key | Values | Default | Effect |
+| --- | --- | --- | --- |
+| `storage` | `global`, `project` | `global` | Where cache files are stored. |
+| `summary` | `conservative`, `balanced`, `aggressive` | `conservative` | How aggressively the `compressed` format is shortened when structural compression alone leaves it close to `detailed`. Prose is condensed extractively (no LLM); headings, code blocks, tables, and lists are always preserved. |
 
 ```bash
 npx @taurgis/bonsai config set storage project --local
+npx @taurgis/bonsai config set summary balanced
 ```
 
-Project config is stored in `.bonsai.json`; project cache files are stored under `.bonsai/research/`.
+Both keys can also be overridden per-invocation via the `BONSAI_STORAGE` and `BONSAI_SUMMARY` environment variables. Project config is stored in `.bonsai.json`; project cache files are stored under `.bonsai/research/`.
 
 ---
 
@@ -234,6 +258,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/salesforce-docs-researcher.agent.md

@@ -0,0 +1,117 @@
+---
+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.0'
+---
+
+# 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
+   bonsai search "<topic or keywords>"
+   ```
+
+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,57 @@
+---
+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.1'
+---
+
+# 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
+
+- 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.
+- 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.
+
+## 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.1'
 ---
 
 # Web Research Requirement
@@ -25,6 +25,7 @@ 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.
+- 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.
 
 ## When Not to Use

package/bin/cli.mjs

@@ -6,17 +6,27 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Normalize argv so the whole oclif pipeline sees one consistent command. oclif's
+// error handler re-reads process.argv (not the args passed to execute) when it renders
+// help on a parse error, so rewriting only the execute() args leaves the help renderer
+// trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
+// process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
 const [firstArg, ...restArgv] = rawArgv;
-const args =
+// Treat any first arg that looks like a URL (carries a scheme) as the `fetch` shorthand.
+// Routing wrong-scheme URLs (ftp://, file://) here too means fetch can answer with a clear
+// "only http/https" error instead of oclif's cryptic "command not found".
+const looksLikeUrl = firstArg?.includes('://') ?? false;
+const normalizedArgv =
   firstArg === 'help'
     ? [...restArgv, '--help']
-    : firstArg?.startsWith('http://') || firstArg?.startsWith('https://')
+    : looksLikeUrl
       ? ['fetch', ...rawArgv]
       : rawArgv;
 
+process.argv = [process.argv[0], process.argv[1], ...normalizedArgv];
+
 await execute({
-  args,
   development: false,
   dir: __dirname + '/../',
 });

package/dist/base-command.d.ts

@@ -17,6 +17,26 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /**
+     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
+     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
+     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
+     */
+    private static exitCodeOf;
+    /**
+     * Align the process exit code with the code reported in the JSON envelope. oclif's default
+     * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
+     * `err.oclif.exit` (never `err.exitCode`), so a usage error (`this.error(msg, { exit: 2 })`) would
+     * exit the process with 1 under `--json` while `toErrorJson` correctly reports `exitCode: 2`. That
+     * contradiction breaks the deterministic-exit-code contract agents rely on. Pre-seed the code from
+     * the shared resolver so the framework's `??` keeps it, then defer to the default behavior.
+     */
+    catch(err: Error & {
+        oclif?: {
+            exit?: number;
+        };
+        exitCode?: number;
+    }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */

package/dist/base-command.js

@@ -1,4 +1,5 @@
 import { Command, Errors } from '@oclif/core';
+import { invalidEnvOverrideWarnings } from './lib/config/index.js';
 /**
  * Shared base for every Bonsai command. Enables oclif's native `--json` flag,
  * parses args/flags once in `init()` so commands read `this.args`/`this.flags`
@@ -19,6 +20,11 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        // Surface a set-but-invalid BONSAI_* override once per run. Resolution silently drops such a
+        // value, so without this a typo'd env var would take no effect with no signal. Warnings go to
+        // stderr (even under --json), so machine output stays clean.
+        for (const warning of invalidEnvOverrideWarnings(process.env))
+            this.warn(warning);
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
@@ -30,6 +36,26 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    /**
+     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
+     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
+     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
+     */
+    static exitCodeOf(err) {
+        return err?.oclif?.exit ?? err?.exitCode ?? 1;
+    }
+    /**
+     * Align the process exit code with the code reported in the JSON envelope. oclif's default
+     * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
+     * `err.oclif.exit` (never `err.exitCode`), so a usage error (`this.error(msg, { exit: 2 })`) would
+     * exit the process with 1 under `--json` while `toErrorJson` correctly reports `exitCode: 2`. That
+     * contradiction breaks the deterministic-exit-code contract agents rely on. Pre-seed the code from
+     * the shared resolver so the framework's `??` keeps it, then defer to the default behavior.
+     */
+    async catch(err) {
+        process.exitCode = process.exitCode ?? BaseCommand.exitCodeOf(err);
+        return super.catch(err);
+    }
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     envelopeCommandId() {
         return this.ctor.id || this.config.bin;
@@ -58,7 +84,7 @@ export class BaseCommand extends Command {
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     toErrorJson(err) {
         const e = err;
-        const exitCode = e?.oclif?.exit ?? e?.exitCode ?? 1;
+        const exitCode = BaseCommand.exitCodeOf(e);
         return this.envelope({ ok: false, exitCode, stderr: e?.message ?? String(err), data: null });
     }
 }

package/dist/commands/config/get.js

@@ -1,10 +1,10 @@
 import { Args } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../lib/config/index.js';
+import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigGet extends ConfigCommand {
     static id = 'config get';
     static summary = 'Get the effective value of a research configuration key.';
-    static description = 'Print a config value. Without --global/--local, shows the merged effective value (flag > env > project > user > default).\n\nValid keys: storage.';
+    static description = `Print a config value. Without --global/--local, shows the merged effective value (flag > env > project > user > default).\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
             description: 'Get the effective storage mode',