@farming-labs/docs 0.2.106 → 0.2.108

package/dist/{agent-CaCWThBY.mjs → agent--fSgaVIK.mjs}

@@ -1,11 +1,11 @@
 import { v as normalizePageAgentFrontmatter, x as stripGeneratedPageAgentContractMarkdown } from "./markdown-sections-BKy4labo.mjs";
-import { V as findDocsMarkdownPage, ot as renderDocsMarkdownDocument } from "./agent-DCTGj6J7.mjs";
-import { d as GENERATED_AGENT_PROVENANCE_VERSION, f as hashGeneratedAgentContent, h as serializeGeneratedAgentDocument, m as parseGeneratedAgentDocument } from "./openapi-mcp-DQ3xptKo.mjs";
+import { V as findDocsMarkdownPage, ot as renderDocsMarkdownDocument } from "./agent-BDrflLmt.mjs";
+import { d as GENERATED_AGENT_PROVENANCE_VERSION, f as hashGeneratedAgentContent, h as serializeGeneratedAgentDocument, m as parseGeneratedAgentDocument } from "./openapi-mcp-CFWUsMUr.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral, u as readEnvReferenceProperty } from "./config-DrZ3fXgf.mjs";
 import { createRequire } from "node:module";
 import matter from "gray-matter";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import pc from "picocolors";
@@ -29,8 +29,11 @@ var __exportAll = (all, no_symbols) => {
 //#endregion
 //#region src/cli/agent.ts
 var agent_exports = /* @__PURE__ */ __exportAll({
+	AGENT_COMPACTION_REVIEW_MANIFEST_VERSION: () => AGENT_COMPACTION_REVIEW_MANIFEST_VERSION,
+	DEFAULT_AGENT_COMPACTION_REVIEW_MANIFEST_PATH: () => DEFAULT_AGENT_COMPACTION_REVIEW_MANIFEST_PATH,
 	compactAgentDocs: () => compactAgentDocs,
 	inspectAgentCompactionState: () => inspectAgentCompactionState,
+	loadAgentCompactionReviews: () => loadAgentCompactionReviews,
 	parseAgentCompactArgs: () => parseAgentCompactArgs,
 	printAgentCompactHelp: () => printAgentCompactHelp,
 	readPageTokenBudget: () => readPageTokenBudget,
@@ -40,11 +43,14 @@ const DEFAULT_COMPRESSION_BASE_URL = "https://api.farming-labs.dev";
 const DEFAULT_COMPRESSION_MODEL = "docs-cloud-compress-v1";
 const DEFAULT_COMPRESSION_AGGRESSIVENESS = .3;
 const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
+const MAX_COMPRESSION_INPUT_CHARACTERS = 2e5;
 const INDEX_PAGE_BASENAMES = new Set([
 	"index",
 	"page",
 	"+page"
 ]);
+const DEFAULT_AGENT_COMPACTION_REVIEW_MANIFEST_PATH = ".farming-labs/agent-compaction-reviews.json";
+const AGENT_COMPACTION_REVIEW_MANIFEST_VERSION = 1;
 function parseBooleanFlag(raw) {
 	if (raw === "true") return true;
 	if (raw === "false") return false;
@@ -76,6 +82,14 @@ function parseAgentCompactArgs(argv) {
 			parsed.dryRun = true;
 			continue;
 		}
+		if (arg === "--check") {
+			parsed.check = true;
+			continue;
+		}
+		if (arg === "--review") {
+			parsed.review = true;
+			continue;
+		}
 		if (arg === "--changed") {
 			parsed.changed = true;
 			continue;
@@ -141,6 +155,15 @@ function parseAgentCompactArgs(argv) {
 			case "protect-json":
 				parsed.protectJson = parseBooleanFlag(value);
 				break;
+			case "reviewed-by":
+				parsed.reviewedBy = value;
+				break;
+			case "reason":
+				parsed.reviewReason = value;
+				break;
+			case "review-manifest":
+				parsed.reviewManifestPath = value;
+				break;
 			default: throw new Error(`Unknown agent compact flag: --${key}.`);
 		}
 	}
@@ -154,6 +177,80 @@ function normalizeUrlPath(value) {
 	if (normalized === "/") return normalized;
 	return normalized.replace(/\/+$/, "");
 }
+function resolveReviewManifestPath(rootDir, configuredPath) {
+	const relativePath = configuredPath?.trim() || DEFAULT_AGENT_COMPACTION_REVIEW_MANIFEST_PATH;
+	if (path.isAbsolute(relativePath)) throw new Error("Agent compaction reviewManifestPath must be project-relative.");
+	const resolved = path.resolve(rootDir, relativePath);
+	const relative = path.relative(rootDir, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Agent compaction reviewManifestPath must stay inside the project root.");
+	return resolved;
+}
+function normalizeReviewRecord(value, index) {
+	const pathLabel = `reviews[${index}]`;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${pathLabel} must be an object.`);
+	const record = value;
+	const readString = (key) => {
+		const field = record[key];
+		if (typeof field !== "string" || !field.trim()) throw new Error(`${pathLabel}.${key} must be a non-empty string.`);
+		return field.trim();
+	};
+	const route = normalizeUrlPath(readString("route"));
+	if (!route.startsWith("/") || route.includes("?") || route.includes("#")) throw new Error(`${pathLabel}.route must be an absolute docs route without query or hash.`);
+	const sourceHash = readString("sourceHash");
+	const settingsHash = readString("settingsHash");
+	const outputHash = readString("outputHash");
+	for (const [key, hash] of Object.entries({
+		sourceHash,
+		settingsHash,
+		outputHash
+	})) if (!/^fnv1a64:[0-9a-f]{16}$/u.test(hash)) throw new Error(`${pathLabel}.${key} must be an fnv1a64 content hash.`);
+	const reviewedAt = readString("reviewedAt");
+	if (!Number.isFinite(Date.parse(reviewedAt))) throw new Error(`${pathLabel}.reviewedAt must be an ISO-compatible timestamp.`);
+	return {
+		route,
+		sourceHash,
+		settingsHash,
+		outputHash,
+		reviewedAt,
+		reviewedBy: readString("reviewedBy"),
+		reason: readString("reason")
+	};
+}
+function loadAgentCompactionReviews(rootDir, configuredPath) {
+	const manifestPath = resolveReviewManifestPath(rootDir, configuredPath);
+	if (!existsSync(manifestPath)) return [];
+	const manifestStat = lstatSync(manifestPath);
+	if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) throw new Error("Agent compaction review manifest must be a regular non-symlink file.");
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+	} catch (error) {
+		throw new Error(`Could not parse agent compaction review manifest ${path.relative(rootDir, manifestPath)}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Agent compaction review manifest must be a JSON object.");
+	const manifest = parsed;
+	if (manifest.version !== AGENT_COMPACTION_REVIEW_MANIFEST_VERSION) throw new Error(`Agent compaction review manifest version must be ${AGENT_COMPACTION_REVIEW_MANIFEST_VERSION}.`);
+	if (!Array.isArray(manifest.reviews)) throw new Error("Agent compaction review manifest reviews must be an array.");
+	const reviews = manifest.reviews.map(normalizeReviewRecord);
+	const routes = /* @__PURE__ */ new Set();
+	for (const review of reviews) {
+		if (routes.has(review.route)) throw new Error(`Agent compaction review route is duplicated: ${review.route}.`);
+		routes.add(review.route);
+	}
+	return reviews;
+}
+function writeAgentCompactionReviews(rootDir, configuredPath, reviews) {
+	const manifestPath = resolveReviewManifestPath(rootDir, configuredPath);
+	const manifest = {
+		version: AGENT_COMPACTION_REVIEW_MANIFEST_VERSION,
+		reviews: [...reviews].sort((left, right) => left.route.localeCompare(right.route))
+	};
+	mkdirSync(path.dirname(manifestPath), { recursive: true });
+	const temporaryPath = `${manifestPath}.tmp-${process.pid}`;
+	writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+	renameSync(temporaryPath, manifestPath);
+	return manifestPath;
+}
 function normalizeRequestedPage(entry, rawValue) {
 	const trimmed = rawValue.trim();
 	if (!trimmed || trimmed === ".") return `/${normalizePathSegment(entry) || "docs"}`;
@@ -286,7 +383,8 @@ function readAgentCompactConfig(content) {
 		aggressiveness: readNumberProperty(compactBlock, "aggressiveness"),
 		maxOutputTokens: readNumberProperty(compactBlock, "maxOutputTokens"),
 		minOutputTokens: readNumberProperty(compactBlock, "minOutputTokens"),
-		protectJson: readBooleanProperty(compactBlock, "protectJson")
+		protectJson: readBooleanProperty(compactBlock, "protectJson"),
+		reviewManifestPath: readStringProperty(compactBlock, "reviewManifestPath")
 	};
 }
 function readCloudApiKeyConfigFromModule(config) {
@@ -304,7 +402,8 @@ function readAgentCompactConfigFromModule(config) {
 		aggressiveness: compact.aggressiveness,
 		maxOutputTokens: compact.maxOutputTokens,
 		minOutputTokens: compact.minOutputTokens,
-		protectJson: compact.protectJson
+		protectJson: compact.protectJson,
+		reviewManifestPath: compact.reviewManifestPath
 	};
 }
 function mergeAgentCompactOptions(defaults, overrides) {
@@ -387,6 +486,23 @@ function inspectAgentCompactionState(page, target, defaults) {
 	};
 	const sourceKind = resolveSourceKindForCompaction(target, currentDocument);
 	const sourceDocument = buildSourceDocumentForCompaction(page, sourceKind);
+	const review = defaults.reviewRecords?.find((candidate) => normalizeUrlPath(candidate.route) === normalizeUrlPath(target.url));
+	if (review) {
+		const reviewMismatches = [];
+		if (hashGeneratedAgentContent(buildResolvedPageSourceDocument(page)) !== review.sourceHash) reviewMismatches.push("source");
+		if (buildCompactionSettingsHash(pageOptions) !== review.settingsHash) reviewMismatches.push("settings");
+		if (hashGeneratedAgentContent(currentDocument.content) !== review.outputHash) reviewMismatches.push("output");
+		return {
+			status: reviewMismatches.length === 0 ? "reviewed" : "review-invalid",
+			sourceKind,
+			pageOptions,
+			sourceDocument,
+			provenance: currentDocument.provenance,
+			review,
+			reviewMismatches,
+			tokenBudget
+		};
+	}
 	if (!currentDocument.provenance) return {
 		status: "unknown",
 		sourceKind,
@@ -414,7 +530,7 @@ function inspectAgentCompactionState(page, target, defaults) {
 		tokenBudget
 	};
 }
-function protectForCompression(input) {
+function protectForCompression(input, protectInlineCode = true) {
 	const segments = [];
 	const stash = (value) => {
 		const token = `__DOCS_SAFE_${segments.length}__`;
@@ -424,14 +540,21 @@ function protectForCompression(input) {
 	let result = input;
 	result = result.replace(/```[\s\S]*?```/g, stash);
 	result = result.replace(/\[[^\]]+\]\([^)]+\)/g, stash);
-	result = result.replace(/`[^`\n]+`/g, stash);
+	if (protectInlineCode) result = result.replace(/`[^`\n]+`/g, stash);
 	result = result.replace(/^(URL|Description|Related):[^\n]*$/gm, stash);
 	result = result.replace(/https?:\/\/[^\s)]+/g, stash);
 	for (let index = 0; index < segments.length; index += 1) result = result.replace(`__DOCS_SAFE_${index}__`, `<docs_safe>${segments[index]}</docs_safe>`);
 	return result;
 }
+function buildCompressionInput(input) {
+	const fullyProtected = protectForCompression(input);
+	if (fullyProtected.length <= MAX_COMPRESSION_INPUT_CHARACTERS) return fullyProtected;
+	const withoutInlineCodeProtection = protectForCompression(input, false);
+	if (withoutInlineCodeProtection.length <= MAX_COMPRESSION_INPUT_CHARACTERS) return withoutInlineCodeProtection;
+	throw new Error(`Docs Cloud compression input is ${withoutInlineCodeProtection.length} characters after adaptive protection; the maximum is ${MAX_COMPRESSION_INPUT_CHARACTERS}. Split or shorten the source page before compacting it.`);
+}
 function sanitizeCompressedOutput(output) {
-	return output.replace(/<\/?docs_safe>/g, "");
+	return output.replace(/<\/?docs_safe>/g, "").replace(/[ \t]+$/gm, "");
 }
 async function compressDocument(input, options) {
 	const apiKey = resolveCompressionApiKey(options.apiKey, options.apiKeyEnv);
@@ -440,7 +563,7 @@ async function compressDocument(input, options) {
 	if (aggressiveness < 0 || aggressiveness > 1) throw new Error("Aggressiveness must be between 0.0 and 1.0.");
 	const payload = {
 		model: options.model ?? DEFAULT_COMPRESSION_MODEL,
-		input: protectForCompression(input),
+		input: buildCompressionInput(input),
 		compression_settings: {
 			aggressiveness,
 			...options.maxOutputTokens !== void 0 ? { max_output_tokens: options.maxOutputTokens } : {},
@@ -509,13 +632,20 @@ async function compactAgentDocs(options = {}) {
 	const loadedConfigModule = await loadDocsConfigModule(rootDir, options.configPath);
 	const configContent = readFileSync(loadedConfigModule?.path ?? resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
 	const resolvedOptions = mergeAgentCompactOptions(mergeAgentCompactOptions(mergeAgentCompactOptions(readCloudApiKeyConfig(configContent), loadedConfigModule?.config ? readCloudApiKeyConfigFromModule(loadedConfigModule.config) : {}), mergeAgentCompactOptions(readAgentCompactConfig(configContent), loadedConfigModule?.config ? readAgentCompactConfigFromModule(loadedConfigModule.config) : {})), options);
+	resolvedOptions.reviewRecords = loadAgentCompactionReviews(rootDir, resolvedOptions.reviewManifestPath);
 	const entry = normalizePathSegment(loadedConfigModule?.config.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs") || "docs";
 	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.");
+	if ((resolvedOptions.reviewedBy || resolvedOptions.reviewReason) && resolvedOptions.review !== true) throw new Error("Use --reviewed-by and --reason together with --review.");
 	const requestedPages = resolvedOptions.pages?.filter((value) => value.trim().length > 0) ?? [];
-	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale && !resolvedOptions.changed) throw new Error("Pass --all, --changed, --stale, or at least one docs page slug/path to compact.");
+	if (resolvedOptions.check && (resolvedOptions.all || resolvedOptions.stale || resolvedOptions.changed || resolvedOptions.includeMissing || resolvedOptions.review || resolvedOptions.dryRun || requestedPages.length > 0)) throw new Error("Use --check by itself; it inspects every compactable docs page without writing.");
+	if (resolvedOptions.review && (resolvedOptions.all || resolvedOptions.stale || resolvedOptions.changed || resolvedOptions.includeMissing || resolvedOptions.check)) throw new Error("Use --review with explicit page arguments, not selection or check flags.");
+	if (resolvedOptions.review && requestedPages.length === 0) throw new Error("Pass at least one explicit docs page with --review.");
+	if (resolvedOptions.review && !resolvedOptions.reviewedBy?.trim()) throw new Error("Pass --reviewed-by <name> with --review.");
+	if (resolvedOptions.review && !resolvedOptions.reviewReason?.trim()) throw new Error("Pass --reason <text> with --review.");
+	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale && !resolvedOptions.changed && !resolvedOptions.check && !resolvedOptions.review) throw new Error("Pass --all, --changed, --stale, or at least one docs page slug/path to compact.");
 	const pages = await createFilesystemDocsMcpSource({
 		rootDir,
 		entry,
@@ -523,7 +653,7 @@ 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 || resolvedOptions.stale === true && requestedPages.length === 0 || resolvedOptions.changed === true && requestedPages.length === 0);
+	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true || resolvedOptions.check === true || resolvedOptions.stale === true && requestedPages.length === 0 || resolvedOptions.changed === true && requestedPages.length === 0);
 	const filteredPages = resolvedOptions.changed ? filterChangedPages(rootDir, contentDir, selectedPages) : selectedPages;
 	if (filteredPages.length === 0) {
 		if (resolvedOptions.changed) {
@@ -532,6 +662,56 @@ async function compactAgentDocs(options = {}) {
 		}
 		throw new Error("No compactable docs pages matched the request.");
 	}
+	if (resolvedOptions.review) {
+		const reviewsByRoute = new Map((resolvedOptions.reviewRecords ?? []).map((review) => [review.route, review]));
+		for (const { page, target } of filteredPages) {
+			const currentDocument = readCurrentAgentDocument(target);
+			if (!currentDocument) throw new Error(`Cannot review ${page.url}: ${target.agentPath} does not exist.`);
+			reviewsByRoute.set(page.url, {
+				route: page.url,
+				sourceHash: hashGeneratedAgentContent(buildResolvedPageSourceDocument(page)),
+				settingsHash: buildCompactionSettingsHash(buildPageOptions(resolvedOptions, target.pagePath).pageOptions),
+				outputHash: hashGeneratedAgentContent(currentDocument.content),
+				reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				reviewedBy: resolvedOptions.reviewedBy.trim(),
+				reason: resolvedOptions.reviewReason.trim()
+			});
+		}
+		if (resolvedOptions.dryRun) {
+			console.log(pc.green(`Dry run: would record ${filteredPages.length} reviewed agent.md page${filteredPages.length === 1 ? "" : "s"}.`));
+			return;
+		}
+		const manifestPath = writeAgentCompactionReviews(rootDir, resolvedOptions.reviewManifestPath, [...reviewsByRoute.values()]);
+		console.log(pc.green(`Recorded ${filteredPages.length} reviewed agent.md page${filteredPages.length === 1 ? "" : "s"} in ${path.relative(rootDir, manifestPath)}.`));
+		return;
+	}
+	if (resolvedOptions.check) {
+		let fresh = 0;
+		let reviewed = 0;
+		let reviewInvalid = 0;
+		let stale = 0;
+		let modified = 0;
+		let unknown = 0;
+		let requiredMissing = 0;
+		let optionalMissing = 0;
+		for (const { page, target } of filteredPages) {
+			const state = inspectAgentCompactionState(page, target, resolvedOptions);
+			if (state.status === "fresh") fresh += 1;
+			else if (state.status === "reviewed") reviewed += 1;
+			else if (state.status === "review-invalid") reviewInvalid += 1;
+			else if (state.status === "stale") stale += 1;
+			else if (state.status === "modified" || state.status === "stale-modified") modified += 1;
+			else if (state.status === "unknown") unknown += 1;
+			else if (state.tokenBudget !== void 0) requiredMissing += 1;
+			else optionalMissing += 1;
+		}
+		const targetRoutes = new Set(filteredPages.map(({ target }) => normalizeUrlPath(target.url)));
+		const orphanedReviews = (resolvedOptions.reviewRecords ?? []).filter((review) => !targetRoutes.has(normalizeUrlPath(review.route))).length;
+		const summary = `${fresh} fresh, ${reviewed} reviewed, ${reviewInvalid} invalid reviews, ${orphanedReviews} orphaned reviews, ${stale} stale, ${modified} modified, ${unknown} unknown, ${requiredMissing} required missing, and ${optionalMissing} optional missing`;
+		if (reviewInvalid > 0 || orphanedReviews > 0 || stale > 0 || requiredMissing > 0) throw new Error(`Agent compaction freshness check failed: ${summary}. Refresh stale output, or re-review intentional agent.md content after inspecting every changed hash.`);
+		console.log(pc.green(`Agent compaction freshness check passed: ${summary}.`));
+		return;
+	}
 	let created = 0;
 	let overwritten = 0;
 	let processed = 0;
@@ -547,6 +727,14 @@ async function compactAgentDocs(options = {}) {
 				skippedFresh += 1;
 				continue;
 			}
+			if (state.status === "reviewed") {
+				skippedFresh += 1;
+				continue;
+			}
+			if (state.status === "review-invalid") {
+				skippedModified += 1;
+				continue;
+			}
 			if (state.status === "modified" || state.status === "stale-modified") {
 				skippedModified += 1;
 				continue;
@@ -598,6 +786,8 @@ ${pc.dim("Examples:")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --changed")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale --include-missing")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --check")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --review --reviewed-by \"docs-team\" --reason \"Preserve operator guidance\" /docs/configuration")}
 
 ${pc.dim("Per-page override:")}
   Add ${pc.cyan("agent.tokenBudget")} to a page frontmatter block to override the compact output target for that page.
@@ -608,6 +798,11 @@ ${pc.dim("Options:")}
   ${pc.cyan("--changed")}                Compact only docs pages changed in the current git working tree
   ${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("--check")}                  Check generated agent.md freshness without an API key, network request, or file write
+  ${pc.cyan("--review")}                 Record hash-bound human review for explicit existing agent.md pages without rewriting them
+  ${pc.cyan("--reviewed-by <name>")}      Reviewer recorded with ${pc.cyan("--review")}
+  ${pc.cyan("--reason <text>")}           Review rationale recorded with ${pc.cyan("--review")}
+  ${pc.cyan("--review-manifest <path>")} Project-relative review manifest path
   ${pc.cyan("--config <path>")}          Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
   ${pc.cyan("--api-key <key>")}          Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
   ${pc.cyan("--api-key-env <name>")}     Env var name for the Docs Cloud API key; prefer ${pc.dim("cloud.apiKey.env")}
@@ -622,4 +817,4 @@ ${pc.dim("Options:")}
 }
 
 //#endregion
-export { scanDocsPageTargets as i, compactAgentDocs as n, inspectAgentCompactionState as r, agent_exports as t };
+export { scanDocsPageTargets as a, loadAgentCompactionReviews as i, compactAgentDocs as n, inspectAgentCompactionState as r, agent_exports as t };

package/dist/{agent-DCTGj6J7.mjs → agent-BDrflLmt.mjs}

@@ -6189,7 +6189,7 @@ function createDocsSitemapResponse({ request, apiRoute, sitemap, entry = "docs",
 	});
 	const headers = new Headers({
 		"Content-Type": format === "xml" ? "application/xml; charset=utf-8" : "text/markdown; charset=utf-8",
-		"Cache-Control": "public, max-age=0, must-revalidate",
+		"Cache-Control": "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400",
 		ETag: hashString(body)
 	});
 	const lastModified = newestLastmod(nextManifest.pages);

package/dist/{agent-evals-D-sPJfXz.mjs → agent-evals-3m5FXStK.mjs}

@@ -1,5 +1,5 @@
 import { S as upsertPageAgentContractMarkdown, l as stripDocsGeneratedAgentContractMarkers, o as findDocsMarkdownSection } from "./markdown-sections-BKy4labo.mjs";
-import { An as normalizeAgentFramework, Dn as agentVersionConstraintGroupsOverlap, Mn as normalizeAgentScopeValues, Nn as normalizeAgentVersion, On as agentVersionConstraintMatches, Qt as buildDocsAskAIContext, dn as normalizeDocsSearchFilters, en as buildDocsRetrievalDigestProjection, fn as performDocsSearch, jn as normalizeAgentLocale, kn as agentVersionConstraintsOverlap, xn as resolveSearchRequestConfig } from "./agent-DCTGj6J7.mjs";
+import { An as normalizeAgentFramework, Dn as agentVersionConstraintGroupsOverlap, Mn as normalizeAgentScopeValues, Nn as normalizeAgentVersion, On as agentVersionConstraintMatches, Qt as buildDocsAskAIContext, dn as normalizeDocsSearchFilters, en as buildDocsRetrievalDigestProjection, fn as performDocsSearch, jn as normalizeAgentLocale, kn as agentVersionConstraintsOverlap, xn as resolveSearchRequestConfig } from "./agent-BDrflLmt.mjs";
 import { n as digestDocsRetrievalContent } from "./retrieval-digest-B-SgtXKK.mjs";
 import { t as getDocsAgentSkillsConfiguredPaths } from "./agent-skills-server-Ddbf15pY.mjs";
 import { buildDocsMcpContext } from "./mcp.mjs";
@@ -841,6 +841,14 @@ function normalizeRuntimeExamples(value, path, issues) {
 		}];
 	});
 }
+function normalizeRuntimeCoverageExpectation(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		issues.push(`${path} must be an object.`);
+		return {};
+	}
+	return { executableExamples: normalizeRuntimeEnum(value.executableExamples, `${path}.executableExamples`, issues, ["applicable", "not-applicable"]) };
+}
 function normalizeGoldenTaskInput(value, index, initialIssues = []) {
 	const issues = [...initialIssues];
 	const path = `tasks[${index}]`;
@@ -882,9 +890,11 @@ function normalizeGoldenTaskInput(value, index, initialIssues = []) {
 		maximum: 1
 	});
 	const examples = normalizeRuntimeExamples(expectation.examples, `${expectPath}.examples`, issues);
+	const coverage = normalizeRuntimeCoverageExpectation(expectation.coverage, `${expectPath}.coverage`, issues);
 	const scope = normalizeRuntimeFilters(expectation.scope, `${expectPath}.scope`, issues);
 	const answer = normalizeRuntimeAnswerExpectation(expectation.answer, `${expectPath}.answer`, issues);
 	const safety = normalizeRuntimeSafetyExpectation(expectation.safety, `${expectPath}.safety`, issues);
+	if (coverage?.executableExamples === "not-applicable" && examples?.some((example) => resolveExampleVerification(example) === "execute")) issues.push(`${expectPath}.coverage.executableExamples cannot be not-applicable when an example uses verification: execute.`);
 	const forbidden = forbiddenSources ?? [];
 	for (const [name, sources] of [
 		["relevantSources", relevantSources],
@@ -911,6 +921,7 @@ function normalizeGoldenTaskInput(value, index, initialIssues = []) {
 				maxFirstRelevantRank,
 				minUsefulByteRatio,
 				examples,
+				coverage,
 				scope,
 				answer,
 				safety
@@ -2523,6 +2534,7 @@ async function evaluateTask(pages, task, configurationIssues = [], runOptions =
 		selection,
 		examples,
 		usage,
+		coverageApplicability: { executableExamples: task.expect.coverage?.executableExamples ?? "applicable" },
 		issues
 	};
 }
@@ -2533,11 +2545,14 @@ async function evaluateTask(pages, task, configurationIssues = [], runOptions =
 */
 function buildGoldenEvaluationCoverage(tasks) {
 	const totalTaskCount = tasks.length;
-	const dimension = (measuredTaskCount) => {
-		const coveragePercent = totalTaskCount === 0 ? 0 : Math.round(measuredTaskCount / totalTaskCount * 100);
+	const dimension = (measuredTaskCount, notApplicableTaskCount = 0) => {
+		const applicableTaskCount = totalTaskCount - notApplicableTaskCount;
+		const coveragePercent = totalTaskCount === 0 ? 0 : applicableTaskCount === 0 ? 100 : Math.round(measuredTaskCount / applicableTaskCount * 100);
 		return {
-			status: measuredTaskCount === 0 ? "unmeasured" : measuredTaskCount === totalTaskCount ? "measured" : "partially-measured",
+			status: totalTaskCount > 0 && applicableTaskCount === 0 ? "not-applicable" : measuredTaskCount === 0 ? "unmeasured" : measuredTaskCount === applicableTaskCount ? "measured" : "partially-measured",
 			measuredTaskCount,
+			applicableTaskCount,
+			notApplicableTaskCount,
 			totalTaskCount,
 			coveragePercent
 		};
@@ -2545,15 +2560,19 @@ function buildGoldenEvaluationCoverage(tasks) {
 	const dimensions = {
 		safety: dimension(tasks.filter((task) => task.safety.cases.length > 0 || task.safety.queryVariants.length > 0).length),
 		answerQuality: dimension(tasks.filter((task) => task.answer.expected).length),
-		executableExamples: dimension(tasks.filter((task) => task.examples.results.some((result) => result.verification === "execute")).length)
+		executableExamples: dimension(tasks.filter((task) => task.examples.results.some((result) => result.verification === "execute")).length, tasks.filter((task) => task.coverageApplicability.executableExamples === "not-applicable").length)
 	};
 	const dimensionValues = Object.values(dimensions);
 	const measuredTaskDimensions = dimensionValues.reduce((total, value) => total + value.measuredTaskCount, 0);
+	const applicableTaskDimensions = dimensionValues.reduce((total, value) => total + value.applicableTaskCount, 0);
+	const notApplicableTaskDimensions = dimensionValues.reduce((total, value) => total + value.notApplicableTaskCount, 0);
 	const totalTaskDimensions = totalTaskCount * dimensionValues.length;
-	const coveragePercent = totalTaskDimensions === 0 ? 0 : Math.round(measuredTaskDimensions / totalTaskDimensions * 100);
+	const coveragePercent = totalTaskDimensions === 0 ? 0 : applicableTaskDimensions === 0 ? 100 : Math.round(measuredTaskDimensions / applicableTaskDimensions * 100);
 	return {
-		status: coveragePercent === 100 ? "measured" : coveragePercent === 0 ? "unmeasured" : "partially-measured",
+		status: totalTaskDimensions > 0 && applicableTaskDimensions === 0 ? "not-applicable" : coveragePercent === 100 ? "measured" : coveragePercent === 0 ? "unmeasured" : "partially-measured",
 		measuredTaskDimensions,
+		applicableTaskDimensions,
+		notApplicableTaskDimensions,
 		totalTaskDimensions,
 		coveragePercent,
 		dimensions

package/dist/{agent-export-GcTZPLfB.mjs → agent-export-CSdby81L.mjs}

@@ -1,14 +1,14 @@
 import { w as isDocsAgentPageAccessible } from "./markdown-sections-BKy4labo.mjs";
-import { A as buildDocsAgentDiscoverySpec, Ft as renderDocsSitemapMarkdown, It as renderDocsSitemapXml, Lt as resolveDocsSitemapConfig, Mt as buildDocsSitemapManifest, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Tt as toDocsMarkdownUrl, a as DEFAULT_AGENT_MD_ROUTE, ar as buildDocsOkfBundle, at as renderDocsLlmsTxt, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, ct as renderDocsSkillDocument, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, it as renderDocsAgentsDocument, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, ot as renderDocsMarkdownDocument, sr as resolveDocsOkfConfig, t as DEFAULT_AGENTS_MD_ROUTE, ut as resolveDocsAgentFeedbackConfig, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-DCTGj6J7.mjs";
+import { A as buildDocsAgentDiscoverySpec, Ft as renderDocsSitemapMarkdown, It as renderDocsSitemapXml, Lt as resolveDocsSitemapConfig, Mt as buildDocsSitemapManifest, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Tt as toDocsMarkdownUrl, a as DEFAULT_AGENT_MD_ROUTE, ar as buildDocsOkfBundle, at as renderDocsLlmsTxt, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, ct as renderDocsSkillDocument, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, it as renderDocsAgentsDocument, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, ot as renderDocsMarkdownDocument, sr as resolveDocsOkfConfig, t as DEFAULT_AGENTS_MD_ROUTE, ut as resolveDocsAgentFeedbackConfig, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-BDrflLmt.mjs";
 import { A as buildDocsLegacySkillsIndex, D as buildDocsA2AAgentCard, L as resolveDocsPublishedAgentSkill, O as buildDocsAgentSkillsIndex, V as formatDocsContentDigest, W as resolveDocsHttpDate, a as DEFAULT_A2A_AGENT_CARD_ROUTE, b as DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, x as DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX } from "./standards-discovery-Bpz90VYq.mjs";
-import "./openapi-mcp-DQ3xptKo.mjs";
+import "./openapi-mcp-CFWUsMUr.mjs";
 import { t as resolveDocsI18n } from "./i18n-B1gJ9EW0.mjs";
-import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-BOjWB1ky.mjs";
-import "./sitemap-server-NeVu8W38.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-dNbBnlVh.mjs";
+import "./sitemap-server-BKNIqgvq.mjs";
 import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-Ddbf15pY.mjs";
-import "./agent-evals-D-sPJfXz.mjs";
+import "./agent-evals-3m5FXStK.mjs";
 import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./authoring-mcp-Be7quE5R.mjs";
+import "./authoring-mcp-Wy-h93DM.mjs";
 import "./code-blocks-D90CCJFs.mjs";
 import "./server.mjs";
 import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, r as extractTopLevelConfigObject, t as extractNestedObjectLiteral } from "./config-DrZ3fXgf.mjs";

package/dist/agent-skills-bundle.d.mts

@@ -1,4 +1,4 @@
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-CjyUCxdy.mjs";
 
 //#region src/agent-skills-bundle.d.ts
 /**

package/dist/{agent-skills-server-D34054x5.d.mts → agent-skills-server-CF6iVTBR.d.mts}

@@ -1,5 +1,5 @@
-import { lt as DocsAgentSkillsInput } from "./types-QhYMnKvb.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
+import { ut as DocsAgentSkillsInput } from "./types-BkAk6B2d.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-CjyUCxdy.mjs";
 
 //#region src/agent-skills-server.d.ts
 interface ResolveConfiguredAgentSkillsOptions {

package/dist/agent-skills-vite.d.mts

@@ -1,6 +1,6 @@
-import { lt as DocsAgentSkillsInput } from "./types-QhYMnKvb.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
-import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-D34054x5.mjs";
+import { ut as DocsAgentSkillsInput } from "./types-BkAk6B2d.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-CjyUCxdy.mjs";
+import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-CF6iVTBR.mjs";
 
 //#region src/agent-skills-vite.d.ts
 declare const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/{agents-e1SYT64z.mjs → agents-DDt41QR8.mjs}

@@ -1,12 +1,12 @@
 import "./markdown-sections-BKy4labo.mjs";
-import { a as DEFAULT_AGENT_MD_ROUTE, it as renderDocsAgentsDocument, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, ut as resolveDocsAgentFeedbackConfig } from "./agent-DCTGj6J7.mjs";
+import { a as DEFAULT_AGENT_MD_ROUTE, it as renderDocsAgentsDocument, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, ut as resolveDocsAgentFeedbackConfig } from "./agent-BDrflLmt.mjs";
 import "./standards-discovery-Bpz90VYq.mjs";
-import "./openapi-mcp-DQ3xptKo.mjs";
-import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-NeVu8W38.mjs";
+import "./openapi-mcp-CFWUsMUr.mjs";
+import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-BKNIqgvq.mjs";
 import "./agent-skills-server-Ddbf15pY.mjs";
-import "./agent-evals-D-sPJfXz.mjs";
+import "./agent-evals-3m5FXStK.mjs";
 import { resolveDocsMcpConfig } from "./mcp.mjs";
-import "./authoring-mcp-Be7quE5R.mjs";
+import "./authoring-mcp-Wy-h93DM.mjs";
 import "./code-blocks-D90CCJFs.mjs";
 import "./server.mjs";
 import { a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-DrZ3fXgf.mjs";

package/dist/{analytics-aeXwEvQX.d.mts → analytics-CwXxM9oL.d.mts}

@@ -1,4 +1,4 @@
-import { dt as DocsAgentTraceEventInput, fn as DocsObservabilityConfig, gt as DocsAnalyticsEventInput, ht as DocsAnalyticsEvent, mn as DocsObservabilityEventInput, mt as DocsAnalyticsConfig, pn as DocsObservabilityEvent } from "./types-QhYMnKvb.mjs";
+import { _t as DocsAnalyticsEventInput, ft as DocsAgentTraceEventInput, gt as DocsAnalyticsEvent, hn as DocsObservabilityEventInput, ht as DocsAnalyticsConfig, mn as DocsObservabilityEvent, pn as DocsObservabilityConfig } from "./types-BkAk6B2d.mjs";
 
 //#region src/analytics.d.ts
 declare const DOCS_AGENT_TRACE_EVENT_TYPES: readonly ["run.start", "run.end", "run.error", "user.input", "prompt.build", "retrieval.query", "retrieval.result", "retrieval.error", "model.call", "model.response", "model.stream", "model.error", "tool.call", "tool.result", "tool.error", "retry", "timeout", "error", "agent.final"];

package/dist/{authoring-Do87QzBd.mjs → authoring-ct8s0Z_X.mjs}

@@ -1,8 +1,8 @@
 import "./markdown-sections-BKy4labo.mjs";
-import "./agent-DCTGj6J7.mjs";
+import "./agent-BDrflLmt.mjs";
 import "./standards-discovery-Bpz90VYq.mjs";
-import "./openapi-mcp-DQ3xptKo.mjs";
-import { r as runDocsAuthoringMcpStdio } from "./authoring-mcp-Be7quE5R.mjs";
+import "./openapi-mcp-CFWUsMUr.mjs";
+import { r as runDocsAuthoringMcpStdio } from "./authoring-mcp-Wy-h93DM.mjs";
 import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, o as loadDocsConfigModuleResult, p as readStringProperty } from "./config-DrZ3fXgf.mjs";
 import { readFileSync } from "node:fs";
 import path from "node:path";

package/dist/{authoring-mcp-Be7quE5R.mjs → authoring-mcp-Wy-h93DM.mjs}

@@ -1,4 +1,4 @@
-import { ot as renderDocsMarkdownDocument } from "./agent-DCTGj6J7.mjs";
+import { ot as renderDocsMarkdownDocument } from "./agent-BDrflLmt.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import { n as analyzeDocsAgentFeedback, r as readDocsAgentFeedbackFile } from "./agent-feedback-loop-vaC-M1sx.mjs";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";

package/dist/browser.d.mts

@@ -1,4 +1,4 @@
-import { c as emitDocsAnalyticsEvent, d as resolveDocsAnalyticsConfig } from "./analytics-aeXwEvQX.mjs";
-import { t as applySidebarFolderIndexBehavior } from "./sidebar-CJze8SBi.mjs";
+import { c as emitDocsAnalyticsEvent, d as resolveDocsAnalyticsConfig } from "./analytics-CwXxM9oL.mjs";
+import { t as applySidebarFolderIndexBehavior } from "./sidebar-Bne72SU-.mjs";
 import { n as resolveDocsAudienceExposure, t as DocsContentAudience } from "./audience-exposure-CkNZNeVX.mjs";
 export { type DocsContentAudience, applySidebarFolderIndexBehavior, emitDocsAnalyticsEvent, resolveDocsAnalyticsConfig, resolveDocsAudienceExposure };

package/dist/cli/index.d.mts

@@ -11,5 +11,6 @@ declare function parseCommandAlias(rawCommand?: string): {
 };
 /** Parse flags like --template next, --name my-docs, --theme concrete, --entry docs, --framework astro (exported for tests). */
 declare function parseFlags(argv: string[]): Record<string, string | boolean | undefined>;
+declare function printAgentHelp(): void;
 //#endregion
-export { formatCliError, parseCommandAlias, parseFlags };
+export { formatCliError, parseCommandAlias, parseFlags, printAgentHelp };