@taurgis/bonsai 3.0.3 → 3.2.0

package/README.md

@@ -112,6 +112,7 @@ Common flags:
 * `--dry-run`: Scrape and validate without writing to cache.
 * `--allow-stale`: Serve stale cache if the remote site is offline.
 * `--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 already expose `--dry-run` (`fetch`, `prune`, `config set`/`unset`) treat it the same as an explicit `--dry-run`; `import` (which has no `--dry-run` of its own) previews the write and reports `dryRun: true` instead of persisting.
+
 ---
 
 ## Shell Autocomplete
@@ -273,6 +286,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. |

package/dist/base-command.d.ts

@@ -8,6 +8,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,6 +28,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;
+    /**
+     * 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.
+     */
+    protected effectiveDryRun(explicitDryRun: boolean): 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

package/dist/base-command.js

@@ -1,5 +1,5 @@
-import { Command, Errors, toConfiguredId } from '@oclif/core';
-import { invalidEnvOverrideWarnings } from './lib/config/index.js';
+import { Command, Errors, Flags, toConfiguredId } from '@oclif/core';
+import { invalidEnvOverrideWarnings, resolveReadOnly } from './lib/config/index.js';
 import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
 import { looksLikeSchemelessUrl } from './lib/research/url.js';
@@ -11,6 +11,20 @@ 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: 'Block all filesystem writes/deletes (cache and config); network fetches still run. ' +
+                'Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.',
+        }),
+    };
     flags;
     args;
     parsedArgv;
@@ -18,6 +32,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,6 +56,21 @@ 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 });
+    }
+    /**
+     * 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.
+     */
+    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;
+    }
     /**
      * 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

package/dist/commands/config/set.js

@@ -51,7 +51,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.effectiveDryRun(this.flags['dry-run'])) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would set ${keyArg} = ${formatted} (${scope})`);
             return { key: keyArg, value: parsed, scope, dryRun: true };

package/dist/commands/config/unset.js

@@ -33,7 +33,7 @@ export default class ConfigUnset extends ConfigCommand {
         const key = this.args.key;
         this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.writeScope(this.flags.local);
-        if (this.flags['dry-run']) {
+        if (this.effectiveDryRun(this.flags['dry-run'])) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would unset ${key} (${scope})`);
             return { key, scope, dryRun: true };

package/dist/commands/fetch.js

@@ -15,6 +15,7 @@ import { capturePage } from '../lib/research/capture.js';
 import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { detectSite } from '../sites/index.js';
+import { applySiteFetchProvenance } from '../sites/types.js';
 const CAPTURE_DEPS = {
     fetchStatic: (url) => fetchStaticHtml(url),
     fetchRendered: (url) => fetchRenderedHtml(url),
@@ -124,9 +125,11 @@ export default class FetchCommand extends BaseCommand {
         let fetchResult;
         let extraction;
         let capture = null;
+        let siteFetch = null;
         if (siteModule?.fetchPage) {
             // Custom site modules own their fetch/extract strategy; the generic capture path is skipped.
-            ({ fetchResult, extraction } = await siteModule.fetchPage(normalizedUrl));
+            siteFetch = await siteModule.fetchPage(normalizedUrl);
+            ({ fetchResult, extraction } = siteFetch);
         }
         else {
             capture = await capturePage(normalizedUrl, { forceRendered: useRendered }, CAPTURE_DEPS);
@@ -140,6 +143,9 @@ export default class FetchCommand extends BaseCommand {
         if (capture) {
             applyCaptureMetadata(artifact, capture);
         }
+        else if (siteFetch?.captureMethod) {
+            applySiteFetchProvenance(artifact.metadata, siteFetch);
+        }
         else if (useRendered) {
             artifact.metadata.capture_method = 'browser_fallback';
         }
@@ -264,8 +270,9 @@ export default class FetchCommand extends BaseCommand {
     }
     async run() {
         const urls = this.parsedArgv;
-        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
+        const { format, ttl, 'max-age': maxAge } = this.flags;
         this.validateDurationFlags(ttl, maxAge);
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
         const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();

package/dist/commands/import.js

@@ -343,13 +343,16 @@ export default class ResearchImport extends BaseCommand {
             dataDir: this.config.dataDir,
             flagOverride: this.flags.storage,
         });
-        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact);
+        const dryRun = this.effectiveDryRun(false);
+        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact, { dryRun });
         const storagePath = getArtifactPath(writeResult.dataDir, cacheKey);
         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.jsonEnabled()) {
-            this.log(`Successfully imported research artifact.`);
+            this.log(dryRun
+                ? `[dry-run] Would import research artifact.`
+                : `Successfully imported research artifact.`);
             this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
             this.log(`${'Storage Path:'.padEnd(25)} ${storagePath}`);
         }
@@ -357,9 +360,10 @@ export default class ResearchImport extends BaseCommand {
         return {
             schemaVersion: 1,
             command: 'import',
+            dryRun,
             cache: {
                 key: cacheKey,
-                status: 'imported',
+                status: dryRun ? 'would_import' : 'imported',
                 freshness: 'fresh',
                 path: storagePath,
                 storage: roots.mode,

package/dist/commands/prune.js

@@ -68,10 +68,21 @@ export default class ResearchPrune extends BaseCommand {
                 ],
             });
         }
+        // Checked before the generic --dry-run/--yes conflict below so a combination like
+        // `--dry-run --yes --read-only` reports the more specific READ_ONLY_MODE code, not
+        // CONFLICTING_FLAGS — read-only mode is the more fundamental constraint being violated.
+        if (this.readOnly && this.flags.yes) {
+            this.error('--yes cannot be used while read-only mode is active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): mutations are disabled.', {
+                exit: 2,
+                code: 'READ_ONLY_MODE',
+                suggestions: [`Preview instead: ${this.config.bin} prune --dry-run`],
+            });
+        }
         if (this.flags['dry-run'] && this.flags.yes) {
             this.error('--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.', { exit: 2, code: 'CONFLICTING_FLAGS' });
         }
-        if (!this.flags['dry-run'] && !this.flags.yes) {
+        // Read-only mode implicitly previews, so the usual "pick one" safety check is redundant here.
+        if (!this.readOnly && !this.flags['dry-run'] && !this.flags.yes) {
             const olderThanPart = this.flags['older-than']
                 ? ` --older-than ${this.flags['older-than']}`
                 : '';
@@ -155,7 +166,7 @@ export default class ResearchPrune extends BaseCommand {
         });
         const currentTime = new Date();
         const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
-        const dryRun = this.flags['dry-run'];
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
         const count = filesToPrune.length;
         // Track deletions actually performed so the JSON envelope and human output agree even when an
         // unlink fails (e.g. a permission error). Reporting candidate count as `prunedCount` would

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

@@ -1,6 +1,6 @@
 export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
 export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
-export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.js';
+export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, type ResolveReadOnlyInput, } from './resolve.js';
 import type { ConfigValues, ResolvedConfig, StorageMode, SummaryLevel } from './schema.js';
 /**
  * Read both config files once and resolve the effective storage mode.

package/dist/lib/config/index.js

@@ -1,6 +1,6 @@
 export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
 export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
-export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, } from './resolve.js';
+export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
 import { resolveStorageMode, resolveSummaryLevel } from './resolve.js';
 /**

package/dist/lib/config/resolve.d.ts

@@ -2,6 +2,15 @@ import type { ConfigValues, StorageMode, SummaryLevel } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export declare const STORAGE_ENV_VAR = "BONSAI_STORAGE";
 export declare const SUMMARY_ENV_VAR = "BONSAI_SUMMARY";
+/** Two names for the same safety switch: `PLAN_MODE` mirrors agent-harness "plan mode" terminology. */
+export declare const READ_ONLY_ENV_VAR = "BONSAI_READ_ONLY";
+export declare const PLAN_MODE_ENV_VAR = "BONSAI_PLAN_MODE";
+/**
+ * Parses a boolean-ish env value. Empty/unset is `undefined` (not present); an unrecognized
+ * non-empty value is also `undefined` (invalid — see {@link invalidEnvOverrideWarnings}), so a
+ * typo never silently reads as `true`.
+ */
+export declare function parseEnvBoolean(raw: string | undefined): boolean | undefined;
 /**
  * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
  * dropped during resolution (falling back to config/default), which would otherwise silently mask
@@ -33,3 +42,15 @@ export interface ResolveSummaryInput {
  * flag > env > project file > user file > built-in default.
  */
 export declare function resolveSummaryLevel(input: ResolveSummaryInput): SummaryLevel;
+export interface ResolveReadOnlyInput {
+    /** True when `--read-only`/`--plan` was passed on this invocation. */
+    flag: boolean;
+    env: Record<string, string | undefined>;
+}
+/**
+ * Resolve whether read-only (plan) mode is active. Unlike storage/summary, this is a safety gate
+ * rather than a preference: composition is OR, not override-by-precedence — if the flag or either
+ * env var says read-only, the run is read-only. There is no way to force writes back on when an
+ * ambient `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` is set, by design.
+ */
+export declare function resolveReadOnly(input: ResolveReadOnlyInput): boolean;

package/dist/lib/config/resolve.js

@@ -2,6 +2,26 @@ import { BUILT_IN_DEFAULTS, STORAGE_MODES, SUMMARY_LEVELS } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export const STORAGE_ENV_VAR = 'BONSAI_STORAGE';
 export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
+/** Two names for the same safety switch: `PLAN_MODE` mirrors agent-harness "plan mode" terminology. */
+export const READ_ONLY_ENV_VAR = 'BONSAI_READ_ONLY';
+export const PLAN_MODE_ENV_VAR = 'BONSAI_PLAN_MODE';
+const BOOLEAN_TRUE_VALUES = ['1', 'true', 'yes'];
+const BOOLEAN_FALSE_VALUES = ['0', 'false', 'no'];
+/**
+ * Parses a boolean-ish env value. Empty/unset is `undefined` (not present); an unrecognized
+ * non-empty value is also `undefined` (invalid — see {@link invalidEnvOverrideWarnings}), so a
+ * typo never silently reads as `true`.
+ */
+export function parseEnvBoolean(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (!v)
+        return undefined;
+    if (BOOLEAN_TRUE_VALUES.includes(v))
+        return true;
+    if (BOOLEAN_FALSE_VALUES.includes(v))
+        return false;
+    return undefined;
+}
 /**
  * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
  * dropped during resolution (falling back to config/default), which would otherwise silently mask
@@ -9,18 +29,36 @@ export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
  * is visible without breaking the run. Returns one message per offending variable, or empty.
  */
 export function invalidEnvOverrideWarnings(env) {
+    // Each check names the var, how to tell a value is invalid, and the hint to show when it is.
     const checks = [
-        [STORAGE_ENV_VAR, STORAGE_MODES],
-        [SUMMARY_ENV_VAR, SUMMARY_LEVELS],
+        [
+            STORAGE_ENV_VAR,
+            (raw) => STORAGE_MODES.includes(raw),
+            `not one of ${STORAGE_MODES.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            SUMMARY_ENV_VAR,
+            (raw) => SUMMARY_LEVELS.includes(raw),
+            `not one of ${SUMMARY_LEVELS.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            READ_ONLY_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
+        [
+            PLAN_MODE_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
     ];
     const warnings = [];
-    for (const [name, valid] of checks) {
+    for (const [name, isValid, hint] of checks) {
         // After trim, an empty/whitespace-only value is falsy and treated as "unset" (no warning),
         // matching parseEnv*; matching is case-sensitive, so a wrong-case value is invalid and warns.
         const raw = env[name]?.trim();
-        if (raw && !valid.includes(raw)) {
-            warnings.push(`Ignoring ${name}="${raw}": not one of ${valid.join(', ')}. ` +
-                `Using the configured value or default instead.`);
+        if (raw && !isValid(raw)) {
+            warnings.push(`Ignoring ${name}="${raw}": ${hint}`);
         }
     }
     return warnings;
@@ -59,3 +97,14 @@ export function resolveSummaryLevel(input) {
         input.userConfig.summary ??
         BUILT_IN_DEFAULTS.summary);
 }
+/**
+ * Resolve whether read-only (plan) mode is active. Unlike storage/summary, this is a safety gate
+ * rather than a preference: composition is OR, not override-by-precedence — if the flag or either
+ * env var says read-only, the run is read-only. There is no way to force writes back on when an
+ * ambient `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` is set, by design.
+ */
+export function resolveReadOnly(input) {
+    return Boolean(input.flag ||
+        parseEnvBoolean(input.env[READ_ONLY_ENV_VAR]) ||
+        parseEnvBoolean(input.env[PLAN_MODE_ENV_VAR]));
+}

package/dist/lib/research/browser.js

@@ -127,6 +127,9 @@ export function buildChromeArgs() {
         ...getChromeTlsCompatibilityArgs(),
     ];
 }
+// CI runners occasionally starve headless Chrome's startup (disk/CPU contention from concurrent
+// jobs), so this is generous enough to absorb that rather than a "typical" local startup time.
+const CHROME_STARTUP_TIMEOUT_MS = 20_000;
 async function spawnChrome(chromePath) {
     const chromeProcess = spawn(chromePath, buildChromeArgs());
     try {
@@ -135,7 +138,7 @@ async function spawnChrome(chromePath) {
             const timeoutId = setTimeout(() => {
                 chromeProcess.kill('SIGKILL');
                 reject(new Error('Timed out waiting for Chrome to start.'));
-            }, 10000);
+            }, CHROME_STARTUP_TIMEOUT_MS);
             const onData = (data) => {
                 output += data.toString();
                 const match = output.match(/ws:\/\/127\.0\.0\.1:\d+\/devtools\/browser\/[a-zA-Z0-9-]+/);
@@ -363,9 +366,17 @@ export function describeNavigationFailure(errorText, url) {
 }
 // Chrome can emit these on first navigation in headless CI when the cert verifier reloads mid-run.
 const TRANSIENT_NAV_ERROR_CODES = ['ERR_CERT_VERIFIER_CHANGED'];
-function isTransientBrowserNavigationError(err) {
+// Resource contention in CI (concurrent jobs competing for CPU/disk) can make Chrome itself fail
+// to come up in time, or die before its devtools websocket URL is printed. Neither reflects a
+// problem with the target page, so it's worth a fresh attempt rather than failing the whole fetch.
+const TRANSIENT_CHROME_STARTUP_MESSAGES = [
+    'Timed out waiting for Chrome to start.',
+    'Chrome exited prematurely',
+];
+function isTransientBrowserError(err) {
     const message = err instanceof Error ? err.message : String(err);
-    return TRANSIENT_NAV_ERROR_CODES.some((code) => message.includes(code));
+    return (TRANSIENT_NAV_ERROR_CODES.some((code) => message.includes(code)) ||
+        TRANSIENT_CHROME_STARTUP_MESSAGES.some((text) => message.includes(text)));
 }
 async function fetchRenderedHtmlOnce(url, options = {}) {
     const timeout = options.timeoutMs ?? 15_000;
@@ -432,7 +443,7 @@ export async function fetchRenderedHtml(url, options = {}) {
             return await fetchRenderedHtmlOnce(url, options);
         }
         catch (err) {
-            if (attempt === maxAttempts || !isTransientBrowserNavigationError(err))
+            if (attempt === maxAttempts || !isTransientBrowserError(err))
                 throw err;
         }
     }

package/dist/lib/research/docs/markdown-source.d.ts

@@ -9,6 +9,13 @@ export declare function parseFrontmatter(md: string): ParsedFrontmatter;
  * handler attributes, and javascript: URLs. Leaves ordinary Markdown and benign inline HTML intact.
  */
 export declare function sanitizeSourceMarkdown(md: string): string;
+/**
+ * Applies a cleanup transform to the parts of a document OUTSIDE fenced code blocks, passing the
+ * fences through verbatim. Every text-level cleanup in this pipeline must go through this guard:
+ * fenced code is quoted material, and "cleaning" it destroys the samples readers came for
+ * (a `<script>` line in an example, a bash `# comment`, a literal `javascript:` URL).
+ */
+export declare function outsideFences(md: string, transform: (segment: string) => string): string;
 /**
  * Builds an ExtractionResult from public Markdown/MDX source. Frontmatter is parsed for the title
  * and the body is sanitized. The detailed Markdown is the source itself, preserving code fences,

package/dist/lib/research/docs/markdown-source.js

@@ -98,28 +98,31 @@ function replaceMacro(_match, inner) {
 function stripMdnHiddenSamples(md) {
     return md.replace(/<pre\b[^>]*\bhidden\b[^>]*>[\s\S]*?<\/pre>/gi, '');
 }
-function cleanKumaScript(md) {
-    // Never touch fenced code blocks.
+/**
+ * Applies a cleanup transform to the parts of a document OUTSIDE fenced code blocks, passing the
+ * fences through verbatim. Every text-level cleanup in this pipeline must go through this guard:
+ * fenced code is quoted material, and "cleaning" it destroys the samples readers came for
+ * (a `<script>` line in an example, a bash `# comment`, a literal `javascript:` URL).
+ */
+export function outsideFences(md, transform) {
     return md
         .split(/(```[\s\S]*?```)/)
-        .map((segment, i) => (i % 2 === 1 ? segment : segment.replace(/\{\{(.+?)\}\}/g, replaceMacro)))
+        .map((segment, i) => (i % 2 === 1 ? segment : transform(segment)))
         .join('');
 }
+function cleanKumaScript(md) {
+    return outsideFences(md, (segment) => segment.replace(/\{\{(.+?)\}\}/g, replaceMacro));
+}
 // MDN (and occasionally other docs) author tables as raw HTML inside their Markdown source, which
 // otherwise leaks verbatim into the artifact and wastes agent tokens. Turndown already emits clean
 // GFM tables, so convert any literal <table> region to Markdown. Code fences are skipped so an HTML
 // table shown as a *code example* (```html …<table>…) is preserved, not rewritten.
 function convertHtmlTables(md) {
-    return md
-        .split(/(```[\s\S]*?```)/)
-        .map((segment, i) => i % 2 === 1
-        ? segment
-        : // ponytail: non-greedy per-table match. A <table> nested in a cell would stop the match at
-            // the inner </table>, leaving the outer wrapper's closing tags as inert residue (no attrs,
-            // so it can't trip the leak gate). Doc sources use flat tables; upgrade to a DOM walk over
-            // the whole segment via htmlToMarkdown if a nested-table source ever appears.
-            segment.replace(/<table\b[\s\S]*?<\/table>/gi, (table) => `\n\n${htmlToMarkdown(table).trim()}\n\n`))
-        .join('');
+    // ponytail: non-greedy per-table match. A <table> nested in a cell would stop the match at
+    // the inner </table>, leaving the outer wrapper's closing tags as inert residue (no attrs,
+    // so it can't trip the leak gate). Doc sources use flat tables; upgrade to a DOM walk over
+    // the whole segment via htmlToMarkdown if a nested-table source ever appears.
+    return outsideFences(md, (segment) => segment.replace(/<table\b[\s\S]*?<\/table>/gi, (table) => `\n\n${htmlToMarkdown(table).trim()}\n\n`));
 }
 const HEADING = /^(#{1,6})\s/;
 function headingLevel(line) {
@@ -140,17 +143,37 @@ function dropEmptySections(md) {
     } while (current !== prev);
     return current;
 }
+const FENCE_DELIMITER = /^\s*```/;
+// Marks each line that belongs to fenced code, delimiters included. Fenced lines are content,
+// never headings: a bash `# comment` in an example must not be classified — and deleted — as an
+// empty section.
+function fencedLineMask(lines) {
+    let fenced = false;
+    return lines.map((line) => {
+        if (!FENCE_DELIMITER.test(line))
+            return fenced;
+        fenced = !fenced;
+        return true;
+    });
+}
+/** Index of the first non-blank line after `start`, or lines.length. */
+function nextContentLine(lines, start) {
+    let next = start + 1;
+    while (next < lines.length && lines[next].trim() === '')
+        next++;
+    return next;
+}
 function dropEmptySectionsOnce(md) {
     const lines = md.split('\n');
+    const inFence = fencedLineMask(lines);
     const keep = lines.map(() => true);
     for (let i = 0; i < lines.length; i++) {
-        const level = headingLevel(lines[i]);
+        const level = inFence[i] ? 0 : headingLevel(lines[i]);
         if (!level)
             continue;
-        let next = i + 1;
-        while (next < lines.length && lines[next].trim() === '')
-            next++;
-        const nextLevel = headingLevel(lines[next]);
+        const next = nextContentLine(lines, i);
+        // A fenced line after the heading means the section has content (nextLevel 0 → not empty).
+        const nextLevel = next < lines.length && !inFence[next] ? headingLevel(lines[next]) : 0;
         const sectionIsEmpty = next >= lines.length || (nextLevel > 0 && nextLevel <= level);
         if (sectionIsEmpty)
             for (let k = i; k < next; k++)
@@ -183,8 +206,11 @@ export function extractFromSource(md, sourceUrl) {
     const deMacroed = /mdn\/content/.test(sourceUrl)
         ? cleanKumaScript(stripMdnHiddenSamples(body))
         : body;
-    const tablesAsMarkdown = convertHtmlTables(sanitizeSourceMarkdown(deMacroed));
-    const cleaned = sanitizePromptInjection(dropEmptySections(dropEmptyLinks(tablesAsMarkdown))).trim();
+    // Sanitization and link/section cleanup are fence-guarded: code samples legitimately contain
+    // <script>/<button>/on*=/javascript: and bare [](…) lines. sanitizePromptInjection deliberately
+    // is NOT guarded — injection text is just as live when the agent reads it inside a code block.
+    const tablesAsMarkdown = convertHtmlTables(outsideFences(deMacroed, sanitizeSourceMarkdown));
+    const cleaned = sanitizePromptInjection(dropEmptySections(outsideFences(tablesAsMarkdown, dropEmptyLinks))).trim();
     const notes = [`captured from public Markdown/MDX source: ${sourceUrl}`];
     return {
         title: titleFrom(frontmatter, cleaned),

package/dist/lib/research/regression.js

@@ -93,7 +93,10 @@ export function contentMetrics(markdown) {
     return {
         chars: markdown.length,
         codeBlocks: Math.floor((markdown.match(/```/g) || []).length / 2),
-        tables: (markdown.match(/^\|(?:\s*---\s*\|)+\s*$/gm) || []).length,
+        // Separator rows come in every authored width and alignment (| --- |, | ------ |, | :---: |).
+        // Converted HTML always emits exactly ---, but route/source Markdown keeps the author's
+        // padding, so a width-sensitive count would misreport source captures as losing tables.
+        tables: (markdown.match(/^\|(?:\s*:?-{3,}:?\s*\|)+\s*$/gm) || []).length,
         images: (markdown.match(/!\[[^\]]*\]\(/g) || []).length,
         orderedSteps: (markdown.match(/^\d+\.\s+/gm) || []).length,
         bullets: (markdown.match(/^[-*]\s+/gm) || []).length,

package/dist/lib/research/revalidate.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { getSiteModuleById } from '../../sites/index.js';
+import { applySiteFetchProvenance } from '../../sites/types.js';
 import { fetchStaticHtml } from './fetcher.js';
 import { extractHtmlContent } from './extract.js';
 import { writeArtifact } from './storage.js';
@@ -111,9 +112,13 @@ function preserveUserMetadata(source, target, rendered) {
 // Builds a refreshed artifact from a fresh fetch, carries over user metadata, persists it, and
 // returns the "refreshed" result. Shared by both refresh paths (conditional-request fallthrough
 // and site-module re-fetch), which differ only in how fetchResult/extraction are obtained.
-function persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options) {
+function persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options, siteFetch) {
     const refreshed = createArtifactFromFetch(meta.source_url, meta.normalized_url, meta.cache_key, fetchResult, extraction, meta.tier, options.ttlOverride || meta.ttl, currentTime, options.summaryLevel);
     preserveUserMetadata(meta, refreshed, options.rendered);
+    // A site-module refresh reports how it actually captured this time; that overrides the
+    // carried-over provenance, so a withdrawn .md twin can't leave a stale source_doc_url behind.
+    if (siteFetch)
+        applySiteFetchProvenance(refreshed.metadata, siteFetch);
     // Back-fill keyword tags when the carried-over set is empty (e.g. an artifact first cached before
     // auto-tagging, or one originally stored without tags), so refreshing keeps it searchable.
     applyAutoTags(refreshed);
@@ -162,8 +167,8 @@ export async function revalidateCache(dataDir, existing, currentTime, options) {
         if (siteModule?.fetchPage) {
             // Site modules use custom fetch strategies that don't speak HTTP conditional requests
             // (no ETag/If-Modified-Since), so a full re-fetch is the only correct revalidation here.
-            const { fetchResult, extraction } = await siteModule.fetchPage(meta.source_url);
-            return persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options);
+            const siteFetch = await siteModule.fetchPage(meta.source_url);
+            return persistRefreshedArtifact(dataDir, meta, siteFetch.fetchResult, siteFetch.extraction, currentTime, options, siteFetch);
         }
         const fetchResult = options.rendered
             ? await fetchRenderedHtml(meta.source_url)

package/dist/lib/research/secure-write.d.ts

@@ -12,5 +12,11 @@ export interface SecureWriteResult {
  * Write an artifact to the configured write root, except when it contains a secret and the
  * target is a (potentially committed) project cache — those are redirected to the global cache.
  * Returns where it landed so the caller can warn the user and report the real path.
+ *
+ * `dryRun` still runs the secret scan and reports the real would-be destination, but skips the
+ * actual `writeArtifact` persist — so a read-only preview never gives a falsely reassuring answer
+ * about where secret-bearing content would land.
  */
-export declare function writeArtifactSecurely(roots: StoreRoots, key: string, artifact: ResearchArtifact): SecureWriteResult;
+export declare function writeArtifactSecurely(roots: StoreRoots, key: string, artifact: ResearchArtifact, options?: {
+    dryRun?: boolean;
+}): SecureWriteResult;

package/dist/lib/research/secure-write.js

@@ -4,14 +4,16 @@ import { scanArtifactForSecret } from './secret-scan.js';
  * Write an artifact to the configured write root, except when it contains a secret and the
  * target is a (potentially committed) project cache — those are redirected to the global cache.
  * Returns where it landed so the caller can warn the user and report the real path.
+ *
+ * `dryRun` still runs the secret scan and reports the real would-be destination, but skips the
+ * actual `writeArtifact` persist — so a read-only preview never gives a falsely reassuring answer
+ * about where secret-bearing content would land.
  */
-export function writeArtifactSecurely(roots, key, artifact) {
+export function writeArtifactSecurely(roots, key, artifact, options = {}) {
     const isProjectWrite = roots.writeRoot !== roots.globalRoot;
     const secretLabel = isProjectWrite ? scanArtifactForSecret(artifact) : null;
-    if (secretLabel) {
-        writeArtifact(roots.globalRoot, key, artifact);
-        return { dataDir: roots.globalRoot, redirected: true, secretLabel };
-    }
-    writeArtifact(roots.writeRoot, key, artifact);
-    return { dataDir: roots.writeRoot, redirected: false, secretLabel: null };
+    const dataDir = secretLabel ? roots.globalRoot : roots.writeRoot;
+    if (!options.dryRun)
+        writeArtifact(dataDir, key, artifact);
+    return { dataDir, redirected: Boolean(secretLabel), secretLabel };
 }

package/dist/sites/salesforce-developer/fetch-page.d.ts

@@ -1,3 +1,8 @@
 import type { SiteFetchResult } from '../types.js';
-/** Fetches a developer.salesforce.com doc page (guides + API reference) via the shared LWR fetcher. */
+/**
+ * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
+ * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
+ * browser render, and it returns the article's source. Pages without a validated twin (API
+ * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ */
 export declare function fetchDeveloperPage(url: string): Promise<SiteFetchResult>;

package/dist/sites/salesforce-developer/fetch-page.js

@@ -1,4 +1,5 @@
 import { fetchSalesforceDoc } from '../salesforce-doc-fetch.js';
+import { fetchDeveloperRouteMarkdown } from './route-markdown.js';
 // Containers a developer doc renders into. doc-content-layout / doc-amf-reference are the
 // web-component hosts for guide pages and API-reference (AMF) pages respectively.
 const CONTENT_SELECTORS = [
@@ -11,8 +12,16 @@ const CONTENT_SELECTORS = [
     'article',
     'main',
 ];
-/** Fetches a developer.salesforce.com doc page (guides + API reference) via the shared LWR fetcher. */
+/**
+ * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
+ * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
+ * browser render, and it returns the article's source. Pages without a validated twin (API
+ * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ */
 export async function fetchDeveloperPage(url) {
+    const fromMarkdownRoute = await fetchDeveloperRouteMarkdown(url);
+    if (fromMarkdownRoute)
+        return fromMarkdownRoute;
     return fetchSalesforceDoc(url, {
         allowedHost: 'developer.salesforce.com',
         contentSelectors: CONTENT_SELECTORS,

package/dist/sites/salesforce-developer/route-markdown.d.ts

@@ -0,0 +1,23 @@
+import { type FetchResult } from '../../lib/research/fetcher.js';
+import type { SiteFetchResult } from '../types.js';
+/**
+ * Derives the candidate `.md` route for a developer.salesforce.com doc URL, or null when the URL
+ * can't serve one (wrong host, not under /docs/, or an atlas.* book — verified to answer `.md`
+ * with an HTML shell, never Markdown). Query/hash are view state and are dropped.
+ */
+export declare function deriveMarkdownUrl(url: string): string | null;
+/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped. */
+export declare function stripIncludeDirectives(md: string): {
+    body: string;
+    dropped: number;
+};
+export type RouteMarkdownFetcher = (url: string, options?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}) => Promise<FetchResult>;
+/**
+ * Probes the derived `.md` route for a developer doc URL. Returns a complete SiteFetchResult
+ * (with route_markdown provenance) when the twin validates, or null so the caller falls back to
+ * the browser capture. Never throws: any network/validation failure is just "no twin".
+ */
+export declare function fetchDeveloperRouteMarkdown(url: string, fetcher?: RouteMarkdownFetcher): Promise<SiteFetchResult | null>;

package/dist/sites/salesforce-developer/route-markdown.js

@@ -0,0 +1,142 @@
+import { fetchText } from '../../lib/research/fetcher.js';
+import { validateTextArtifact } from '../../lib/research/docs/validate.js';
+import { extractFromSource } from '../../lib/research/docs/markdown-source.js';
+// developer.salesforce.com now publishes a Markdown twin for supported doc articles (the
+// "View as Markdown" link): /docs/<cloud>/<book>/guide/<article>[.html] also serves
+// <article>.md with Content-Type text/markdown. The URL mapping is deterministic, so we derive
+// the .md URL and probe it BEFORE the browser path — one static request replaces a ~45s
+// shadow-DOM render and returns the article's actual source (code fences, admonitions intact).
+//
+// Coverage is rolling out per doc set, so the probe result is only a candidate (T-19/T-24):
+// unsupported articles 404, and atlas.* books answer the .md route with an HTTP 200 HTML SPA
+// shell — which makes the strict content-type + body validation below load-bearing, not
+// defensive garnish.
+const DEVELOPER_HOST = 'developer.salesforce.com';
+const MARKDOWN_CONTENT_TYPE = 'text/markdown';
+// Salesforce's WAF answers 403 unless the User-Agent LEADS with a recognized HTTP-tool token
+// (curl/wget/python-requests pass; bare product names and browser UAs on a non-browser TLS stack
+// are blocked). Lead with the compatibility token — the same convention as browsers' Mozilla/5.0
+// prefix — and carry Bonsai's honest identity after it.
+const PROBE_HEADERS = {
+    'user-agent': 'curl/8.7.1 bonsai-research-cache (+https://bonsai.rhino-inquisitor.com)',
+};
+/**
+ * Derives the candidate `.md` route for a developer.salesforce.com doc URL, or null when the URL
+ * can't serve one (wrong host, not under /docs/, or an atlas.* book — verified to answer `.md`
+ * with an HTML shell, never Markdown). Query/hash are view state and are dropped.
+ */
+export function deriveMarkdownUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.hostname.toLowerCase() !== DEVELOPER_HOST)
+        return null;
+    let path = parsed.pathname.replace(/\/+$/, '');
+    if (!path.startsWith('/docs/') || path.startsWith('/docs/atlas.'))
+        return null;
+    if (path.endsWith('.md'))
+        return `https://${DEVELOPER_HOST}${path}`;
+    path = path.replace(/\.html?$/i, '');
+    return `https://${DEVELOPER_HOST}${path}.md`;
+}
+// `::include{src="../../shared/….md"}` directives reference build-time snippet files that are
+// not published on the .md route (they 404), so they'd survive as inert noise in the artifact.
+const INCLUDE_DIRECTIVE = /^\s*::include\{[^}]*\}\s*$/;
+/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped. */
+export function stripIncludeDirectives(md) {
+    let dropped = 0;
+    const body = md
+        .split(/(```[\s\S]*?```)/)
+        .map((segment, i) => {
+        // Fenced code is untouched: an ::include shown as a syntax example is content.
+        if (i % 2 === 1)
+            return segment;
+        return segment
+            .split('\n')
+            .filter((line) => {
+            if (!INCLUDE_DIRECTIVE.test(line))
+                return true;
+            dropped++;
+            return false;
+        })
+            .join('\n');
+    })
+        .join('');
+    return { body, dropped };
+}
+// A probe response counts as the Markdown twin only when the server labels it text/markdown AND
+// the redirect chain ended on https at the developer host AND the body validates as non-HTML,
+// non-error text. Atlas shells fail the content-type check; non-2xx statuses already threw in
+// the fetcher (the probe sends no conditional headers, so a 304 can't occur either).
+function isMarkdownResponse(res) {
+    if (!res.content)
+        return false;
+    const mediaType = (res.contentType?.split(';')[0] ?? '').trim().toLowerCase();
+    if (mediaType !== MARKDOWN_CONTENT_TYPE)
+        return false;
+    let finalUrl;
+    try {
+        finalUrl = new URL(res.finalUrl);
+    }
+    catch {
+        return false;
+    }
+    // Scheme matters, not just host: a redirect hop downgrading to plain http would let an on-path
+    // response be cached as the trusted twin.
+    if (finalUrl.protocol !== 'https:' || finalUrl.hostname.toLowerCase() !== DEVELOPER_HOST) {
+        return false;
+    }
+    return validateTextArtifact(res.content).ok;
+}
+// A real twin is a small static file that answers fast; anything slower should mean "no twin,
+// fall back now" instead of stacking the fetcher's default 10s on top of the browser render.
+const PROBE_TIMEOUT_MS = 4_000;
+// The browser path refuses to cache captures under this floor (MIN_CONTAINER_CHARS); a twin that
+// thin is a rollout stub, and falling back gives the rendered page a chance to do better.
+const MIN_TWIN_CHARS = 100;
+/**
+ * Probes the derived `.md` route for a developer doc URL. Returns a complete SiteFetchResult
+ * (with route_markdown provenance) when the twin validates, or null so the caller falls back to
+ * the browser capture. Never throws: any network/validation failure is just "no twin".
+ */
+export async function fetchDeveloperRouteMarkdown(url, fetcher = fetchText) {
+    const candidate = deriveMarkdownUrl(url);
+    if (!candidate)
+        return null;
+    let res;
+    try {
+        res = await fetcher(candidate, { headers: PROBE_HEADERS, timeoutMs: PROBE_TIMEOUT_MS });
+    }
+    catch {
+        return null;
+    }
+    if (!isMarkdownResponse(res))
+        return null;
+    const { body, dropped } = stripIncludeDirectives(res.content);
+    const extraction = extractFromSource(body, res.finalUrl);
+    if (extraction.detailedMarkdown.length < MIN_TWIN_CHARS)
+        return null;
+    if (dropped > 0) {
+        extraction.qualityNotes = [
+            ...(extraction.qualityNotes ?? []),
+            `${dropped} ::include directive(s) removed (shared snippets are not published on the .md route)`,
+        ];
+    }
+    return {
+        fetchResult: {
+            contentType: res.contentType,
+            etag: res.etag,
+            lastModified: res.lastModified,
+            finalUrl: res.finalUrl,
+            responseSize: res.responseSize,
+            content: res.content,
+        },
+        extraction,
+        captureMethod: 'route_markdown',
+        sourceDocUrl: res.finalUrl,
+    };
+}

package/dist/sites/salesforce-doc-fetch.js

@@ -64,13 +64,19 @@ function confidenceFor(length) {
 // page. Help wraps it in a removable component (see fetch-page.ts), but Developer renders it
 // as bare divs, so we also strip its lines from the converted Markdown for both sites.
 const BOILERPLATE_LINE = /(did this article solve your issue|let us know so we can improve|share your feedback)/i;
+// Toolbar of the "View as Markdown" feature on Developer articles. When the .md route probe
+// succeeds the browser never runs, but rollout/network asymmetries can still land such a page
+// here, and the toolbar labels serialize as bare paragraph lines.
+const MARKDOWN_TOOLBAR_LINE = /^(copy as markdown|view as markdown|copy url to markdown)$/i;
 // A link with empty anchor text — e.g. an icon-only "home" logo link. It carries no readable
 // content and renders as a bare `[](url)`. (Images `![](url)` are intentionally not matched.)
 const EMPTY_LINK_LINE = /^\[\]\([^)]*\)$/;
 export function stripBoilerplate(markdown) {
     return markdown
         .split('\n')
-        .filter((line) => !BOILERPLATE_LINE.test(line) && !EMPTY_LINK_LINE.test(line.trim()))
+        .filter((line) => !BOILERPLATE_LINE.test(line) &&
+        !MARKDOWN_TOOLBAR_LINE.test(line.trim()) &&
+        !EMPTY_LINK_LINE.test(line.trim()))
         .join('\n')
         .replace(/\n{3,}/g, '\n\n')
         .trim();
@@ -336,6 +342,9 @@ function buildSalesforceFetchResult(url, html, title, detailedMarkdown, qualityN
             confidence: confidenceFor(detailedMarkdown.length),
             qualityNotes,
         },
+        // Rendered capture is this fetcher's only strategy; reporting it lets a refresh overwrite
+        // route_markdown provenance when an article's .md twin has since vanished.
+        captureMethod: 'browser_fallback',
     };
 }
 /**

package/dist/sites/types.d.ts

@@ -1,4 +1,5 @@
 import type { ExtractionResult } from '../lib/research/extract.js';
+import type { CaptureMethod } from '../lib/research/schema.js';
 export interface SiteFetchResult {
     fetchResult: {
         contentType: string | null;
@@ -9,7 +10,19 @@ export interface SiteFetchResult {
         content: string;
     };
     extraction: ExtractionResult;
+    captureMethod?: CaptureMethod;
+    sourceDocUrl?: string;
 }
+/**
+ * Stamps a site module's reported provenance onto artifact metadata. Shared by the cache-miss
+ * fetch and revalidation so the two write paths can't drift. A result without captureMethod (a
+ * module predating provenance reporting) leaves the metadata untouched.
+ */
+export declare function applySiteFetchProvenance(metadata: {
+    capture_method: CaptureMethod | null;
+    source_doc_url: string | null;
+    source_urls: string[];
+}, siteFetch: SiteFetchResult): void;
 export interface SiteModule {
     id: string;
     name: string;

package/dist/sites/types.js

@@ -1 +1,14 @@
-export {};
+/**
+ * Stamps a site module's reported provenance onto artifact metadata. Shared by the cache-miss
+ * fetch and revalidation so the two write paths can't drift. A result without captureMethod (a
+ * module predating provenance reporting) leaves the metadata untouched.
+ */
+export function applySiteFetchProvenance(metadata, siteFetch) {
+    if (!siteFetch.captureMethod)
+        return;
+    metadata.capture_method = siteFetch.captureMethod;
+    metadata.source_doc_url = siteFetch.sourceDocUrl ?? null;
+    if (siteFetch.sourceDocUrl && !metadata.source_urls.includes(siteFetch.sourceDocUrl)) {
+        metadata.source_urls.push(siteFetch.sourceDocUrl);
+    }
+}

package/oclif.manifest.json

@@ -28,6 +28,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
           "description": "the main category/topic of the research for metadata tagging",
@@ -169,6 +178,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "stdin": {
           "description": "read Markdown from stdin",
           "name": "stdin",
@@ -288,6 +306,15 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -331,6 +358,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
           "description": "filter by exact topic (case-insensitive)",
@@ -438,6 +474,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "older-than": {
           "description": "prune entries older than duration (e.g. \"30d\", \"90d\")",
           "name": "older-than",
@@ -525,6 +570,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "tier": {
           "description": "freshness tier policy to evaluate against",
           "name": "tier",
@@ -586,6 +640,15 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -627,6 +690,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Read from user-level config only.",
@@ -679,6 +751,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Show user-level config only.",
@@ -742,6 +823,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Write to user-level config (default).",
@@ -806,6 +896,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Remove from user-level config (default).",
@@ -843,5 +942,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "3.0.3"
+  "version": "3.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",