@taurgis/bonsai 1.0.0

package/dist/lib/research/docs/__fixtures__/sphinx-searchindex.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/research/docs/__fixtures__/sphinx-searchindex.js

@@ -0,0 +1,2 @@
+Search.setIndex({ "docnames": ["index", "library/functions", "library/string"], "filenames": ["index.rst", "library/functions.rst", "library/string.rst"], "titles": ["Python Documentation", "Built-in Functions", "String Methods"], "terms": { "function": [1], "string": [2], "print": [1], "format": [2] }, "titleterms": { "function": [1], "string": [2], "python": [0], "built": [1], "methods": [2] }, "objects": {}, "envversion": {} });
+export {};

package/dist/lib/research/docs/capabilities.d.ts

@@ -0,0 +1,43 @@
+export type Evidence = 'verified' | 'signal';
+export type DocsEngine = 'vitepress' | 'docusaurus' | 'starlight' | 'next' | 'generated-static' | 'spa';
+export type DocsFramework = 'mkdocs' | 'material-mkdocs' | 'sphinx' | 'nextra' | 'fumadocs' | 'gitbook' | 'mintlify' | 'readme' | 'redocly' | 'docsify' | 'rspress' | 'vuepress' | 'docsy' | 'just-the-docs';
+export type MachineReadableType = 'llms.txt' | 'llms-full.txt' | 'route-markdown' | 'search-index' | 'sitemap' | 'source-edit-link';
+export interface MachineReadableArtifact {
+    type: MachineReadableType;
+    url: string;
+    evidence: Evidence;
+}
+export interface SourceHint {
+    type: 'markdown' | 'mdx' | 'html';
+    url?: string;
+    repository?: string;
+    branch?: string;
+    path?: string;
+    evidence: Evidence;
+}
+export type SearchProvider = 'algolia-docsearch' | 'vitepress-local' | 'pagefind' | 'docusaurus-local' | 'mkdocs-local' | 'sphinx-searchindex' | 'jekyll-json' | 'readme-algolia' | 'custom';
+export interface SearchCapability {
+    provider: SearchProvider;
+    evidence: Evidence;
+    indexUrl?: string;
+    indexName?: string;
+    appId?: string;
+    apiKey?: string;
+    publicEndpoint?: string;
+}
+export interface PageMapEntry {
+    title: string;
+    url: string;
+    sourcePath?: string;
+}
+export interface SiteCapabilities {
+    docsEngine?: DocsEngine;
+    framework?: DocsFramework;
+    recommendedCapture: 'static' | 'rendered' | 'source';
+    machineReadable: MachineReadableArtifact[];
+    source?: SourceHint;
+    search?: SearchCapability;
+    pageMap?: PageMapEntry[];
+    notes: string[];
+}
+export declare function emptyCapabilities(): SiteCapabilities;

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

@@ -0,0 +1,9 @@
+// Capability model for documentation-aware research. A docs-engine detector (and, later,
+// machine-readable/source/search probes) fill this in so the generic pipeline can prefer the
+// best available artifact before falling back to HTML extraction. Evidence is deliberately
+// two-valued: `verified` means observed in the supplied bytes (markup/data/HTTP), `signal` means
+// the page hints at the capability but the endpoint/index/source is not proven. A visible search
+// button is at most a `signal` — never `verified` (see T-16/T-20 acceptance criteria).
+export function emptyCapabilities() {
+    return { recommendedCapture: 'static', machineReadable: [], notes: [] };
+}

package/dist/lib/research/docs/clean-dom.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Strips decorative docs chrome and base64 images from the document in place before extraction.
+ */
+export declare function cleanDocsChrome(document: any): void;

package/dist/lib/research/docs/clean-dom.js

@@ -0,0 +1,41 @@
+// Targeted pre-Readability cleanup for documentation chrome that Readability keeps but agents do
+// not want (T-21): Pagefind-ignored regions, contributor/avatar/sponsor galleries, theme
+// customizer widgets, and base64 `data:` images (e.g. the TypeScript logo, Astro contributor grid).
+// Deliberately narrow — Readability already drops generic nav/footer; over-stripping risks content.
+const CHROME_SELECTORS = [
+    '[data-pagefind-ignore]',
+    '[class*="contributor" i]',
+    '[class*="avatar" i]',
+    '[class*="sponsor" i]',
+    '[class*="customizer" i]',
+    '[class*="theme-toggle" i]',
+    '[class*="edit-link" i]',
+    '[aria-label*="theme" i]',
+];
+function removeMatching(document, selector) {
+    let nodes = [];
+    try {
+        nodes = Array.from(document.querySelectorAll(selector));
+    }
+    catch {
+        return; // ignore selectors linkedom can't parse
+    }
+    for (const node of nodes)
+        node.remove();
+}
+// Drops <img> with a data: URI and any anchor reduced to an empty icon link after that removal.
+function dropDataImages(document) {
+    for (const img of Array.from(document.querySelectorAll('img'))) {
+        const src = img.getAttribute('src') || '';
+        if (src.trim().toLowerCase().startsWith('data:'))
+            img.remove();
+    }
+}
+/**
+ * Strips decorative docs chrome and base64 images from the document in place before extraction.
+ */
+export function cleanDocsChrome(document) {
+    for (const selector of CHROME_SELECTORS)
+        removeMatching(document, selector);
+    dropDataImages(document);
+}

package/dist/lib/research/docs/code-blocks.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reconstructs newline-delimited text for every highlighted code block in the document and tags it
+ * with a `language-x` class when one is detectable. Idempotent and a no-op on plain `<pre>` blocks.
+ */
+export declare function normalizeCodeBlocks(document: any): void;

package/dist/lib/research/docs/code-blocks.js

@@ -0,0 +1,69 @@
+// Normalizes highlighted code DOM before Readability/Turndown so multi-line examples survive
+// (T-17). Syntax highlighters (Shiki, Expressive Code, Prism/Docusaurus) wrap each source line in
+// a <span class="line"> with no newline between spans; serialized to text they collapse onto one
+// line — exactly the Tailwind/Redux defects from Phase 2. We rebuild newline-delimited text and
+// preserve the language label as a `language-x` class Turndown understands. Operates in place.
+const LANGUAGE_HINTS = /\b(bash|shell|sh|zsh|console|ts|tsx|typescript|js|jsx|javascript|json|jsonc|html|xml|css|scss|less|python|py|go|golang|rust|rs|java|kotlin|ruby|rb|php|sql|yaml|yml|toml|diff|graphql|vue|svelte|astro|md|mdx|dockerfile|c|cpp|csharp|cs)\b/i;
+function detectLanguage(pre, code) {
+    const sources = [
+        code?.getAttribute?.('class'),
+        pre.getAttribute('class'),
+        pre.getAttribute('data-language'),
+        code?.getAttribute?.('data-language'),
+        pre.getAttribute('data-lang'),
+    ];
+    for (const src of sources) {
+        if (!src)
+            continue;
+        const explicit = src.match(/language-([\w-]+)/i);
+        if (explicit)
+            return explicit[1].toLowerCase();
+    }
+    // data-language attributes often hold a bare token (e.g. "bash").
+    for (const attr of ['data-language', 'data-lang']) {
+        const raw = pre.getAttribute(attr) || code?.getAttribute?.(attr);
+        if (raw && LANGUAGE_HINTS.test(raw))
+            return raw.toLowerCase();
+    }
+    return null;
+}
+function reconstructLines(code) {
+    const lineEls = code.querySelectorAll('.line, .token-line, [data-line]');
+    if (!lineEls.length)
+        return false;
+    const text = Array.from(lineEls)
+        .map((el) => el.textContent ?? '')
+        .join('\n')
+        .replace(/\n+$/, '');
+    code.textContent = text;
+    return true;
+}
+// Copy buttons render inside or beside code blocks and otherwise leak a stray "Copy" into Markdown.
+function removeCopyButtons(document) {
+    const candidates = document.querySelectorAll('button, [class*="copy" i], [class*="Copy"], [aria-label*="copy" i]');
+    for (const el of candidates) {
+        const cls = (el.getAttribute('class') || '').toString();
+        const aria = el.getAttribute('aria-label') || '';
+        const text = (el.textContent || '').trim();
+        if (/copy/i.test(cls) || /copy/i.test(aria) || /^copy$/i.test(text)) {
+            el.remove();
+        }
+    }
+}
+/**
+ * Reconstructs newline-delimited text for every highlighted code block in the document and tags it
+ * with a `language-x` class when one is detectable. Idempotent and a no-op on plain `<pre>` blocks.
+ */
+export function normalizeCodeBlocks(document) {
+    removeCopyButtons(document);
+    const pres = document.querySelectorAll('pre');
+    for (const pre of pres) {
+        const code = pre.querySelector('code') ?? pre;
+        const language = detectLanguage(pre, code === pre ? null : code);
+        reconstructLines(code);
+        if (language) {
+            const existing = (code.getAttribute('class') || '').replace(/language-[\w-]+/gi, '').trim();
+            code.setAttribute('class', `${existing} language-${language}`.trim());
+        }
+    }
+}

package/dist/lib/research/docs/detect.d.ts

@@ -0,0 +1,6 @@
+import type { SiteCapabilities } from './capabilities.js';
+/**
+ * Inspects page HTML and returns the detected docs engine/framework plus any capability signals.
+ * Always returns a result; an unrecognized page yields a best-effort static/SPA shape classification.
+ */
+export declare function detectDocsEngine(html: string, url: string): SiteCapabilities;

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

@@ -0,0 +1,239 @@
+import { parseHTML } from 'linkedom';
+import { emptyCapabilities } from './capabilities.js';
+import { parseGithubSourceLink } from './source-map.js';
+import { extractNextRscData } from './rsc.js';
+function getMetaGenerator(doc) {
+    const meta = doc.querySelector('meta[name="generator"]');
+    return (meta?.getAttribute('content') || '').toLowerCase();
+}
+// True when a link is genuinely an "edit this page" link, not just any GitHub link on the page.
+// Footer "Code of Conduct"/"License" links are `/blob/` links that must NOT be mistaken for the
+// page source — that produced a wrong tiny artifact in live testing. Require the `/edit/` route, or
+// an anchor whose class/text explicitly says edit.
+function isPageEditLink(link, href) {
+    if (href.includes('/edit/'))
+        return true;
+    const cls = (link.getAttribute('class') || '').toString();
+    const text = (link.textContent || '').trim();
+    return (/edit[-_ ]?(?:this|on|page)|edit-link/i.test(cls) ||
+        /edit (?:this )?page|edit on github/i.test(text));
+}
+// Finds the page's edit/source link and turns it into a source hint. Only a `signal` until the raw
+// URL is fetched/verified by the source-mapping layer (T-19).
+function findEditLinkSource(doc) {
+    const links = doc.querySelectorAll('a[href]');
+    for (const link of links) {
+        const href = link.getAttribute('href') || '';
+        if (!isPageEditLink(link, href))
+            continue;
+        const parsed = parseGithubSourceLink(href);
+        if (parsed) {
+            return {
+                type: parsed.path.endsWith('.mdx') ? 'mdx' : 'markdown',
+                repository: parsed.repository,
+                branch: parsed.branch,
+                path: parsed.path,
+                url: parsed.rawUrl,
+                evidence: 'signal',
+            };
+        }
+    }
+    return undefined;
+}
+// An advertised llms.txt link/hint in the markup (managed platforms embed these). Conventional
+// probing of llms.txt happens later (T-24); this only records what the page itself points to.
+function findLlmsTxtSignal(ctx) {
+    const match = ctx.html.match(/href=["']([^"']*llms(?:-full)?\.txt)["']/i);
+    if (!match)
+        return undefined;
+    try {
+        const resolved = new URL(match[1], ctx.url).toString();
+        const type = /llms-full\.txt$/i.test(resolved) ? 'llms-full.txt' : 'llms.txt';
+        return { type, url: resolved, evidence: 'signal' };
+    }
+    catch {
+        return undefined;
+    }
+}
+// Records search shape as a SIGNAL only. A visible button or a config blob is a lead, never proof
+// (T-16/T-20). Connectors promote these to `verified` from fixtures.
+function detectSearchSignal(ctx) {
+    const h = ctx.html;
+    // VitePress site data is embedded via JSON.parse("…") so quotes may be backslash-escaped.
+    if (/__VP_SITE_DATA__/.test(h) && /\\?"provider\\?"\s*:\s*\\?"local\\?"/.test(h)) {
+        return { provider: 'vitepress-local', evidence: 'signal' };
+    }
+    if (/docsearch/i.test(h) || /algolia/i.test(h)) {
+        return { provider: 'algolia-docsearch', evidence: 'signal' };
+    }
+    if (/data-pagefind-body/.test(h)) {
+        return { provider: 'pagefind', evidence: 'signal' };
+    }
+    return undefined;
+}
+function finalize(ctx, engine, framework, recommendedCapture, notes) {
+    const caps = emptyCapabilities();
+    caps.docsEngine = engine;
+    caps.framework = framework;
+    caps.recommendedCapture = recommendedCapture;
+    caps.notes = notes;
+    const source = findEditLinkSource(ctx.doc);
+    if (source) {
+        caps.source = source;
+        caps.machineReadable.push({ type: 'source-edit-link', url: source.url, evidence: 'signal' });
+    }
+    const llms = findLlmsTxtSignal(ctx);
+    if (llms)
+        caps.machineReadable.push(llms);
+    const search = detectSearchSignal(ctx);
+    if (search)
+        caps.search = search;
+    return caps;
+}
+const detectVitePress = (ctx) => {
+    if (!/__VP_HASH_MAP__|__VP_SITE_DATA__|class="[^"]*\bVPDoc\b/.test(ctx.html))
+        return null;
+    return finalize(ctx, 'vitepress', undefined, 'static', ['detected VitePress globals (verified)']);
+};
+const detectStarlight = (ctx) => {
+    // Starlight = Astro docs theme. Require its content markers; the Astro generator only strengthens
+    // the note (a bare Astro site without Starlight markers is not a docs page we special-case).
+    const starlightMarkers = /data-pagefind-body|sl-(?:doc-search|markdown-content|container)|starlight/i;
+    if (!starlightMarkers.test(ctx.html))
+        return null;
+    const note = ctx.generator.includes('astro')
+        ? 'detected Astro Starlight (generator + markers, verified)'
+        : 'detected Starlight markers (verified)';
+    return finalize(ctx, 'starlight', undefined, 'static', [note]);
+};
+const detectDocusaurus = (ctx) => {
+    if (!ctx.generator.includes('docusaurus') &&
+        !/__docusaurus|theme-doc-|docusaurus/i.test(ctx.html))
+        return null;
+    return finalize(ctx, 'docusaurus', undefined, 'static', [
+        'detected Docusaurus markers (verified)',
+    ]);
+};
+// Next/RSC frameworks: classify the framework first, then fall back to bare Next.
+const detectNextFamily = (ctx) => {
+    const isNext = /__NEXT_DATA__|\/_next\/static\/|self\.__next_f/.test(ctx.html);
+    const gen = ctx.generator;
+    let framework;
+    if (gen.includes('mintlify') || /mintlify/i.test(ctx.html))
+        framework = 'mintlify';
+    else if (/nextra/i.test(ctx.html))
+        framework = 'nextra';
+    else if (/fumadocs|fd-/i.test(ctx.html))
+        framework = 'fumadocs';
+    if (!isNext && !framework)
+        return null;
+    const note = framework
+        ? `detected Next.js + ${framework} (verified)`
+        : 'detected Next.js docs/app (verified)';
+    const caps = finalize(ctx, 'next', framework, 'static', [note]);
+    // Recover the RSC/App Router page map and source-path hints (inert; never executed).
+    const rsc = extractNextRscData(ctx.html);
+    if (rsc.pageMap.length)
+        caps.pageMap = rsc.pageMap;
+    if (rsc.sourcePathHints.length) {
+        caps.notes.push(`source-path hints (unverified): ${rsc.sourcePathHints.slice(0, 5).join(', ')}`);
+    }
+    return caps;
+};
+const detectMkDocs = (ctx) => {
+    const gen = ctx.generator;
+    if (!gen.includes('mkdocs') && !/mkdocs/i.test(ctx.html))
+        return null;
+    const framework = gen.includes('material') ? 'material-mkdocs' : 'mkdocs';
+    return finalize(ctx, 'generated-static', framework, 'static', [
+        `detected ${framework} (verified)`,
+    ]);
+};
+const detectSphinx = (ctx) => {
+    if (!ctx.generator.includes('sphinx') &&
+        !/DOCUMENTATION_OPTIONS|searchindex\.js|documentation_options\.js|class="sphinxsidebar"/.test(ctx.html))
+        return null;
+    return finalize(ctx, 'generated-static', 'sphinx', 'static', ['detected Sphinx (verified)']);
+};
+// Per-framework capability notes beyond the base "detected X" line. Kept out of the detector loop
+// so the loop stays a flat match-and-return.
+function managedFrameworkNotes(ctx, framework) {
+    const notes = [`detected ${framework} (verified)`];
+    if (framework === 'readme') {
+        if (/algolia/i.test(ctx.html))
+            notes.push('ReadMe Algolia search metadata present (signal)');
+        if (/openapi|oas/i.test(ctx.html))
+            notes.push('OpenAPI registry metadata present (signal)');
+    }
+    // Redocly did not expose llms.txt at the conventional path in research; do not assume one.
+    if (framework === 'redocly')
+        notes.push('llms.txt unverified at conventional path');
+    return notes;
+}
+const detectManagedAndThemes = (ctx) => {
+    const checks = [
+        [/gitbook/i, 'gitbook', undefined],
+        [/readme(?:\.io|\.com)|data-rm-|\brm-Guides\b/i, 'readme', undefined],
+        [/redocly|redoc/i, 'redocly', undefined],
+        [/rspress/i, 'rspress', 'generated-static'],
+        [/vuepress/i, 'vuepress', 'generated-static'],
+        [/just-the-docs|search-data\.json/i, 'just-the-docs', 'generated-static'],
+        [/td-(?:sidebar|content)|docsy/i, 'docsy', 'generated-static'],
+    ];
+    for (const [re, framework, engine] of checks) {
+        if (re.test(ctx.html) || ctx.generator.includes(framework)) {
+            return finalize(ctx, engine, framework, 'static', managedFrameworkNotes(ctx, framework));
+        }
+    }
+    return null;
+};
+const detectDocsify = (ctx) => {
+    if (!/\$docsify|docsify(?:\.min)?\.js|window\.\$docsify/i.test(ctx.html))
+        return null;
+    // Docsify renders Markdown client-side; static HTML is an empty app shell, so prefer rendered
+    // unless a source-Markdown mapping is found later (T-28).
+    return finalize(ctx, 'spa', 'docsify', 'rendered', [
+        'detected Docsify client-side Markdown renderer (verified)',
+    ]);
+};
+// Last resort: tell a script-heavy empty SPA shell apart from a real static/generated doc page.
+function detectGenericShape(ctx) {
+    const bodyText = (ctx.doc.body?.textContent || '').trim();
+    const scriptCount = ctx.doc.querySelectorAll('script').length;
+    if (bodyText.length < 400 && scriptCount >= 3) {
+        return finalize(ctx, 'spa', undefined, 'rendered', [
+            'thin body with heavy script payload; SPA rendered candidate (signal)',
+        ]);
+    }
+    const headings = ctx.doc.querySelectorAll('h1, h2, h3').length;
+    if (headings >= 8) {
+        return finalize(ctx, 'generated-static', undefined, 'static', [
+            'long static reference shape (many headings) (signal)',
+        ]);
+    }
+    return finalize(ctx, undefined, undefined, 'static', ['no docs-engine markers detected']);
+}
+const FAMILY_DETECTORS = [
+    detectVitePress,
+    detectStarlight,
+    detectDocusaurus,
+    detectMkDocs,
+    detectSphinx,
+    detectDocsify,
+    detectNextFamily,
+    detectManagedAndThemes,
+];
+/**
+ * Inspects page HTML and returns the detected docs engine/framework plus any capability signals.
+ * Always returns a result; an unrecognized page yields a best-effort static/SPA shape classification.
+ */
+export function detectDocsEngine(html, url) {
+    const { document } = parseHTML(html);
+    const ctx = { html, url, doc: document, generator: getMetaGenerator(document) };
+    for (const detector of FAMILY_DETECTORS) {
+        const result = detector(ctx);
+        if (result)
+            return result;
+    }
+    return detectGenericShape(ctx);
+}

package/dist/lib/research/docs/machine-readable.d.ts

@@ -0,0 +1,21 @@
+import type { MachineReadableArtifact, SiteCapabilities } from './capabilities.js';
+export interface MachineReadableResult {
+    artifact: MachineReadableArtifact;
+    body: string;
+}
+export type TextFetcher = (url: string) => Promise<{
+    content: string;
+    finalUrl: string;
+    status: number;
+    contentType: string | null;
+}>;
+/**
+ * Probes conventional and advertised `llms.txt` URLs. Returns the first that validates as same-origin
+ * text, or null. The result is a site-INDEX artifact for discovery — not a replacement for page content.
+ */
+export declare function probeLlmsTxt(pageUrl: string, caps: SiteCapabilities, fetcher?: TextFetcher): Promise<MachineReadableResult | null>;
+/**
+ * Probes a page-level `.md` route, but only when the engine/framework is known to serve one or the
+ * page advertises one. Returns validated Markdown source for the page, or null.
+ */
+export declare function probeRouteMarkdown(pageUrl: string, caps: SiteCapabilities, fetcher?: TextFetcher): Promise<MachineReadableResult | null>;

package/dist/lib/research/docs/machine-readable.js

@@ -0,0 +1,73 @@
+import { fetchText } from '../fetcher.js';
+import { isSameDocsOrigin, validateTextArtifact } from './validate.js';
+import { vitepressRouteMarkdown } from './source-map.js';
+const defaultFetcher = (url) => fetchText(url);
+// Frameworks/engines that the research observed serving page-level `.md` routes (T-24 evidence).
+function advertisesRouteMarkdown(caps) {
+    return (caps.docsEngine === 'vitepress' || caps.framework === 'rspress' || caps.framework === 'gitbook');
+}
+function llmsTxtCandidates(pageUrl, caps) {
+    const advertised = caps.machineReadable
+        .filter((m) => m.type === 'llms.txt' || m.type === 'llms-full.txt')
+        .map((m) => m.url);
+    const candidates = [...advertised];
+    try {
+        const u = new URL(pageUrl);
+        candidates.push(`${u.origin}/llms.txt`);
+        const firstSegment = u.pathname.split('/').filter(Boolean)[0];
+        if (firstSegment)
+            candidates.push(`${u.origin}/${firstSegment}/llms.txt`);
+    }
+    catch {
+        // pageUrl already validated upstream; ignore
+    }
+    // De-duplicate while preserving order (advertised first).
+    return [...new Set(candidates)];
+}
+async function tryFetchValidText(url, fetcher) {
+    try {
+        const res = await fetcher(url);
+        if (res.status === 304 || !res.content)
+            return null;
+        return validateTextArtifact(res.content).ok ? res.content : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Probes conventional and advertised `llms.txt` URLs. Returns the first that validates as same-origin
+ * text, or null. The result is a site-INDEX artifact for discovery — not a replacement for page content.
+ */
+export async function probeLlmsTxt(pageUrl, caps, fetcher = defaultFetcher) {
+    for (const candidate of llmsTxtCandidates(pageUrl, caps)) {
+        if (!isSameDocsOrigin(candidate, pageUrl))
+            continue;
+        const body = await tryFetchValidText(candidate, fetcher);
+        if (body) {
+            const type = /llms-full\.txt$/i.test(candidate) ? 'llms-full.txt' : 'llms.txt';
+            return { artifact: { type, url: candidate, evidence: 'verified' }, body };
+        }
+    }
+    return null;
+}
+/**
+ * Probes a page-level `.md` route, but only when the engine/framework is known to serve one or the
+ * page advertises one. Returns validated Markdown source for the page, or null.
+ */
+export async function probeRouteMarkdown(pageUrl, caps, fetcher = defaultFetcher) {
+    const advertised = caps.machineReadable
+        .filter((m) => m.type === 'route-markdown')
+        .map((m) => m.url);
+    const derived = advertisesRouteMarkdown(caps) ? [vitepressRouteMarkdown(pageUrl)] : [];
+    const candidates = [...new Set([...advertised, ...derived].filter((u) => !!u))];
+    for (const candidate of candidates) {
+        if (!isSameDocsOrigin(candidate, pageUrl))
+            continue;
+        const body = await tryFetchValidText(candidate, fetcher);
+        if (body) {
+            return { artifact: { type: 'route-markdown', url: candidate, evidence: 'verified' }, body };
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,17 @@
+import type { ExtractionResult } from '../extract.js';
+export interface ParsedFrontmatter {
+    frontmatter: Record<string, string>;
+    body: string;
+}
+export declare function parseFrontmatter(md: string): ParsedFrontmatter;
+/**
+ * Removes dangerous embedded HTML from untrusted Markdown: <script>/<style> blocks, inline event
+ * handler attributes, and javascript: URLs. Leaves ordinary Markdown and benign inline HTML intact.
+ */
+export declare function sanitizeSourceMarkdown(md: 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,
+ * tabs, and admonitions better than HTML conversion.
+ */
+export declare function extractFromSource(md: string, sourceUrl: string): ExtractionResult;