@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/lib/research/storage.js

@@ -37,7 +37,8 @@ export function getArtifactPath(dataDir, key) {
     return join(dataDir, 'research', `${key}.md`);
 }
 function processFileForLookup(file, dir, key) {
-    if (!file.endsWith('.md') || file.includes('.tmp')) {
+    // Same file filter as scanCacheDir — superseded/corrupt/tmp archives must not resolve as active.
+    if (!isResearchFile(file)) {
         return null;
     }
     const filePath = join(dir, file);
@@ -162,12 +163,16 @@ export function locateArtifact(dataDirs, key) {
  * order and deduplicates by cache key so an entry present in an earlier root (project) shadows
  * the same key in a later root (global) — even when the callback filters it out. Composes
  * scanCacheDir so the file-format and read/parse rules stay defined in exactly one place.
+ *
+ * Pass `persistIndex: false` under read-only/plan mode so listing never creates `.search-index.json`.
  */
-export function scanCacheDirs(dataDirs, fn) {
+export function scanCacheDirs(dataDirs, fn, options = {}) {
     const seen = new Set();
     return dataDirs.flatMap((dataDir) => {
         const researchDir = join(dataDir, 'research');
-        const searchable = loadIndexedArtifactsForDir(researchDir);
+        const searchable = loadIndexedArtifactsForDir(researchDir, {
+            persist: options.persistIndex,
+        });
         return searchable
             .map(({ artifact, filePath }) => {
             const key = artifact.metadata.cache_key;

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

@@ -1,5 +1,9 @@
 import type { SummaryLevel } from '../config/schema.js';
+/** Re-export of the configured summary aggressiveness level (`conservative` | `balanced` | `aggressive`). */
 export type { SummaryLevel };
+/**
+ * Options for `summarizeMarkdown`. All fields are optional; omitted values use the documented defaults.
+ */
 export interface SummarizeOptions {
     /** Aggressiveness of prose reduction. Default 'conservative'. */
     level?: SummaryLevel;
@@ -8,10 +12,21 @@ export interface SummarizeOptions {
     /** Prose paragraphs with fewer sentences than this are kept whole. Default 2. */
     minSentences?: number;
 }
+/**
+ * Splits a prose paragraph into individual sentences. Avoids false boundaries inside inline code,
+ * after known abbreviations, and before digits.
+ *
+ * @param paragraph - A single prose paragraph (no Markdown structure like headings or lists).
+ * @returns Array of sentence strings in document order.
+ */
 export declare function splitSentences(paragraph: string): string[];
 /**
  * Extractively shortens the prose paragraphs of a Markdown document while preserving headings,
  * fenced code blocks, tables, and lists verbatim. Returns the input unchanged when it is below
  * `minTokens` or contains no prose to condense. Deterministic for identical input + options.
+ *
+ * @param markdown - Markdown document to summarize.
+ * @param options - Summarization options (level, minTokens, minSentences).
+ * @returns Summarized Markdown, or the original when no summarization is needed.
  */
 export declare function summarizeMarkdown(markdown: string, options?: SummarizeOptions): string;

package/dist/lib/research/summarize.js

@@ -166,6 +166,13 @@ function shouldSkipBoundary(masked, i, end) {
 // Splits a single prose paragraph into sentences, avoiding splits inside inline code, after known
 // abbreviations or single-letter initials, and before digits. Exported for unit testing because
 // sentence boundaries are not observable once kept sentences are rejoined.
+/**
+ * Splits a prose paragraph into individual sentences. Avoids false boundaries inside inline code,
+ * after known abbreviations, and before digits.
+ *
+ * @param paragraph - A single prose paragraph (no Markdown structure like headings or lists).
+ * @returns Array of sentence strings in document order.
+ */
 export function splitSentences(paragraph) {
     const { masked, restore } = maskInlineCode(paragraph);
     const sentences = [];
@@ -381,6 +388,10 @@ function reassemble(segments, sentences, kept) {
  * Extractively shortens the prose paragraphs of a Markdown document while preserving headings,
  * fenced code blocks, tables, and lists verbatim. Returns the input unchanged when it is below
  * `minTokens` or contains no prose to condense. Deterministic for identical input + options.
+ *
+ * @param markdown - Markdown document to summarize.
+ * @param options - Summarization options (level, minTokens, minSentences).
+ * @returns Summarized Markdown, or the original when no summarization is needed.
  */
 export function summarizeMarkdown(markdown, options = {}) {
     const level = options.level ?? 'conservative';

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

@@ -1,11 +1,13 @@
 /**
  * Checks if a literal IPv4 address is in a safe range.
- * Rejects loopback, private RFC1918, and link-local ranges.
+ * Rejects "this network", loopback, private RFC1918, shared address space (CGNAT), and link-local
+ * ranges — the non-globally-reachable blocks in the IANA IPv4 special-purpose registry
+ * (https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml).
  */
 export declare function isSafeIpv4(ip: string): boolean;
 /**
  * Checks if a literal IPv6 address is in a safe range.
- * Rejects loopback, unspecified, link-local, and mapped unsafe IPv4 ranges.
+ * Rejects loopback, unspecified, link-local, unique-local, and mapped unsafe IPv4 ranges.
  */
 export declare function isSafeIpv6(ip: string): boolean;
 /**
@@ -13,10 +15,6 @@ export declare function isSafeIpv6(ip: string): boolean;
  * Returns false for loopback, private, link-local, or unspecified ranges.
  */
 export declare function isSafeIp(ip: string): boolean;
-/**
- * Validates a hostname to ensure it is not blocked (e.g. localhost or literal private IP).
- */
-export declare function validateHostname(hostname: string): void;
 /**
  * Whether the input looks like a URL that simply forgot its `http(s)://` scheme
  * (`example.com`, `docs.nestjs.com/guide`, `192.168.1.1`) rather than unparseable junk.
@@ -40,6 +38,11 @@ export declare function artifactMatchesUrlFilter(meta: {
     source_urls?: string[];
     source_url?: string;
 }, filterUrl: string | undefined): boolean;
+/**
+ * Reject empty/whitespace `--url` globs on list/prune. Almost always a shell-quoting mistake;
+ * matching the empty string silently would look like "no results" instead of bad input.
+ */
+export declare function emptyUrlFilterError(url: string | undefined): string | undefined;
 /**
  * Checks if a filename matches the standard research note naming pattern.
  */

package/dist/lib/research/url.js

@@ -1,7 +1,9 @@
 import { isIP } from 'node:net';
 /**
  * Checks if a literal IPv4 address is in a safe range.
- * Rejects loopback, private RFC1918, and link-local ranges.
+ * Rejects "this network", loopback, private RFC1918, shared address space (CGNAT), and link-local
+ * ranges — the non-globally-reachable blocks in the IANA IPv4 special-purpose registry
+ * (https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml).
  */
 export function isSafeIpv4(ip) {
     const parts = ip.split('.').map(Number);
@@ -10,6 +12,10 @@ export function isSafeIpv4(ip) {
     const [a, b, c] = parts;
     if (a === undefined || b === undefined || c === undefined)
         return false;
+    // "This network" / unspecified: 0.0.0.0/8 (includes 0.0.0.0 itself, a well-known SSRF-filter
+    // bypass — many stacks route it to the loopback interface, same as 127.0.0.1).
+    if (a === 0)
+        return false;
     // Loopback: 127.0.0.0/8
     if (a === 127)
         return false;
@@ -20,6 +26,9 @@ export function isSafeIpv4(ip) {
         return false;
     if (a === 192 && b === 168)
         return false;
+    // Shared Address Space / CGNAT (RFC6598): 100.64.0.0/10
+    if (a === 100 && b >= 64 && b <= 127)
+        return false;
     // Link-local: 169.254.0.0/16
     if (a === 169 && b === 254)
         return false;
@@ -27,7 +36,7 @@ export function isSafeIpv4(ip) {
 }
 /**
  * Checks if a literal IPv6 address is in a safe range.
- * Rejects loopback, unspecified, link-local, and mapped unsafe IPv4 ranges.
+ * Rejects loopback, unspecified, link-local, unique-local, and mapped unsafe IPv4 ranges.
  */
 export function isSafeIpv6(ip) {
     const cleanIp = ip.toLowerCase().trim();
@@ -44,6 +53,13 @@ export function isSafeIpv6(ip) {
         cleanIp.startsWith('feb')) {
         return false;
     }
+    // Unique Local Address (RFC4193): fc00::/7 (fc00 to fdff) — IPv6's RFC1918 equivalent, commonly
+    // used for internal/container networks. Only a full 4-digit first hextet can reach 0xfc00; a
+    // shorter one (leading zeros suppressed) is always < 0x1000 and safely out of range.
+    const firstGroup = cleanIp.split(':')[0] ?? '';
+    if (firstGroup.length === 4 && (firstGroup.startsWith('fc') || firstGroup.startsWith('fd'))) {
+        return false;
+    }
     // IPv4-mapped IPv6: ::ffff:127.0.0.1
     if (cleanIp.startsWith('::ffff:')) {
         const ipv4Part = ip.slice(7);
@@ -65,24 +81,6 @@ export function isSafeIp(ip) {
         return isSafeIpv6(ip);
     return false;
 }
-/**
- * Validates a hostname to ensure it is not blocked (e.g. localhost or literal private IP).
- */
-export function validateHostname(hostname) {
-    const lower = hostname.toLowerCase().trim();
-    if (lower === 'localhost' || lower.endsWith('.localhost')) {
-        throw new Error(`Hostname "${hostname}" is a blocked local target.`);
-    }
-    let ipToCheck = lower;
-    if (ipToCheck.startsWith('[') && ipToCheck.endsWith(']')) {
-        ipToCheck = ipToCheck.slice(1, -1);
-    }
-    if (isIP(ipToCheck) !== 0) {
-        if (!isSafeIp(ipToCheck)) {
-            throw new Error(`IP address "${ipToCheck}" is a blocked local or private target.`);
-        }
-    }
-}
 // Dot-separated, non-empty labels: a real domain (`docs.nestjs.com`) or IPv4 (`192.168.1.1`). The
 // URL parser also accepts a leading-dot filename (`.env`) or relative path (`./x`) as a "host", whose
 // suggestion would be a nonsense `https://.env`; requiring well-formed labels rejects those. Anchored
@@ -133,7 +131,9 @@ export function normalizeUrl(input) {
     if (url.username || url.password) {
         throw new Error('URLs containing usernames or passwords are rejected.');
     }
-    validateHostname(url.hostname);
+    // Localhost / private hosts are valid cache keys (import + cache-hit lookup). SSRF protection
+    // lives in the network layer (fetcher/browser DNS checks), so a later `bonsai http://localhost/…`
+    // can serve an imported note without ever opening a socket — while a cache miss still fails safely.
     // Clear default ports
     if (url.protocol === 'https:' && url.port === '443') {
         url.port = '';
@@ -175,6 +175,18 @@ export function artifactMatchesUrlFilter(meta, filterUrl) {
     const urls = meta.source_urls || (meta.source_url ? [meta.source_url] : []);
     return urls.some((u) => matchesUrlGlob(u, filterUrl));
 }
+/**
+ * Reject empty/whitespace `--url` globs on list/prune. Almost always a shell-quoting mistake;
+ * matching the empty string silently would look like "no results" instead of bad input.
+ */
+export function emptyUrlFilterError(url) {
+    if (url === undefined)
+        return undefined;
+    if (url.trim() === '') {
+        return '--url must be a non-empty glob pattern (e.g. "https://react.dev/*").';
+    }
+    return undefined;
+}
 /**
  * Checks if a filename matches the standard research note naming pattern.
  */

package/dist/lib/text.d.ts

@@ -18,8 +18,8 @@ export interface ResultListLabels {
 /** Heading for a result listing; notes truncation inline when more matched than are shown. */
 export declare function resultListHeading(total: number, shown: number, labels: ResultListLabels): string;
 /**
- * One-line truncation notice for stderr, or null when nothing was cut. Used under --json, where the
- * stdout heading is suppressed and an agent would otherwise get no signal that results were capped.
+ * One-line truncation notice for stderr, or null when nothing was cut. Available for human-mode
+ * tips; `list --json` surfaces truncation via the envelope `truncation` field instead (#91).
  */
 export declare function truncationNotice(total: number, shown: number, labels: ResultListLabels): string | null;
 /** Max edit distance for a plausible typo; scales with input length. */
@@ -35,3 +35,8 @@ export declare function levenshtein(s1: string, s2: string): number;
  * gets no correction rather than an absurd one.
  */
 export declare function closestMatch(input: string, candidates: readonly string[], maxDistance: number): string | null;
+/**
+ * Plausible option-value corrections: edit-distance first, then prefix matches for truncated enums
+ * (`stale` → `stale_grace` / `stale_expired`) where Levenshtein alone is too far.
+ */
+export declare function closestOptionValues(input: string, options: readonly string[]): string[];

package/dist/lib/text.js

@@ -16,8 +16,8 @@ export function resultListHeading(total, shown, labels) {
         : `Found ${total} ${noun}:`;
 }
 /**
- * One-line truncation notice for stderr, or null when nothing was cut. Used under --json, where the
- * stdout heading is suppressed and an agent would otherwise get no signal that results were capped.
+ * One-line truncation notice for stderr, or null when nothing was cut. Available for human-mode
+ * tips; `list --json` surfaces truncation via the envelope `truncation` field instead (#91).
  */
 export function truncationNotice(total, shown, labels) {
     if (total <= shown)
@@ -71,3 +71,14 @@ export function closestMatch(input, candidates, maxDistance) {
     }
     return bestDistance <= maxDistance ? best : null;
 }
+/**
+ * Plausible option-value corrections: edit-distance first, then prefix matches for truncated enums
+ * (`stale` → `stale_grace` / `stale_expired`) where Levenshtein alone is too far.
+ */
+export function closestOptionValues(input, options) {
+    const edit = closestMatch(input, options, maxFuzzyDistance(input));
+    if (edit)
+        return [edit];
+    // Exact equals already won via closestMatch; prefix covers truncated enums (stale → stale_*).
+    return options.filter((option) => option.startsWith(`${input}_`));
+}

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

@@ -0,0 +1,14 @@
+import type { Command } from '@oclif/core';
+type FlagDef = {
+    type?: string;
+    char?: string;
+    aliases?: string[] | string;
+    charAliases?: string[];
+};
+/**
+ * Derive every CLI token that consumes a following argv value from command class metadata
+ * (long names, short chars, aliases). Used by argv normalization so VALUE_TAKING_FLAG_TOKENS
+ * cannot drift from the real command surface.
+ */
+export declare function valueTakingFlagTokensFromCommands(commands: Record<string, typeof Command>, extraBaseFlags?: Record<string, FlagDef>): Set<string>;
+export {};

package/dist/lib/value-flags.js

@@ -0,0 +1,28 @@
+/** Every argv token that selects this flag: long name, short char, and all aliases. */
+function flagTokens(name, flag) {
+    const tokens = [`--${name}`];
+    if (flag.char)
+        tokens.push(`-${flag.char}`);
+    const aliases = typeof flag.aliases === 'string' ? [flag.aliases] : (flag.aliases ?? []);
+    tokens.push(...aliases.map((alias) => `--${alias}`));
+    tokens.push(...(flag.charAliases ?? []).map((charAlias) => `-${charAlias}`));
+    return tokens;
+}
+/**
+ * Derive every CLI token that consumes a following argv value from command class metadata
+ * (long names, short chars, aliases). Used by argv normalization so VALUE_TAKING_FLAG_TOKENS
+ * cannot drift from the real command surface.
+ */
+export function valueTakingFlagTokensFromCommands(commands, extraBaseFlags = {}) {
+    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)) {
+            if (!flag || flag.type === 'boolean')
+                continue;
+            for (const token of flagTokens(name, flag))
+                tokens.add(token);
+        }
+    }
+    return tokens;
+}

package/dist/sites/coveo.d.ts

@@ -1,7 +1,17 @@
+/** Hostnames served by Salesforce-operated Lightning Web Runtime (LWR) doc sites with shared browser-capture logic. */
 export declare const ALLOWED_DOC_HOSTS: Set<string>;
+/**
+ * Returns true when `hostname` is one of the allowed Salesforce doc hosts.
+ *
+ * @param hostname - Hostname to check (case-insensitive).
+ * @returns True when the hostname is in `ALLOWED_DOC_HOSTS`.
+ */
 export declare function isAllowedDocHost(hostname: string): boolean;
 /**
  * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
  * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ *
+ * @param rawUrl - Any URL string; non-matching URLs are returned unchanged.
+ * @returns The canonical articleView URL, or `rawUrl` unchanged if no rewrite applies.
  */
 export declare function normalizeHelpDocContentUrl(rawUrl: string): string;

package/dist/sites/coveo.js

@@ -1,10 +1,20 @@
+/** Hostnames served by Salesforce-operated Lightning Web Runtime (LWR) doc sites with shared browser-capture logic. */
 export const ALLOWED_DOC_HOSTS = new Set(['help.salesforce.com', 'developer.salesforce.com']);
+/**
+ * Returns true when `hostname` is one of the allowed Salesforce doc hosts.
+ *
+ * @param hostname - Hostname to check (case-insensitive).
+ * @returns True when the hostname is in `ALLOWED_DOC_HOSTS`.
+ */
 export function isAllowedDocHost(hostname) {
     return ALLOWED_DOC_HOSTS.has(hostname.toLowerCase());
 }
 /**
  * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
  * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ *
+ * @param rawUrl - Any URL string; non-matching URLs are returned unchanged.
+ * @returns The canonical articleView URL, or `rawUrl` unchanged if no rewrite applies.
  */
 export function normalizeHelpDocContentUrl(rawUrl) {
     let url;

package/dist/sites/index.d.ts

@@ -1,4 +1,20 @@
 import type { SiteModule } from './types.js';
+/**
+ * Built-in documentation site modules shipped with the CLI (not a runtime registry).
+ * Salesforce Help and Salesforce Developer are separate entries — different domains and extractors.
+ */
 export declare const SITES: SiteModule[];
+/**
+ * Matches a URL to its registered site module by hostname. Returns undefined for unrecognized hosts.
+ *
+ * @param url - Any URL string; invalid URLs return undefined rather than throwing.
+ * @returns The matching SiteModule, or undefined when no registered site owns the URL's hostname.
+ */
 export declare function detectSite(url: string): SiteModule | undefined;
+/**
+ * Looks up a registered site module by its stable identifier (e.g. `'salesforce'`).
+ *
+ * @param id - The site module's `id` field.
+ * @returns The matching SiteModule, or undefined when no module with that id is registered.
+ */
 export declare function getSiteModuleById(id: string): SiteModule | undefined;

package/dist/sites/index.js

@@ -1,9 +1,9 @@
 import { salesforce } from './salesforce/index.js';
 import { salesforceDeveloper } from './salesforce-developer/index.js';
-// The known documentation sites. A plain constant, not a registry: these ship
-// with the CLI, so there is nothing to register at runtime. Sites with custom
-// fetch behavior live in their own module (e.g. ./salesforce). Salesforce Help and
-// Salesforce Developer are separate modules — different domains, different extraction.
+/**
+ * Built-in documentation site modules shipped with the CLI (not a runtime registry).
+ * Salesforce Help and Salesforce Developer are separate entries — different domains and extractors.
+ */
 export const SITES = [
     salesforce,
     salesforceDeveloper,
@@ -12,6 +12,12 @@ export const SITES = [
     // Forcing rendered here bypassed that and dropped fenced code samples (e.g. useQueries).
     { id: 'tanstack', name: 'TanStack', domains: ['tanstack.com'] },
 ];
+/**
+ * Matches a URL to its registered site module by hostname. Returns undefined for unrecognized hosts.
+ *
+ * @param url - Any URL string; invalid URLs return undefined rather than throwing.
+ * @returns The matching SiteModule, or undefined when no registered site owns the URL's hostname.
+ */
 export function detectSite(url) {
     let hostname;
     try {
@@ -22,6 +28,12 @@ export function detectSite(url) {
     }
     return SITES.find((site) => site.domains.includes(hostname));
 }
+/**
+ * Looks up a registered site module by its stable identifier (e.g. `'salesforce'`).
+ *
+ * @param id - The site module's `id` field.
+ * @returns The matching SiteModule, or undefined when no module with that id is registered.
+ */
 export function getSiteModuleById(id) {
     return SITES.find((site) => site.id === id);
 }

package/dist/sites/markdown-twin.d.ts

@@ -0,0 +1,31 @@
+import { fetchText } from '../lib/research/fetcher.js';
+import type { SiteFetchResult } from './types.js';
+/** Result of a per-site body transform applied before extraction. */
+export interface TwinBodyTransform {
+    body: string;
+    /** Appended to the extraction's qualityNotes when set (e.g. "N directive(s) removed"). */
+    qualityNote?: string;
+}
+/** Options for {@link probeMarkdownTwin}. */
+export interface MarkdownTwinOptions {
+    /** Hostname the redirect chain must land on (see `isValidatedMarkdownTwin`). */
+    allowedHost: string;
+    /** Injectable fetcher (tests supply a fixture; production defaults to `fetchText`). */
+    fetcher?: typeof fetchText;
+    timeoutMs?: number;
+    /** Extra request headers (e.g. a WAF-appeasing User-Agent). */
+    headers?: Record<string, string>;
+    /** Applied to the raw body before extraction. Omit when the twin needs no preprocessing. */
+    transformBody?: (body: string) => TwinBodyTransform;
+}
+/**
+ * Probes candidate `.md`-twin URLs in order and returns the first that validates as a usable
+ * article, packaged as a SiteFetchResult with `route_markdown` provenance. Returns null when
+ * every candidate 404s, fails validation, or extracts thinner than the minimum viable article —
+ * callers fall back to their browser capture in that case. Never throws.
+ *
+ * @param candidates - Candidate `.md` URLs to try, in order.
+ * @param options - Allowed host, injectable fetcher/timeout, and an optional body transform.
+ * @returns SiteFetchResult with `route_markdown` provenance, or null when no candidate validates.
+ */
+export declare function probeMarkdownTwin(candidates: string[], { allowedHost, fetcher, timeoutMs, headers, transformBody, }: MarkdownTwinOptions): Promise<SiteFetchResult | null>;

package/dist/sites/markdown-twin.js

@@ -0,0 +1,56 @@
+import { fetchText } from '../lib/research/fetcher.js';
+import { isValidatedMarkdownTwin } from '../lib/research/docs/validate.js';
+import { extractFromSource } from '../lib/research/docs/markdown-source.js';
+// Shared shape behind every site module's ".md twin" probe: try candidate URLs, validate the
+// response against the expected host, and — once the body clears the minimum-viable-article
+// length — package it into the SiteFetchResult shape createArtifactFromFetch expects. Two site
+// modules use this: developer.salesforce.com (one derived URL) and help.salesforce.com (two
+// category candidates on the b2c-developer-tooling mirror). `transformBody` covers the one place
+// they differ — Developer strips unresolvable `::include{…}` directives before extraction.
+const DEFAULT_PROBE_TIMEOUT_MS = 4_000;
+// A twin this thin reads as a rollout stub/placeholder rather than a real article.
+const MIN_TWIN_CHARS = 100;
+/**
+ * Probes candidate `.md`-twin URLs in order and returns the first that validates as a usable
+ * article, packaged as a SiteFetchResult with `route_markdown` provenance. Returns null when
+ * every candidate 404s, fails validation, or extracts thinner than the minimum viable article —
+ * callers fall back to their browser capture in that case. Never throws.
+ *
+ * @param candidates - Candidate `.md` URLs to try, in order.
+ * @param options - Allowed host, injectable fetcher/timeout, and an optional body transform.
+ * @returns SiteFetchResult with `route_markdown` provenance, or null when no candidate validates.
+ */
+export async function probeMarkdownTwin(candidates, { allowedHost, fetcher = fetchText, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS, headers, transformBody, }) {
+    for (const candidate of candidates) {
+        let res;
+        try {
+            res = await fetcher(candidate, { timeoutMs, headers });
+        }
+        catch {
+            continue;
+        }
+        if (!isValidatedMarkdownTwin(res, allowedHost))
+            continue;
+        const transformed = transformBody?.(res.content);
+        const extraction = extractFromSource(transformed?.body ?? res.content, res.finalUrl);
+        if (extraction.detailedMarkdown.length < MIN_TWIN_CHARS)
+            continue;
+        if (transformed?.qualityNote) {
+            extraction.qualityNotes = [...(extraction.qualityNotes ?? []), transformed.qualityNote];
+        }
+        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,
+        };
+    }
+    return null;
+}

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

@@ -1,6 +1,12 @@
 import type { SiteFetchResult } from '../types.js';
 /**
- * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten
- * to the canonical /s/articleView page first; the shared LWR fetcher does the rest.
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten to
+ * the canonical /s/articleView page first. The Salesforce B2C Developer Tooling project mirrors a
+ * curated set of B2C Commerce Help articles as static Markdown; that twin is probed next, and used
+ * when it validates. Otherwise the shared Lightning Web Runtime (LWR) fetcher renders the page.
+ *
+ * @param url - The help.salesforce.com article URL (or a Coveo /help_doccontent URL).
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export declare function fetchSalesforcePage(url: string): Promise<SiteFetchResult>;

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

@@ -1,5 +1,6 @@
 import { fetchSalesforceDoc } from '../salesforce-doc-fetch.js';
 import { normalizeHelpDocContentUrl } from '../coveo.js';
+import { fetchHelpToolingMarkdown } from './help-tooling-markdown.js';
 // Containers a Help article renders into (inside shadow DOM); the shared fetcher pierces
 // shadow roots to find them, falling back to the page body when none match.
 const CONTENT_SELECTORS = [
@@ -13,11 +14,21 @@ const CONTENT_SELECTORS = [
     '.cHCPortalTheme',
 ];
 /**
- * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten
- * to the canonical /s/articleView page first; the shared LWR fetcher does the rest.
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten to
+ * the canonical /s/articleView page first. The Salesforce B2C Developer Tooling project mirrors a
+ * curated set of B2C Commerce Help articles as static Markdown; that twin is probed next, and used
+ * when it validates. Otherwise the shared Lightning Web Runtime (LWR) fetcher renders the page.
+ *
+ * @param url - The help.salesforce.com article URL (or a Coveo /help_doccontent URL).
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export async function fetchSalesforcePage(url) {
-    return fetchSalesforceDoc(normalizeHelpDocContentUrl(url), {
+    const normalizedUrl = normalizeHelpDocContentUrl(url);
+    const fromToolingMirror = await fetchHelpToolingMarkdown(normalizedUrl);
+    if (fromToolingMirror)
+        return fromToolingMirror;
+    return fetchSalesforceDoc(normalizedUrl, {
         allowedHost: 'help.salesforce.com',
         contentSelectors: CONTENT_SELECTORS,
         removeSelectors: [

package/dist/sites/salesforce/help-tooling-markdown.d.ts

@@ -0,0 +1,30 @@
+import { fetchText } from '../../lib/research/fetcher.js';
+import type { SiteFetchResult } from '../types.js';
+/**
+ * Extracts the b2c-developer-tooling slug from a help.salesforce.com article URL, or null when the
+ * URL isn't a `cc.<slug>.htm` B2C Commerce Help article (wrong host, missing `id`, or an `id` that
+ * doesn't follow that pattern — e.g. numeric knowledge-article ids, or other clouds' Help content).
+ *
+ * @param url - A help.salesforce.com article URL (or any URL; non-matching returns null).
+ * @returns The derived slug (e.g. `b2c_inventory_list_object_import_export`), or null.
+ */
+export declare function deriveHelpToolingSlug(url: string): string | null;
+/**
+ * Builds the candidate mirror URLs for a slug, one per known category. Category membership isn't
+ * derivable from the URL, so callers must probe each until one validates.
+ *
+ * @param slug - Slug derived by {@link deriveHelpToolingSlug}.
+ * @returns Candidate `.md` URLs on the b2c-developer-tooling mirror, one per category.
+ */
+export declare function candidateHelpToolingUrls(slug: string): string[];
+/**
+ * Probes the b2c-developer-tooling Markdown mirror for a help.salesforce.com article. Returns a
+ * complete SiteFetchResult (with route_markdown provenance) for the first category whose twin
+ * validates, or null so the caller falls back to the browser capture. Never throws: any
+ * network/validation failure just means "no twin in this category," or "no twin at all."
+ *
+ * @param url - The help.salesforce.com article URL to probe.
+ * @param fetcher - HTTP fetcher (injectable for tests; defaults to `fetchText`).
+ * @returns SiteFetchResult with route_markdown provenance, or null when no valid twin is found.
+ */
+export declare function fetchHelpToolingMarkdown(url: string, fetcher?: typeof fetchText): Promise<SiteFetchResult | null>;