@taurgis/bonsai 1.0.1 → 1.0.3

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

@@ -1,19 +1,31 @@
 ---
-description: 'Require the Official Docs Researcher subagent before technical repo changes.'
+description: 'Verify current official docs before technical repo changes — inline via the web-research skill for minor research, via the Official Docs Researcher subagent for extensive research.'
 applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '3.0.0'
+  version: '3.1.0'
 ---
 
 # Web Research Requirement
 
 ## Mandatory Pre-Step
 
-- Run the **Official Docs Researcher** subagent before creating, updating, refactoring, scaffolding, or deleting technical content.
-- Use its findings to apply current official documentation and references in the change.
-- The researcher keeps a freshness-tiered Bonsai cache (its data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss. Re-running on a recent topic is cheap — invoke it rather than skipping research to "save" a fetch.
+- Verify the relevant current official documentation **in the same task** before creating, updating, refactoring, scaffolding, or deleting technical content.
+- Apply what you find — cite official source URLs when the change relies on platform behavior or standards.
+- Research is the requirement; how you run it scales with scope (below). Training-data knowledge never satisfies this — only docs fetched in the current task do.
+
+## Choose How to Research by Scope
+
+- **Minor research — run it inline.** For a single known page, one platform, or a quick flag/API/version check, the main agent invokes the **web-research** skill directly. A separate subagent is not required.
+- **Extensive research — delegate to a subagent.** For multiple sources or platforms, unfamiliar territory, broad audits, or anything that produces verbose output you do not want in the main context, run the **Official Docs Researcher** subagent and apply its findings.
+- The main agent may always use the **web-research** skill directly — choose the subagent to isolate large research, not because inline research is disallowed.
+- When unsure, start inline and escalate to the subagent once the work spans several sources.
+
+## Shared Cache
+
+- 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.
+- Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
 
 ## When Not to Use
 
@@ -23,7 +35,8 @@ metadata:
 
 ## Examples
 
-- ✅ Before editing instructions, prompts, agents, skills, workflows, or docs.
-- ✅ Before auditing or refactoring source — reading source code does not replace checking current platform guidance.
+- ✅ Confirming one platform's current flag or frontmatter field before a small edit → run the web-research skill inline.
+- ✅ Comparing conventions across several platforms, or auditing/refactoring source broadly → delegate to the Official Docs Researcher subagent.
+- ✅ Before editing instructions, prompts, agents, skills, workflows, or docs — reading source code does not replace checking current platform guidance.
 - ✅ Include official source URLs when the change references platform behavior or standards.
-- ❌ Don't modify technical content without running the subagent first, or treat cached/training knowledge as equivalent — official guidance evolves and must be verified per task.
+- ❌ 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/dist/base-command.d.ts

@@ -1,14 +1,28 @@
 import { Command, Interfaces } from '@oclif/core';
+/**
+ * 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`
+ * directly in `run()`, and wraps `--json` output in the Bonsai envelope via the
+ * framework's `toSuccessJson`/`toErrorJson` hooks.
+ */
 export declare abstract class BaseCommand<T extends typeof Command> extends Command {
-    static jsonEnvelope: boolean;
-    static baseFlags: {
-        json: Interfaces.BooleanFlag<boolean>;
-    };
-    flags: Interfaces.InferredFlags<T['flags'] & typeof BaseCommand.baseFlags>;
+    static enableJsonFlag: boolean;
+    flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
-    protected requestedJson(): boolean;
+    init(): Promise<void>;
+    /**
+     * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
+     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
+     * JSON envelope, so machine output stays clean.
+     */
+    warn(input: string | Error): string | Error;
+    /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
-    protected _run<R>(): Promise<R>;
-    abstract execute(): Promise<unknown>;
-    run(): Promise<unknown>;
+    /** 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`. */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
+    /** 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,56 +1,64 @@
-import { Command, Flags } from '@oclif/core';
+import { Command, Errors } from '@oclif/core';
+/**
+ * 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`
+ * directly in `run()`, and wraps `--json` output in the Bonsai envelope via the
+ * framework's `toSuccessJson`/`toErrorJson` hooks.
+ */
 export class BaseCommand extends Command {
-    static jsonEnvelope = false;
-    static baseFlags = {
-        json: Flags.boolean({
-            description: 'Return the output as a machine-readable JSON object.',
-        }),
-    };
+    static enableJsonFlag = true;
     flags;
     args;
-    requestedJson() {
-        return Boolean(this.flags?.json);
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse({
+            flags: this.ctor.flags,
+            enableJsonFlag: this.ctor.enableJsonFlag,
+            args: this.ctor.args,
+            strict: this.ctor.strict,
+        });
+        this.flags = flags;
+        this.args = args;
     }
+    /**
+     * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
+     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
+     * JSON envelope, so machine output stays clean.
+     */
+    warn(input) {
+        Errors.warn(input);
+        return input;
+    }
+    /** 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;
     }
-    async _run() {
-        // Check argv directly for --json because if parsing fails in init(),
-        // we still want to output the failure in the JSON envelope format.
-        const isJson = this.argv.includes('--json');
-        if (isJson) {
-            try {
-                await this.init();
-                const result = await this.run();
-                const exitCode = process.exitCode || 0;
-                console.log(JSON.stringify({
-                    schemaVersion: 1,
-                    command: this.envelopeCommandId(),
-                    ok: exitCode === 0 || exitCode === 5,
-                    exitCode,
-                    stdout: '',
-                    stderr: '',
-                    data: result,
-                }, null, 2));
-            }
-            catch (error) {
-                const exitCode = error.oclif?.exit ?? 1;
-                console.log(JSON.stringify({
-                    schemaVersion: 1,
-                    command: this.envelopeCommandId(),
-                    ok: false,
-                    exitCode,
-                    stdout: '',
-                    stderr: error.message || String(error),
-                    data: null,
-                }, null, 2));
-                process.exitCode = exitCode;
-            }
-            return undefined;
-        }
-        return super._run();
+    /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
+    envelope(parts) {
+        return {
+            schemaVersion: 1,
+            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) {
+        // 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 });
     }
-    async run() {
-        return this.execute();
+    /** 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;
+        return this.envelope({ ok: false, exitCode, stderr: e?.message ?? String(err), data: null });
     }
 }

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

@@ -15,6 +15,5 @@ export default class ConfigGet extends ConfigCommand<typeof ConfigGet> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/config/get.js

@@ -25,13 +25,7 @@ export default class ConfigGet extends ConfigCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ConfigGet);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
+    async run() {
         const key = this.args.key;
         this.assertKnownKey(key);
         this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
@@ -41,7 +35,7 @@ export default class ConfigGet extends ConfigCommand {
         const displayValue = value !== undefined ? value : BUILT_IN_DEFAULTS[key];
         const formatted = meta.format(displayValue);
         const suffix = value === undefined ? ' (not configured)' : '';
-        if (!this.requestedJson())
+        if (!this.jsonEnabled())
             this.log(formatted + suffix);
         return { key, value: displayValue };
     }

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

@@ -12,6 +12,5 @@ export default class ConfigList extends ConfigCommand<typeof ConfigList> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/config/list.js

@@ -21,16 +21,11 @@ export default class ConfigList extends ConfigCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { flags } = await this.parse(ConfigList);
-        this.flags = flags;
-    }
-    async execute() {
+    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());
-        if (!this.requestedJson()) {
+        if (!this.jsonEnabled()) {
             const width = Math.max(...ALL_KEYS.map((k) => k.length)) + 2;
             for (const key of ALL_KEYS) {
                 const raw = scoped[key];

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

@@ -17,6 +17,5 @@ export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/config/set.js

@@ -31,13 +31,7 @@ export default class ConfigSet extends ConfigCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ConfigSet);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
+    async run() {
         const { keyArg, valueArg } = splitInlineKeyValue(this.args.key, this.args.value);
         if (!keyArg) {
             this.error('Missing required argument: key', { exit: 2 });
@@ -56,7 +50,7 @@ export default class ConfigSet extends ConfigCommand {
         const scope = this.writeScope(this.flags.local);
         const formatted = meta.format(parsed);
         if (this.flags['dry-run']) {
-            if (!this.requestedJson())
+            if (!this.jsonEnabled())
                 this.log(`[dry-run] Would set ${keyArg} = ${formatted} (${scope})`);
             return { key: keyArg, value: parsed, scope, dryRun: true };
         }
@@ -73,7 +67,7 @@ export default class ConfigSet extends ConfigCommand {
             }
             writeUserConfig(configDir, patch);
         }
-        if (!this.requestedJson())
+        if (!this.jsonEnabled())
             this.log(`Set ${keyArg} = ${formatted} (${scope})`);
         return { key: keyArg, value: parsed, scope, dryRun: false };
     }

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

@@ -16,6 +16,5 @@ export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/config/unset.js

@@ -29,19 +29,13 @@ export default class ConfigUnset extends ConfigCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ConfigUnset);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
+    async run() {
         const key = this.args.key;
         this.assertKnownKey(key);
         this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
         const scope = this.writeScope(this.flags.local);
         if (this.flags['dry-run']) {
-            if (!this.requestedJson())
+            if (!this.jsonEnabled())
                 this.log(`[dry-run] Would unset ${key} (${scope})`);
             return { key, scope, dryRun: true };
         }
@@ -58,7 +52,7 @@ export default class ConfigUnset extends ConfigCommand {
             }
             writeUserConfig(configDir, patch);
         }
-        if (!this.requestedJson())
+        if (!this.jsonEnabled())
             this.log(`Unset ${key} (${scope})`);
         return { key, scope, dryRun: false };
     }

package/dist/commands/fetch.d.ts

@@ -26,7 +26,6 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     };
     static stdoutIsPrimaryData: boolean;
     protected envelopeCommandId(): string;
-    init(): Promise<void>;
     private executeCacheHit;
     private executeCacheMiss;
     private buildResultData;
@@ -34,5 +33,5 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private resolveArtifact;
     private persistFreshArtifact;
     private persistSectionsIfFresh;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/fetch.js

@@ -92,12 +92,6 @@ export default class FetchCommand extends BaseCommand {
     envelopeCommandId() {
         return this.config.bin;
     }
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(FetchCommand);
-        this.args = args;
-        this.flags = flags;
-    }
     async executeCacheHit(cached, targetDir, currentTime) {
         const { ttl, 'max-age': maxAge, 'allow-stale': allowStale, rendered } = this.flags;
         const isExpired = checkMaxAgeExpired(cached, currentTime, maxAge);
@@ -246,7 +240,7 @@ export default class FetchCommand extends BaseCommand {
             /* section generation is non-essential; ignore failures */
         }
     }
-    async execute() {
+    async run() {
         const { url } = this.args;
         const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
         this.validateDurationFlags(ttl, maxAge);
@@ -272,7 +266,7 @@ export default class FetchCommand extends BaseCommand {
             this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus);
             const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
             const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
-            if (!this.requestedJson()) {
+            if (!this.jsonEnabled()) {
                 this.log(content);
             }
             return resultData;

package/dist/commands/import.d.ts

@@ -23,7 +23,6 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
     private readStdin;
     private getSourceUrls;
     private validateSourceMode;
@@ -34,5 +33,5 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
     private readAndValidateInput;
     private deriveImportCacheKey;
     private buildImportArtifact;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/import.js

@@ -76,12 +76,6 @@ export default class ResearchImport extends BaseCommand {
         })(),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ResearchImport);
-        this.args = args;
-        this.flags = flags;
-    }
     async readStdin(limitBytes = 1024 * 1024) {
         return new Promise((resolve, reject) => {
             let data = '';
@@ -254,7 +248,7 @@ export default class ResearchImport extends BaseCommand {
             provenance: `Imported via agent-supplied research at ${currentTime.toISOString()}`,
         };
     }
-    async execute() {
+    async run() {
         const hasSingle = Boolean(this.args.url);
         const multiUrls = this.flags['source-url'] || [];
         const hasMulti = multiUrls.length > 0;
@@ -275,7 +269,7 @@ export default class ResearchImport extends BaseCommand {
         if (writeResult.redirected) {
             this.warn(`Detected ${writeResult.secretLabel} in the imported content; stored in the global cache instead of the project to avoid committing secrets.`);
         }
-        if (!this.requestedJson()) {
+        if (!this.jsonEnabled()) {
             this.log(`Successfully imported research artifact.`);
             this.log(`Cache Key: ${cacheKey}`);
             this.log(`Storage Path: ${storagePath}`);

package/dist/commands/inspect.d.ts

@@ -7,7 +7,6 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
     private findSections;
 }

package/dist/commands/inspect.js

@@ -13,12 +13,7 @@ export default class ResearchInspect extends BaseCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args } = await this.parse(ResearchInspect);
-        this.args = args;
-    }
-    async execute() {
+    async run() {
         const { url } = this.args;
         let target;
         try {
@@ -39,7 +34,7 @@ export default class ResearchInspect extends BaseCommand {
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
-        if (!this.requestedJson()) {
+        if (!this.jsonEnabled()) {
             this.log(`Cache Key: ${cacheKey}`);
             this.log(`Cache Path: ${artifactPath}`);
             this.log(`--- Metadata ---`);

package/dist/commands/list.d.ts

@@ -16,10 +16,9 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
     private validateListFlags;
     private matchesFilters;
     private scanCacheDirForList;
     private logListResults;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/list.js

@@ -49,11 +49,6 @@ export default class ResearchList extends BaseCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { flags } = await this.parse(ResearchList);
-        this.flags = flags;
-    }
     validateListFlags() {
         const limit = this.flags.limit;
         if (limit !== undefined && (limit < 1 || limit > 100)) {
@@ -107,7 +102,7 @@ export default class ResearchList extends BaseCommand {
         });
     }
     logListResults(finalResults) {
-        if (this.requestedJson())
+        if (this.jsonEnabled())
             return;
         if (finalResults.length === 0) {
             this.log('No cached research entries found matching filters.');
@@ -121,7 +116,7 @@ export default class ResearchList extends BaseCommand {
             this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);
         });
     }
-    async execute() {
+    async run() {
         this.validateListFlags();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,

package/dist/commands/prune.d.ts

@@ -15,10 +15,9 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
     private validatePruneFlags;
     private shouldPrune;
     private findPruneCandidates;
     private deletePruneCandidates;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/prune.js

@@ -41,11 +41,6 @@ export default class ResearchPrune extends BaseCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { flags } = await this.parse(ResearchPrune);
-        this.flags = flags;
-    }
     validatePruneFlags() {
         if (!this.flags['older-than'] && !this.flags.inactive && !this.flags['artifact-type']) {
             this.error('Must specify at least one pruning filter: --older-than, --inactive, or --artifact-type.', { exit: 2 });
@@ -103,7 +98,7 @@ export default class ResearchPrune extends BaseCommand {
         }
         return prunedCount;
     }
-    async execute() {
+    async run() {
         this.validatePruneFlags();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
@@ -115,7 +110,7 @@ export default class ResearchPrune extends BaseCommand {
         const dryRun = this.flags['dry-run'];
         const count = filesToPrune.length;
         if (dryRun) {
-            if (!this.requestedJson()) {
+            if (!this.jsonEnabled()) {
                 this.log(`[Dry Run] Found ${count} research cache entries that would be pruned:\n`);
                 filesToPrune.forEach((f) => {
                     this.log(`- [${f.topic || 'No Topic'}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
@@ -124,7 +119,7 @@ export default class ResearchPrune extends BaseCommand {
         }
         else {
             const prunedCount = this.deletePruneCandidates(filesToPrune);
-            if (!this.requestedJson()) {
+            if (!this.jsonEnabled()) {
                 this.log(`Successfully pruned ${prunedCount} of ${count} research cache entries.`);
             }
         }

package/dist/commands/search.d.ts

@@ -16,7 +16,6 @@ export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
         remote: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
     private validateSearchFlags;
     private getSearchQueryTerms;
     private matchesFilters;
@@ -28,5 +27,5 @@ export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
     private printResults;
     private executeSiteSearch;
     private executeRemoteSearch;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/search.js

@@ -58,12 +58,6 @@ export default class ResearchSearch extends BaseCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ResearchSearch);
-        this.args = args;
-        this.flags = flags;
-    }
     validateSearchFlags() {
         const limit = this.flags.limit;
         if (limit !== undefined && (limit < 1 || limit > 50)) {
@@ -187,7 +181,7 @@ export default class ResearchSearch extends BaseCommand {
         });
     }
     logSearchResults(finalResults) {
-        if (this.requestedJson())
+        if (this.jsonEnabled())
             return;
         this.log(`Found ${finalResults.length} matching cached research entries:\n`);
         finalResults.forEach((res, index) => {
@@ -200,7 +194,7 @@ export default class ResearchSearch extends BaseCommand {
     // Prints a numbered result list to stdout for human (non-JSON) output. Shared by site and remote
     // search so the two paths can't drift in formatting.
     printResults(heading, results) {
-        if (this.requestedJson())
+        if (this.jsonEnabled())
             return;
         this.log(heading);
         results.forEach((r, i) => {
@@ -235,7 +229,7 @@ export default class ResearchSearch extends BaseCommand {
             return undefined;
         }
     }
-    async execute() {
+    async run() {
         const { query } = this.args;
         const { domain, remote } = this.flags;
         if (domain) {

package/dist/commands/status.d.ts

@@ -12,6 +12,5 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
+    run(): Promise<unknown>;
 }

package/dist/commands/status.js

@@ -43,13 +43,7 @@ export default class ResearchStatus extends BaseCommand {
         }),
     };
     static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ResearchStatus);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
+    async run() {
         const { url } = this.args;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
         let target;
@@ -76,7 +70,7 @@ export default class ResearchStatus extends BaseCommand {
         }
         // On a hit, report where it actually lives; on a miss, where a fetch would write it.
         const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
-        if (!this.requestedJson()) {
+        if (!this.jsonEnabled()) {
             this.log(`URL: ${normalizedUrl}`);
             this.log(`Cache Key: ${cacheKey}`);
             this.log(`Cache Path: ${artifactPath}`);

package/dist/lib/research/docs/validate.js

@@ -6,6 +6,9 @@ const ERROR_PAGE_PATTERNS = [
     /\bnot\s*found\b/i,
     /there\s*isn'?t\s*a\s*github\s*pages\s*site\s*here/i,
     /site\s*not\s*found/i,
+    // Client-rendered (SPA) failure shells that return HTTP 200 but render only an error notice.
+    /something\s+went\s+wrong/i,
+    /an?\s+error\s+occurred/i,
 ];
 /** True when short text reads like an error/soft-404 page rather than real content. */
 export function looksLikeErrorPage(text) {

package/dist/lib/research/revalidate.js

@@ -7,6 +7,7 @@ import { evaluateFreshness, getPolicy } from './freshness.js';
 import { compressMarkdown } from './compress.js';
 import { estimateTokens } from './token-estimate.js';
 import { fetchRenderedHtml } from './browser.js';
+import { looksLikeErrorPage } from './docs/validate.js';
 function buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed) {
     const contentHash = createHash('sha256').update(extraction.detailedMarkdown).digest('hex');
     const staleAfterTime = new Date(currentTime);
@@ -51,10 +52,39 @@ function buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, ti
         section_heading_path: null,
     };
 }
+// Builds a compact error marker instead of caching a full error page. Subsequent lookups serve this
+// tiny marker (a handful of tokens) instead of re-fetching, and revalidation re-checks it when stale
+// so a transient failure recovers into a real artifact.
+function buildErrorArtifact(url, normalizedUrl, cacheKey, fetchResult, tier, ttl, currentTime, reason) {
+    const marker = `Error: ${url} could not be cached — ${reason}. ` +
+        'The page returned an error, so its content was not stored; it will be re-fetched when this entry goes stale.';
+    const extraction = {
+        title: `Error: ${reason}`,
+        detailedMarkdown: marker,
+        confidence: 'low',
+        qualityNotes: [`error: ${reason}`],
+    };
+    const metadata = buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, marker);
+    metadata.extraction_status = 'failed';
+    metadata.extraction_confidence = null;
+    return {
+        metadata,
+        summary: extraction.title,
+        compressed: marker,
+        detailed: marker,
+        provenance: `Fetched from ${url} on ${currentTime.toISOString()} (error page; content not cached)`,
+    };
+}
 /**
  * Helper to construct a ResearchArtifact from a fresh HTML fetch.
  */
 export function createArtifactFromFetch(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime) {
+    // A managed platform / SPA can return HTTP 200 but render only a "not found" / "something went
+    // wrong" shell. Cache a compact marker for those instead of the full error markdown, so repeat
+    // lookups cost a few tokens and revalidation still re-checks the page when the entry goes stale.
+    if (looksLikeErrorPage(extraction.detailedMarkdown)) {
+        return buildErrorArtifact(url, normalizedUrl, cacheKey, fetchResult, tier, ttl, currentTime, 'page reported an error or was not found');
+    }
     const compressed = compressMarkdown(extraction.detailedMarkdown);
     const metadata = buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed);
     return {

package/dist/lib/research/storage.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, renameSync, } from 'node:fs';
 import { atomicWriteFile } from '../atomic-write.js';
 import { parseArtifact, serializeArtifact } from './artifact.js';
 function isResearchFile(file) {

package/oclif.manifest.json

@@ -22,7 +22,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -129,8 +130,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "An advanced, locally cached web research tool optimized for LLM ingestion.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "import": {
@@ -159,7 +159,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -253,8 +254,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Import agent-supplied clean Markdown notes into the local cache.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "inspect": {
@@ -269,7 +269,8 @@
       "description": "Inspects local storage and displays full frontmatter metadata for the URL (without printing the content body).",
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -283,8 +284,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Inspect cached research metadata for a URL.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "list": {
@@ -307,7 +307,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -380,8 +381,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "List cached research artifacts by metadata filters.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "prune": {
@@ -400,7 +400,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -452,8 +453,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Clean up old or inactive research cache entries.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "search": {
@@ -468,7 +468,8 @@
       "description": "Scans the local research cache database and ranks matching entries based on topic, tags, source URLs, summary, and content.",
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -539,8 +540,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Search locally cached research artifacts by keywords.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "status": {
@@ -555,7 +555,8 @@
       "description": "Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.",
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -597,8 +598,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Check the cache status of a URL without fetching or writing.",
-      "enableJsonFlag": false,
-      "jsonEnvelope": false,
+      "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
     "config:get": {
@@ -623,7 +623,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -674,7 +675,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -736,7 +738,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -799,7 +802,8 @@
       ],
       "flags": {
         "json": {
-          "description": "Return the output as a machine-readable JSON object.",
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
@@ -841,5 +845,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "1.0.1"
+  "version": "1.0.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,7 @@
     "regression:suite": "tsc -b && node testing/regression/run-suite.mjs",
     "regression:promote": "tsc -b && node testing/regression/run-suite.mjs --promote",
     "regression:check": "tsc -b && node testing/regression/run-suite.mjs --strict",
+    "nexus:sync": "npx forward-nexus update && npx forward-nexus sync",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
     "type-check": "tsc --noEmit"