@taurgis/bonsai 3.1.0 → 3.2.2

package/README.md

@@ -110,8 +110,9 @@ Common flags:
 * `--max-age`: Read-time freshness threshold.
 * `--force`: Force a fresh fetch.
 * `--dry-run`: Scrape and validate without writing to cache.
-* `--allow-stale`: Serve stale cache if the remote site is offline.
+* `--allow-stale`: Suppress the exit `5` signal when a within-grace stale entry is served after failed revalidation (see [Freshness and Cache Rules](#freshness-and-cache-rules) below). Stale content is served within the grace window regardless of this flag; it does not extend serving beyond the grace window.
 * `--rendered`: Use browser-rendered extraction for SPA pages.
+* `--read-only` (alias `--plan`): Block all filesystem writes/deletes across every command; network fetches still run. See [Read-only / plan mode](#read-only--plan-mode) below.
 * `--json`: Return structured machine-readable output.
 
 ### `import [url]`
@@ -148,7 +149,7 @@ npx @taurgis/bonsai list [flags]
 
 ### `prune`
 
-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).
+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). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
 
 ```bash
 npx @taurgis/bonsai prune --older-than 90d --dry-run
@@ -170,6 +171,18 @@ npx @taurgis/bonsai config set summary balanced
 
 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/`.
 
+### Read-only / plan mode
+
+Every command accepts a global `--read-only` flag (alias `--plan`) that blocks all filesystem writes and deletes — cache persistence, config file writes, `prune` deletions — while still allowing network fetches to run. This is for agent harnesses (Claude Code and others) that enter a read-only "plan mode": set it once and every `bonsai` invocation for the rest of that session automatically skips writes, without needing the flag on every call.
+
+```bash
+BONSAI_READ_ONLY=1 npx @taurgis/bonsai https://example.com/docs
+npx @taurgis/bonsai import https://example.com/docs --file notes.md --read-only
+npx @taurgis/bonsai prune --older-than 90d --plan
+```
+
+It can also be set via the `BONSAI_READ_ONLY` or `BONSAI_PLAN_MODE` environment variables (both are equivalent). Composition is OR, not override: read-only mode is active if *either* env var or the flag is set, and there is no way to force writes back on once one of them is — this is a safety gate, not a preference. Commands that expose `--dry-run` (`fetch`, `import`, `prune`, `config set`/`unset`) treat global read-only the same as an explicit `--dry-run` and report `dryRun: true` (with `would_*` cache statuses where applicable) instead of persisting.
+
 ---
 
 ## Shell Autocomplete
@@ -222,7 +235,10 @@ If no `--ttl` is specified, freshness is computed from the tier:
 | `standard` | 30 days | 14 days | General API docs and developer guides |
 | `stable` | 180 days | 60 days | RFCs, standards, long-lived references |
 
-When stale entries still have `ETag` or `Last-Modified` metadata, Bonsai attempts cheap revalidation before a full refetch. If revalidation fails and `--allow-stale` is omitted, the CLI can serve the stale content while exiting with code `5`.
+When stale entries still have `ETag` or `Last-Modified` metadata, Bonsai attempts cheap revalidation before a full refetch. If revalidation fails:
+
+* **Within the grace window**, the stale content is served either way. By default this exits with code `5` so a caller can detect "this result may be outdated"; `--allow-stale` suppresses that signal and exits `0` instead, since the caller has already said outdated content is acceptable.
+* **Past the grace window**, the entry is expired and revalidation failure is always a hard error (exit `1`) — `--allow-stale` has no effect here, since there is no fresher fallback to serve.
 
 ---
 
@@ -273,6 +289,7 @@ 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`). |
+| `BONSAI_READ_ONLY` / `BONSAI_PLAN_MODE` | Set to `1`/`true`/`yes` to enable [read-only/plan mode](#read-only--plan-mode) for every command in the session, equivalent to passing `--read-only` (`--plan`) each time. Either variable is sufficient; there is no way to override it back off from a single invocation. |
 | `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. |
@@ -289,7 +306,7 @@ When run with `--json`, commands return a stable envelope:
 | `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. |
+| `5` | Stale content served — revalidation failed within the grace window and `--allow-stale` was omitted. The returned content is still usable. |
 
 ---
 

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.0.0'
+  version: '2.1.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -22,6 +22,8 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 
 Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
 
+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.
@@ -68,6 +70,17 @@ Choose the freshness tier based on the source:
 
 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>`), including the rendered Salesforce site-module fetches above, 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:

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

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '2.0.0'
+  version: '2.1.0'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -29,6 +29,7 @@ metadata:
 - **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.
+- 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`.
 
 ## Working with Salesforce Sites
 

package/bin/cli.mjs

@@ -7,6 +7,8 @@ import updateNotifier from 'update-notifier';
 import { createRequire } from 'node:module';
 
 import { normalizeArgv } from '../dist/lib/argv.js';
+import { VALUE_TAKING_FLAG_TOKENS } from '../dist/lib/cli-flag-manifest.js';
+import { exitWithPreflight } from '../dist/lib/cli-emit.js';
 import { tryUnknownHelpOutput } from '../dist/lib/help-preflight.js';
 import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
 
@@ -21,35 +23,25 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
 // process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
-const result = normalizeArgv(rawArgv);
+const result = normalizeArgv(rawArgv, { valueTakingFlags: VALUE_TAKING_FLAG_TOKENS });
 const root = __dirname + '/../';
 
-if (result.exitWithJson) {
-  process.exitCode = result.exitWithJson.exitCode;
-  console.log(JSON.stringify(result.exitWithJson.envelope, null, 2));
-  process.exit();
+if (result.earlyExit) {
+  exitWithPreflight(result.earlyExit);
 }
 
 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();
+  exitWithPreflight(unknownHelp);
 }
 
 const jsonMeta = await tryJsonMetaOutput(result.argv, root);
 if (jsonMeta) {
-  process.exitCode = jsonMeta.exitCode;
-  console.log(JSON.stringify(jsonMeta.envelope, null, 2));
-  process.exit();
+  exitWithPreflight({ ...jsonMeta, json: true });
 }
 
-// Only notify after the exitWithJson fast-path so the notifier never fires before
-// a JSON envelope exits. Also skip under --json so agent callers never see stderr noise.
+// Only notify after the earlyExit fast-path so the notifier never fires before
+// a usage-error envelope exits. Also skip under --json so agent callers never see stderr noise.
 if (!process.argv.includes('--json')) {
   updateNotifier({ pkg }).notify();
 }

package/dist/base-command.d.ts

@@ -1,5 +1,6 @@
-import { Command, Interfaces } from '@oclif/core';
+import { Command, Errors, Interfaces } from '@oclif/core';
 import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from './lib/research/resolve-target.js';
+import { type CliIo } from './lib/research/cli-io.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`
@@ -8,6 +9,15 @@ import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from '
  */
 export declare abstract class BaseCommand<T extends typeof Command> extends Command {
     static enableJsonFlag: boolean;
+    /**
+     * Flags shared by every command. Passed as `baseFlags` to `this.parse()` in `init()` below, which
+     * is oclif's own mechanism for merging them into `this.ctor.flags` at both parse time and
+     * `--help`/manifest generation — no per-command `static flags` changes are needed to expose these.
+     * `--plan` mirrors agent-harness "plan mode" terminology; `--read-only` is the canonical name.
+     */
+    static baseFlags: {
+        'read-only': Interfaces.BooleanFlag<boolean>;
+    };
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
     parsedArgv: string[];
@@ -19,12 +29,14 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
+    protected get readOnly(): boolean;
     /**
-     * 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.
+     * Combines a command's own explicit dry-run intent with global read-only mode. Warns once (on
+     * stderr, so it never pollutes `--json`) when read-only mode is what's actually suppressing the
+     * write, so a skipped write is never a silent surprise to the caller.
      */
-    private static exitCodeOf;
+    protected effectiveDryRun(explicitDryRun: boolean): boolean;
     /**
      * 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
@@ -39,6 +51,7 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
         };
         exitCode?: number;
         code?: string;
+        suggestions?: string[];
     }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
@@ -49,16 +62,30 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * 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.
-     */
+    /** Exit for a URL that failed normalization; see {@link failInvalidUrl} for the code contract. */
     protected failInvalidUrl(url: string, message: string): never;
+    /** Command context handed to command services (fetch/import) so they stay oclif-free. */
+    protected cliIo(): CliIo;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     private envelope;
+    /**
+     * Base success envelope from `process.exitCode` (including exit 5 = served stale / ok).
+     * Subclasses that overlay batch failures must call this — not `toSuccessJson` — to avoid
+     * recursing through their own override.
+     */
+    protected baseSuccessJson(data: unknown): Record<string, unknown>;
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     protected toSuccessJson(data: unknown): Record<string, unknown>;
+    /**
+     * Success overlay for multi-URL read commands (`status`, `inspect`). Apply CACHE_MISS first,
+     * then row `.error` so validation failures win when both appear in one batch.
+     */
+    protected batchReadSuccessJson(data: unknown): Record<string, unknown>;
+    /**
+     * Map each URL through `fn`. In a multi-URL batch, per-URL CLIErrors become failure rows so
+     * prior hits are kept — matching fetch's INVALID_URL / MISSING_URL_SCHEME batch contract.
+     */
+    protected mapUrlsAllowingBatchErrors<T, F>(urls: string[], fn: (url: string) => T, failureRow: (url: string, err: InstanceType<typeof Errors.CLIError>) => F): Array<T | F>;
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     protected toErrorJson(err: unknown): Record<string, unknown>;
 }

package/dist/base-command.js

@@ -1,8 +1,11 @@
-import { Command, Errors, toConfiguredId } from '@oclif/core';
-import { invalidEnvOverrideWarnings } from './lib/config/index.js';
-import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
+import { Command, Errors, Flags, toConfiguredId } from '@oclif/core';
+import { invalidEnvOverrideWarnings, resolveReadOnly } from './lib/config/index.js';
+import { CLI_FLAG_DESCRIPTIONS } from './lib/cli-presentation.js';
+import { enrichErrorForDisplay, resolveExitCode, prepareCliError, EXIT_OK, EXIT_STALE_SERVED, } from './lib/cli-error-policy.js';
+import { buildEnvelope, enrichCacheMissEnvelope, enrichRowErrorEnvelope, formatErrorForJson, } from './lib/envelope.js';
+import { enrichParseError } from './lib/parse-error-ux.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
-import { looksLikeSchemelessUrl } from './lib/research/url.js';
+import { failInvalidUrl } from './lib/research/cli-io.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`
@@ -11,6 +14,19 @@ import { looksLikeSchemelessUrl } from './lib/research/url.js';
  */
 export class BaseCommand extends Command {
     static enableJsonFlag = true;
+    /**
+     * Flags shared by every command. Passed as `baseFlags` to `this.parse()` in `init()` below, which
+     * is oclif's own mechanism for merging them into `this.ctor.flags` at both parse time and
+     * `--help`/manifest generation — no per-command `static flags` changes are needed to expose these.
+     * `--plan` mirrors agent-harness "plan mode" terminology; `--read-only` is the canonical name.
+     */
+    static baseFlags = {
+        'read-only': Flags.boolean({
+            aliases: ['plan'],
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.readOnly,
+        }),
+    };
     flags;
     args;
     parsedArgv;
@@ -18,6 +34,7 @@ export class BaseCommand extends Command {
         await super.init();
         const { args, flags, argv } = await this.parse({
             flags: this.ctor.flags,
+            baseFlags: this.ctor.baseFlags,
             enableJsonFlag: this.ctor.enableJsonFlag,
             args: this.ctor.args,
             strict: this.ctor.strict,
@@ -41,13 +58,20 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    /** 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 });
+    }
     /**
-     * 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.
+     * Combines a command's own explicit dry-run intent with global read-only mode. Warns once (on
+     * stderr, so it never pollutes `--json`) when read-only mode is what's actually suppressing the
+     * write, so a skipped write is never a silent surprise to the caller.
      */
-    static exitCodeOf(err) {
-        return err?.oclif?.exit ?? err?.exitCode ?? 1;
+    effectiveDryRun(explicitDryRun) {
+        if (this.readOnly && !explicitDryRun) {
+            this.warn('Read-only mode active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): skipping filesystem writes.');
+        }
+        return explicitDryRun || this.readOnly;
     }
     /**
      * Align the process exit code with the code reported in the JSON envelope. oclif's default
@@ -62,16 +86,10 @@ export class BaseCommand extends Command {
         // [UnparsedCommand] warning to stderr even under `--json`. CLIParseError subclasses carry `parse`.
         if (err && typeof err === 'object' && 'parse' in err)
             this.parsed = true;
-        // Attach the stable code to the error itself so oclif's human pretty-print renders the same
-        // `Code:` line that `--json` already reports via stableErrorCodeFrom. Without this, built-in
-        // oclif parse errors (invalid enum value, missing arg, unknown flag) printed a code under
-        // --json but not for humans — the two output modes disagreed on whether an error had a code.
-        if (err && typeof err === 'object' && !err.code) {
-            const code = stableErrorCodeFrom(err);
-            if (code)
-                err.code = code;
-        }
-        process.exitCode = process.exitCode ?? BaseCommand.exitCodeOf(err);
+        // Unwrap / fuzzy tips are no-ops when not applicable (including non-Error throws with no message).
+        enrichParseError(err);
+        enrichErrorForDisplay(err, { bin: this.config.bin, command: this.envelopeCommandId() });
+        process.exitCode = process.exitCode ?? resolveExitCode(err);
         return super.catch(err);
     }
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
@@ -98,16 +116,22 @@ export class BaseCommand extends Command {
             this.failInvalidUrl(url, err.message);
         }
     }
-    /**
-     * 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.
-     */
+    /** Exit for a URL that failed normalization; see {@link failInvalidUrl} for the code contract. */
     failInvalidUrl(url, message) {
-        if (looksLikeSchemelessUrl(url)) {
-            this.error(message, { exit: 2, code: 'MISSING_URL_SCHEME' });
-        }
-        this.error(`Invalid URL: ${message}`, { exit: 2, code: 'INVALID_URL' });
+        failInvalidUrl((msg, opts) => this.error(msg, opts), url, message);
+    }
+    /** Command context handed to command services (fetch/import) so they stay oclif-free. */
+    cliIo() {
+        return {
+            bin: this.config.bin,
+            configDir: this.config.configDir,
+            dataDir: this.config.dataDir,
+            cwd: process.cwd(),
+            json: this.jsonEnabled(),
+            warn: (msg) => void this.warn(msg),
+            log: (msg) => this.log(msg),
+            error: (msg, opts) => this.error(msg, opts),
+        };
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     envelope(parts) {
@@ -119,33 +143,76 @@ export class BaseCommand extends Command {
             data: parts.data,
         });
     }
+    /**
+     * Base success envelope from `process.exitCode` (including exit 5 = served stale / ok).
+     * Subclasses that overlay batch failures must call this — not `toSuccessJson` — to avoid
+     * recursing through their own override.
+     */
+    baseSuccessJson(data) {
+        // ponytail: the stale-serve path signals EXIT_STALE_SERVED by setting process.exitCode inside
+        // run() (e.g. fetch's handleStaleRevalidationResult); this reads it back to mark the envelope.
+        // If that signalling moves off process.exitCode, update here too. Number() normalizes Node's
+        // string codes.
+        const exitCode = Number(process.exitCode ?? EXIT_OK);
+        // EXIT_STALE_SERVED means "served stale" — a successful, usable result, so it reports ok.
+        return this.envelope({
+            ok: exitCode === EXIT_OK || exitCode === EXIT_STALE_SERVED,
+            exitCode,
+            stderr: '',
+            data,
+        });
+    }
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     toSuccessJson(data) {
-        // ponytail: the stale-serve path signals "exit 5" by setting process.exitCode inside run()
-        // (e.g. fetch's handleStaleRevalidationResult); this reads it back to mark the envelope. If that
-        // signalling moves off process.exitCode, update here too. Number() normalizes Node's string codes.
-        const exitCode = Number(process.exitCode ?? 0);
-        // Exit 5 means "served stale" — a successful, usable result, so it reports ok.
-        return this.envelope({ ok: exitCode === 0 || exitCode === 5, exitCode, stderr: '', data });
+        return this.baseSuccessJson(data);
+    }
+    /**
+     * Success overlay for multi-URL read commands (`status`, `inspect`). Apply CACHE_MISS first,
+     * then row `.error` so validation failures win when both appear in one batch.
+     */
+    batchReadSuccessJson(data) {
+        return enrichRowErrorEnvelope(enrichCacheMissEnvelope(this.baseSuccessJson(data), data, this.config.bin), data);
+    }
+    /**
+     * Map each URL through `fn`. In a multi-URL batch, per-URL CLIErrors become failure rows so
+     * prior hits are kept — matching fetch's INVALID_URL / MISSING_URL_SCHEME batch contract.
+     */
+    mapUrlsAllowingBatchErrors(urls, fn, failureRow) {
+        const batch = urls.length > 1;
+        const results = [];
+        for (const url of urls) {
+            try {
+                results.push(fn(url));
+            }
+            catch (err) {
+                if (!batch || !(err instanceof Errors.CLIError))
+                    throw err;
+                // Mirror the single-URL error format (message + Code: + Try this:) rather than a bare
+                // message, so a row failure in a batch is exactly as actionable as it is standalone.
+                if (!this.jsonEnabled())
+                    this.warn(formatErrorForJson(err));
+                results.push(failureRow(url, err));
+            }
+        }
+        return results;
     }
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     toErrorJson(err) {
-        const e = err;
-        const exitCode = BaseCommand.exitCodeOf(e);
-        const code = stableErrorCodeFrom(e);
-        const message = typeof e?.message === 'string' ? normalizeCliErrorMessage(e.message) : undefined;
-        const stderr = message || code || e?.suggestions?.length || e?.ref
-            ? formatErrorForJson({ ...e, message, code })
-            : String(err);
+        const prepared = prepareCliError(err, {
+            bin: this.config.bin,
+            command: this.envelopeCommandId(),
+        });
+        // oclif prints the returned object to stdout; error text lives in envelope.stderr only
+        // so process stderr stays clean under `--json` (CACHE_MISS / batch overlays + oclif JSON log suppression).
         return buildEnvelope({
             command: this.envelopeCommandId(),
             ok: false,
-            exitCode,
-            stderr,
+            exitCode: prepared.exitCode,
+            stderr: prepared.stderr,
             data: null,
-            code,
-            suggestions: e.suggestions?.length ? e.suggestions : undefined,
-            ref: e.ref,
+            code: prepared.code,
+            suggestions: prepared.suggestions,
+            ref: prepared.ref,
         });
     }
 }

package/dist/commands/config/base.js

@@ -1,4 +1,4 @@
-import { Flags } from '@oclif/core';
+import { Flags, toConfiguredId } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
 /**
@@ -30,15 +30,24 @@ export class ConfigCommand extends BaseCommand {
         if (!isKnownKey(keyArg)) {
             const suggestion = suggestKey(keyArg);
             const hint = suggestion ? ` Did you mean: ${suggestion}?` : '';
+            const command = this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : 'config';
             this.error(`Unknown config key: "${keyArg}".${hint} Valid keys: ${validKeysHint()}.`, {
                 exit: 2,
                 code: 'UNKNOWN_KEY',
+                suggestions: suggestion
+                    ? [`Use "${suggestion}": ${this.config.bin} ${command} ${suggestion}`]
+                    : [`Use one of: ${validKeysHint()}`],
             });
         }
     }
     requireConfigKey(key) {
         if (!key) {
-            this.error('Missing required argument: key', { exit: 2, code: 'MISSING_ARGUMENT' });
+            const command = this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : 'config';
+            this.error('Missing required argument: key', {
+                exit: 2,
+                code: 'MISSING_ARGUMENT',
+                suggestions: [`Choose a key: ${this.config.bin} ${command} storage`],
+            });
         }
         this.assertKnownKey(key);
     }

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, validKeysHint, } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntry, 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: ${validKeysHint()}.`;
+    static summary = 'Get a research configuration value';
+    static description = `Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. \`fetch --storage\`) > env var > project file > user file > built-in default.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
             description: 'get the effective storage mode',
@@ -20,8 +20,8 @@ export default class ConfigGet extends ConfigCommand {
     };
     static flags = {
         ...configScopeFlags({
-            global: 'Read from user-level config only.',
-            local: 'Read from project-level config only.',
+            global: 'read user-level config only',
+            local: 'read project-level config only',
         }),
     };
     static stdoutIsPrimaryData = true;
@@ -29,13 +29,9 @@ export default class ConfigGet extends ConfigCommand {
         const key = this.args.key;
         this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.readScope(this.flags.global, this.flags.local);
-        const value = readScopedConfig(scope, this.config.configDir, process.cwd())[key];
-        const meta = KEY_META[key];
-        const displayValue = value !== undefined ? value : BUILT_IN_DEFAULTS[key];
-        const formatted = meta.format(displayValue);
-        const suffix = value === undefined ? ' (not configured)' : '';
+        const entry = resolveConfigEntry(key, scope, this.config.configDir, process.cwd());
         if (!this.jsonEnabled())
-            this.log(formatted + suffix);
-        return { key, value: displayValue };
+            this.log(formatConfigEntry(entry, scope));
+        return entry;
     }
 }

package/dist/commands/config/index.js

@@ -2,7 +2,7 @@ import { Help, toConfiguredId } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 export default class ConfigIndex extends BaseCommand {
     static id = 'config';
-    static summary = 'Manage research cache storage configuration (global vs project).';
+    static summary = 'Manage research cache configuration';
     static description = 'Show config subcommands for reading and writing Bonsai research cache configuration.';
     static examples = [
         {
@@ -10,7 +10,7 @@ export default class ConfigIndex extends BaseCommand {
             command: '<%= config.bin %> <%= command.id %> get storage',
         },
         {
-            description: 'set a configuration value for the current project',
+            description: 'set project storage mode',
             command: '<%= config.bin %> <%= command.id %> set storage project --local',
         },
     ];

package/dist/commands/config/list.js

@@ -1,8 +1,8 @@
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntries, validKeysHint } from '../../lib/config/index.js';
 export default class ConfigList extends ConfigCommand {
     static id = 'config list';
-    static summary = 'List all research configuration keys and their effective values.';
+    static summary = 'List research configuration values';
     static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
@@ -16,28 +16,22 @@ export default class ConfigList extends ConfigCommand {
     ];
     static flags = {
         ...configScopeFlags({
-            global: 'Show user-level config only.',
-            local: 'Show project-level config only.',
+            global: 'show user-level config only',
+            local: 'show project-level config only',
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
         const scope = this.readScope(this.flags.global, this.flags.local);
-        const scoped = readScopedConfig(scope, this.config.configDir, process.cwd());
+        const entries = resolveConfigEntries(scope, this.config.configDir, process.cwd());
         if (!this.jsonEnabled()) {
-            const width = Math.max(...ALL_KEYS.map((k) => k.length)) + 2;
-            for (const key of ALL_KEYS) {
-                const raw = scoped[key];
-                const formatted = raw !== undefined ? KEY_META[key].format(raw) : '(not configured)';
-                this.log(`${key.padEnd(width)}${formatted}`);
+            const width = Math.max(...entries.map((e) => e.key.length)) + 2;
+            for (const entry of entries) {
+                this.log(`${entry.key.padEnd(width)}${formatConfigEntry(entry, scope)}`);
             }
         }
-        const values = {};
-        for (const key of ALL_KEYS) {
-            const raw = scoped[key];
-            values[key] = raw !== undefined ? raw : BUILT_IN_DEFAULTS[key];
-        }
-        return values;
+        // Bare array — same shape as `list`'s data payload; no `{ entries }` wrapper.
+        return entries;
     }
 }

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

@@ -1,4 +1,5 @@
 import { ConfigCommand } from './base.js';
+import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
     static id: string;
     static summary: string;
@@ -17,5 +18,5 @@ export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    run(): Promise<unknown>;
+    run(): Promise<ConfigWriteResult>;
 }