@taurgis/bonsai 1.0.3 → 1.0.5

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

@@ -1,5 +1,24 @@
+import { type SummaryLevel } from './summarize.js';
 /**
  * Compresses Markdown text by removing images, simplifying links from [text](url) to [text],
  * and collapsing multiple consecutive blank lines.
  */
 export declare function compressMarkdown(markdown: string): string;
+/**
+ * Produces the `compressed` form of fetched content. Structural compression (strip images,
+ * simplify links, collapse blank lines) runs first, then the dependency-free extractive summarizer
+ * condenses prose to the chosen aggressiveness while keeping headings, code, tables, and lists
+ * intact. The summarizer self-guards: documents below the token floor, or with no prose to drop
+ * (e.g. pure structure once links/images are stripped), come back unchanged. Running it
+ * unconditionally — rather than only as a fallback when structural compression underperforms — is
+ * what makes the `summary` level matter even on link-heavy pages that structural compression
+ * already shrinks. This is the single place the "how do we build compressed" policy lives.
+ *
+ * A trust guard backs all of this: `compressed` is only useful if it is a non-empty, no-larger view
+ * of `detailed`. Both steps only ever remove content, so that should always hold — but rather than
+ * assume it, we verify and fall back through progressively safer forms (summarized → structural →
+ * detailed). This means the cache can never end up serving a `compressed` that is larger than
+ * `detailed`, or one that is empty while `detailed` has content — if the auto-compaction can't be
+ * trusted, the caller transparently gets the (verified) structural form or the detailed text itself.
+ */
+export declare function buildCompressed(detailed: string, level: SummaryLevel): string;

package/dist/lib/research/compress.js

@@ -1,3 +1,6 @@
+import { summarizeMarkdown } from './summarize.js';
+// Below this token count a page is never extractively summarized — there is nothing to gain.
+const SUMMARY_FLOOR_TOKENS = 200;
 /**
  * Compresses Markdown text by removing images, simplifying links from [text](url) to [text],
  * and collapsing multiple consecutive blank lines.
@@ -15,3 +18,31 @@ export function compressMarkdown(markdown) {
     result = result.replace(/\n{3,}/g, '\n\n');
     return result.trim();
 }
+/**
+ * Produces the `compressed` form of fetched content. Structural compression (strip images,
+ * simplify links, collapse blank lines) runs first, then the dependency-free extractive summarizer
+ * condenses prose to the chosen aggressiveness while keeping headings, code, tables, and lists
+ * intact. The summarizer self-guards: documents below the token floor, or with no prose to drop
+ * (e.g. pure structure once links/images are stripped), come back unchanged. Running it
+ * unconditionally — rather than only as a fallback when structural compression underperforms — is
+ * what makes the `summary` level matter even on link-heavy pages that structural compression
+ * already shrinks. This is the single place the "how do we build compressed" policy lives.
+ *
+ * A trust guard backs all of this: `compressed` is only useful if it is a non-empty, no-larger view
+ * of `detailed`. Both steps only ever remove content, so that should always hold — but rather than
+ * assume it, we verify and fall back through progressively safer forms (summarized → structural →
+ * detailed). This means the cache can never end up serving a `compressed` that is larger than
+ * `detailed`, or one that is empty while `detailed` has content — if the auto-compaction can't be
+ * trusted, the caller transparently gets the (verified) structural form or the detailed text itself.
+ */
+export function buildCompressed(detailed, level) {
+    const structural = compressMarkdown(detailed);
+    const summarized = summarizeMarkdown(structural, { level, minTokens: SUMMARY_FLOOR_TOKENS });
+    // Trustworthy = not larger than detailed, and not empty unless detailed is itself empty.
+    const trustworthy = (candidate) => candidate.length <= detailed.length && (candidate.trim() !== '' || detailed.trim() === '');
+    if (trustworthy(summarized))
+        return summarized;
+    if (trustworthy(structural))
+        return structural;
+    return detailed;
+}

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

@@ -15,7 +15,7 @@ export interface SourceHint {
     path?: string;
     evidence: Evidence;
 }
-export type SearchProvider = 'algolia-docsearch' | 'vitepress-local' | 'pagefind' | 'docusaurus-local' | 'mkdocs-local' | 'sphinx-searchindex' | 'jekyll-json' | 'readme-algolia' | 'custom';
+export type SearchProvider = 'algolia-docsearch' | 'vitepress-local' | 'pagefind' | 'docusaurus-local' | 'mkdocs-local' | 'sphinx-searchindex' | 'jekyll-json' | 'sitemap' | 'llms.txt' | 'readme-algolia' | 'custom';
 export interface SearchCapability {
     provider: SearchProvider;
     evidence: Evidence;

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

@@ -42,6 +42,12 @@ function reconstructLines(code) {
 function removeCopyButtons(document) {
     const candidates = document.querySelectorAll('button, [class*="copy" i], [class*="Copy"], [aria-label*="copy" i]');
     for (const el of candidates) {
+        // Never remove a container that wraps a code block. Some highlighters put a copy-related class
+        // on the <pre>'s wrapper (e.g. Elementor's `<div class="copy-to-clipboard"><pre>…`); removing
+        // it would delete the entire code example, not just the button. Guard on <pre> specifically: a
+        // real copy button never contains a <pre>, but may contain a decorative <code> icon.
+        if (el.querySelector?.('pre'))
+            continue;
         const cls = (el.getAttribute('class') || '').toString();
         const aria = el.getAttribute('aria-label') || '';
         const text = (el.textContent || '').trim();
@@ -50,6 +56,23 @@ function removeCopyButtons(document) {
         }
     }
 }
+// Some highlighters (e.g. Elementor's code-highlight widget) wrap the authored source in a
+// deprecated <xmp>/<plaintext> element and pretty-print the markup, so <code> is not <pre>'s first
+// child. Turndown's fenced-code rule requires <code> as the first child; without this the block
+// collapses onto a single inline span. Flatten to a clean <pre><code>…</code></pre>.
+function flattenCodeStructure(pre, code) {
+    if (code === pre)
+        return;
+    const rawHolder = code.querySelector?.('xmp, plaintext');
+    const raw = rawHolder?.textContent ?? '';
+    if (raw)
+        code.textContent = raw;
+    if (pre.firstChild !== code || pre.childNodes.length > 1) {
+        while (pre.firstChild)
+            pre.removeChild(pre.firstChild);
+        pre.appendChild(code);
+    }
+}
 /**
  * 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.
@@ -65,5 +88,6 @@ export function normalizeCodeBlocks(document) {
             const existing = (code.getAttribute('class') || '').replace(/language-[\w-]+/gi, '').trim();
             code.setAttribute('class', `${existing} language-${language}`.trim());
         }
+        flattenCodeStructure(pre, code);
     }
 }

package/dist/lib/research/docs/discovery-index.d.ts

@@ -0,0 +1,14 @@
+import type { DocsSearchResult } from './search-index.js';
+interface DiscoveryEntry {
+    title: string;
+    url: string;
+    body?: string;
+}
+export interface SitemapParseResult {
+    entries: DiscoveryEntry[];
+    sitemapUrls: string[];
+}
+export declare function parseSitemap(body: string): SitemapParseResult;
+export declare function searchSitemap(body: string, indexUrl: string, query: string): DocsSearchResult[];
+export declare function searchLlmsTxt(body: string, indexUrl: string, query: string): DocsSearchResult[];
+export {};

package/dist/lib/research/docs/discovery-index.js

@@ -0,0 +1,112 @@
+import { DOMParser } from 'linkedom';
+function queryTerms(query) {
+    return query.toLowerCase().split(/\s+/).filter(Boolean);
+}
+function scoreEntry(entry, terms) {
+    const haystack = `${entry.title} ${entry.url} ${entry.body ?? ''}`.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+        if (entry.title.toLowerCase().includes(term))
+            score += 10;
+        if (entry.url.toLowerCase().includes(term))
+            score += 5;
+        score += Math.min(haystack.split(term).length - 1, 5);
+    }
+    return score;
+}
+function snippetFrom(entry) {
+    return (entry.body || entry.url).replace(/\s+/g, ' ').trim().slice(0, 150);
+}
+function titleFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const last = parsed.pathname.split('/').filter(Boolean).pop();
+        return last ? last.replace(/\.[a-z0-9]+$/i, '').replace(/[-_]+/g, ' ') : parsed.hostname;
+    }
+    catch {
+        return url;
+    }
+}
+function toResults(entries, indexUrl, provider, query) {
+    const terms = queryTerms(query);
+    return entries
+        .map((entry) => ({ entry, score: scoreEntry(entry, terms) }))
+        .filter(({ score }) => score > 0)
+        .map(({ entry, score }) => ({
+        title: entry.title,
+        url: entry.url,
+        snippet: snippetFrom(entry),
+        provider,
+        score,
+        indexUrl,
+    }))
+        .sort((a, b) => b.score - a.score);
+}
+function textContent(element) {
+    const text = element?.textContent?.trim();
+    return text || undefined;
+}
+export function parseSitemap(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return { entries: [], sitemapUrls: [] };
+    if (!trimmed.startsWith('<')) {
+        const entries = trimmed
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => /^https?:\/\//i.test(line))
+            .map((url) => ({ title: titleFromUrl(url), url }));
+        return { entries, sitemapUrls: [] };
+    }
+    const doc = new DOMParser().parseFromString(trimmed, 'text/xml');
+    const sitemapUrls = Array.from(doc.querySelectorAll('sitemap > loc'))
+        .map((loc) => textContent(loc))
+        .filter((url) => !!url);
+    const entries = Array.from(doc.querySelectorAll('url'))
+        .map((urlElement) => {
+        const url = textContent(urlElement.querySelector('loc'));
+        if (!url)
+            return null;
+        const lastmod = textContent(urlElement.querySelector('lastmod'));
+        return { title: titleFromUrl(url), url, body: lastmod ? `Last modified ${lastmod}` : '' };
+    })
+        .filter((entry) => !!entry);
+    return { entries, sitemapUrls };
+}
+export function searchSitemap(body, indexUrl, query) {
+    return toResults(parseSitemap(body).entries, indexUrl, 'sitemap', query);
+}
+function referenceDefinitions(body) {
+    const refs = new Map();
+    for (const match of body.matchAll(/^\s*\[([^\]]+)\]:\s*(\S+)/gm)) {
+        refs.set(match[1].toLowerCase(), match[2]);
+    }
+    return refs;
+}
+export function searchLlmsTxt(body, indexUrl, query) {
+    const refs = referenceDefinitions(body);
+    const entries = [];
+    let section = '';
+    for (const line of body.split(/\r?\n/)) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading)
+            section = heading[1];
+        const inline = line.match(/^\s*[-*]\s+\[([^\]]+)\]\(([^)]+)\)\s*:?\s*(.*)$/);
+        const ref = line.match(/^\s*[-*]\s+\[([^\]]+)\]\s*:?\s*(.*)$/);
+        const title = inline?.[1] ?? ref?.[1];
+        const url = inline?.[2] ?? (title ? refs.get(title.toLowerCase()) : undefined);
+        if (!title || !url)
+            continue;
+        try {
+            entries.push({
+                title,
+                url: new URL(url, indexUrl).toString(),
+                body: [section, inline?.[3] ?? ref?.[2]].filter(Boolean).join(' - '),
+            });
+        }
+        catch {
+            // Ignore malformed links in untrusted machine-readable text.
+        }
+    }
+    return toResults(entries, indexUrl, 'llms.txt', query);
+}

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

@@ -15,7 +15,7 @@ export type TextFetcher = (url: string) => Promise<{
  */
 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.
+ * Probes a page-level `.md` route. The derived route is only a candidate: it must be same-origin,
+ * fetch successfully, and validate as non-HTML/non-error Markdown before being trusted.
  */
 export declare function probeRouteMarkdown(pageUrl: string, caps: SiteCapabilities, fetcher?: TextFetcher): Promise<MachineReadableResult | null>;

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

@@ -2,10 +2,6 @@ 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')
@@ -52,14 +48,14 @@ export async function probeLlmsTxt(pageUrl, caps, fetcher = defaultFetcher) {
     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.
+ * Probes a page-level `.md` route. The derived route is only a candidate: it must be same-origin,
+ * fetch successfully, and validate as non-HTML/non-error Markdown before being trusted.
  */
 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 derived = [vitepressRouteMarkdown(pageUrl)];
     const candidates = [...new Set([...advertised, ...derived].filter((u) => !!u))];
     for (const candidate of candidates) {
         if (!isSameDocsOrigin(candidate, pageUrl))

package/dist/lib/research/docs/remote-search-runner.js

@@ -1,5 +1,7 @@
 import { detectDocsEngine } from './detect.js';
+import { probeLlmsTxt } from './machine-readable.js';
 import { searchMkDocsIndex, searchJekyllIndex, searchSphinxIndex } from './search-index.js';
+import { parseSitemap, searchLlmsTxt, searchSitemap } from './discovery-index.js';
 import { extractAlgoliaConfig, algoliaQueryUrl, parseAlgoliaResponse } from './remote-search.js';
 async function getText(url, deps) {
     const res = await deps.fetchText(url);
@@ -7,6 +9,14 @@ async function getText(url, deps) {
         throw new Error(`empty search index at ${url}`);
     return res.content;
 }
+function sameHost(url, base) {
+    try {
+        return new URL(url).hostname === new URL(base).hostname;
+    }
+    catch {
+        return false;
+    }
+}
 // Conventional static index path + parser per framework (verified by T-25 fixtures).
 async function staticIndexSearch(framework, origin, query, deps) {
     if (framework === 'mkdocs' || framework === 'material-mkdocs') {
@@ -32,6 +42,50 @@ async function staticIndexSearch(framework, origin, query, deps) {
     }
     return null;
 }
+async function llmsTxtSearch(docsUrl, caps, query, deps) {
+    const llms = await probeLlmsTxt(docsUrl, caps, async (url) => {
+        const res = await deps.fetchText(url);
+        return { ...res, finalUrl: url, contentType: 'text/plain' };
+    });
+    if (!llms)
+        return null;
+    return {
+        provider: llms.artifact.type,
+        results: searchLlmsTxt(llms.body, llms.artifact.url, query),
+    };
+}
+async function sitemapSearch(pageUrl, query, deps) {
+    const origin = new URL(pageUrl).origin;
+    const firstSegment = new URL(pageUrl).pathname.split('/').filter(Boolean)[0];
+    const candidates = [
+        `${origin}/sitemap.xml`,
+        `${origin}/sitemap_index.xml`,
+        firstSegment ? `${origin}/${firstSegment}/sitemap.xml` : undefined,
+    ].filter((url) => !!url);
+    for (const sitemapUrl of [...new Set(candidates)]) {
+        try {
+            const body = await getText(sitemapUrl, deps);
+            const results = searchSitemap(body, sitemapUrl, query);
+            if (results.length > 0)
+                return { provider: 'sitemap', results };
+            const index = parseSitemap(body);
+            const childResults = [];
+            for (const childUrl of index.sitemapUrls.slice(0, 10)) {
+                if (!sameHost(childUrl, pageUrl))
+                    continue;
+                const childBody = await getText(childUrl, deps);
+                childResults.push(...searchSitemap(childBody, childUrl, query));
+            }
+            if (childResults.length > 0) {
+                return { provider: 'sitemap', results: childResults.sort((a, b) => b.score - a.score) };
+            }
+        }
+        catch {
+            // Try the next conventional sitemap location.
+        }
+    }
+    return null;
+}
 /**
  * Runs remote docs search for a documentation site. Detects the provider from the page, queries the
  * matching connector, and returns normalized results. Throws when no verified connector applies.
@@ -49,6 +103,12 @@ export async function runRemoteDocsSearch(docsUrl, query, deps) {
     const staticResult = await staticIndexSearch(caps.framework, origin, query, deps);
     if (staticResult)
         return staticResult;
+    const llmsResult = await llmsTxtSearch(page.finalUrl, caps, query, deps);
+    if (llmsResult)
+        return llmsResult;
+    const sitemapResult = await sitemapSearch(page.finalUrl, query, deps);
+    if (sitemapResult)
+        return sitemapResult;
     throw new Error(`No verified remote search connector for this site (detected: ${caps.framework ?? caps.docsEngine ?? 'unknown'}). ` +
-        'Supported: Algolia DocSearch, MkDocs/Material, Sphinx, Just the Docs.');
+        'Supported: Algolia DocSearch, MkDocs/Material, Sphinx, Just the Docs, llms.txt, sitemap.xml.');
 }

package/dist/lib/research/docs/section-artifacts.d.ts

@@ -1,12 +1,13 @@
 import type { ResearchArtifact } from '../schema.js';
+import type { SummaryLevel } from '../../config/schema.js';
 /**
  * Derives section child artifacts from a parent page artifact. Returns [] when the page is short
  * or has too few headings to chunk.
  */
-export declare function buildSectionArtifacts(parent: ResearchArtifact, currentTime: Date): ResearchArtifact[];
+export declare function buildSectionArtifacts(parent: ResearchArtifact, currentTime: Date, summaryLevel: SummaryLevel): ResearchArtifact[];
 /**
  * Regenerates a page's section artifacts: writes fresh children and archives any prior child whose
  * heading no longer exists, so a revalidated parent never leaves orphaned sections active. Returns
  * the number of active section children written.
  */
-export declare function persistSectionArtifacts(dataDir: string, parent: ResearchArtifact, currentTime: Date): number;
+export declare function persistSectionArtifacts(dataDir: string, parent: ResearchArtifact, currentTime: Date, summaryLevel: SummaryLevel): number;

package/dist/lib/research/docs/section-artifacts.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { compressMarkdown } from '../compress.js';
+import { buildCompressed } from '../compress.js';
 import { estimateTokens } from '../token-estimate.js';
 import { scanCacheDir, writeArtifact } from '../storage.js';
 import { splitMarkdownSections } from './sections.js';
@@ -17,7 +17,7 @@ function childKey(parentKey, anchor) {
  * Derives section child artifacts from a parent page artifact. Returns [] when the page is short
  * or has too few headings to chunk.
  */
-export function buildSectionArtifacts(parent, currentTime) {
+export function buildSectionArtifacts(parent, currentTime, summaryLevel) {
     if (estimateTokens(parent.detailed) <= SECTION_TOKEN_THRESHOLD)
         return [];
     const sections = splitMarkdownSections(parent.detailed);
@@ -25,7 +25,7 @@ export function buildSectionArtifacts(parent, currentTime) {
     return sections.map((section) => {
         const key = childKey(pm.cache_key, section.anchor);
         const detailed = section.content;
-        const compressed = compressMarkdown(detailed);
+        const compressed = buildCompressed(detailed, summaryLevel);
         return {
             metadata: {
                 ...pm,
@@ -59,8 +59,8 @@ function activeChildrenOf(dataDir, parentKey) {
  * heading no longer exists, so a revalidated parent never leaves orphaned sections active. Returns
  * the number of active section children written.
  */
-export function persistSectionArtifacts(dataDir, parent, currentTime) {
-    const children = buildSectionArtifacts(parent, currentTime);
+export function persistSectionArtifacts(dataDir, parent, currentTime, summaryLevel) {
+    const children = buildSectionArtifacts(parent, currentTime, summaryLevel);
     const freshKeys = new Set(children.map((c) => c.metadata.cache_key));
     for (const orphan of activeChildrenOf(dataDir, parent.metadata.cache_key)) {
         if (!freshKeys.has(orphan.metadata.cache_key)) {

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

@@ -4,6 +4,7 @@ export interface SectionChunk {
     level: number;
     content: string;
 }
+export declare function headingPlainText(raw: string): string;
 export declare function slugifyHeading(text: string): string;
 /**
  * Splits Markdown into H2/H3 section chunks. Returns an empty array when the document has fewer

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

@@ -2,6 +2,24 @@
 // big API reference (e.g. Node `url.html`, ~17.5k tokens) becomes addressable section artifacts.
 // Pure string work: no I/O, no artifact construction. H4+ headings stay within their parent chunk.
 const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+// Reduce a heading's inline Markdown to the plain text GitHub anchors and breadcrumbs are built from.
+// GitHub strips formatting (links, emphasis, code) and slugs the *rendered* text, so a heading like
+// `## [API documentation](https://prismjs.com/extending.html#api-documentation)` must collapse to
+// "API documentation" — not the raw link syntax, which otherwise leaks the URL into the anchor and
+// breadcrumb. Confirmed against github-slugger, which documents that it operates on plain heading
+// text rather than parsing Markdown: https://github.com/Flet/github-slugger
+export function headingPlainText(raw) {
+    // The `\(…\)` part tolerates one level of balanced parens so a real-world target like
+    // `URL_(disambiguation)` doesn't leave a dangling ")" in the rendered breadcrumb text.
+    return raw
+        .replace(/!\[([^\]]*)\]\([^()]*(?:\([^()]*\)[^()]*)*\)/g, '$1') // images: ![alt](url) -> alt
+        .replace(/\[([^\]]*)\]\([^()]*(?:\([^()]*\)[^()]*)*\)/g, '$1') // inline links: [text](url) -> text
+        .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1') // reference links: [text][ref] -> text
+        .replace(/`([^`]*)`/g, '$1') // inline code: `code` -> code
+        .replace(/[*_~]/g, '') // emphasis / strikethrough markers
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 // GitHub-style anchor slug: lowercase, drop punctuation, spaces -> hyphens.
 export function slugifyHeading(text) {
     return text
@@ -22,7 +40,7 @@ function findHeadings(lines) {
             continue;
         const match = lines[i].match(HEADING_RE);
         if (match)
-            out.push({ index: i, level: match[1].length, text: match[2].trim() });
+            out.push({ index: i, level: match[1].length, text: headingPlainText(match[2]) });
     }
     return out;
 }

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

@@ -4,9 +4,17 @@ export interface FreshnessPolicy {
     graceWindowMs: number;
 }
 /**
- * Parses simple TTL duration strings (e.g. '24h', '7d', '30d') to milliseconds.
+ * Parses simple TTL duration strings to milliseconds. The unit `m` is months (not minutes); the
+ * smallest unit is hours, since sub-hour cache lifespans are not meaningful for research artifacts.
  */
 export declare function parseTtlToMs(ttl: string): number;
+/**
+ * Validate a duration-valued flag. Returns an actionable error message that names the
+ * offending flag when the value is malformed, or null when the flag is absent or valid.
+ * Callers map a non-null message onto `this.error(msg, { exit: 2 })`, so every command
+ * reports the same parse failure while naming the exact flag the user passed.
+ */
+export declare function durationFlagError(flag: string, value: string | undefined): string | null;
 /**
  * Derives the active freshness policy based on the tier and optional TTL override.
  */

package/dist/lib/research/freshness.js

@@ -1,12 +1,17 @@
 const HOUR_MS = 3600 * 1000;
 const DAY_MS = 24 * HOUR_MS;
 /**
- * Parses simple TTL duration strings (e.g. '24h', '7d', '30d') to milliseconds.
+ * Parses simple TTL duration strings to milliseconds. The unit `m` is months (not minutes); the
+ * smallest unit is hours, since sub-hour cache lifespans are not meaningful for research artifacts.
  */
 export function parseTtlToMs(ttl) {
     const match = ttl.match(/^(\d+)([hdwmy])$/);
     if (!match) {
-        throw new Error(`Invalid TTL format "${ttl}". Use formats like '24h', '7d', '30d'.`);
+        // Deliberately does not start with "Invalid": durationFlagError wraps this as
+        // "Invalid <flag>: <message>", and a leading "Invalid" here produced a "Invalid --ttl:
+        // Invalid TTL format" stutter.
+        throw new Error(`Duration "${ttl}" is not a valid format. Use a whole number plus a unit: ` +
+            `h (hours), d (days), w (weeks), m (months), or y (years), e.g. '24h', '7d', '6m'.`);
     }
     const val = parseInt(match[1] || '', 10);
     const unit = match[2] || '';
@@ -25,6 +30,23 @@ export function parseTtlToMs(ttl) {
             return 0;
     }
 }
+/**
+ * Validate a duration-valued flag. Returns an actionable error message that names the
+ * offending flag when the value is malformed, or null when the flag is absent or valid.
+ * Callers map a non-null message onto `this.error(msg, { exit: 2 })`, so every command
+ * reports the same parse failure while naming the exact flag the user passed.
+ */
+export function durationFlagError(flag, value) {
+    if (!value)
+        return null;
+    try {
+        parseTtlToMs(value);
+        return null;
+    }
+    catch (err) {
+        return `Invalid ${flag}: ${err.message}`;
+    }
+}
 /**
  * Derives the active freshness policy based on the tier and optional TTL override.
  */

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

@@ -0,0 +1,24 @@
+import type { ResearchArtifact } from './schema.js';
+export declare const STOPWORDS: Set<string>;
+export declare function tokenize(text: string): string[];
+/**
+ * Derives up to `max` keyword tags from free-form Markdown/text by term frequency.
+ * Code blocks, inline code, and URLs are stripped first; stopwords, pure numbers, and very short
+ * tokens are dropped; terms appearing in Markdown headings get a frequency boost. Ranking is
+ * deterministic (frequency desc, then alphabetical) so the same input always yields the same tags.
+ */
+export declare function extractKeywords(text: string, max?: number): string[];
+/**
+ * Removes duplicate and blank tags, comparing case-insensitively (search/list filtering already
+ * matches tags case-insensitively, so "node" and "Node" are the same tag) while preserving
+ * first-seen order and the original casing of the kept tag. Whitespace is trimmed.
+ */
+export declare function dedupeTags(tags: string[]): string[];
+/**
+ * Back-fills keyword tags for an artifact that has none, deriving them from its detailed content and
+ * recording a quality note. When tags are already present they win, but are still deduped/trimmed so
+ * caller-supplied tags do not persist blank or duplicate entries. Mutates and returns the same
+ * artifact. This is the single entry point every ingestion path (import, fetch, revalidation) uses,
+ * so tag hygiene lives in exactly one place.
+ */
+export declare function applyAutoTags(artifact: ResearchArtifact): ResearchArtifact;