@farming-labs/docs 0.2.52 → 0.2.54

package/dist/{package-version-C8PigBZk.mjs → package-version-DRIc08EU.mjs}

@@ -1,4 +1,4 @@
-import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-D-xTRNuh.mjs";
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-DBCCkkJS.mjs";
 import pc from "picocolors";
 import * as p from "@clack/prompts";
 

package/dist/{reading-time-CPAy1SWO.mjs → reading-time-BrTd3DIh.mjs}

@@ -1,3 +1,5 @@
+import { Dt as DEFAULT_SITEMAP_XML_ROUTE, Gt as hasStructuredPageAgentContract, Kt as normalizePageAgentFrontmatter, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, Tt as DEFAULT_SITEMAP_MD_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE } from "./agent-DXkXi-pS.mjs";
+import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-DAptQnkx.mjs";
 import matter from "gray-matter";
 
 //#region src/define-docs.ts
@@ -158,41 +160,236 @@ function extendTheme(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]
-	};
+//#region src/agent-conformance.ts
+const DOCS_AGENT_CONTRACT_VERSION = "1.0";
+function normalizeOrigin(value) {
+	return value.replace(/\/+$/, "");
 }
-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);
+function normalizeEntry(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "docs";
+}
+/**
+* The framework-neutral public surface every first-party adapter must implement.
+* Adapter tests consume this list so new routes and invariants are added once.
+*/
+function createDocsAgentContractCases(options = {}) {
+	const origin = normalizeOrigin(options.origin ?? "http://localhost");
+	const entry = normalizeEntry(options.entry ?? "docs");
+	const locale = options.locale === void 0 ? "fr" : options.locale;
+	const url = (route) => `${origin}${route.startsWith("/") ? route : `/${route}`}`;
+	const markdown = ["text/markdown"];
+	const json = ["application/json"];
+	const cases = [
+		{
+			surface: "discovery",
+			request: { url: url(DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json
+			}
+		},
+		{
+			surface: "config",
+			request: { url: url(DEFAULT_DOCS_CONFIG_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-config-map.v1"]
+			}
+		},
+		{
+			surface: "diagnostics",
+			request: { url: url(DEFAULT_DOCS_DIAGNOSTICS_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-diagnostics.v1"]
+			}
+		},
+		{
+			surface: "feedback-schema",
+			request: { url: url(`${DEFAULT_AGENT_FEEDBACK_ROUTE}/schema`) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/schema+json"]
+			}
+		},
+		{
+			surface: "markdown",
+			request: { url: url(`/${entry}.md`) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-accept",
+			request: {
+				url: url(`/${entry}`),
+				init: { headers: { Accept: "text/markdown" } }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-missing",
+			request: { url: url(`/${entry}/missing.md`) },
+			expect: {
+				statuses: [200, 404],
+				contentTypes: markdown,
+				bodyIncludes: ["not found"]
+			}
+		},
+		{
+			surface: "llms",
+			request: { url: url(DEFAULT_LLMS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "llms-full",
+			request: { url: url(DEFAULT_LLMS_FULL_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "agents",
+			request: { url: url(DEFAULT_AGENTS_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["AGENTS.md"]
+			}
+		},
+		{
+			surface: "skill",
+			request: { url: url(DEFAULT_SKILL_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["name:"]
+			}
+		},
+		{
+			surface: "sitemap-xml",
+			request: { url: url(DEFAULT_SITEMAP_XML_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/xml", "text/xml"],
+				bodyIncludes: ["<urlset"]
+			}
+		},
+		{
+			surface: "sitemap-markdown",
+			request: { url: url(DEFAULT_SITEMAP_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "robots",
+			request: { url: url(DEFAULT_ROBOTS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["User-agent:"]
+			}
+		},
+		{
+			surface: "mcp",
+			request: {
+				url: url(DEFAULT_MCP_WELL_KNOWN_ROUTE),
+				init: {
+					method: "POST",
+					headers: {
+						Accept: "application/json, text/event-stream",
+						"Content-Type": "application/json",
+						"MCP-Protocol-Version": "2025-11-25"
+					},
+					body: JSON.stringify({
+						jsonrpc: "2.0",
+						id: 1,
+						method: "initialize",
+						params: {
+							protocolVersion: "2025-11-25",
+							capabilities: {},
+							clientInfo: {
+								name: "agent-conformance",
+								version: DOCS_AGENT_CONTRACT_VERSION
+							}
+						}
+					})
+				}
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/json", "text/event-stream"],
+				bodyIncludes: ["serverInfo", "protocolVersion"]
+			}
+		}
+	];
+	if (locale) cases.splice(6, 0, {
+		surface: "markdown-locale",
+		request: { url: url(`/${entry}.md?lang=${encodeURIComponent(locale)}`) },
+		expect: {
+			statuses: [200],
+			contentTypes: markdown,
+			bodyIncludes: ["Bonjour"]
+		}
+	});
+	return cases;
+}
+function matchesContentType(actual, expected) {
+	const [mediaType] = actual.split(";", 1);
+	const normalized = mediaType?.trim().toLowerCase();
+	if (!normalized) return false;
+	return expected.some((value) => normalized === value.trim().toLowerCase());
+}
+async function runDocsAgentConformance(options) {
+	const cases = createDocsAgentContractCases(options);
+	const results = [];
+	for (const contractCase of cases) {
+		const issues = [];
+		try {
+			const response = await options.handle(new Request(contractCase.request.url, contractCase.request.init), contractCase.surface);
+			const contentType = response.headers.get("content-type") ?? "";
+			const body = await response.text();
+			if (!contractCase.expect.statuses.includes(response.status)) issues.push(`expected status ${contractCase.expect.statuses.join(" or ")}, received ${response.status}`);
+			if (!matchesContentType(contentType, contractCase.expect.contentTypes)) issues.push(`expected content-type ${contractCase.expect.contentTypes.join(" or ")}, received ${contentType || "<missing>"}`);
+			for (const requiredText of contractCase.expect.bodyIncludes ?? []) if (!body.toLowerCase().includes(requiredText.toLowerCase())) issues.push(`response body did not include ${JSON.stringify(requiredText)}`);
+			results.push({
+				surface: contractCase.surface,
+				passed: issues.length === 0,
+				status: response.status,
+				contentType,
+				issues
+			});
+		} catch (error) {
+			issues.push(error instanceof Error ? error.message : String(error));
+			results.push({
+				surface: contractCase.surface,
+				passed: false,
+				issues
+			});
+		}
 	}
 	return {
-		slug: rest.join("/"),
-		entryPath: entryBase
+		adapter: options.adapter,
+		contractVersion: DOCS_AGENT_CONTRACT_VERSION,
+		passed: results.every((result) => result.passed),
+		cases: results
 	};
 }
 
@@ -327,6 +524,51 @@ function normalizeDateModified(value) {
 	const date = new Date(value);
 	return Number.isNaN(date.getTime()) ? value : date.toISOString();
 }
+function buildAgentContractHowTo(value, fallback) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent || !hasStructuredPageAgentContract(agent)) return void 0;
+	const steps = [];
+	for (const command of agent.commands ?? []) {
+		const run = typeof command === "string" ? command : command.run;
+		const description = typeof command === "string" ? void 0 : command.description;
+		const cwd = typeof command === "string" ? void 0 : command.cwd;
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description ?? "Run command",
+			text: cwd ? `${run} (from ${cwd})` : run
+		});
+	}
+	for (const verification of agent.verification ?? []) {
+		const description = typeof verification === "string" ? verification : verification.description ?? "Verify the result";
+		const details = typeof verification === "string" ? verification : [verification.run, verification.expect ? `Expected: ${verification.expect}` : void 0].filter(Boolean).join(". ");
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description,
+			text: details || description
+		});
+	}
+	const supplies = [...(agent.prerequisites ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	})), ...(agent.files ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	}))];
+	const about = Object.entries(agent.appliesTo ?? {}).flatMap(([kind, values]) => (typeof values === "string" ? [values] : values ?? []).map((name) => ({
+		"@type": "Thing",
+		name: `${kind}: ${name}`
+	})));
+	return {
+		"@type": "HowTo",
+		name: agent.task ?? fallback.title,
+		...agent.outcome ?? fallback.description ? { description: agent.outcome ?? fallback.description } : {},
+		...about.length > 0 ? { about } : {},
+		...supplies.length > 0 ? { supply: supplies } : {},
+		...steps.length > 0 ? { step: steps } : {}
+	};
+}
 /**
 * Resolve the public docs site URL from existing agent-facing config.
 *
@@ -370,6 +612,8 @@ function buildDocsPageStructuredData(input) {
 		}
 	};
 	if (input.description) result.description = input.description;
+	const agentContract = buildAgentContractHowTo(input.agent, input);
+	if (agentContract) result.mainEntity = agentContract;
 	const dateModified = normalizeDateModified(input.dateModified);
 	if (dateModified) result.dateModified = dateModified;
 	return result;
@@ -437,4 +681,4 @@ function resolveReadingTimeFromSource(source, wordsPerMinute, options) {
 }
 
 //#endregion
-export { extendTheme as _, resolveReadingTimeOptions as a, defineDocs as b, buildPageTwitter as c, resolveOGImage as d, resolveTitle as f, createTheme as g, resolveDocsPath as h, resolveReadingTimeFromSource as i, renderDocsPageStructuredDataJson as l, resolveDocsLocale as m, resolvePageReadingTime as n, buildDocsPageStructuredData as o, resolveDocsI18n as p, resolveReadingTimeFromContent as r, buildPageOpenGraph as s, estimateReadingTimeMinutes as t, resolveDocsMetadataBaseUrl as u, deepMerge as v, resolveChangelogConfig as y };
+export { extendTheme as _, resolveReadingTimeOptions as a, defineDocs as b, buildPageTwitter as c, resolveOGImage as d, resolveTitle as f, createTheme as g, runDocsAgentConformance as h, resolveReadingTimeFromSource as i, renderDocsPageStructuredDataJson as l, createDocsAgentContractCases as m, resolvePageReadingTime as n, buildDocsPageStructuredData as o, DOCS_AGENT_CONTRACT_VERSION as p, resolveReadingTimeFromContent as r, buildPageOpenGraph as s, estimateReadingTimeMinutes as t, resolveDocsMetadataBaseUrl as u, deepMerge as v, resolveChangelogConfig as y };

package/dist/{review-lm3dt7yy.mjs → review-B6gyEFkD.mjs}

@@ -1,13 +1,19 @@
-import { a as ensureDocsReviewWorkflow, o as readDocsReviewConfigFromSource, s as resolveDocsReviewConfig } from "./review-B7goPYUb.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, p as resolveDocsConfigPath } from "./config-tiQCZ46q.mjs";
+import { Bt as PAGE_AGENT_CONTRACT_FIELDS, Gt as hasStructuredPageAgentContract, Kt as normalizePageAgentFrontmatter, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, Wt as getPageAgentFrontmatterIssues, f as DEFAULT_DOCS_CONFIG_ROUTE, u as DEFAULT_DOCS_API_ROUTE } from "./agent-DXkXi-pS.mjs";
+import "./search-CJIC1Cqo.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-BD17jOqL.mjs";
+import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-C9awWzEQ.mjs";
+import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, m as resolveDocsConfigPath, p as readTopLevelStringProperty } from "./config-CydaZ5PB.mjs";
+import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
+import { n as analyzeAgentUsefulness, r as createAgentUsefulnessPagesFromMcp, t as analyzeAgentSurfaceDrift } from "./agent-surface-drift-LS8zQgbq.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
-import pc from "picocolors";
 import { execFileSync } from "node:child_process";
+import pc from "picocolors";
 
 //#region src/cli/review.ts
-const DOCS_FILE_PATTERN = /\.(?:md|mdx)$/;
+const DOCS_FILE_PATTERN = /\.(?:md|mdx|svx)$/;
 const IGNORED_DIRS = new Set([
 	".git",
 	".next",
@@ -19,6 +25,26 @@ const IGNORED_DIRS = new Set([
 	"node_modules",
 	"out"
 ]);
+function isPlainRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveGoldenEvaluationTasks(evaluationInput) {
+	if (evaluationInput === void 0 || typeof evaluationInput === "boolean") return void 0;
+	if (!isPlainRecord(evaluationInput)) return { evaluationConfig: evaluationInput };
+	if (evaluationInput.enabled === false) return void 0;
+	if ("enabled" in evaluationInput && typeof evaluationInput.enabled !== "boolean") return evaluationInput;
+	if (!("tasks" in evaluationInput)) return void 0;
+	const runtimeTasks = evaluationInput.tasks;
+	if (!Array.isArray(runtimeTasks)) return runtimeTasks;
+	return runtimeTasks.map((task) => {
+		if (!isPlainRecord(task)) return task;
+		return {
+			...task,
+			tokenBudget: task.tokenBudget ?? evaluationInput.tokenBudget,
+			topK: task.topK ?? evaluationInput.topK
+		};
+	});
+}
 function parseReviewArgs(argv) {
 	const parsed = {};
 	for (let index = 0; index < argv.length; index += 1) {
@@ -84,7 +110,8 @@ async function runReview(options = {}) {
 	const rootDir = process.cwd();
 	const configPath = resolveDocsConfigPath(rootDir, options.configPath);
 	const configContent = readFileSync(configPath, "utf-8");
-	const config = (await loadDocsConfigModule(rootDir, options.configPath))?.config;
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	const review = withReviewOptionOverrides(resolveDocsReviewConfig(config?.review ?? readDocsReviewConfigFromSource(configContent)), options.mode, options.scoreThreshold);
 	if (options.setup) {
 		const result = ensureDocsReviewWorkflow({
@@ -100,7 +127,8 @@ async function runReview(options = {}) {
 	}
 	if (!review.enabled) {
 		const report = {
-			score: 100,
+			status: "disabled",
+			score: null,
 			threshold: review.score.threshold,
 			mode: options.ci ? review.ci.mode : "local",
 			reviewedFiles: [],
@@ -122,6 +150,18 @@ async function runReview(options = {}) {
 		rootDir,
 		contentDir
 	});
+	const mcpSource = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle: typeof config?.nav?.title === "string" ? config.nav.title : "Documentation"
+	});
+	const corpusPages = await Promise.resolve(mcpSource.getPages());
+	const usefulness = analyzeAgentUsefulness({
+		rootDir,
+		pages: createAgentUsefulnessPagesFromMcp(rootDir, corpusPages),
+		projectFramework: detectFramework(rootDir) ?? void 0
+	});
 	const findings = collectReviewFindings({
 		rootDir,
 		entry,
@@ -129,15 +169,95 @@ async function runReview(options = {}) {
 		files: relevantFiles,
 		review
 	});
+	const relevantSet = new Set(relevantFiles);
+	for (const issue of usefulness.findings) {
+		if (!relevantSet.has(issue.file)) continue;
+		pushFinding(findings, review, {
+			rule: issue.category === "command" ? "commandHealth" : issue.category === "related" ? "relatedCoverage" : "agentContext",
+			code: issue.code,
+			severity: issue.severity === "warning" ? "warn" : issue.severity === "error" ? "error" : "suggestion",
+			file: issue.file,
+			line: issue.line,
+			message: issue.message
+		});
+	}
+	const evaluationInput = config?.agent?.evaluations;
+	const evaluations = await runDocsGoldenTasks(corpusPages, resolveGoldenEvaluationTasks(evaluationInput));
+	if (relevantFiles.length > 0 && evaluations.status === "unmeasured") pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-tasks-unmeasured",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: evaluationInput === false || typeof evaluationInput === "object" && evaluationInput.enabled === false ? "Golden agent tasks are disabled, so retrieval usefulness is unmeasured." : "No golden agent tasks are configured; retrieval, citations, version selection, executable examples, and token usage are unmeasured."
+	});
+	for (const task of evaluations.tasks.filter((task) => !task.passed)) pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-task-failed",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `Golden task ${JSON.stringify(task.id)} scored ${task.score}/100: ${task.issues.join(" ")}`
+	});
+	if (configLoad.status === "static-fallback") pushFinding(findings, review, {
+		rule: "configConfidence",
+		code: "config-static-fallback",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `docs.config could not be evaluated; review used partial static parsing. ${configLoad.error}`
+	});
+	else {
+		const evaluatedConfig = configLoad.config;
+		const searchEnabled = evaluatedConfig.search !== false && !(typeof evaluatedConfig.search === "object" && evaluatedConfig.search?.enabled === false);
+		const mcp = resolveDocsMcpConfig(evaluatedConfig.mcp, { defaultName: typeof evaluatedConfig.nav?.title === "string" ? evaluatedConfig.nav.title : void 0 });
+		const discovery = buildDocsAgentDiscoverySpec({
+			origin: "http://localhost",
+			entry,
+			search: evaluatedConfig.search,
+			mcp
+		});
+		const configuredAgentReviewPaths = Object.values(buildDocsConfigMap(evaluatedConfig).pointers).map((pointer) => pointer.path).filter((optionPath) => optionPath === "agent" || optionPath.startsWith("agent.") || optionPath === "review" || optionPath.startsWith("review."));
+		const drift = analyzeAgentSurfaceDrift({
+			configOptionPaths: [...new Set([...DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, ...configuredAgentReviewPaths])],
+			schemaOptions: getDocsConfigSchema().options,
+			agentContractFields: PAGE_AGENT_CONTRACT_FIELDS,
+			discovery,
+			expected: {
+				entry,
+				search: {
+					enabled: searchEnabled,
+					endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`
+				},
+				mcp: {
+					enabled: mcp.enabled,
+					endpoint: mcp.route,
+					tools: mcp.tools
+				},
+				routes: {
+					"api.docs": DEFAULT_DOCS_API_ROUTE,
+					"api.config": DEFAULT_DOCS_CONFIG_ROUTE,
+					"config.endpoint": DEFAULT_DOCS_CONFIG_ROUTE
+				}
+			}
+		});
+		for (const issue of drift) pushFinding(findings, review, {
+			rule: "agentSurfaceDrift",
+			code: issue.code,
+			severity: "error",
+			file: toPosixPath(path.relative(rootDir, configPath)),
+			message: issue.message
+		});
+	}
 	const score = calculateReviewScore(findings, review);
 	const mode = options.ci ? review.ci.mode : "local";
 	const report = {
+		status: "measured",
 		score,
 		threshold: review.score.threshold,
 		mode,
 		reviewedFiles: relevantFiles,
 		changedFiles,
-		findings
+		findings,
+		usefulness: usefulness.metrics,
+		evaluations
 	};
 	if (options.json) console.log(JSON.stringify(report, null, 2));
 	else printReviewReport(report);
@@ -214,7 +334,8 @@ function collectReviewFindings(options) {
 			checkAgentContext(findings, options.review, {
 				file,
 				source,
-				rootDir: options.rootDir
+				rootDir: options.rootDir,
+				agent: parsed.data.agent
 			});
 		}
 		checkBrokenLinks(findings, options.review, {
@@ -294,6 +415,39 @@ function checkCodeFences(findings, review, options) {
 	}
 }
 function checkAgentContext(findings, review, options) {
+	for (const issue of getPageAgentFrontmatterIssues(options.agent)) pushFinding(findings, review, {
+		rule: "agentContext",
+		severity: "warn",
+		file: options.file,
+		line: 1,
+		message: `Invalid ${issue.path}: ${issue.message}${/[.!?]$/.test(issue.message) ? "" : "."}`
+	});
+	const agent = normalizePageAgentFrontmatter(options.agent);
+	if (hasStructuredPageAgentContract(agent)) {
+		const missing = [!agent?.task ? "task" : void 0, !agent?.outcome ? "outcome" : void 0].filter(Boolean).join(" and ");
+		if (missing) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: `Structured agent contract is missing ${missing}.`
+		});
+		if (agent?.commands?.length && !agent.verification?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines commands without verification steps."
+		});
+		if (agent?.sideEffects?.length && !agent.rollback?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines side effects without rollback guidance."
+		});
+		if (agent?.task && agent.outcome) return;
+	}
 	if (options.source.includes("<Agent>") || options.source.includes("</Agent>")) return;
 	if (existsSync(path.join(path.dirname(path.join(options.rootDir, options.file)), "agent.md"))) return;
 	if (!/\b(install|configure|setup|implement|defineDocs|docs\.config|MCP|agent)\b/i.test(options.source)) return;
@@ -332,11 +486,17 @@ function printReviewReport(report) {
 	console.log(`Changed files: ${report.changedFiles.length}`);
 	console.log(`Reviewed docs files: ${report.reviewedFiles.length}`);
 	console.log(`Findings: ${counts.error} error${counts.error === 1 ? "" : "s"}, ${counts.warn} warning${counts.warn === 1 ? "" : "s"}, ${counts.suggestion} suggestion${counts.suggestion === 1 ? "" : "s"}`);
-	if (report.reviewedFiles.length === 0) {
+	if (report.usefulness) console.log(`Useful Agent blocks: ${report.usefulness.agentBlocks.useful}/${report.usefulness.agentBlocks.total}; task-complete pages: ${report.usefulness.taskCompleteness.completePages}/${report.usefulness.actionablePages}`);
+	if (report.evaluations) console.log(`Golden tasks: ${report.evaluations.status === "unmeasured" ? "unmeasured" : `${report.evaluations.passedTaskCount}/${report.evaluations.taskCount} passed (${report.evaluations.score}/100)`}`);
+	if (report.reviewedFiles.length === 0 && report.findings.length === 0) {
 		console.log("");
 		console.log(pc.green("No docs changes detected. Skipping review."));
 		return;
 	}
+	if (report.reviewedFiles.length === 0) {
+		console.log("");
+		console.log(pc.yellow("No docs files changed; reporting project-wide findings."));
+	}
 	if (report.findings.length === 0) {
 		console.log("");
 		console.log(pc.green("No docs review findings."));
@@ -376,7 +536,17 @@ function selectReviewFiles(options) {
 	const pageFiles = new Set(options.pages.map((page) => page.relativePath));
 	const normalizedConfigPath = toPosixPath(options.configPath);
 	if (options.changedFiles.includes(normalizedConfigPath)) return Array.from(pageFiles).sort();
-	return options.changedFiles.map(toPosixPath).filter((file) => pageFiles.has(file)).sort();
+	const selected = /* @__PURE__ */ new Set();
+	for (const changedFile of options.changedFiles.map(toPosixPath)) {
+		if (pageFiles.has(changedFile)) {
+			selected.add(changedFile);
+			continue;
+		}
+		if (!changedFile.endsWith("/agent.md") && changedFile !== "agent.md") continue;
+		const sibling = options.pages.find((page) => path.posix.dirname(page.relativePath) === path.posix.dirname(changedFile));
+		if (sibling) selected.add(sibling.relativePath);
+	}
+	return Array.from(selected).sort();
 }
 function getChangedFiles(rootDir, options) {
 	const ranges = [
@@ -404,7 +574,7 @@ function getChangedFiles(rootDir, options) {
 function scanDocsPages(rootDir, contentDir, entry) {
 	const contentRoot = path.isAbsolute(contentDir) ? contentDir : path.join(rootDir, contentDir);
 	if (!existsSync(contentRoot)) return [];
-	return listFiles(contentRoot).filter((file) => DOCS_FILE_PATTERN.test(file)).map((absolutePath) => {
+	return listFiles(contentRoot).filter((file) => DOCS_FILE_PATTERN.test(file) && path.basename(file) !== "agent.md").map((absolutePath) => {
 		const relativeToContent = toPosixPath(path.relative(contentRoot, absolutePath));
 		const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
 		const slug = docsSlugFromFile(relativeToContent);
@@ -434,9 +604,9 @@ function listFiles(dir) {
 	return files;
 }
 function docsSlugFromFile(relativePath) {
-	const withoutExt = relativePath.replace(/\.(?:md|mdx)$/, "");
-	if (withoutExt === "page" || withoutExt === "index") return "";
-	if (withoutExt.endsWith("/page") || withoutExt.endsWith("/index")) return withoutExt.replace(/\/(?:page|index)$/, "");
+	const withoutExt = relativePath.replace(/\.(?:md|mdx|svx)$/, "");
+	if (withoutExt === "page" || withoutExt === "+page" || withoutExt === "index") return "";
+	if (withoutExt.endsWith("/page") || withoutExt.endsWith("/+page") || withoutExt.endsWith("/index")) return withoutExt.replace(/\/(?:\+?page|index)$/, "");
 	return withoutExt;
 }
 function normalizeInternalHref(href) {

package/dist/{robots-DV7u4Ire.mjs → robots-4BUJxlvV.mjs}

@@ -1,7 +1,7 @@
-import "./agent-CaOBIVFy.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-XVPs9lVz.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, o as readBooleanProperty, p as resolveDocsConfigPath, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-tiQCZ46q.mjs";
-import { t as detectFramework } from "./utils-D-xTRNuh.mjs";
+import "./agent-DXkXi-pS.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-DAptQnkx.mjs";
+import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-CydaZ5PB.mjs";
+import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{robots-XVPs9lVz.mjs → robots-DAptQnkx.mjs}

@@ -1,4 +1,4 @@
-import { S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, X as normalizeDocsPathSegment, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, kt as resolveDocsSitemapConfig, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-CaOBIVFy.mjs";
+import { $ as normalizeDocsPathSegment, Nt as resolveDocsSitemapConfig, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-DXkXi-pS.mjs";
 
 //#region src/robots.ts
 const DEFAULT_ROBOTS_TXT_ROUTE = "/robots.txt";