@taurgis/bonsai 1.0.5 → 1.0.6

package/README.md

@@ -180,6 +180,35 @@ Both keys can also be overridden per-invocation via the `BONSAI_STORAGE` and `BO
 
 ---
 
+## Shell Autocomplete
+
+Bonsai ships with shell autocomplete via `@oclif/plugin-autocomplete`. After installing globally, set it up once for your shell:
+
+```bash
+# Bash — add to ~/.bashrc
+eval "$(bonsai autocomplete bash)"
+
+# Zsh — add to ~/.zshrc
+eval "$(bonsai autocomplete zsh)"
+
+# Fish
+bonsai autocomplete fish > ~/.config/fish/completions/bonsai.fish
+```
+
+To see full setup instructions including the copy-paste snippet for your shell:
+
+```bash
+bonsai autocomplete
+```
+
+Refresh cached completions after upgrading:
+
+```bash
+bonsai autocomplete --refresh-cache
+```
+
+---
+
 ## Freshness and Cache Rules
 
 Global cache files live in Bonsai's oclif data directory, typically:
@@ -246,6 +275,30 @@ When run with `--json`, commands return a stable envelope:
 
 ---
 
+## Environment Variables
+
+| Variable | Effect |
+| --- | --- |
+| `BONSAI_STORAGE` | Override the default storage location per-invocation (`global` or `project`). |
+| `BONSAI_SUMMARY` | Override the summary compression level per-invocation (`conservative`, `balanced`, or `aggressive`). |
+| `NO_COLOR` | Disable all ANSI color output (also respected via `TERM=dumb`). |
+| `NO_UPDATE_NOTIFIER` | Suppress the "update available" notification. |
+| `CI` | Set to `1` or `true` to suppress the update notification in CI environments (detected automatically). |
+| `DEBUG` | Enable debug output for specific Bonsai namespaces, e.g. `DEBUG=bonsai:*`. |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Runtime failure (network error, fetch failed, file read error). |
+| `2` | Usage error (invalid flag, bad URL, missing required argument). |
+| `5` | Stale content served — the cache entry is past its grace window but `--allow-stale` is set. The returned content is still usable. |
+
+---
+
 ## Security and Limits
 
 * Fetched HTML is treated as untrusted input.

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

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What topic should I research in official docs?'
 metadata:
-  version: '3.0.0'
+  version: '3.0.1'
 ---
 
 # Official Docs Researcher Agent
@@ -24,7 +24,16 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 2. Search the Bonsai cache first:
 
    ```bash
+   # 1. Default search: Checks the local cache across EVERYTHING you've researched, 
+   # including domains that do not support online search APIs.
    bonsai search "<topic or keywords>"
+   
+   # 2. Remote API search: Use this to quickly find URLs for documentation pages online
+   # ONLY if you don't find any information in the local cache.
+   bonsai search "<topic or keywords>" --domain <domain>
+   # Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org,
+   # jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org,
+   # vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
    ```
 
 3. If the cache misses or does not cover the question, locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes.

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

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What Salesforce topic should I research in official docs?'
 metadata:
-  version: '1.0.0'
+  version: '1.0.1'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -24,7 +24,16 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 2. Search the Bonsai cache first:
 
    ```bash
+   # 1. Default search: Checks the local cache across EVERYTHING you've researched, 
+   # including domains that do not support online search APIs.
    bonsai search "<topic or keywords>"
+   
+   # 2. Remote API search: Use this to quickly find URLs for documentation pages online
+   # ONLY if you don't find any information in the local cache.
+   bonsai search "<topic or keywords>" --domain <domain>
+   # Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org,
+   # jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org,
+   # vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
    ```
 
 3. If the cache misses or does not cover the question, locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes.

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

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '1.0.1'
+  version: '1.0.2'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -24,9 +24,11 @@ metadata:
 
 ## Shared Cache
 
-- Both paths use the same freshness-tiered Bonsai cache (data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss.
+- **Local Cache Search (Default)**: Always search the local cache first using `bonsai search "<query>"`. This checks everything you've researched across all domains, even ones that don't support online search APIs.
+- **Online URL Discovery (Fallback)**: If the local cache comes up empty, use `--domain <domain>` or `--remote <docs-url>` to quickly hit a site's search API and find the official URLs you need to fetch. This is specifically for online URL discovery when local cache fails.
 - If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
 - Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
+- Supported remote API domains: `help.salesforce.com`, `react.dev`, `vuejs.org`, `tailwindcss.com`, `nextjs.org`, `jestjs.io`, `cypress.io`, `vitest.dev`, `vitepress.dev`, `angular.dev`, `redux.js.org`, `vitejs.dev`, `fastify.dev`, `rollupjs.org`, `vueuse.org`.
 
 ## Working with Salesforce Sites
 

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

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '3.1.1'
+  version: '3.1.2'
 ---
 
 # Web Research Requirement
@@ -24,9 +24,11 @@ metadata:
 
 ## Shared Cache
 
-- Both paths use the same freshness-tiered Bonsai cache (data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss.
+- **Local Cache Search (Default)**: Always search the local cache first using `bonsai search "<query>"`. This checks everything you've researched across all domains, even ones that don't support online search APIs.
+- **Online URL Discovery (Fallback)**: If the local cache comes up empty, use `--domain <domain>` or `--remote <docs-url>` to quickly hit a site's search API and find the official URLs you need to fetch. This is specifically for online URL discovery when local cache fails.
 - If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
 - Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
+- Supported remote API domains: `help.salesforce.com`, `react.dev`, `vuejs.org`, `tailwindcss.com`, `nextjs.org`, `jestjs.io`, `cypress.io`, `vitest.dev`, `vitepress.dev`, `angular.dev`, `redux.js.org`, `vitejs.dev`, `fastify.dev`, `rollupjs.org`, `vueuse.org`.
 
 ## When Not to Use
 

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

@@ -4,7 +4,7 @@ description: 'Bonsai-backed official documentation and web research workflow. Us
 license: Forward Proprietary
 compatibility: VS Code 1.x+, GitHub Copilot
 metadata:
-  version: '2.1.0'
+  version: '2.1.1'
 ---
 
 # Web Research Skill
@@ -15,10 +15,15 @@ Use Bonsai as the cache-first research path for official documentation and web c
 
 Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
 
-Search the cache first:
-
 ```bash
+# 1. Default search: Checks the local cache across EVERYTHING you've researched, 
+# including domains that do not support online search APIs.
 bonsai search "<topic or keywords>"
+
+# 2. Remote API search: Use this to quickly find URLs for documentation pages online
+# ONLY if you don't find any information in the local cache.
+bonsai search "<topic or keywords>" --domain <domain>
+# Supported domains: help.salesforce.com, react.dev, vuejs.org, tailwindcss.com, nextjs.org, jestjs.io, cypress.io, vitest.dev, vitepress.dev, angular.dev, redux.js.org, vitejs.dev, fastify.dev, rollupjs.org, vueuse.org
 ```
 
 If the cache misses or does not cover the question, fetch the source through Bonsai:

package/bin/cli.mjs

@@ -3,6 +3,14 @@
 import { execute } from '@oclif/core';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import updateNotifier from 'update-notifier';
+import { createRequire } from 'node:module';
+
+import { normalizeArgv } from '../dist/lib/argv.js';
+import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
+
+const req = createRequire(import.meta.url);
+const pkg = req('../package.json');
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -12,19 +20,28 @@ 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 [firstArg, ...restArgv] = rawArgv;
-// 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']
-    : looksLikeUrl
-      ? ['fetch', ...rawArgv]
-      : rawArgv;
-
-process.argv = [process.argv[0], process.argv[1], ...normalizedArgv];
+const result = normalizeArgv(rawArgv);
+
+if (result.exitWithJson) {
+  process.exitCode = result.exitWithJson.exitCode;
+  console.log(JSON.stringify(result.exitWithJson.envelope, null, 2));
+  process.exit();
+}
+
+const jsonMeta = await tryJsonMetaOutput(result.argv, __dirname + '/../');
+if (jsonMeta) {
+  process.exitCode = jsonMeta.exitCode;
+  console.log(JSON.stringify(jsonMeta.envelope, null, 2));
+  process.exit();
+}
+
+// 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.
+if (!process.argv.includes('--json')) {
+  updateNotifier({ pkg }).notify();
+}
+
+process.argv = [process.argv[0], process.argv[1], ...result.argv];
 
 await execute({
   development: false,

package/dist/base-command.d.ts

@@ -1,4 +1,5 @@
 import { Command, Interfaces } from '@oclif/core';
+import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from './lib/research/resolve-target.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`
@@ -39,6 +40,8 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
+    /** Resolve a URL against the research cache, exiting with INVALID_URL on normalization failure. */
+    protected resolveResearchTargetOrFail(url: string, extra?: Pick<ResolveResearchTargetOptions, 'flagOverride' | 'lookup'>): ResolvedResearchTarget;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     private envelope;
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */

package/dist/base-command.js

@@ -1,5 +1,7 @@
-import { Command, Errors } from '@oclif/core';
+import { Command, Errors, toConfiguredId } from '@oclif/core';
 import { invalidEnvOverrideWarnings } from './lib/config/index.js';
+import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
+import { resolveResearchTarget, } from './lib/research/resolve-target.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`
@@ -53,24 +55,41 @@ export class BaseCommand extends Command {
      * the shared resolver so the framework's `??` keeps it, then defer to the default behavior.
      */
     async catch(err) {
+        // Parse failures throw before `this.parse()` sets `parsed`, which makes oclif emit a spurious
+        // [UnparsedCommand] warning to stderr even under `--json`. CLIParseError subclasses carry `parse`.
+        if (err && typeof err === 'object' && 'parse' in err)
+            this.parsed = true;
         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;
+        return this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : this.config.bin;
+    }
+    /** Resolve a URL against the research cache, exiting with INVALID_URL on normalization failure. */
+    resolveResearchTargetOrFail(url, extra) {
+        try {
+            return resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                url,
+                ...extra,
+            });
+        }
+        catch (err) {
+            this.error(`Invalid URL: ${err.message}`, { exit: 2, code: 'INVALID_URL' });
+        }
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     envelope(parts) {
-        return {
-            schemaVersion: 1,
+        return buildEnvelope({
             command: this.envelopeCommandId(),
             ok: parts.ok,
             exitCode: parts.exitCode,
-            stdout: '',
             stderr: parts.stderr,
             data: parts.data,
-        };
+        });
     }
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     toSuccessJson(data) {
@@ -85,6 +104,20 @@ export class BaseCommand extends Command {
     toErrorJson(err) {
         const e = err;
         const exitCode = BaseCommand.exitCodeOf(e);
-        return this.envelope({ ok: false, exitCode, stderr: e?.message ?? String(err), data: null });
+        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);
+        return buildEnvelope({
+            command: this.envelopeCommandId(),
+            ok: false,
+            exitCode,
+            stderr,
+            data: null,
+            code,
+            suggestions: e.suggestions?.length ? e.suggestions : undefined,
+            ref: e.ref,
+        });
     }
 }

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

@@ -12,6 +12,8 @@ export declare abstract class ConfigCommand<T extends typeof Command> extends Ba
     /** Read scope for get/list: an explicit `--global`/`--local`, else the merged effective view. */
     protected readScope(global?: boolean, local?: boolean): ConfigScope;
     protected assertKnownKey(keyArg: string): asserts keyArg is ConfigKey;
+    protected requireConfigKey(key: string | undefined): asserts key is ConfigKey;
+    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: {

package/dist/commands/config/base.js

@@ -8,7 +8,10 @@ import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {
         if (global && local) {
-            this.error('--global and --local are mutually exclusive.', { exit: 2 });
+            this.error('--global and --local are mutually exclusive.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+            });
         }
     }
     /** `--local` writes/reads the project file; otherwise the user-level file. */
@@ -29,9 +32,20 @@ export class ConfigCommand extends BaseCommand {
             const hint = suggestion ? ` Did you mean: ${suggestion}?` : '';
             this.error(`Unknown config key: "${keyArg}".${hint} Valid keys: ${validKeysHint()}.`, {
                 exit: 2,
+                code: 'UNKNOWN_KEY',
             });
         }
     }
+    requireConfigKey(key) {
+        if (!key) {
+            this.error('Missing required argument: key', { exit: 2, code: 'MISSING_ARGUMENT' });
+        }
+        this.assertKnownKey(key);
+    }
+    validateConfigKeyAndScope(key, global, local) {
+        this.requireConfigKey(key);
+        this.assertScopeFlagsExclusive(global, local);
+    }
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
 export function configScopeFlags(descriptions) {

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

@@ -8,7 +8,7 @@ export default class ConfigGet extends ConfigCommand<typeof ConfigGet> {
         command: string;
     }[];
     static args: {
-        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         global: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/config/get.js

@@ -7,16 +7,16 @@ export default class ConfigGet extends ConfigCommand {
     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',
+            description: 'get the effective storage mode',
             command: '<%= config.bin %> config get storage',
         },
         {
-            description: 'Read only the project-level value',
+            description: 'read only the project-level value',
             command: '<%= config.bin %> config get storage --local',
         },
     ];
     static args = {
-        key: Args.string({ required: true, description: 'The configuration key to read.' }),
+        key: Args.string({ required: false, description: 'the configuration key to read' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -27,8 +27,7 @@ export default class ConfigGet extends ConfigCommand {
     static stdoutIsPrimaryData = true;
     async run() {
         const key = this.args.key;
-        this.assertKnownKey(key);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        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];

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

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ConfigIndex extends BaseCommand<typeof ConfigIndex> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static stdoutIsPrimaryData: boolean;
+    run(): Promise<unknown>;
+}

package/dist/commands/config/index.js

@@ -0,0 +1,34 @@
+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 description = 'Show config subcommands for reading and writing Bonsai research cache configuration.';
+    static examples = [
+        {
+            description: 'get a configuration value',
+            command: '<%= config.bin %> <%= command.id %> get storage',
+        },
+        {
+            description: 'set a configuration value for the current project',
+            command: '<%= config.bin %> <%= command.id %> set storage project --local',
+        },
+    ];
+    static stdoutIsPrimaryData = true;
+    async run() {
+        if (!this.jsonEnabled()) {
+            await new Help(this.config, this.config.pjson.oclif.helpOptions ?? {}).showHelp(['config']);
+        }
+        const commands = this.config.commands
+            .filter((c) => c.id.startsWith('config:') && !c.hidden)
+            .map((c) => ({
+            id: toConfiguredId(c.id, this.config),
+            summary: c.summary || c.description || '',
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+        return {
+            topic: 'config',
+            commands,
+        };
+    }
+}

package/dist/commands/config/list.js

@@ -6,11 +6,11 @@ export default class ConfigList extends ConfigCommand {
     static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
-            description: 'Show all effective config values',
+            description: 'show all effective config values',
             command: '<%= config.bin %> config list',
         },
         {
-            description: 'Show only project-level config',
+            description: 'show only project-level config',
             command: '<%= config.bin %> config list --local',
         },
     ];

package/dist/commands/config/set.js

@@ -8,17 +8,17 @@ export default class ConfigSet extends ConfigCommand {
         `Valid keys: ${validKeysHint()}. The inline form \`<key>=<value>\` is also accepted.`;
     static examples = [
         {
-            description: 'Store research cache inside the current project',
+            description: 'store research cache inside the current project',
             command: '<%= config.bin %> config set storage project --local',
         },
         {
-            description: 'Set the user-level default using the inline key=value form',
+            description: 'set the user-level default using the inline key=value form',
             command: '<%= config.bin %> config set storage=global',
         },
     ];
     static args = {
-        key: Args.string({ required: false, description: 'The configuration key to set.' }),
-        value: Args.string({ required: false, description: 'The value to assign.' }),
+        key: Args.string({ required: false, description: 'the configuration key to set' }),
+        value: Args.string({ required: false, description: 'the value to assign' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -26,26 +26,28 @@ export default class ConfigSet extends ConfigCommand {
             local: 'Write to project-level config (.bonsai.json in cwd).',
         }),
         'dry-run': Flags.boolean({
-            description: 'Show what would be written without saving.',
+            description: 'show what would be written without saving',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const { keyArg, valueArg } = splitInlineKeyValue(this.args.key, this.args.value);
-        if (!keyArg) {
-            this.error('Missing required argument: key', { exit: 2 });
-        }
-        this.assertKnownKey(keyArg);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        this.validateConfigKeyAndScope(keyArg, this.flags.global, this.flags.local);
         const meta = KEY_META[keyArg];
         if (valueArg === undefined) {
-            this.error(`Missing required argument: value for key "${keyArg}"`, { exit: 2 });
+            this.error(`Missing required argument: value for key "${keyArg}"`, {
+                exit: 2,
+                code: 'MISSING_ARGUMENT',
+            });
         }
         const parsed = meta.parseValue(valueArg);
         if (!meta.isValid(parsed)) {
             const guidance = meta.values ? `Valid values: ${meta.values.join(', ')}.` : meta.description;
-            this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, { exit: 2 });
+            this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, {
+                exit: 2,
+                code: 'INVALID_VALUE',
+            });
         }
         const scope = this.writeScope(this.flags.local);
         const formatted = meta.format(parsed);
@@ -63,6 +65,10 @@ export default class ConfigSet extends ConfigCommand {
             if (!configDir) {
                 this.error('Could not determine user config directory. Use --local to write project config.', {
                     exit: 1,
+                    code: 'CONFIG_DIR_UNAVAILABLE',
+                    suggestions: [
+                        `Write project config instead: ${this.config.bin} config set <key> <value> --local`,
+                    ],
                 });
             }
             writeUserConfig(configDir, patch);

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

@@ -8,7 +8,7 @@ export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
         command: string;
     }[];
     static args: {
-        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/config/unset.js

@@ -7,16 +7,16 @@ export default class ConfigUnset extends ConfigCommand {
     static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
-            description: 'Remove the user-level storage setting',
+            description: 'remove the user-level storage setting',
             command: '<%= config.bin %> config unset storage',
         },
         {
-            description: 'Remove the project-level storage setting',
+            description: 'remove the project-level storage setting',
             command: '<%= config.bin %> config unset storage --local',
         },
     ];
     static args = {
-        key: Args.string({ required: true, description: 'The configuration key to remove.' }),
+        key: Args.string({ required: false, description: 'the configuration key to remove' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -24,15 +24,14 @@ export default class ConfigUnset extends ConfigCommand {
             local: 'Remove from project-level config (.bonsai.json in cwd).',
         }),
         'dry-run': Flags.boolean({
-            description: 'Show what would be removed without saving.',
+            description: 'show what would be removed without saving',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const key = this.args.key;
-        this.assertKnownKey(key);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.writeScope(this.flags.local);
         if (this.flags['dry-run']) {
             if (!this.jsonEnabled())
@@ -48,6 +47,10 @@ export default class ConfigUnset extends ConfigCommand {
             if (!configDir) {
                 this.error('Could not determine user config directory. Use --local to remove project config.', {
                     exit: 1,
+                    code: 'CONFIG_DIR_UNAVAILABLE',
+                    suggestions: [
+                        `Remove project config instead: ${this.config.bin} config unset ${key} --local`,
+                    ],
                 });
             }
             writeUserConfig(configDir, patch);