@farming-labs/docs 0.1.50 → 0.1.52

package/dist/{agent-CuYI2Nji.mjs → agent-C3rj3o1l.mjs}

@@ -1,10 +1,10 @@
-import "./reading-time-DCZXC6-3.mjs";
-import { C as renderDocsMarkdownDocument, g as findDocsMarkdownPage } from "./agent-CbAtuZAc.mjs";
+import { C as renderDocsMarkdownDocument, g as findDocsMarkdownPage } from "./agent-Xh0UaY5I.mjs";
+import { d as hashGeneratedAgentContent, m as serializeGeneratedAgentDocument, p as parseGeneratedAgentDocument, u as GENERATED_AGENT_PROVENANCE_VERSION } from "./search-Cu_pxL8o.mjs";
 import "./index.mjs";
-import "./api-reference-y7cqtq4w.mjs";
+import "./api-reference-GDAEzQn1.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import "./server.mjs";
-import { a as loadProjectEnv, c as readNavTitle, d as readTopLevelStringProperty, f as resolveDocsConfigPath, i as loadDocsConfigModule, l as readNumberProperty, o as readBooleanProperty, p as resolveDocsContentDir, s as readEnvReferenceProperty, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-C7sUsMkm.mjs";
+import { a as loadProjectEnv, c as readNavTitle, d as readTopLevelStringProperty, f as resolveDocsConfigPath, i as loadDocsConfigModule, l as readNumberProperty, o as readBooleanProperty, p as resolveDocsContentDir, s as readEnvReferenceProperty, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-Si-yUfM_.mjs";
 import matter from "gray-matter";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -50,6 +50,14 @@ function parseAgentCompactArgs(argv) {
 			parsed.dryRun = true;
 			continue;
 		}
+		if (arg === "--stale") {
+			parsed.stale = true;
+			continue;
+		}
+		if (arg === "--include-missing") {
+			parsed.includeMissing = true;
+			continue;
+		}
 		if (arg === "--protect-json") {
 			const nextValue = argv[index + 1];
 			if (nextValue && !nextValue.startsWith("--")) {
@@ -221,6 +229,95 @@ function readPageTokenBudget(pagePath) {
 	const { data } = matter(readFileSync(pagePath, "utf-8"));
 	return normalizeTokenBudget(data.agent?.tokenBudget);
 }
+function buildCompactionSettingsHash(options) {
+	return hashGeneratedAgentContent(JSON.stringify({
+		model: options.model ?? DEFAULT_TTC_MODEL,
+		aggressiveness: options.aggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS,
+		maxOutputTokens: options.maxOutputTokens ?? null,
+		minOutputTokens: options.minOutputTokens ?? null,
+		protectJson: options.protectJson ?? null
+	}));
+}
+function buildPageOptions(defaults, pagePath) {
+	const tokenBudget = readPageTokenBudget(pagePath);
+	const pageOptions = mergeAgentCompactOptions(defaults, { maxOutputTokens: tokenBudget });
+	if (pageOptions.minOutputTokens !== void 0 && pageOptions.maxOutputTokens !== void 0 && pageOptions.minOutputTokens > pageOptions.maxOutputTokens) pageOptions.minOutputTokens = pageOptions.maxOutputTokens;
+	return {
+		pageOptions,
+		tokenBudget
+	};
+}
+function buildResolvedPageSourceDocument(page) {
+	return renderDocsMarkdownDocument({
+		...page,
+		agentRawContent: void 0
+	});
+}
+function buildAgentSourceDocument(page) {
+	if (typeof page.agentRawContent === "string") return page.agentRawContent;
+	return renderDocsMarkdownDocument(page);
+}
+function readCurrentAgentDocument(target) {
+	if (!target.hasAgentFile || !existsSync(target.agentPath)) return void 0;
+	return parseGeneratedAgentDocument(readFileSync(target.agentPath, "utf-8"));
+}
+function resolveSourceKindForCompaction(target, currentDocument) {
+	if (!target.hasAgentFile) return "resolved-page";
+	if (currentDocument?.provenance?.sourceKind === "resolved-page") return "resolved-page";
+	return "agent-md";
+}
+function buildSourceDocumentForCompaction(page, sourceKind) {
+	return sourceKind === "resolved-page" ? buildResolvedPageSourceDocument(page) : buildAgentSourceDocument(page);
+}
+function buildGeneratedAgentProvenance(sourceKind, sourceDocument, output, pageOptions) {
+	return {
+		version: GENERATED_AGENT_PROVENANCE_VERSION,
+		sourceKind,
+		sourceHash: hashGeneratedAgentContent(sourceDocument),
+		settingsHash: buildCompactionSettingsHash(pageOptions),
+		outputHash: hashGeneratedAgentContent(output),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function inspectAgentCompactionState(page, target, defaults) {
+	const { pageOptions, tokenBudget } = buildPageOptions(defaults, target.pagePath);
+	const currentDocument = readCurrentAgentDocument(target);
+	if (!currentDocument) return {
+		status: "missing",
+		sourceKind: "resolved-page",
+		pageOptions,
+		sourceDocument: buildResolvedPageSourceDocument(page),
+		tokenBudget
+	};
+	const sourceKind = resolveSourceKindForCompaction(target, currentDocument);
+	const sourceDocument = buildSourceDocumentForCompaction(page, sourceKind);
+	if (!currentDocument.provenance) return {
+		status: "unknown",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		tokenBudget
+	};
+	const outputModified = hashGeneratedAgentContent(currentDocument.content) !== currentDocument.provenance.outputHash;
+	if (currentDocument.provenance.sourceKind === "agent-md") return {
+		status: outputModified ? "modified" : "unknown",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		provenance: currentDocument.provenance,
+		tokenBudget
+	};
+	const sourceChanged = hashGeneratedAgentContent(sourceDocument) !== currentDocument.provenance.sourceHash;
+	const settingsChanged = buildCompactionSettingsHash(pageOptions) !== currentDocument.provenance.settingsHash;
+	return {
+		status: outputModified && (sourceChanged || settingsChanged) ? "stale-modified" : outputModified ? "modified" : sourceChanged || settingsChanged ? "stale" : "fresh",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		provenance: currentDocument.provenance,
+		tokenBudget
+	};
+}
 function protectForCompression(input) {
 	const segments = [];
 	const stash = (value) => {
@@ -311,8 +408,9 @@ async function compactAgentDocs(options = {}) {
 	const contentDir = typeof loadedConfigModule?.config.contentDir === "string" ? loadedConfigModule.config.contentDir : resolveDocsContentDir(rootDir, configContent, entry);
 	const siteTitle = typeof loadedConfigModule?.config.nav?.title === "string" ? loadedConfigModule.config.nav.title : readNavTitle(configContent) ?? "Documentation";
 	if (resolvedOptions.all && resolvedOptions.pages && resolvedOptions.pages.length > 0) throw new Error("Use either --all or specific page arguments, not both.");
+	if (resolvedOptions.includeMissing && !resolvedOptions.stale) throw new Error("Use --include-missing together with --stale.");
 	const requestedPages = resolvedOptions.pages?.filter((value) => value.trim().length > 0) ?? [];
-	if (!resolvedOptions.all && requestedPages.length === 0) throw new Error("Pass --all or at least one docs page slug/path to compact.");
+	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale) throw new Error("Pass --all, --stale, or at least one docs page slug/path to compact.");
 	const pages = await createFilesystemDocsMcpSource({
 		rootDir,
 		entry,
@@ -320,25 +418,58 @@ async function compactAgentDocs(options = {}) {
 		siteTitle
 	}).getPages();
 	if (pages.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
-	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true);
+	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true || resolvedOptions.stale === true && requestedPages.length === 0);
 	if (selectedPages.length === 0) throw new Error("No compactable docs pages matched the request.");
 	let created = 0;
 	let overwritten = 0;
+	let processed = 0;
+	let skippedFresh = 0;
+	let skippedModified = 0;
+	let skippedUnknown = 0;
+	let skippedMissing = 0;
+	const requestedExplicitPages = requestedPages.length > 0;
 	for (const { page, target } of selectedPages) {
-		const sourceDocument = renderDocsMarkdownDocument(page);
-		const pageOptions = mergeAgentCompactOptions(resolvedOptions, { maxOutputTokens: readPageTokenBudget(target.pagePath) });
-		if (pageOptions.minOutputTokens !== void 0 && pageOptions.maxOutputTokens !== void 0 && pageOptions.minOutputTokens > pageOptions.maxOutputTokens) pageOptions.minOutputTokens = pageOptions.maxOutputTokens;
-		const compressed = await compressDocument(sourceDocument, pageOptions);
+		const state = inspectAgentCompactionState(page, target, resolvedOptions);
+		if (resolvedOptions.stale) {
+			if (state.status === "fresh") {
+				skippedFresh += 1;
+				continue;
+			}
+			if (state.status === "modified" || state.status === "stale-modified") {
+				skippedModified += 1;
+				continue;
+			}
+			if (state.status === "unknown") {
+				skippedUnknown += 1;
+				continue;
+			}
+			if (state.status === "missing") {
+				if (!(resolvedOptions.includeMissing === true && (requestedExplicitPages || state.tokenBudget !== void 0))) {
+					skippedMissing += 1;
+					continue;
+				}
+			}
+		}
+		const compressed = await compressDocument(state.sourceDocument, state.pageOptions);
 		const nextContent = compressed.output.trimEnd();
+		const generatedDocument = serializeGeneratedAgentDocument(nextContent, buildGeneratedAgentProvenance(state.sourceKind, state.sourceDocument, nextContent, state.pageOptions));
 		console.log(pc.dim(`Compacting ${page.url} (${compressed.original_input_tokens ?? "?"} -> ${compressed.output_tokens ?? "?"} tokens)...`));
 		if (resolvedOptions.dryRun) continue;
 		mkdirSync(target.pageDir, { recursive: true });
-		writeFileSync(target.agentPath, `${nextContent}\n`, "utf-8");
+		writeFileSync(target.agentPath, generatedDocument, "utf-8");
 		if (target.hasAgentFile) overwritten += 1;
 		else created += 1;
+		processed += 1;
+	}
+	if (resolvedOptions.dryRun) processed = selectedPages.length - skippedFresh - skippedModified - skippedUnknown - skippedMissing;
+	if (resolvedOptions.stale && processed === 0) {
+		console.log(pc.green("No stale generated agent.md files needed updates."));
+		if (skippedFresh + skippedModified + skippedUnknown + skippedMissing > 0) console.log(pc.dim(`Skipped ${skippedFresh} fresh, ${skippedModified} modified, ${skippedUnknown} unknown, and ${skippedMissing} missing page${skippedFresh + skippedModified + skippedUnknown + skippedMissing === 1 ? "" : "s"}.`));
+		return;
 	}
 	const summaryPrefix = resolvedOptions.dryRun ? "Dry run complete" : "Compaction complete";
-	console.log(pc.green(`${summaryPrefix}: ${selectedPages.length} page${selectedPages.length === 1 ? "" : "s"} processed` + (resolvedOptions.dryRun ? "." : ` (${created} created, ${overwritten} overwritten).`)));
+	console.log(pc.green(`${summaryPrefix}: ${processed} page${processed === 1 ? "" : "s"} processed` + (resolvedOptions.dryRun ? "." : ` (${created} created, ${overwritten} overwritten).`)));
+	if (resolvedOptions.stale) console.log(pc.dim(`Skipped ${skippedFresh} fresh, ${skippedModified} modified, ${skippedUnknown} unknown, and ${skippedMissing} missing page${skippedFresh + skippedModified + skippedUnknown + skippedMissing === 1 ? "" : "s"}.`));
 }
 function printAgentCompactHelp() {
 	console.log(`
@@ -352,6 +483,8 @@ ${pc.dim("Examples:")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact /docs/installation")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --page installation --page configuration")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --all")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale --include-missing")}
 
 ${pc.dim("Per-page override:")}
   Add ${pc.cyan("agent.tokenBudget")} to a page frontmatter block to override the compact output target for that page.
@@ -359,6 +492,8 @@ ${pc.dim("Per-page override:")}
 ${pc.dim("Options:")}
   ${pc.cyan("--all")}                    Compact every folder-based docs page under the configured contentDir
   ${pc.cyan("--page <slug|path>")}       Add a page explicitly (repeatable); positional page args work too
+  ${pc.cyan("--stale")}                  Re-compact only stale generated agent.md files
+  ${pc.cyan("--include-missing")}        With ${pc.cyan("--stale")}, also create missing agent.md files for explicit pages or pages that define ${pc.cyan("agent.tokenBudget")}
   ${pc.cyan("--config <path>")}          Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
   ${pc.cyan("--api-key <key>")}          Token Company API key (or set ${pc.dim("TOKEN_COMPANY_API_KEY")})
   ${pc.cyan("--api-key-env <name>")}     Custom env var name for the Token Company API key
@@ -373,4 +508,4 @@ ${pc.dim("Options:")}
 }
 
 //#endregion
-export { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp };
+export { compactAgentDocs, inspectAgentCompactionState, parseAgentCompactArgs, printAgentCompactHelp, scanDocsPageTargets };

package/dist/{agent-CbAtuZAc.mjs → agent-Xh0UaY5I.mjs}

@@ -1,5 +1,314 @@
-import { u as renderDocsRelatedMarkdownLines } from "./search-8oEskRtz.mjs";
+import { _ as renderDocsRelatedMarkdownLines } from "./search-Cu_pxL8o.mjs";
+import matter from "gray-matter";
 
+//#region src/define-docs.ts
+/**
+* Define docs configuration. Validates and returns the config.
+*/
+function defineDocs(config) {
+	return {
+		entry: config.entry ?? "docs",
+		contentDir: config.contentDir,
+		i18n: config.i18n,
+		theme: config.theme,
+		nav: config.nav,
+		github: config.github,
+		themeToggle: config.themeToggle,
+		breadcrumb: config.breadcrumb,
+		sidebar: config.sidebar,
+		components: config.components,
+		onCopyClick: config.onCopyClick,
+		feedback: config.feedback,
+		search: config.search,
+		mcp: config.mcp,
+		icons: config.icons,
+		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		readingTime: config.readingTime,
+		llmsTxt: config.llmsTxt,
+		ai: config.ai,
+		ordering: config.ordering,
+		metadata: config.metadata,
+		og: config.og,
+		changelog: config.changelog,
+		apiReference: config.apiReference,
+		agent: config.agent
+	};
+}
+
+//#endregion
+//#region src/changelog.ts
+function normalizePathSegment(value, fallback) {
+	return (value ?? fallback).trim().replace(/^\/+|\/+$/g, "") || fallback;
+}
+function normalizeContentDir(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return "changelog";
+	return trimmed.replace(/\/+$/, "") || "changelog";
+}
+function resolveChangelogConfig(value) {
+	if (value === false || value === void 0) return {
+		enabled: false,
+		path: "changelog",
+		contentDir: "changelog",
+		title: "Changelog",
+		description: void 0,
+		search: true
+	};
+	if (value === true) return {
+		enabled: true,
+		path: "changelog",
+		contentDir: "changelog",
+		title: "Changelog",
+		description: void 0,
+		search: true
+	};
+	return {
+		enabled: value.enabled !== false,
+		path: normalizePathSegment(value.path, "changelog"),
+		contentDir: normalizeContentDir(value.contentDir),
+		title: value.title?.trim() || "Changelog",
+		description: value.description?.trim() || void 0,
+		search: value.search !== false,
+		actionsComponent: value.actionsComponent
+	};
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Deep merge utility for theme overrides.
+* Merges objects recursively; later values override earlier ones.
+*/
+function deepMerge(target, ...sources) {
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return target;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sourceVal = source[key];
+		const targetVal = result[key];
+		if (sourceVal && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal && typeof targetVal === "object" && !Array.isArray(targetVal)) result[key] = deepMerge(targetVal, sourceVal);
+		else if (sourceVal !== void 0) result[key] = sourceVal;
+	}
+	if (sources.length) return deepMerge(result, ...sources);
+	return result;
+}
+
+//#endregion
+//#region src/create-theme.ts
+/**
+* Create a theme preset factory.
+*
+* Returns a function that accepts optional overrides and deep-merges them
+* with the base theme defaults. This is the same pattern used by the
+* built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+*
+* @param baseTheme - The default theme configuration
+* @returns A factory function `(overrides?) => DocsTheme`
+*
+* @example
+* ```ts
+* import { createTheme } from "@farming-labs/docs";
+*
+* export const myTheme = createTheme({
+*   name: "my-theme",
+*   ui: {
+*     colors: { primary: "#6366f1" },
+*     layout: { contentWidth: 800 },
+*   },
+* });
+* ```
+*/
+function createTheme(baseTheme) {
+	return function themeFactory(overrides = {}) {
+		const merged = deepMerge(baseTheme, overrides);
+		if (overrides.ui?.colors) merged._userColorOverrides = { ...overrides.ui.colors };
+		return merged;
+	};
+}
+/**
+* Extend an existing theme preset with additional defaults.
+*
+* Useful when you want to build on top of an existing theme (e.g. fumadocs)
+* rather than starting from scratch.
+*
+* @example
+* ```ts
+* import { extendTheme } from "@farming-labs/docs";
+* import { fumadocs } from "@farming-labs/theme/default";
+*
+* // Start with fumadocs defaults, override some values
+* export const myTheme = extendTheme(fumadocs(), {
+*   name: "my-custom-fumadocs",
+*   ui: { colors: { primary: "#22c55e" } },
+* });
+* ```
+*/
+function extendTheme(baseTheme, extensions) {
+	return deepMerge(baseTheme, extensions);
+}
+
+//#endregion
+//#region src/i18n.ts
+function normalizeSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function splitSegments(value) {
+	const cleaned = normalizeSegment(value);
+	return cleaned ? cleaned.split("/").filter(Boolean) : [];
+}
+function resolveDocsI18n(config) {
+	if (!config || !Array.isArray(config.locales)) return null;
+	const locales = Array.from(new Set(config.locales.map((l) => l.trim()).filter(Boolean)));
+	if (locales.length === 0) return null;
+	return {
+		locales,
+		defaultLocale: config.defaultLocale && locales.includes(config.defaultLocale) ? config.defaultLocale : locales[0]
+	};
+}
+function resolveDocsLocale(searchParams, i18n) {
+	if (!i18n) return void 0;
+	const raw = searchParams.get("lang") ?? searchParams.get("locale");
+	if (!raw) return void 0;
+	if (i18n.locales.includes(raw)) return raw;
+	return i18n.defaultLocale;
+}
+function resolveDocsPath(pathname, entry) {
+	const entryBase = normalizeSegment(entry || "docs") || "docs";
+	const entryParts = splitSegments(entryBase);
+	const pathParts = splitSegments(pathname);
+	let rest = pathParts;
+	if (entryParts.length > 0) {
+		if (pathParts.slice(0, entryParts.length).join("/") === entryParts.join("/")) rest = pathParts.slice(entryParts.length);
+	}
+	return {
+		slug: rest.join("/"),
+		entryPath: entryBase
+	};
+}
+
+//#endregion
+//#region src/metadata.ts
+/**
+* Resolve page title using metadata titleTemplate.
+* %s is replaced with page title.
+*/
+function resolveTitle(pageTitle, metadata) {
+	return (metadata?.titleTemplate ?? "%s").replace("%s", pageTitle);
+}
+/**
+* Resolve OG image URL for a page.
+* Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
+*/
+function resolveOGImage(page, ogConfig, baseUrl) {
+	if (page.openGraph?.images?.length) return resolveImageUrl(page.openGraph.images[0].url, baseUrl);
+	if (!ogConfig?.enabled) return void 0;
+	if (page.ogImage) return resolveImageUrl(page.ogImage, baseUrl);
+	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
+	return ogConfig.defaultImage;
+}
+function resolveImageUrl(url, baseUrl) {
+	if (url.startsWith("/") || url.startsWith("http")) return url;
+	const base = baseUrl ?? "";
+	return `${base}${base.length > 0 && !base.endsWith("/") ? "/" : ""}${url}`;
+}
+/**
+* Build the Open Graph metadata object for a page.
+* When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+* Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+*/
+function buildPageOpenGraph(page, ogConfig, baseUrl) {
+	if (page.openGraph) {
+		const images = page.openGraph.images?.length ? page.openGraph.images.map((img) => ({
+			url: resolveImageUrl(img.url, baseUrl),
+			width: img.width ?? 1200,
+			height: img.height ?? 630
+		})) : void 0;
+		return {
+			title: page.openGraph.title ?? page.title,
+			description: page.openGraph.description ?? page.description,
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [{
+			url,
+			width: 1200,
+			height: 630
+		}]
+	};
+}
+/**
+* Build the Twitter card metadata object for a page.
+* When the page has twitter in frontmatter, uses it.
+* Otherwise builds from ogImage or config (dynamic endpoint).
+*/
+function buildPageTwitter(page, ogConfig, baseUrl) {
+	if (page.twitter) {
+		const images = page.twitter.images?.length ? page.twitter.images.map((url) => resolveImageUrl(url, baseUrl)) : void 0;
+		return {
+			...page.twitter.card && { card: page.twitter.card },
+			...page.twitter.title !== void 0 && { title: page.twitter.title },
+			...page.twitter.description !== void 0 && { description: page.twitter.description },
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		card: "summary_large_image",
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [url]
+	};
+}
+
+//#endregion
+//#region src/reading-time.ts
+function hasExplicitReadingTime(frontmatter) {
+	return Object.prototype.hasOwnProperty.call(frontmatter ?? {}, "readingTime");
+}
+function normalizeWordsPerMinute(wordsPerMinute) {
+	if (typeof wordsPerMinute !== "number" || !Number.isFinite(wordsPerMinute)) return 220;
+	return Math.max(1, Math.floor(wordsPerMinute));
+}
+function stripNonReadingContent(content) {
+	return content.replace(/(`{3,})[^\n]*\n[\s\S]*?\1/g, " ").replace(/(~{3,})[^\n]*\n[\s\S]*?\1/g, " ").replace(/`[^`\n]+`/g, " ").replace(/!\[[^\]]*\]\([^)]+\)/g, " ").replace(/\[([^\]]+)\]\([^)]+\)/g, " $1 ").replace(/<[^>]+>/g, " ").replace(/\{[^{}]*\}/g, " ").replace(/https?:\/\/\S+/g, " ").replace(/[#>*_~|]/g, " ");
+}
+function estimateReadingTimeMinutes(content, wordsPerMinute) {
+	const wordCount = stripNonReadingContent(content).match(/\b[\p{L}\p{N}][\p{L}\p{N}'’-]*\b/gu)?.length ?? 0;
+	return Math.max(1, Math.ceil(wordCount / normalizeWordsPerMinute(wordsPerMinute)));
+}
+function resolveReadingTimeOptions(readingTime) {
+	if (readingTime === true) return { enabled: true };
+	if (readingTime === false || readingTime === void 0 || readingTime === null) return { enabled: false };
+	if (typeof readingTime !== "object") return { enabled: false };
+	return {
+		enabled: readingTime.enabled !== false,
+		wordsPerMinute: typeof readingTime.wordsPerMinute === "number" && Number.isFinite(readingTime.wordsPerMinute) ? readingTime.wordsPerMinute : void 0
+	};
+}
+function resolveReadingTimeFromContent(frontmatter, content, wordsPerMinute) {
+	const pageData = frontmatter ?? {};
+	if (pageData.readingTime === false) return null;
+	if (typeof pageData.readingTime === "number" && Number.isFinite(pageData.readingTime)) return Math.max(1, Math.ceil(pageData.readingTime));
+	return estimateReadingTimeMinutes(content, wordsPerMinute);
+}
+function resolvePageReadingTime(frontmatter, content, options) {
+	if (!(options?.enabledByDefault ?? false) && !hasExplicitReadingTime(frontmatter)) return;
+	return resolveReadingTimeFromContent(frontmatter, content, options?.wordsPerMinute);
+}
+function resolveReadingTimeFromSource(source, wordsPerMinute) {
+	const { data, content } = matter(source);
+	return resolveReadingTimeFromContent(data, content, wordsPerMinute);
+}
+
+//#endregion
 //#region src/agent.ts
 const DEFAULT_DOCS_API_ROUTE = "/api/docs";
 const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
@@ -318,4 +627,4 @@ function toYamlString(value) {
 }
 
 //#endregion
-export { renderDocsMarkdownDocument as C, resolveDocsMarkdownRequest as D, resolveDocsLlmsTxtFormat as E, resolveDocsSkillFormat as O, normalizeDocsUrlPath as S, resolveDocsAgentMdxContent as T, isDocsAgentDiscoveryRequest as _, DEFAULT_DOCS_API_ROUTE as a, isDocsSkillRequest as b, DEFAULT_LLMS_TXT_ROUTE as c, DEFAULT_MCP_ROUTE as d, DEFAULT_MCP_WELL_KNOWN_ROUTE as f, findDocsMarkdownPage as g, buildDocsAgentDiscoverySpec as h, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as i, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as l, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as m, DEFAULT_AGENT_SPEC_ROUTE as n, DEFAULT_LLMS_FULL_TXT_ROUTE as o, DEFAULT_SKILL_MD_ROUTE as p, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as r, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as s, DEFAULT_AGENT_FEEDBACK_ROUTE as t, DEFAULT_MCP_PUBLIC_ROUTE as u, isDocsMcpRequest as v, renderDocsSkillDocument as w, normalizeDocsPathSegment as x, isDocsPublicGetRequest as y };
+export { resolvePageReadingTime as A, resolveDocsPath as B, renderDocsMarkdownDocument as C, resolveDocsMarkdownRequest as D, resolveDocsLlmsTxtFormat as E, buildPageTwitter as F, defineDocs as G, extendTheme as H, resolveOGImage as I, resolveTitle as L, resolveReadingTimeFromSource as M, resolveReadingTimeOptions as N, resolveDocsSkillFormat as O, buildPageOpenGraph as P, resolveDocsI18n as R, normalizeDocsUrlPath as S, resolveDocsAgentMdxContent as T, deepMerge as U, createTheme as V, resolveChangelogConfig as W, isDocsAgentDiscoveryRequest as _, DEFAULT_DOCS_API_ROUTE as a, isDocsSkillRequest as b, DEFAULT_LLMS_TXT_ROUTE as c, DEFAULT_MCP_ROUTE as d, DEFAULT_MCP_WELL_KNOWN_ROUTE as f, findDocsMarkdownPage as g, buildDocsAgentDiscoverySpec as h, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as i, resolveReadingTimeFromContent as j, estimateReadingTimeMinutes as k, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as l, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as m, DEFAULT_AGENT_SPEC_ROUTE as n, DEFAULT_LLMS_FULL_TXT_ROUTE as o, DEFAULT_SKILL_MD_ROUTE as p, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as r, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as s, DEFAULT_AGENT_FEEDBACK_ROUTE as t, DEFAULT_MCP_PUBLIC_ROUTE as u, isDocsMcpRequest as v, renderDocsSkillDocument as w, normalizeDocsPathSegment as x, isDocsPublicGetRequest as y, resolveDocsLocale as z };

package/dist/cli/index.mjs

@@ -69,13 +69,13 @@ async function main() {
 		searchApiKey: typeof flags["search-api-key"] === "string" ? flags["search-api-key"] : void 0
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-CShiL8Ch.mjs");
+		const { init } = await import("../init-C1tsFxXo.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "mcp") {
-		const { runMcp } = await import("../mcp-CYpMeMfi.mjs");
+		const { runMcp } = await import("../mcp-C-TmMrdw.mjs");
 		await runMcp(mcpOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "compact") {
-		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-CuYI2Nji.mjs");
+		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-C3rj3o1l.mjs");
 		const agentCompactOptions = parseAgentCompactArgs(args.slice(2));
 		if (agentCompactOptions.help) {
 			printAgentCompactHelp();
@@ -85,11 +85,11 @@ async function main() {
 	} else if (parsedCommand.command === "agent") {
 		console.error(pc.red(`Unknown agent subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentCompactHelp } = await import("../agent-CuYI2Nji.mjs");
+		const { printAgentCompactHelp } = await import("../agent-C3rj3o1l.mjs");
 		printAgentCompactHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-D0UYKEFN.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-B0xEGzBU.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -97,7 +97,7 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "search" && subcommand === "sync") {
-		const { syncSearch } = await import("../search-D7DS0MLc.mjs");
+		const { syncSearch } = await import("../search-C7mKYgqQ.mjs");
 		await syncSearch(searchSyncOptions);
 	} else if (parsedCommand.command === "search") {
 		console.error(pc.red(`Unknown search subcommand: ${subcommand ?? "(missing)"}`));
@@ -105,7 +105,7 @@ async function main() {
 		printHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "upgrade") {
-		const { upgrade } = await import("../upgrade-2xcgMsj6.mjs");
+		const { upgrade } = await import("../upgrade-a185_G5A.mjs");
 		await upgrade({
 			framework: (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0),
 			tag: args.includes("--beta") ? "beta" : args.includes("--latest") ? "latest" : parsedCommand.tag ?? "latest"
@@ -152,7 +152,9 @@ ${pc.dim("Options for mcp:")}
 ${pc.dim("Options for agent compact:")}
   ${pc.cyan("agent compact <page...>")}             Compact pages and write sibling ${pc.dim("agent.md")} files
   ${pc.cyan("agent compact --all")}                 Compact every folder-based docs page
+  ${pc.cyan("agent compact --stale")}               Refresh only stale generated ${pc.dim("agent.md")} files
   ${pc.cyan("--page <slug|path>")}                  Repeatable explicit page flag; positional page args work too
+  ${pc.cyan("--include-missing")}                   With ${pc.cyan("--stale")}, also create explicit or token-budget pages missing ${pc.dim("agent.md")}
   ${pc.cyan("--api-key <key>")}                     Token Company API key (or use ${pc.dim("TOKEN_COMPANY_API_KEY")})
   ${pc.cyan("--api-key-env <name>")}                Custom env var name for the Token Company API key
   ${pc.cyan("--base-url <url>")}                    Override the Token Company API base URL
@@ -164,6 +166,7 @@ ${pc.dim("Options for doctor:")}
   ${pc.cyan("doctor --agent")}                      Same as ${pc.cyan("doctor")}; explicit agent scoring mode
   ${pc.cyan("doctor --site")}                       Score the current docs app for reader-facing docs quality
   ${pc.cyan("doctor --human")}                      Alias for ${pc.cyan("doctor --site")}
+  ${pc.cyan("doctor --json")}                       Print the report as JSON for CI, scripts, and automation
   ${pc.cyan("doctor agent")}                        Subcommand alias for agent scoring
   ${pc.cyan("doctor site")}                         Subcommand alias for reader-facing scoring
   ${pc.cyan("doctor human")}                        Legacy alias for reader-facing scoring