@farming-labs/docs 0.2.52 → 0.2.54

package/dist/{doctor-O9o9kjN8.mjs → doctor-CQpQ2zZm.mjs}

@@ -1,13 +1,16 @@
-import "./reading-time-CPAy1SWO.mjs";
-import { Ct as DEFAULT_SITEMAP_XML_ROUTE, P as buildDocsMcpEndpointCandidates, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, St as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, kt as resolveDocsSitemapConfig, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, xt as DEFAULT_SITEMAP_MD_ROUTE } from "./agent-CaOBIVFy.mjs";
-import "./search-BWuU70B0.mjs";
-import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-XVPs9lVz.mjs";
-import "./sitemap-server-xEHtDUDB.mjs";
-import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-BXvi0uhS.mjs";
+import "./reading-time-BrTd3DIh.mjs";
+import { Bt as PAGE_AGENT_CONTRACT_FIELDS, Dt as DEFAULT_SITEMAP_XML_ROUTE, Et as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, I as buildDocsMcpEndpointCandidates, M as buildDocsAgentDiscoverySpec, Nt as resolveDocsSitemapConfig, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Tt as DEFAULT_SITEMAP_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_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, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, u as DEFAULT_DOCS_API_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE } from "./agent-DXkXi-pS.mjs";
+import "./search-CJIC1Cqo.mjs";
+import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-DAptQnkx.mjs";
+import "./sitemap-server-wsNLyVkb.mjs";
+import { t as runDocsGoldenTasks } from "./agent-evals-BD17jOqL.mjs";
+import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-C9awWzEQ.mjs";
 import "./server.mjs";
-import { a as loadProjectEnv, c as readNavTitle, f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, o as readBooleanProperty, p as resolveDocsConfigPath, r as extractTopLevelConfigObject, t as extractNestedObjectLiteral } from "./config-tiQCZ46q.mjs";
-import { t as detectFramework } from "./utils-D-xTRNuh.mjs";
-import { n as inspectAgentCompactionState, o as scanDocsPageTargets, t as compactAgentDocs } from "./codeblocks-z9iT794h.mjs";
+import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, l as readNavTitle, m as resolveDocsConfigPath, p as readTopLevelStringProperty, r as extractTopLevelConfigObject, s as readBooleanProperty, t as extractNestedObjectLiteral } 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 { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
@@ -583,8 +586,18 @@ function navigationScore(navigationCoverage) {
 		score: 0
 	};
 }
-function gradeForAgentScore(score) {
-	if (score >= 90) return "Agent-optimized";
+const AGENT_OPTIMIZATION_BLOCKING_CHECKS = new Set([
+	"surface-drift",
+	"agent-context-quality",
+	"agent-task-completeness",
+	"agent-applicability",
+	"command-health",
+	"related-coverage",
+	"golden-tasks"
+]);
+function gradeForAgentScore(score, checks = []) {
+	const hasBlockingFailure = checks.some((check) => check.status === "fail" && AGENT_OPTIMIZATION_BLOCKING_CHECKS.has(check.id));
+	if (score >= 90 && !hasBlockingFailure) return "Agent-optimized";
 	if (score >= 75) return "Agent-ready";
 	if (score >= 60) return "Promising";
 	return "Needs work";
@@ -631,6 +644,20 @@ function buildCoverage(pages) {
 		}
 	};
 }
+function scoreUsefulnessCoverage(completed, total, maxScore) {
+	if (total === 0) return {
+		status: "warn",
+		score: 0,
+		coverage: 0
+	};
+	const coverage = Math.round(completed / total * 100);
+	const score = Math.round(coverage / 100 * maxScore);
+	return {
+		status: coverage >= 80 ? "pass" : coverage > 0 ? "warn" : "fail",
+		score,
+		coverage
+	};
+}
 function buildCompactionCoverage(rootDir, contentDir, entry, pages, defaults) {
 	const targets = scanDocsPageTargets(rootDir, contentDir, entry);
 	const targetsBySlug = new Map(targets.map((target) => [target.slug, target]));
@@ -962,7 +989,7 @@ async function postMcpJson(baseUrl, route, body, sessionId) {
 		body: JSON.stringify(body)
 	});
 }
-async function probeMcpRoute(baseUrl, route) {
+async function probeMcpRoute(baseUrl, route, expectedTools) {
 	try {
 		const initializeResponse = await postMcpJson(baseUrl, route, {
 			jsonrpc: "2.0",
@@ -1008,15 +1035,7 @@ async function probeMcpRoute(baseUrl, route) {
 		};
 		const tools = toolsPayload.result?.tools;
 		const toolNames = Array.isArray(tools) ? tools.map((tool) => tool.name).filter((name) => typeof name === "string") : [];
-		const missingTools = [
-			"list_docs",
-			"list_pages",
-			"get_navigation",
-			"search_docs",
-			"read_page",
-			"get_code_examples",
-			"get_config_schema"
-		].filter((tool) => !toolNames.includes(tool));
+		const missingTools = expectedTools.filter((tool) => !toolNames.includes(tool));
 		if (missingTools.length > 0) return {
 			ok: false,
 			detail: `${route} connected but is missing tools: ${missingTools.join(", ")}.`
@@ -1032,10 +1051,10 @@ async function probeMcpRoute(baseUrl, route) {
 		};
 	}
 }
-async function probeMcpRouteCandidates(baseUrl, routes) {
+async function probeMcpRouteCandidates(baseUrl, routes, expectedTools) {
 	const candidates = buildDocsMcpEndpointCandidates(baseUrl, routes);
 	const probes = await Promise.all(candidates.map(async (candidate) => {
-		const probe = await probeMcpRoute(candidate.baseUrl, candidate.route);
+		const probe = await probeMcpRoute(candidate.baseUrl, candidate.route, expectedTools);
 		return {
 			...probe,
 			detail: `${candidate.label}: ${probe.detail}`
@@ -1049,6 +1068,44 @@ async function probeMcpRouteCandidates(baseUrl, routes) {
 function asRecord(value) {
 	return value && typeof value === "object" ? value : void 0;
 }
+function isPlainRecord(value) {
+	return Boolean(asRecord(value)) && !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 isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isBooleanRecord(value) {
+	const record = asRecord(value);
+	return Boolean(record && Object.keys(record).length > 0 && Object.values(record).every((item) => typeof item === "boolean"));
+}
+function isHostedAgentDiscoveryManifest(value) {
+	const root = asRecord(value);
+	const site = asRecord(root?.site);
+	const capabilities = asRecord(root?.capabilities);
+	const api = asRecord(root?.api);
+	const config = asRecord(root?.config);
+	const search = asRecord(root?.search);
+	const mcp = asRecord(root?.mcp);
+	const agentContractFields = asRecord(asRecord(root?.agentContract)?.fields);
+	return Boolean(root && isNonEmptyString(root.version) && isNonEmptyString(root.name) && isNonEmptyString(root.baseUrl) && isNonEmptyString(site?.entry) && typeof capabilities?.search === "boolean" && typeof capabilities?.mcp === "boolean" && isNonEmptyString(api?.docs) && isNonEmptyString(api?.config) && isNonEmptyString(config?.endpoint) && typeof search?.enabled === "boolean" && isNonEmptyString(search?.endpoint) && typeof mcp?.enabled === "boolean" && isNonEmptyString(mcp?.endpoint) && isBooleanRecord(mcp?.tools) && agentContractFields && Object.keys(agentContractFields).length > 0);
+}
 function readDiscoveryRoute(value) {
 	return typeof value === "string" && value.startsWith("/") ? value : void 0;
 }
@@ -1085,6 +1142,22 @@ function hostedMcpRoutes(discoveryBody) {
 	if (declaredRoutes.length > 0) return Array.from(new Set(declaredRoutes));
 	return Array.from(new Set([readDiscoveryRoute(mcp?.publicEndpoint) ?? DEFAULT_MCP_PUBLIC_ROUTE, readDiscoveryRoute(mcp?.wellKnownEndpoint) ?? DEFAULT_MCP_WELL_KNOWN_ROUTE]));
 }
+const MCP_DISCOVERY_TOOL_NAMES = [
+	["listDocs", "list_docs"],
+	["listPages", "list_pages"],
+	["listTasks", "list_tasks"],
+	["readTask", "read_task"],
+	["getNavigation", "get_navigation"],
+	["searchDocs", "search_docs"],
+	["readPage", "read_page"],
+	["getCodeExamples", "get_code_examples"],
+	["getConfigSchema", "get_config_schema"],
+	["getContext", "get_context"]
+];
+function hostedMcpExpectedTools(discoveryBody) {
+	const tools = asRecord(asRecord(asRecord(discoveryBody)?.mcp)?.tools);
+	return MCP_DISCOVERY_TOOL_NAMES.filter(([flag]) => tools?.[flag] !== false).map(([, name]) => name);
+}
 function hostedCapability(discoveryBody, key) {
 	const root = asRecord(discoveryBody);
 	const capability = asRecord(root?.capabilities)?.[key];
@@ -1181,7 +1254,8 @@ async function buildHostedAgentChecks(url, pages) {
 	}
 	const checks = [];
 	const discovery = await probeJsonRoute(baseUrl, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE);
-	checks.push(makeCheck("hosted-agent-discovery", "Hosted agent discovery", discovery.ok ? "pass" : "fail", discovery.ok ? 5 : 0, 5, `${baseUrl}: ${discovery.detail}`, discovery.ok ? void 0 : `Make sure ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} is routed to the shared docs API on the deployed site.`));
+	const discoveryManifestValid = discovery.ok && isHostedAgentDiscoveryManifest(discovery.body);
+	checks.push(makeCheck("hosted-agent-discovery", "Hosted agent discovery", discoveryManifestValid ? "pass" : "fail", discoveryManifestValid ? 5 : 0, 5, `${baseUrl}: ${discovery.ok && !discoveryManifestValid ? `${discovery.detail} The payload is not a complete agent discovery manifest.` : discovery.detail}`, discoveryManifestValid ? void 0 : `Make sure ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} returns the complete agent discovery manifest from the shared docs API.`));
 	const llms = await Promise.all([probeTextRoute(baseUrl, DEFAULT_LLMS_TXT_ROUTE), probeTextRoute(baseUrl, DEFAULT_LLMS_FULL_TXT_ROUTE)]);
 	const llmsPassed = llms.filter((result) => result.ok).length;
 	checks.push(makeCheck("hosted-llms", "Hosted llms.txt", llmsPassed === llms.length ? "pass" : llmsPassed > 0 ? "warn" : "fail", llmsPassed === llms.length ? 5 : llmsPassed > 0 ? 3 : 0, 5, llms.map((result) => result.detail).join(" "), llmsPassed === llms.length ? void 0 : "Verify deployed /llms.txt and /llms-full.txt routes return non-empty text."));
@@ -1226,27 +1300,18 @@ async function buildHostedAgentChecks(url, pages) {
 	const markdownAlternateScore = hostedSurfaceScore(htmlPageProbes, (probe) => probe.hasMarkdownAlternate);
 	const markdownRoutesEnabled = hostedCapability(discovery.body, "markdownRoutes");
 	checks.push(makeCheck("hosted-markdown-alternate", "Hosted markdown alternate links", markdownRoutesEnabled === false ? "warn" : markdownAlternateScore.status, markdownRoutesEnabled === false ? 0 : markdownAlternateScore.score, 5, markdownRoutesEnabled === false ? "The hosted discovery spec reports markdown routes as disabled." : markdownAlternateScore.total > 0 ? `${markdownAlternateScore.passed}/${markdownAlternateScore.total} sampled hosted docs pages include <link rel="alternate" type="text/markdown"> pointing to .md routes.` : "No hosted docs pages were available to verify markdown alternate links.", markdownRoutesEnabled === false || markdownAlternateScore.status === "pass" ? void 0 : "Add a text/markdown alternate link in each docs page head, usually through `alternates.types['text/markdown']`, so agents can discover the page markdown URL from HTML."));
-	const mcp = await probeMcpRouteCandidates(baseUrl, hostedMcpRoutes(discovery.body));
-	const mcpPassed = mcp.probes.filter((result) => result.ok).length;
-	const mcpDetailProbes = mcpPassed > 0 ? mcp.probes.filter((result) => result.ok) : mcp.probes;
-	checks.push(makeCheck("hosted-mcp", "Hosted MCP handshake", mcpPassed > 0 ? "pass" : "fail", mcpPassed > 0 ? 10 : 0, 10, mcpDetailProbes.map((result) => result.detail).join(" "), mcpPassed > 0 ? void 0 : `Verify one of ${mcp.labels.join(" or ")} supports Streamable HTTP initialize and tools/list.`));
+	if (hostedCapability(discovery.body, "mcp") === false) checks.push(makeCheck("hosted-mcp", "Hosted MCP handshake", "warn", 0, 10, "The hosted discovery spec reports MCP as disabled.", "Enable MCP when agents should use structured list/search/read tools."));
+	else {
+		const mcp = await probeMcpRouteCandidates(baseUrl, hostedMcpRoutes(discovery.body), hostedMcpExpectedTools(discovery.body));
+		const mcpPassed = mcp.probes.filter((result) => result.ok).length;
+		const mcpDetailProbes = mcpPassed > 0 ? mcp.probes.filter((result) => result.ok) : mcp.probes;
+		checks.push(makeCheck("hosted-mcp", "Hosted MCP handshake", mcpPassed > 0 ? "pass" : "fail", mcpPassed > 0 ? 10 : 0, 10, mcpDetailProbes.map((result) => result.detail).join(" "), mcpPassed > 0 ? void 0 : `Verify one of ${mcp.labels.join(" or ")} supports Streamable HTTP initialize and tools/list.`));
+	}
 	return {
 		baseUrl,
 		checks
 	};
 }
-async function loadDocsConfigModuleWithProjectEnv(rootDir, explicitPath) {
-	const env = loadProjectEnv(rootDir);
-	const injectedKeys = Object.entries(env).filter(([key]) => process.env[key] === void 0).map(([key, value]) => {
-		process.env[key] = value;
-		return key;
-	});
-	try {
-		return await loadDocsConfigModule(rootDir, explicitPath);
-	} finally {
-		for (const key of injectedKeys) delete process.env[key];
-	}
-}
 function makeCheck(id, title, status, score, maxScore, detail, recommendation) {
 	return {
 		id,
@@ -1294,8 +1359,8 @@ async function inspectAgentReadiness(options = {}) {
 		};
 	}
 	const configContent = readFileSync(configPath, "utf-8");
-	const loadedConfig = await loadDocsConfigModuleWithProjectEnv(rootDir, options.configPath);
-	const config = loadedConfig?.config;
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
 	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
 	const ordering = config?.ordering === "alphabetical" || config?.ordering === "numeric" || Array.isArray(config?.ordering) ? config.ordering : void 0;
@@ -1317,11 +1382,24 @@ async function inspectAgentReadiness(options = {}) {
 	});
 	const pages = await Promise.resolve(source.getPages());
 	const coverage = buildCoverage(pages);
+	const usefulness = analyzeAgentUsefulness({
+		rootDir,
+		pages: createAgentUsefulnessPagesFromMcp(rootDir, pages),
+		projectFramework: framework === "unknown" ? void 0 : framework
+	});
+	const evaluationInput = config?.agent?.evaluations;
+	const evaluations = await runDocsGoldenTasks(pages, resolveGoldenEvaluationTasks(evaluationInput));
 	const compactionCoverage = buildCompactionCoverage(rootDir, contentDir, entry, pages, config?.agent?.compact ?? {});
 	coverage.compaction = compactionCoverage;
 	const metadataCoverage = buildMetadataCoverage(pages);
 	const metadataResult = metadataScore(metadataCoverage.descriptionCoverage, metadataCoverage.relatedCoverage);
 	const compactionResult = compactionFreshnessScore(compactionCoverage, compactConfigured);
+	const contextQualityResult = scoreUsefulnessCoverage(usefulness.metrics.agentBlocks.useful, usefulness.metrics.agentBlocks.total, 15);
+	const taskCompletenessResult = scoreUsefulnessCoverage(usefulness.metrics.taskCompleteness.completePages, usefulness.metrics.actionablePages, 15);
+	const applicabilityIssueCount = usefulness.metrics.applicability.conflictingPages + usefulness.metrics.applicability.ambiguousPages + usefulness.metrics.applicability.mismatchedPages;
+	const applicabilityResult = scoreUsefulnessCoverage(Math.max(0, usefulness.metrics.actionablePages - applicabilityIssueCount), usefulness.metrics.actionablePages, 10);
+	const commandHealthResult = scoreUsefulnessCoverage(usefulness.metrics.commands.healthy, usefulness.metrics.commands.total, 10);
+	const relatedCoverageResult = scoreUsefulnessCoverage(usefulness.metrics.related.coveredActionablePages, usefulness.metrics.actionablePages, 5);
 	const routeSurface = detectRouteSurface(rootDir, framework, staticExport, files);
 	const mcpConfig = resolveDocsMcpConfig(config?.mcp ?? void 0, { defaultName: siteTitle });
 	const sitemapConfig = resolveDocsSitemapConfig(config?.sitemap ?? readSitemapConfigFromStatic(configContent) ?? true);
@@ -1330,8 +1408,47 @@ async function inspectAgentReadiness(options = {}) {
 	const robotsPath = resolveRobotsFilePath(rootDir, framework, typeof robotsInput === "object" ? robotsInput : void 0);
 	const feedbackRoute = DEFAULT_AGENT_FEEDBACK_ROUTE;
 	const feedbackSchemaRoute = `${feedbackRoute}/schema`;
+	const discovery = buildDocsAgentDiscoverySpec({
+		origin: "http://localhost",
+		entry,
+		search: searchEnabled,
+		mcp: mcpConfig,
+		feedback: {
+			enabled: agentFeedbackEnabled,
+			route: feedbackRoute,
+			schemaRoute: feedbackSchemaRoute
+		}
+	});
+	const configuredAgentReviewPaths = configLoad.status === "evaluated" ? Object.values(buildDocsConfigMap(configLoad.config).pointers).map((pointer) => pointer.path).filter((optionPath) => optionPath === "agent" || optionPath.startsWith("agent.") || optionPath === "review" || optionPath.startsWith("review.")) : [];
+	const surfaceDrift = 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: mcpConfig.enabled,
+				endpoint: mcpConfig.route,
+				tools: mcpConfig.tools
+			},
+			routes: {
+				"api.docs": DEFAULT_DOCS_API_ROUTE,
+				"api.config": DEFAULT_DOCS_CONFIG_ROUTE,
+				"config.endpoint": DEFAULT_DOCS_CONFIG_ROUTE
+			}
+		}
+	});
 	const checks = [];
-	checks.push(makeCheck("config", "Docs config", "pass", 10, configCheckMax, loadedConfig ? `Resolved ${path.relative(rootDir, loadedConfig.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback.`));
+	checks.push(makeCheck("config", "Docs config", configLoad.status === "evaluated" ? "pass" : "warn", configLoad.status === "evaluated" ? 10 : 2, configCheckMax, configLoad.status === "evaluated" ? `Resolved ${path.relative(rootDir, configLoad.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback.`, configLoad.status === "evaluated" ? void 0 : "Fix docs.config module evaluation before relying on resolved diagnostic scores."));
+	const canScoreSurfaceDrift = configLoad.status === "evaluated";
+	checks.push(makeCheck("surface-drift", "Discovery/config/schema consistency", !canScoreSurfaceDrift ? "warn" : surfaceDrift.length === 0 ? "pass" : "fail", !canScoreSurfaceDrift ? 0 : surfaceDrift.length === 0 ? 10 : Math.max(0, 10 - surfaceDrift.length * 2), 10, !canScoreSurfaceDrift ? "Not scored because docs.config could not be evaluated; static parsing cannot prove discovery/config/schema consistency." : surfaceDrift.length === 0 ? "Resolved config, discovery metadata, MCP tool flags, config schema, and agent contract fields agree." : surfaceDrift.slice(0, 3).map((issue) => issue.message).join(" "), canScoreSurfaceDrift && surfaceDrift.length === 0 ? void 0 : canScoreSurfaceDrift ? "Align docs config, agent discovery, MCP tools, config schema, and the canonical page agent contract before publishing." : "Fix docs.config module evaluation so doctor can compare resolved config with discovery and schema surfaces."));
+	const dynamicStaticFallback = configLoad.status === "static-fallback" && /(?:\.\.\.|process\.env|import\.meta\.env|\[[^\]]+\]\s*:|:\s*[A-Za-z_$][\w$]*\s*[,}])/u.test(configContent);
+	checks.push(configLoad.status === "evaluated" ? makeCheck("config-confidence", "Config loading confidence", "pass", 5, 5, "High confidence: docs.config was evaluated with project-local environment values.") : makeCheck("config-confidence", "Config loading confidence", "warn", dynamicStaticFallback ? 1 : 2, 5, `${dynamicStaticFallback ? "Low" : "Partial"} confidence: only static config parsing succeeded. ${configLoad.error}`, "Fix docs.config module evaluation so doctor and review can inspect dynamic values, golden tasks, and resolved feature settings."));
 	const contentDirAbs = path.resolve(rootDir, contentDir);
 	checks.push(coverage.totalPages > 0 ? makeCheck("content", "Docs content", "pass", 10, 10, `Found ${coverage.totalPages} docs page${coverage.totalPages === 1 ? "" : "s"} in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`) : makeCheck("content", "Docs content", "fail", 0, 10, `No folder-based docs pages were found in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`, "Add index/page MDX files under the configured contentDir so the machine-readable surfaces have pages to serve."));
 	checks.push(makeCheck("api-route", "Docs API route", routeSurface.apiMounted ? "pass" : "fail", routeSurface.apiMounted ? 10 : 0, 10, routeSurface.apiDetail, routeSurface.apiMounted ? void 0 : "Wire the framework docs API route so /api/docs can serve markdown, llms.txt, sitemap, AGENTS.md, skill.md, and discovery responses."));
@@ -1367,7 +1484,16 @@ async function inspectAgentReadiness(options = {}) {
 	checks.push(makeCheck("metadata", "Page metadata", metadataResult.status, metadataResult.score, 5, coverage.totalPages > 0 ? `${metadataCoverage.describedPages}/${coverage.totalPages} pages include descriptions and ${metadataCoverage.relatedPages}/${coverage.totalPages} pages include related links (${metadataCoverage.descriptionCoverage}% described, ${metadataCoverage.relatedCoverage}% related).` : "No docs pages were available to score page metadata.", metadataCoverage.descriptionCoverage >= 75 ? void 0 : "Add page descriptions and related links to more docs pages so agent markdown output carries better context and navigation hints."));
 	const coverageResult = coverageScore(coverage.explicitCoverage);
 	checks.push(makeCheck("coverage", "Explicit page optimization", coverageResult.status, coverageResult.score, 10, coverage.totalPages > 0 ? `${coverage.explicitPages}/${coverage.totalPages} pages define explicit machine-only context (${coverage.pagesWithAgentFiles} agent.md, ${coverage.pagesWithAgentBlocks} Agent blocks, ${coverage.explicitCoverage}% of pages).` : "No docs pages were available to score explicit page optimization.", coverage.explicitCoverage >= 50 ? void 0 : "Add agent.md files or <Agent> blocks to more pages, or run docs agent compact to create page-level machine docs."));
+	checks.push(makeCheck("agent-context-quality", "Agent context usefulness", contextQualityResult.status, contextQualityResult.score, 15, usefulness.metrics.agentBlocks.total > 0 ? `${usefulness.metrics.agentBlocks.useful}/${usefulness.metrics.agentBlocks.total} Agent blocks are specific and non-repetitive (${usefulness.metrics.agentBlocks.duplicate} duplicate, ${usefulness.metrics.agentBlocks.boilerplate} boilerplate, ${usefulness.metrics.agentBlocks.generic} generic).` : "No embedded Agent blocks were present; page contracts and sibling agent.md files remain available as alternatives.", usefulness.metrics.agentBlocks.total > 0 && usefulness.metrics.agentBlocks.useful === usefulness.metrics.agentBlocks.total ? void 0 : "Replace repeated Agent boilerplate with page-specific constraints, commands, files, expected results, and recovery guidance."));
+	checks.push(makeCheck("agent-task-completeness", "Agent task completeness", taskCompletenessResult.status, taskCompletenessResult.score, 15, `${usefulness.metrics.taskCompleteness.completePages}/${usefulness.metrics.actionablePages} actionable pages include prerequisites, an expected result, and recovery guidance (${usefulness.metrics.taskCompleteness.coverage}% complete).`, usefulness.metrics.actionablePages > 0 && usefulness.metrics.taskCompleteness.coverage >= 80 ? void 0 : "Add prerequisites, observable outcomes or verification expectations, and rollback or resolved failure modes to actionable pages."));
+	checks.push(makeCheck("agent-applicability", "Framework and version applicability", applicabilityResult.status, applicabilityResult.score, 10, `${usefulness.metrics.applicability.conflictingPages} conflicting, ${usefulness.metrics.applicability.ambiguousPages} ambiguous, and ${usefulness.metrics.applicability.mismatchedPages} project-mismatched actionable pages.`, usefulness.metrics.actionablePages > 0 && applicabilityIssueCount === 0 ? void 0 : "Declare consistent framework/version metadata in page frontmatter and agent.appliesTo so retrieval can select the right variant."));
+	checks.push(makeCheck("command-health", "Documented command health", commandHealthResult.status, commandHealthResult.score, 10, `${usefulness.metrics.commands.healthy}/${usefulness.metrics.commands.total} statically inspected commands are healthy; ${usefulness.metrics.commands.unhealthy} are unhealthy and ${usefulness.metrics.commands.unverified} could not be verified safely.`, usefulness.metrics.commands.total > 0 && usefulness.metrics.commands.unhealthy === 0 && usefulness.metrics.commands.unverified === 0 ? void 0 : "Update broken or stale commands and make workspace selectors resolvable so scripts, working directories, package managers, and docs CLI subcommands can be verified."));
+	checks.push(makeCheck("related-coverage", "Related-page task coverage", relatedCoverageResult.status, relatedCoverageResult.score, 5, `${usefulness.metrics.related.coveredActionablePages}/${usefulness.metrics.actionablePages} actionable pages link to a valid related docs route; ${usefulness.metrics.related.brokenLinks} related links are broken.`, usefulness.metrics.actionablePages > 0 && usefulness.metrics.related.coverage >= 80 && usefulness.metrics.related.brokenLinks === 0 ? void 0 : "Add and validate related routes on actionable pages so agents can expand context without guessing."));
 	checks.push(makeCheck("compact", "Agent compaction freshness", compactionResult.status, compactionResult.score, 5, `${compactionCoverage.freshGeneratedPages} fresh, ${compactionCoverage.staleGeneratedPages} stale, ${compactionCoverage.modifiedGeneratedPages} modified, ${compactionCoverage.unknownGeneratedPages} unknown, ${compactionCoverage.tokenBudgetMissingPages} token-budget missing, and ${compactionCoverage.otherMissingPages} other missing page${compactionCoverage.otherMissingPages === 1 ? "" : "s"} across compactable docs pages.` + (compactConfigured ? " agent.compact defaults are configured." : " No agent.compact defaults were found in docs config."), compactionResult.recommendation));
+	const averageMetric = (values) => values.length === 0 ? 0 : Math.round(values.reduce((total, value) => total + value, 0) / values.length * 100) / 100;
+	const proportionalEvaluationScore = evaluations.score === null ? 0 : Math.round(evaluations.score / 100 * 15);
+	const evaluationScore = evaluations.status === "failed" ? Math.min(14, proportionalEvaluationScore) : proportionalEvaluationScore;
+	checks.push(makeCheck("golden-tasks", "Golden agent tasks", evaluations.status === "passed" ? "pass" : evaluations.status === "failed" ? "fail" : "warn", evaluationScore, 15, evaluations.status === "unmeasured" ? "No golden agent tasks are configured; retrieval usefulness is unmeasured." : `${evaluations.passedTaskCount}/${evaluations.taskCount} golden tasks passed with ${evaluations.score}/100 average score, ${averageMetric(evaluations.tasks.map((task) => task.retrieval.recallAtK))} retrieval recall, ${averageMetric(evaluations.tasks.map((task) => task.citations.recall))} citation recall, and ${evaluations.tasks.reduce((total, task) => total + task.usage.usedUtf8Bytes, 0)} UTF-8 context bytes used.`, evaluations.status === "passed" ? void 0 : evaluations.status === "unmeasured" ? "Configure agent.evaluations.tasks so doctor and review can measure retrieval, citations, framework/version selection, executable examples, and token usage." : "Inspect the failed golden task metrics and fix retrieval ranking, citations, applicability metadata, examples, or context budgets."));
 	const hosted = options.url ? await buildHostedAgentChecks(options.url, pages) : void 0;
 	if (hosted) checks.push(...hosted.checks);
 	const { score, maxScore } = normalizedDoctorScore(checks.reduce((total, check) => total + check.score, 0), checks.reduce((total, check) => total + check.maxScore, 0));
@@ -1380,9 +1506,11 @@ async function inspectAgentReadiness(options = {}) {
 		url: hosted?.baseUrl,
 		score,
 		maxScore,
-		grade: gradeForAgentScore(score),
+		grade: gradeForAgentScore(score, checks),
 		checks,
 		coverage,
+		usefulness: usefulness.metrics,
+		evaluations,
 		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
 	};
 }
@@ -1416,8 +1544,8 @@ async function inspectHumanReadiness(options = {}) {
 		};
 	}
 	const configContent = readFileSync(configPath, "utf-8");
-	const loadedConfig = await loadDocsConfigModuleWithProjectEnv(rootDir, options.configPath);
-	const config = loadedConfig?.config;
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
 	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
 	const ordering = config?.ordering === "alphabetical" || config?.ordering === "numeric" || Array.isArray(config?.ordering) ? config.ordering : void 0;
@@ -1440,7 +1568,7 @@ async function inspectHumanReadiness(options = {}) {
 	const navigationCoverage = coverage.totalPages === 0 ? 0 : Math.min(100, Math.round(coverage.navigationPages / coverage.totalPages * 100));
 	const navigationResult = navigationScore(navigationCoverage);
 	const checks = [];
-	checks.push(makeCheck("config", "Docs config", "pass", 10, 10, loadedConfig ? `Resolved ${path.relative(rootDir, loadedConfig.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback.`));
+	checks.push(makeCheck("config", "Docs config", configLoad.status === "evaluated" ? "pass" : "warn", configLoad.status === "evaluated" ? 10 : 2, 10, configLoad.status === "evaluated" ? `Resolved ${path.relative(rootDir, configLoad.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback. ${configLoad.error}`, configLoad.status === "evaluated" ? void 0 : "Fix docs.config module evaluation so the site score uses resolved dynamic configuration."));
 	const contentDirAbs = path.resolve(rootDir, contentDir);
 	checks.push(coverage.totalPages > 0 ? makeCheck("content", "Docs content", "pass", 15, 15, `Found ${coverage.totalPages} docs page${coverage.totalPages === 1 ? "" : "s"} in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`) : makeCheck("content", "Docs content", "fail", 0, 15, `No folder-based docs pages were found in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`, "Add index/page MDX files under the configured contentDir so the human docs site has pages to render."));
 	checks.push(makeCheck("navigation", "Navigation coverage", navigationResult.status, navigationResult.score, 15, coverage.totalPages > 0 ? `The generated docs navigation exposes ${coverage.navigationPages}/${coverage.totalPages} page entries (${navigationCoverage}% coverage).` : "No docs pages were available to score navigation coverage.", navigationCoverage >= 100 ? void 0 : "Make sure every important docs page is reachable from the generated navigation tree and not stranded outside the main docs flow."));
@@ -1473,6 +1601,8 @@ function printAgentDoctorReport(report) {
 	console.log(`${pc.bold("Framework:")} ${report.framework} ${pc.dim("•")} ${pc.bold("Entry:")} ${report.entry ?? "docs"} ${pc.dim("•")} ${pc.bold("Content:")} ${report.contentDir ?? "-"}`);
 	if (report.url) console.log(`${pc.bold("Hosted URL:")} ${report.url}`);
 	console.log(`${pc.bold("Explicit agent-friendly pages:")} ${report.coverage.explicitPages}/${report.coverage.totalPages} pages ${pc.dim(`(${report.coverage.explicitCoverage}%)`)}`);
+	if (report.usefulness) console.log(`${pc.bold("Useful Agent blocks:")} ${report.usefulness.agentBlocks.useful}/${report.usefulness.agentBlocks.total} ${pc.dim(`• ${report.usefulness.taskCompleteness.completePages}/${report.usefulness.actionablePages} actionable pages task-complete`)}`);
+	if (report.evaluations) console.log(`${pc.bold("Golden tasks:")} ${report.evaluations.status === "unmeasured" ? "unmeasured" : `${report.evaluations.passedTaskCount}/${report.evaluations.taskCount} passed (${report.evaluations.score}/100)`}`);
 	console.log(`${pc.bold("Generated agent.md freshness:")} ${report.coverage.compaction.freshGeneratedPages} fresh ${pc.dim("•")} ${report.coverage.compaction.staleGeneratedPages} stale ${pc.dim("•")} ${report.coverage.compaction.modifiedGeneratedPages} modified ${pc.dim("•")} ${report.coverage.compaction.tokenBudgetMissingPages} token-budget missing`);
 	if (report.fixes && report.fixes.length > 0) console.log(`${pc.bold("Fixes:")} ${report.fixes.map((fix) => `${fix.status === "applied" ? "applied" : "skipped"} ${fix.title}`).join(pc.dim(" • "))}`);
 	console.log();

package/dist/{downgrade-CYEaOctn.mjs → downgrade-BStNhyCc.mjs}

@@ -1,5 +1,5 @@
-import { c as fileExists, o as exec, s as execOutput } from "./utils-D-xTRNuh.mjs";
-import { a as getPackagesForFramework, c as resolveDocsPackageManager, l as validateUpgradeVersion, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework } from "./package-version-C8PigBZk.mjs";
+import { c as fileExists, o as exec, s as execOutput } from "./utils-DBCCkkJS.mjs";
+import { a as getPackagesForFramework, c as resolveDocsPackageManager, l as validateUpgradeVersion, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework } from "./package-version-DRIc08EU.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/i18n-CAlj1ADU.mjs

@@ -0,0 +1,40 @@
+//#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
+export { resolveDocsLocale as n, resolveDocsPath as r, resolveDocsI18n as t };