@taurgis/bonsai 4.1.0 → 4.1.1

package/README.md

@@ -316,8 +316,6 @@ When run with `--json`, commands return a stable envelope:
 | `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. |
-| `NO_UPDATE_NOTIFIER` | Suppress the "update available" notification. |
-| `CI` | Set to `1` or `true` to suppress the update notification in CI environments (detected automatically). |
 | `DEBUG` | Enable debug output for specific Bonsai namespaces, e.g. `DEBUG=bonsai:*`. |
 
 ---

package/bin/cli.mjs

@@ -3,8 +3,6 @@
 import { execute } from '@oclif/core';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import updateNotifier from 'update-notifier';
-import { createRequire } from 'node:module';
 
 import { normalizeArgv } from '../dist/lib/argv.js';
 import { VALUE_TAKING_FLAG_TOKENS, KNOWN_COMMAND_ROOT_TOKENS } from '../dist/lib/cli-flag-manifest.js';
@@ -12,9 +10,6 @@ import { exitWithPreflight } from '../dist/lib/cli-emit.js';
 import { tryUnknownHelpOutput } from '../dist/lib/help-preflight.js';
 import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
 
-const req = createRequire(import.meta.url);
-const pkg = req('../package.json');
-
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Normalize argv so the whole oclif pipeline sees one consistent command. oclif's
@@ -43,12 +38,6 @@ if (jsonMeta) {
   exitWithPreflight({ ...jsonMeta, json: true });
 }
 
-// Only notify after the earlyExit fast-path so the notifier never fires before
-// a usage-error envelope exits. Also skip under --json/--toon so agent callers never see stderr noise.
-if (!process.argv.includes('--json') && !process.argv.includes('--toon')) {
-  updateNotifier({ pkg }).notify();
-}
-
 process.argv = [process.argv[0], process.argv[1], ...result.argv];
 
 await execute({

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

@@ -1,4 +1,4 @@
-import { ConfigCommand } from './base.js';
+import { ConfigCommand } from '../../lib/config-command.js';
 export default class ConfigGet extends ConfigCommand<typeof ConfigGet> {
     static id: string;
     static summary: string;

package/dist/commands/config/get.js

@@ -1,5 +1,5 @@
 import { Args } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { formatConfigEntry, resolveConfigEntry, keyValuesHint } from '../../lib/config/index.js';
 export default class ConfigGet extends ConfigCommand {
     static id = 'config get';

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

@@ -1,4 +1,4 @@
-import { ConfigCommand } from './base.js';
+import { ConfigCommand } from '../../lib/config-command.js';
 export default class ConfigList extends ConfigCommand<typeof ConfigList> {
     static id: string;
     static summary: string;

package/dist/commands/config/list.js

@@ -1,4 +1,4 @@
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { formatConfigEntry, resolveConfigEntries, keyValuesHint } from '../../lib/config/index.js';
 export default class ConfigList extends ConfigCommand {
     static id = 'config list';

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

@@ -1,4 +1,4 @@
-import { ConfigCommand } from './base.js';
+import { ConfigCommand } from '../../lib/config-command.js';
 import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
     static id: string;

package/dist/commands/config/set.js

@@ -1,5 +1,5 @@
 import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { KEY_META, keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigSet extends ConfigCommand {

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

@@ -1,4 +1,4 @@
-import { ConfigCommand } from './base.js';
+import { ConfigCommand } from '../../lib/config-command.js';
 import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
     static id: string;

package/dist/commands/config/unset.js

@@ -1,5 +1,5 @@
 import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigUnset extends ConfigCommand {

package/dist/lib/cli-flag-manifest.d.ts

@@ -1,6 +1,6 @@
 /**
- * Composition-root flag manifest: every CLI token that consumes a following argv value.
- * Built from command class metadata so argv normalization stays free of command imports.
+ * Every CLI token that consumes a following argv value, from the shipped oclif manifest.
+ * Argv normalization stays off the command-class import graph.
  */
 export declare const VALUE_TAKING_FLAG_TOKENS: ReadonlySet<string>;
 /**

package/dist/lib/cli-flag-manifest.js

@@ -1,15 +1,23 @@
-import { BaseCommand } from '../base-command.js';
-import { commands } from '../commands.js';
-import { valueTakingFlagTokensFromCommands } from './value-flags.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { valueTakingFlagTokensFromFlagMaps } from './value-flags.js';
+// Startup reads the generated manifest instead of importing every command class. Importing the
+// registry pulls the fetch stack (Readability, Turndown, the browser fallback) into --help.
+function readOclifManifest() {
+    const manifestPath = join(dirname(fileURLToPath(import.meta.url)), '../../oclif.manifest.json');
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+const manifest = readOclifManifest();
 /**
- * Composition-root flag manifest: every CLI token that consumes a following argv value.
- * Built from command class metadata so argv normalization stays free of command imports.
+ * Every CLI token that consumes a following argv value, from the shipped oclif manifest.
+ * Argv normalization stays off the command-class import graph.
  */
-export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromCommands(commands, BaseCommand.baseFlags);
+export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromFlagMaps(Object.values(manifest.commands).map((command) => command.flags));
 /**
  * Root segment of every registered command id (`config:get` → `config`). oclif joins namespaced
  * command ids with `:` regardless of the display-only `topicSeparator` setting, so a token like
  * `config:get` is a real command, not a URL — argv normalization checks this set before assuming
  * `word:` is a URL scheme.
  */
-export const KNOWN_COMMAND_ROOT_TOKENS = new Set(Object.keys(commands).map((id) => id.split(':')[0]));
+export const KNOWN_COMMAND_ROOT_TOKENS = new Set(Object.keys(manifest.commands).map((id) => id.split(':')[0]));

package/dist/{commands/config/base.d.ts → lib/config-command.d.ts}

@@ -1,10 +1,13 @@
 import { Command } from '@oclif/core';
-import { BaseCommand } from '../../base-command.js';
-import type { ConfigKey, ConfigScope } from '../../lib/config/index.js';
-import { scopeFlags } from '../../lib/scope-flags.js';
+import { BaseCommand } from '../base-command.js';
+import type { ConfigKey, ConfigScope } from './config/index.js';
+import { scopeFlags } from './scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
+ *
+ * Lives outside `src/commands` so oclif's file-based command discovery does not
+ * publish it as `config base`.
  */
 export declare abstract class ConfigCommand<T extends typeof Command> extends BaseCommand<T> {
     protected assertScopeFlagsExclusive(global?: boolean, local?: boolean): void;

package/dist/{commands/config/base.js → lib/config-command.js}

@@ -1,10 +1,13 @@
 import { toConfiguredId } from '@oclif/core';
-import { BaseCommand } from '../../base-command.js';
-import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
-import { assertScopeFlagsExclusive, scopeFlags } from '../../lib/scope-flags.js';
+import { BaseCommand } from '../base-command.js';
+import { isKnownKey, suggestKey, validKeysHint } from './config/index.js';
+import { assertScopeFlagsExclusive, scopeFlags } from './scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
+ *
+ * Lives outside `src/commands` so oclif's file-based command discovery does not
+ * publish it as `config base`.
  */
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {

package/dist/lib/research/fetcher.d.ts

@@ -65,3 +65,14 @@ export declare function fetchStaticHtml(url: string, options?: FetchOptions): Pr
  * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
  */
 export declare function fetchText(url: string, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Same DNS, redirect, and status checks as {@link fetchText}, but the body is cancelled once the
+ * status line is known. Use this to reject HTTP 404 before a browser render without downloading
+ * the document.
+ *
+ * @param url - Absolute URL to probe.
+ * @param options - Optional timeout, redirect cap, and headers.
+ * @returns The final HTTP status.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
+ */
+export declare function fetchStatus(url: string, options?: FetchOptions): Promise<number>;

package/dist/lib/research/fetcher.js

@@ -264,3 +264,29 @@ export async function fetchStaticHtml(url, options = {}) {
 export async function fetchText(url, options = {}) {
     return fetchWithRedirects(url, options, processTextResponse);
 }
+/**
+ * Same DNS, redirect, and status checks as {@link fetchText}, but the body is cancelled once the
+ * status line is known. Use this to reject HTTP 404 before a browser render without downloading
+ * the document.
+ *
+ * @param url - Absolute URL to probe.
+ * @param options - Optional timeout, redirect cap, and headers.
+ * @returns The final HTTP status.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
+ */
+export async function fetchStatus(url, options = {}) {
+    const result = await fetchWithRedirects(url, options, async (res, _limit, currentUrl) => {
+        await res.body?.cancel().catch(() => { });
+        assertOk(res);
+        return {
+            status: res.status,
+            contentType: null,
+            etag: null,
+            lastModified: null,
+            finalUrl: currentUrl,
+            responseSize: 0,
+            content: '',
+        };
+    });
+    return result.status;
+}

package/dist/lib/research/regression.js

@@ -117,7 +117,12 @@ const LEAKAGE_PATTERNS = [
     { label: 'base64-image', re: /data:image\/[a-z]+;base64,/i },
     { label: 'skip-to-content', re: /skip to (?:main )?content/i },
     { label: 'on-this-page', re: /^on this page$/im },
-    { label: 'theme-toggle', re: /(?:toggle|switch to) (?:dark|light|the)? ?(?:mode|theme)/i },
+    // "dark"/"light" or the word "theme" is required. An optional group also matched
+    // "switch to mode" after inline code was stripped from "switch to `history` mode".
+    {
+        label: 'theme-toggle',
+        re: /(?:toggle|switch to) (?:the )?(?:dark|light)(?: mode)?|(?:toggle|switch to) (?:the )?theme/i,
+    },
     {
         label: 'cookie-consent',
         re: /(?:accept all cookies|we use cookies|cookie (?:policy|preferences|settings))/i,

package/dist/lib/value-flags.d.ts

@@ -11,4 +11,6 @@ type FlagDef = {
  * cannot drift from the real command surface.
  */
 export declare function valueTakingFlagTokensFromCommands(commands: Record<string, typeof Command>, extraBaseFlags?: Record<string, FlagDef>): Set<string>;
+/** Same token set, read from a generated oclif manifest instead of command classes. */
+export declare function valueTakingFlagTokensFromFlagMaps(flagMaps: Array<Record<string, FlagDef> | undefined>): Set<string>;
 export {};

package/dist/lib/value-flags.js

@@ -14,10 +14,18 @@ function flagTokens(name, flag) {
  * cannot drift from the real command surface.
  */
 export function valueTakingFlagTokensFromCommands(commands, extraBaseFlags = {}) {
+    const maps = Object.values(commands).map((command) => ({
+        ...extraBaseFlags,
+        ...command.baseFlags,
+        ...command.flags,
+    }));
+    return valueTakingFlagTokensFromFlagMaps(maps);
+}
+/** Same token set, read from a generated oclif manifest instead of command classes. */
+export function valueTakingFlagTokensFromFlagMaps(flagMaps) {
     const tokens = new Set();
-    for (const command of Object.values(commands)) {
-        const flags = { ...extraBaseFlags, ...command.baseFlags, ...command.flags };
-        for (const [name, flag] of Object.entries(flags)) {
+    for (const flags of flagMaps) {
+        for (const [name, flag] of Object.entries(flags ?? {})) {
             if (!flag || flag.type === 'boolean')
                 continue;
             for (const token of flagTokens(name, flag))

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

@@ -3,7 +3,7 @@ import type { SiteFetchResult } from '../types.js';
  * 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 Lightning Web Runtime (LWR)
+ * reference, atlas books whose `.md` route is still an HTML shell, landing pages) fall back to the shared Lightning Web Runtime (LWR)
  * shadow-DOM fetcher.
  *
  * @param url - The developer.salesforce.com doc page URL.

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

@@ -5,7 +5,9 @@ import { fetchDeveloperRouteMarkdown } from './route-markdown.js';
 const CONTENT_SELECTORS = [
     // API-reference pages: doc-amf-reference holds the method/type tables. doc-content-layout only
     // carries the shared deprecation banner and must not win selector priority on those pages.
+    // doc-redoc-reference is the Connect REST (B2B Commerce and platform) three-panel host.
     'doc-amf-reference',
+    'doc-redoc-reference',
     'doc-content-layout',
     '.markdown-content',
     'main article',
@@ -16,7 +18,7 @@ const CONTENT_SELECTORS = [
  * 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 Lightning Web Runtime (LWR)
+ * reference, atlas books whose `.md` route is still an HTML shell, landing pages) fall back to the shared Lightning Web Runtime (LWR)
  * shadow-DOM fetcher.
  *
  * @param url - The developer.salesforce.com doc page URL.

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

@@ -2,8 +2,9 @@ import { fetchText } 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.
+ * can't serve one (wrong host, or not under /docs/). Atlas books are included: a shell is
+ * rejected later by content-type, and a redirect to Markdown is kept. Query/hash are view
+ * state and are dropped.
  *
  * @param url - A developer.salesforce.com doc URL (or any URL; non-matching returns null).
  * @returns The derived `.md` URL, or null when no `.md` route exists for this URL.

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

@@ -7,9 +7,10 @@ import { probeMarkdownTwin } from '../markdown-twin.js';
 // 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 in probeMarkdownTwin
-// load-bearing, not defensive garnish.
+// unsupported articles 404, and some atlas.* books still answer the .md route with an HTTP 200
+// HTML SPA shell. Others (REST API, Bulk API's successor) now redirect that same .md route to a
+// real text/markdown article under /docs/platform. Content-type validation rejects the shells;
+// skipping atlas.* up front would miss the books that moved.
 const DEVELOPER_HOST = 'developer.salesforce.com';
 // 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
@@ -20,8 +21,9 @@ const PROBE_HEADERS = {
 };
 /**
  * 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.
+ * can't serve one (wrong host, or not under /docs/). Atlas books are included: a shell is
+ * rejected later by content-type, and a redirect to Markdown is kept. Query/hash are view
+ * state and are dropped.
  *
  * @param url - A developer.salesforce.com doc URL (or any URL; non-matching returns null).
  * @returns The derived `.md` URL, or null when no `.md` route exists for this URL.
@@ -37,7 +39,7 @@ export function deriveMarkdownUrl(url) {
     if (parsed.hostname.toLowerCase() !== DEVELOPER_HOST)
         return null;
     let path = parsed.pathname.replace(/\/+$/, '');
-    if (!path.startsWith('/docs/') || path.startsWith('/docs/atlas.'))
+    if (!path.startsWith('/docs/'))
         return null;
     if (path.endsWith('.md'))
         return `https://${DEVELOPER_HOST}${path}`;

package/dist/sites/salesforce-doc-fetch.d.ts

@@ -1,16 +1,12 @@
 import type { SiteFetchResult } from './types.js';
-/** True when the extracted text is an error/not-found/loading shell rather than real content.
- *
- * @param text - Extracted Markdown text to check.
- * @returns True when the text matches a Salesforce error/not-found pattern.
- */
-export declare function looksLikeSalesforceError(text: string): boolean;
+import { looksLikeSalesforceError } from './salesforce-dom-probe.js';
+export { looksLikeSalesforceError };
 /**
- * Removes known boilerplate lines from converted Salesforce Markdown: the feedback widget text,
- * "View as Markdown" toolbar labels, and empty icon-anchor lines.
+ * Removes known boilerplate from converted Salesforce Markdown: the feedback widget, doc-chrome
+ * toolbar labels, the atlas release switcher, and empty icon-anchor lines.
  *
  * @param markdown - Markdown output from the DOM or content API conversion.
- * @returns Markdown with boilerplate lines stripped and excess blank lines collapsed.
+ * @returns Markdown with boilerplate stripped and excess blank lines collapsed.
  */
 export declare function stripBoilerplate(markdown: string): string;
 /** Parses the Salesforce private content API JSON payload.
@@ -45,6 +41,21 @@ export interface SalesforceDocOptions {
     contentSelectors: string[];
     removeSelectors?: string[];
 }
+/** Article identity for a Salesforce doc URL: Help `id`, otherwise the last path segment.
+ * Underscores and hyphens match so a REST rename (`intro_what_is_rest_api` →
+ * `intro-what-is-rest-api`) stays the same article.
+ *
+ * @param url - Requested or post-navigation URL.
+ * @returns Normalized article key, or null when the URL has no article identity.
+ */
+export declare function salesforceArticleKey(url: string): string | null;
+/** True when both URLs name the same Salesforce article, or either key can't be read.
+ *
+ * @param requested - URL the caller asked for.
+ * @param finalUrl - URL the browser landed on.
+ * @returns False only when both keys exist and differ.
+ */
+export declare function sameSalesforceArticle(requested: string, finalUrl: string): boolean;
 /**
  * Renders a Salesforce Lightning Web Runtime (LWR) doc page, serializes its shadow-DOM content
  * container, and converts it to Markdown. Validates the host before any network access.
@@ -53,7 +64,8 @@ export interface SalesforceDocOptions {
  * @param options - Allowed host, priority content selectors, and optional per-site remove selectors.
  * @returns Extracted Markdown, fetch metadata, and browser-capture provenance.
  * @throws {Error} When the URL is invalid, the host is not the allowed host, DNS is unsafe,
- *   Chrome/CDP navigation or evaluation fails, the response body exceeds the size limit,
- *   or the captured content is too short / looks like an error page.
+ *   the document itself is HTTP 404/410, Chrome/CDP navigation or evaluation fails, the page
+ *   redirects to a different article, the response body exceeds the size limit, or the captured
+ *   content is too short / looks like an error page.
  */
 export declare function fetchSalesforceDoc(url: string, { allowedHost, contentSelectors, removeSelectors }: SalesforceDocOptions): Promise<SiteFetchResult>;

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

@@ -1,9 +1,10 @@
 import { openCdpPage, waitForLoad, ResponseCapture, describeNavigationFailure, } from '../lib/research/browser.js';
-import { checkDnsSafety } from '../lib/research/fetcher.js';
+import { checkDnsSafety, fetchStatus } from '../lib/research/fetcher.js';
 import { htmlToMarkdown } from '../lib/research/markdown.js';
 import { sanitizePromptInjection } from '../lib/research/prompt-injection.js';
 import { contentMetrics, contentRicherThan } from '../lib/research/regression.js';
-import { SALESFORCE_SHADOW_DOM_HELPERS, buildPriorityContainerPickBlock, pollSalesforceContentReady, } from './salesforce-dom-probe.js';
+import { SALESFORCE_SHADOW_DOM_HELPERS, buildPriorityContainerPickBlock, pollSalesforceContentReady, looksLikeSalesforceError, } from './salesforce-dom-probe.js';
+export { looksLikeSalesforceError };
 // Both help.salesforce.com and developer.salesforce.com are LWR sites that render doc content
 // client-side inside web components (shadow DOM). document.documentElement.outerHTML captures
 // only the "Loading…" shell, and Readability prunes the structured result to a single block —
@@ -19,20 +20,11 @@ const BODY_LIMIT_BYTES = 6 * 1024 * 1024;
 /** Grace period after DOM settle for late /docs/get_document_content/ responses on guide pages. */
 const DOCS_API_GRACE_MS = 500;
 const ACCEPT_CONSENT_EXPRESSION = "(() => { const b = document.querySelector('#onetrust-accept-btn-handler'); if (b) b.click(); })()";
-const ERROR_PATTERNS = [
-    /page\s*(not\s*found|doesn'?t\s*exist|can'?t\s*be\s*found)/i,
-    /we\s*couldn'?t\s*find/i,
-    /we looked high and low/i,
-    /sorry to interrupt/i,
-];
-/** True when the extracted text is an error/not-found/loading shell rather than real content.
- *
- * @param text - Extracted Markdown text to check.
- * @returns True when the text matches a Salesforce error/not-found pattern.
- */
-export function looksLikeSalesforceError(text) {
-    return ERROR_PATTERNS.some((re) => re.test(text));
-}
+// Salesforce's WAF answers 403 unless the User-Agent leads with a recognized HTTP-tool token.
+// Same token the Markdown probe sends, so a missing-doc check sees the real status.
+const DOC_PROBE_HEADERS = {
+    'user-agent': 'curl/8.7.1 bonsai-research-cache (+https://bonsai.rhino-inquisitor.com)',
+};
 // Chrome present on every LWR doc page; stripped before serialization. Per-site noise (e.g.
 // Help's article-feedback widget) is appended via SalesforceDocOptions.removeSelectors.
 const BASE_REMOVE_SELECTORS = [
@@ -69,25 +61,28 @@ 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;
+// Toolbar labels that serialize as their own paragraph: "View as Markdown" on articles that
+// missed the .md probe, and the llms.txt / "Open in ChatGPT" cluster on the newer guide chrome.
+const DOC_CHROME_LINE = /^(copy as markdown|view as markdown|copy url to markdown|view llms\.txt|copy url to llms\.txt|open in chatgpt|open in claude|open in perplexity|this page|all documentation|more actions)$/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 = /^\[\]\([^)]*\)$/;
+// Atlas books render a release switcher as one link per season. Turndown splits the anchor
+// text across lines, so the link is not a single line. Drop the whole link; the article follows.
+const VERSION_PICKER_LINK = /\[\s*(?:Spring|Summer|Winter|Fall)\s+'\d{2}\s+\(API version\s+[\d.]+\)\s*\]\([^)\n]*\)/gi;
 /**
- * Removes known boilerplate lines from converted Salesforce Markdown: the feedback widget text,
- * "View as Markdown" toolbar labels, and empty icon-anchor lines.
+ * Removes known boilerplate from converted Salesforce Markdown: the feedback widget, doc-chrome
+ * toolbar labels, the atlas release switcher, and empty icon-anchor lines.
  *
  * @param markdown - Markdown output from the DOM or content API conversion.
- * @returns Markdown with boilerplate lines stripped and excess blank lines collapsed.
+ * @returns Markdown with boilerplate stripped and excess blank lines collapsed.
  */
 export function stripBoilerplate(markdown) {
     return markdown
+        .replace(VERSION_PICKER_LINK, '')
         .split('\n')
         .filter((line) => !BOILERPLATE_LINE.test(line) &&
-        !MARKDOWN_TOOLBAR_LINE.test(line.trim()) &&
+        !DOC_CHROME_LINE.test(line.trim()) &&
         !EMPTY_LINK_LINE.test(line.trim()))
         .join('\n')
         .replace(/\n{3,}/g, '\n\n')
@@ -286,6 +281,65 @@ function buildCaptureScript(contentSelectors, extraRemove) {
     return { html: serialize(container), title };
   })()`;
 }
+/** Article identity for a Salesforce doc URL: Help `id`, otherwise the last path segment.
+ * Underscores and hyphens match so a REST rename (`intro_what_is_rest_api` →
+ * `intro-what-is-rest-api`) stays the same article.
+ *
+ * @param url - Requested or post-navigation URL.
+ * @returns Normalized article key, or null when the URL has no article identity.
+ */
+export function salesforceArticleKey(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const id = parsed.searchParams.get('id');
+    const raw = (id ?? parsed.pathname.replace(/\/+$/, '').split('/').pop() ?? '').trim();
+    const stripped = raw.replace(/\.(html?|md)$/i, '');
+    if (!stripped)
+        return null;
+    return stripped.toLowerCase().replace(/_/g, '-');
+}
+/** True when both URLs name the same Salesforce article, or either key can't be read.
+ *
+ * @param requested - URL the caller asked for.
+ * @param finalUrl - URL the browser landed on.
+ * @returns False only when both keys exist and differ.
+ */
+export function sameSalesforceArticle(requested, finalUrl) {
+    const requestedKey = salesforceArticleKey(requested);
+    const finalKey = salesforceArticleKey(finalUrl);
+    if (!requestedKey || !finalKey)
+        return true;
+    return requestedKey === finalKey;
+}
+async function assertSalesforceDocumentExists(url) {
+    try {
+        await fetchStatus(url, { headers: DOC_PROBE_HEADERS, timeoutMs: 8_000 });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : '';
+        // Any other failure (WAF 403, timeout) still goes to the browser. Only a real
+        // not-found status is enough to skip Chrome.
+        if (/\bstatus (404|410)\b/.test(message)) {
+            throw new Error(`Salesforce doc not found: ${url}`);
+        }
+    }
+}
+async function assertLandedOnRequestedArticle(page, url) {
+    const result = await page.client
+        .send('Runtime.evaluate', { expression: 'location.href', returnByValue: true }, page.sessionId)
+        .catch(() => null);
+    const finalHref = result?.result?.value;
+    if (typeof finalHref !== 'string' || !finalHref)
+        return;
+    if (!sameSalesforceArticle(url, finalHref)) {
+        throw new Error(`Salesforce doc ${url} redirected to a different article (${finalHref}).`);
+    }
+}
 function parseSalesforceDocUrl(url, allowedHost) {
     let parsed;
     try {
@@ -300,7 +354,10 @@ function parseSalesforceDocUrl(url, allowedHost) {
     return parsed;
 }
 function assertReadableSalesforceContent(detailedMarkdown, url) {
-    if (detailedMarkdown.length < MIN_CONTAINER_CHARS || looksLikeSalesforceError(detailedMarkdown)) {
+    if (looksLikeSalesforceError(detailedMarkdown)) {
+        throw new Error(`Salesforce doc not found: ${url}`);
+    }
+    if (detailedMarkdown.length < MIN_CONTAINER_CHARS) {
         throw new Error(`Salesforce returned no readable content for ${url} (page may be missing, gated, or still loading).`);
     }
 }
@@ -351,6 +408,9 @@ async function captureSalesforceAttempt(page, url, captureScript, contentSelecto
     }
     let detailedMarkdown = stripBoilerplate(htmlToMarkdown(html));
     let usedDocsApi = false;
+    // Retired atlas leaves (apex_qs_hello.htm) stay HTTP 200, then the SPA swaps in the book
+    // home. Storing that home under the requested URL would cache the wrong article.
+    await assertLandedOnRequestedArticle(page, url);
     if (docsApiHtml) {
         const picked = preferRicherMarkdown(detailedMarkdown, docsApiHtml, title, docsApiTitle);
         detailedMarkdown = picked.markdown;
@@ -393,12 +453,14 @@ function buildSalesforceFetchResult(url, html, title, detailedMarkdown, qualityN
  * @param options - Allowed host, priority content selectors, and optional per-site remove selectors.
  * @returns Extracted Markdown, fetch metadata, and browser-capture provenance.
  * @throws {Error} When the URL is invalid, the host is not the allowed host, DNS is unsafe,
- *   Chrome/CDP navigation or evaluation fails, the response body exceeds the size limit,
- *   or the captured content is too short / looks like an error page.
+ *   the document itself is HTTP 404/410, Chrome/CDP navigation or evaluation fails, the page
+ *   redirects to a different article, the response body exceeds the size limit, or the captured
+ *   content is too short / looks like an error page.
  */
 export async function fetchSalesforceDoc(url, { allowedHost, contentSelectors, removeSelectors = [] }) {
     const parsed = parseSalesforceDocUrl(url, allowedHost);
     await checkDnsSafety(parsed.hostname);
+    await assertSalesforceDocumentExists(url);
     const captureScript = buildCaptureScript(contentSelectors, removeSelectors);
     const page = await openCdpPage();
     try {

package/dist/sites/salesforce-dom-probe.d.ts

@@ -1,6 +1,12 @@
 import type { CdpPage } from '../lib/research/browser.js';
 /** Shared in-page helpers for traversing Salesforce Lightning Web Runtime (LWR) open shadow roots. */
 export declare const SALESFORCE_SHADOW_DOM_HELPERS = "\nconst deepElements = (root) => {\n  const out = [];\n  const visit = (node) => {\n    if (node.shadowRoot) visit(node.shadowRoot);\n    for (const child of Array.from(node.children || [])) {\n      out.push(child);\n      visit(child);\n    }\n  };\n  visit(root);\n  return out;\n};\n\nconst deepText = (root) => {\n  let txt = '';\n  const visit = (node) => {\n    if (node.nodeType === 3) {\n      txt += node.textContent || '';\n    } else if (node.nodeType === 1 || node.nodeType === 9 || node.nodeType === 11) {\n      const tag = node.tagName ? node.tagName.toLowerCase() : '';\n      if (tag !== 'style' && tag !== 'script') {\n        if (node.shadowRoot) visit(node.shadowRoot);\n        for (const child of Array.from(node.childNodes || [])) visit(child);\n      }\n    }\n  };\n  visit(root);\n  return txt;\n};\n\nconst textLenFor = (el) =>\n  Math.max((el.innerText || '').trim().length, deepText(el).trim().length);\n";
+/** True when extracted text is a Salesforce not-found or error shell rather than an article.
+ *
+ * @param text - Extracted Markdown or visible page text.
+ * @returns True when the text matches a Salesforce error/not-found pattern.
+ */
+export declare function looksLikeSalesforceError(text: string): boolean;
 /**
  * In-page block: pick the highest-priority content container that exists on the page.
  * Does not fall through to lower-priority selectors when a higher-priority host is present

package/dist/sites/salesforce-dom-probe.js

@@ -33,6 +33,23 @@ const deepText = (root) => {
 const textLenFor = (el) =>
   Math.max((el.innerText || '').trim().length, deepText(el).trim().length);
 `;
+// Shells Salesforce renders for a missing article. Shared with the readiness probe so a
+// not-found page ends the wait instead of burning the full content timeout.
+const SALESFORCE_ERROR_PATTERNS = [
+    /page\s*(not\s*found|doesn'?t\s*exist|can'?t\s*be\s*found)/i,
+    /we\s*couldn'?t\s*find/i,
+    /we looked high and low/i,
+    /sorry to interrupt/i,
+    /head back to the space station/i,
+];
+/** True when extracted text is a Salesforce not-found or error shell rather than an article.
+ *
+ * @param text - Extracted Markdown or visible page text.
+ * @returns True when the text matches a Salesforce error/not-found pattern.
+ */
+export function looksLikeSalesforceError(text) {
+    return SALESFORCE_ERROR_PATTERNS.some((re) => re.test(text));
+}
 /**
  * In-page block: pick the highest-priority content container that exists on the page.
  * Does not fall through to lower-priority selectors when a higher-priority host is present
@@ -64,6 +81,20 @@ export function buildPriorityContainerPickBlock(selectors, minChars, containerVa
       }
     }
     ${containerVar} = ${containerVar} || document.body || document.documentElement;
+    // A Redoc hash (#tag/…/operation/…) names one operation inside the reference.
+    // getElementById stops at the shadow boundary, so match the id while walking.
+    try {
+      const hashId = decodeURIComponent((location.hash || '').replace(/^#/, ''));
+      if (hashId) {
+        let hashBest = null, hashLen = 0;
+        for (const el of deepElements(document)) {
+          if (el.id !== hashId) continue;
+          const len = textLenFor(el);
+          if (len > hashLen) { hashBest = el; hashLen = len; }
+        }
+        if (hashBest && hashLen >= MIN_CHARS) ${containerVar} = hashBest;
+      }
+    } catch (e) {}
   `;
 }
 /**
@@ -75,8 +106,14 @@ export function buildPriorityContainerPickBlock(selectors, minChars, containerVa
  * @returns A self-invoking JS expression string that evaluates to `{ has: boolean, len: number }`.
  */
 export function buildContentReadyProbeExpression(selectors, minChars) {
+    const errorSource = SALESFORCE_ERROR_PATTERNS.map((re) => re.source).join('|');
     return `(() => {
     ${SALESFORCE_SHADOW_DOM_HELPERS}
+    const errorRe = new RegExp(${JSON.stringify(errorSource)}, 'i');
+    const pageText = deepText(document.body || document.documentElement);
+    if (errorRe.test(pageText)) {
+      return { has: true, len: pageText.length, error: true };
+    }
     const SELS = ${JSON.stringify(selectors)};
     const MIN = ${minChars};
     let has = false;
@@ -119,6 +156,9 @@ export async function pollSalesforceContentReady(page, selectors, minChars, time
             .send('Runtime.evaluate', { expression, returnByValue: true }, page.sessionId)
             .catch(() => null);
         const value = rawResult?.result?.value;
+        // A not-found shell is ready now; waiting for it to "settle" only delays the failure.
+        if (value?.error)
+            return;
         if (value?.has) {
             const grew = Math.abs((value.len || 0) - previousLength) > Math.max(40, previousLength * 0.02);
             if (!grew && ++stablePolls >= 2)

package/oclif.manifest.json

@@ -47,7 +47,13 @@
       "strict": true,
       "summary": "Show a compact cache dashboard for ambient session context",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "context.js"
+      ]
     },
     "fetch": {
       "aliases": [],
@@ -199,7 +205,13 @@
       "strict": false,
       "summary": "Fetch and cache URL research Markdown",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "fetch.js"
+      ]
     },
     "import": {
       "aliases": [],
@@ -349,7 +361,13 @@
       "strict": true,
       "summary": "Import agent-supplied Markdown into cache",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "import.js"
+      ]
     },
     "inspect": {
       "aliases": [],
@@ -408,7 +426,13 @@
       "strict": false,
       "summary": "Inspect cached research metadata for a URL",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "inspect.js"
+      ]
     },
     "list": {
       "aliases": [],
@@ -550,7 +574,13 @@
       "strict": true,
       "summary": "List cached research artifacts by metadata",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "list.js"
+      ]
     },
     "prune": {
       "aliases": [],
@@ -670,7 +700,13 @@
       "strict": true,
       "summary": "Prune cached research artifacts",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "prune.js"
+      ]
     },
     "search": {
       "aliases": [],
@@ -816,7 +852,13 @@
       "strict": true,
       "summary": "Search cached research artifacts by tags and content",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "search.js"
+      ]
     },
     "setup": {
       "aliases": [],
@@ -900,7 +942,13 @@
       "strict": true,
       "summary": "Install a SessionStart hook that shows live cache context",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "setup.js"
+      ]
     },
     "status": {
       "aliases": [],
@@ -986,20 +1034,32 @@
       "strict": false,
       "summary": "Check cache status without fetching or writing",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "status.js"
+      ]
     },
-    "config": {
+    "config:get": {
       "aliases": [],
-      "args": {},
-      "description": "Show config subcommands for reading and writing Bonsai research cache configuration.",
+      "args": {
+        "key": {
+          "description": "the configuration key to read",
+          "name": "key",
+          "required": false
+        }
+      },
+      "description": "Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. `fetch --storage`) > env var > project file > user file > built-in default.\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive).",
       "examples": [
         {
-          "description": "get a configuration value",
-          "command": "<%= config.bin %> <%= command.id %> get storage"
+          "description": "get the effective storage mode",
+          "command": "<%= config.bin %> config get storage"
         },
         {
-          "description": "set project storage mode",
-          "command": "<%= config.bin %> <%= command.id %> set storage project --local"
+          "description": "read only the project-level value",
+          "command": "<%= config.bin %> config get storage --local"
         }
       ],
       "flags": {
@@ -1024,37 +1084,56 @@
           "name": "toon",
           "allowNo": false,
           "type": "boolean"
+        },
+        "global": {
+          "char": "g",
+          "description": "read user-level config only",
+          "name": "global",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "local": {
+          "aliases": [
+            "project"
+          ],
+          "charAliases": [
+            "p"
+          ],
+          "description": "read project-level config only",
+          "name": "local",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "config",
+      "id": "config:get",
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
       "strict": true,
-      "summary": "Manage research cache configuration",
-      "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "summary": "Get a research configuration value",
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "get.js"
+      ]
     },
-    "config:get": {
+    "config": {
       "aliases": [],
-      "args": {
-        "key": {
-          "description": "the configuration key to read",
-          "name": "key",
-          "required": false
-        }
-      },
-      "description": "Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. `fetch --storage`) > env var > project file > user file > built-in default.\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive).",
+      "args": {},
+      "description": "Show config subcommands for reading and writing Bonsai research cache configuration.",
       "examples": [
         {
-          "description": "get the effective storage mode",
-          "command": "<%= config.bin %> config get storage"
+          "description": "get a configuration value",
+          "command": "<%= config.bin %> <%= command.id %> get storage"
         },
         {
-          "description": "read only the project-level value",
-          "command": "<%= config.bin %> config get storage --local"
+          "description": "set project storage mode",
+          "command": "<%= config.bin %> <%= command.id %> set storage project --local"
         }
       ],
       "flags": {
@@ -1079,36 +1158,25 @@
           "name": "toon",
           "allowNo": false,
           "type": "boolean"
-        },
-        "global": {
-          "char": "g",
-          "description": "read user-level config only",
-          "name": "global",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "local": {
-          "aliases": [
-            "project"
-          ],
-          "charAliases": [
-            "p"
-          ],
-          "description": "read project-level config only",
-          "name": "local",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "config:get",
+      "id": "config",
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
       "strict": true,
-      "summary": "Get a research configuration value",
-      "stdoutIsPrimaryData": true
+      "summary": "Manage research cache configuration",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "index.js"
+      ]
     },
     "config:list": {
       "aliases": [],
@@ -1175,7 +1243,14 @@
       "pluginType": "core",
       "strict": true,
       "summary": "List research configuration values",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "list.js"
+      ]
     },
     "config:set": {
       "aliases": [],
@@ -1259,7 +1334,14 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Set a research configuration key",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "set.js"
+      ]
     },
     "config:unset": {
       "aliases": [],
@@ -1338,8 +1420,15 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Remove a research configuration key",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "unset.js"
+      ]
     }
   },
-  "version": "4.1.0"
+  "version": "4.1.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -35,27 +35,23 @@
   },
   "dependencies": {
     "@mozilla/readability": "^0.5.0",
-    "@oclif/core": "^4.11.4",
-    "@oclif/plugin-autocomplete": "^3.2.52",
+    "@oclif/core": "^5.1.8",
+    "@oclif/plugin-autocomplete": "^4.0.4",
     "@toon-format/toon": "^4.0.0",
-    "linkedom": "^0.18.12",
+    "linkedom": "^0.18.13",
     "turndown": "^7.2.0",
-    "undici": "^8.7.0",
-    "update-notifier": "^7.3.1"
+    "undici": "^8.12.2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@types/jsdom": "^21.1.7",
-    "@types/mozilla-readability": "^0.2.1",
     "@types/node": "^22.10.0",
     "@types/turndown": "^5.0.5",
     "@vitest/coverage-istanbul": "^4.0.18",
     "eslint": "^10.7.0",
     "fallow": "^2.102.0",
     "husky": "^9.1.7",
-    "jsdom": "^26.0.0",
     "lint-staged": "^16.2.7",
-    "oclif": "^4.23.21",
+    "oclif": "^6.0.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.64.0",
@@ -78,9 +74,8 @@
       "@oclif/plugin-autocomplete"
     ],
     "commands": {
-      "strategy": "explicit",
-      "target": "./dist/commands.js",
-      "identifier": "commands"
+      "strategy": "pattern",
+      "target": "./dist/commands"
     },
     "topicSeparator": " ",
     "hooks": {