@farming-labs/docs 0.2.62 → 0.2.64

package/dist/doctor-DtGYZ41i.mjs

@@ -0,0 +1,2036 @@
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-CQTH7NFu.mjs";
+import { l as httpLinkHeaderHasTargetRelation } from "./reading-time-CYZ5VvKU.mjs";
+import { Dt as DEFAULT_SITEMAP_MD_ROUTE, Ft as resolveDocsSitemapConfig, Ht as PAGE_AGENT_CONTRACT_FIELDS, N as buildDocsMcpEndpointCandidates, Ot as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, dn as normalizeDocsMcpAuthorizationServerUrls, en as DEFAULT_MCP_PUBLIC_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, in as getDocsMcpProtectedResourceMetadataRoutes, j as buildDocsConfigMap, k as buildDocsAgentDiscoverySpec, kt as DEFAULT_SITEMAP_XML_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, nn as DEFAULT_MCP_WELL_KNOWN_ROUTE, sn as isDocsMcpOAuthScopeToken, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-DKKptIgy.mjs";
+import { c as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, g as DEFAULT_API_CATALOG_ROUTE, h as DEFAULT_API_CATALOG_FORMAT, k as resolveDocsDiscoveryApiRoute, l as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, n as API_CATALOG_MEDIA_TYPE, p as DEFAULT_AGENT_SKILL_FORMAT, r as API_CATALOG_PROFILE_URI, s as DEFAULT_AGENT_SKILLS_INDEX_FORMAT, t as AGENT_SKILLS_DISCOVERY_SCHEMA_URI, u as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX } from "./standards-discovery-jkykaXq1.mjs";
+import { d as resolveAskAISearchRequestConfig } from "./search-B6V6qtiI.mjs";
+import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-BIpC4j4P.mjs";
+import { a as resolveDocsMetadataBaseUrl } from "./metadata-DWExHQnx.mjs";
+import "./sitemap-server-C_6Wes83.mjs";
+import { t as runDocsGoldenTasks } from "./agent-evals-B7MIxuEX.mjs";
+import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import "./agent-skills-server-DraIb6FV.mjs";
+import "./server.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, r as extractTopLevelConfigObject, s as loadDocsConfigModuleResultWithProjectEnv, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { t as detectFramework } from "./utils-DpiIioYb.mjs";
+import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dj-9Eo3v.mjs";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
+import { createHash } from "node:crypto";
+import pc from "picocolors";
+
+//#region src/cli/doctor.ts
+const NEXT_CONFIG_PATTERN = /^next\.config\.(?:[cm]?js|[cm]?ts)$/;
+const ASTRO_CONFIG_PATTERN = /^astro\.config\.(?:[cm]?js|[cm]?ts)$/;
+const CODE_FILE_PATTERN = /\.(?:[cm]?js|[cm]?ts|jsx|tsx)$/;
+const IGNORED_DIRS = new Set([
+	".git",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	".turbo",
+	"build",
+	"coverage",
+	"dist",
+	"node_modules",
+	"out"
+]);
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseDoctorOnlyMode(value) {
+	if (value === "agent") return "agent";
+	if (value === "site") return "human";
+	throw new Error("Invalid value for --only. Expected agent or site.");
+}
+function parseDoctorFailOn(value) {
+	if (value === "warn" || value === "fail") return value;
+	throw new Error("Invalid value for --fail-on. Expected warn or fail.");
+}
+function parseDoctorArgs(argv) {
+	const parsed = {};
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--agent" || arg === "agent") {
+			parsed.mode = "agent";
+			continue;
+		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--strict") {
+			parsed.strict = true;
+			continue;
+		}
+		if (arg === "--fix") {
+			parsed.fix = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			parsed.dryRun = true;
+			continue;
+		}
+		if (arg.startsWith("--fail-on=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --fail-on.");
+			parsed.failOn = parseDoctorFailOn(value);
+			continue;
+		}
+		if (arg === "--fail-on") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --fail-on.");
+			parsed.failOn = parseDoctorFailOn(value);
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--only=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --only.");
+			parsed.mode = parseDoctorOnlyMode(value);
+			continue;
+		}
+		if (arg === "--only") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --only.");
+			parsed.mode = parseDoctorOnlyMode(value);
+			index += 1;
+			continue;
+		}
+		if (arg === "--human" || arg === "human" || arg === "--site" || arg === "site") {
+			parsed.mode = "human";
+			continue;
+		}
+		if (arg.startsWith("--config=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			continue;
+		}
+		if (arg.startsWith("--url=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --url.");
+			parsed.url = value;
+			continue;
+		}
+		if (arg === "--url") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --url.");
+			parsed.url = value;
+			index += 1;
+			continue;
+		}
+		if (arg === "--config") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown doctor flag or subcommand: ${arg}.`);
+	}
+	if (!parsed.help && !parsed.mode) parsed.mode = "agent";
+	return parsed;
+}
+function printDoctorHelp() {
+	console.log(`
+${pc.bold("@farming-labs/docs doctor")}
+
+${pc.dim("Usage:")}
+  pnpm exec docs doctor
+  pnpm exec docs doctor --agent
+  pnpm exec docs doctor --site
+  pnpm exec docs doctor --agent --json
+  pnpm exec docs doctor --agent --strict
+  pnpm exec docs doctor --agent --fix
+  pnpm exec docs doctor --agent --fix --dry-run
+  pnpm exec docs doctor --agent --fail-on fail
+  pnpm exec docs doctor --only agent
+  pnpm exec docs doctor --only site
+  pnpm exec docs doctor agent
+  pnpm exec docs doctor site
+
+${pc.dim("Options:")}
+  ${pc.cyan("--agent")}            Score agent-readiness for the current docs app (default)
+  ${pc.cyan("--site")}             Score reader-facing docs quality for the current docs app
+  ${pc.cyan("--human")}            Alias for ${pc.cyan("--site")}
+  ${pc.cyan("--only <mode>")}      Run only one doctor suite: ${pc.cyan("agent")} or ${pc.cyan("site")}
+  ${pc.cyan("--json")}             Print the report as JSON for CI, scripts, and other agents
+  ${pc.cyan("--strict")}           Exit with failure when any check warns or fails
+  ${pc.cyan("--fix")}              Refresh stale generated agent.md files and token-budget missing outputs
+  ${pc.cyan("--dry-run")}          With ${pc.cyan("--fix")}, report the compaction command without writing files
+  ${pc.cyan("--fail-on <level>")}  Exit with failure on ${pc.cyan("warn")} or only on ${pc.cyan("fail")}
+  ${pc.cyan("--url <url>")}        Probe hosted agent surfaces, e.g. ${pc.dim("https://docs.example.com")}
+  ${pc.cyan("--config <path>")}    Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+  ${pc.cyan("-h, --help")}         Show this help message
+`);
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function splitTopLevelProperties(content) {
+	const properties = [];
+	let start = 0;
+	let stringQuote = null;
+	let escaped = false;
+	let braceDepth = 0;
+	let bracketDepth = 0;
+	let parenDepth = 0;
+	for (let index = 0; index < content.length; index += 1) {
+		const char = content[index];
+		if (stringQuote) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			stringQuote = char;
+			continue;
+		}
+		if (char === "{") {
+			braceDepth += 1;
+			continue;
+		}
+		if (char === "}") {
+			braceDepth = Math.max(0, braceDepth - 1);
+			continue;
+		}
+		if (char === "[") {
+			bracketDepth += 1;
+			continue;
+		}
+		if (char === "]") {
+			bracketDepth = Math.max(0, bracketDepth - 1);
+			continue;
+		}
+		if (char === "(") {
+			parenDepth += 1;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			continue;
+		}
+		if (char === "," && braceDepth === 0 && bracketDepth === 0 && parenDepth === 0) {
+			properties.push(content.slice(start, index));
+			start = index + 1;
+		}
+	}
+	const trailing = content.slice(start);
+	if (trailing.trim().length > 0) properties.push(trailing);
+	return properties;
+}
+function readTopLevelBooleanProperty(content, key) {
+	const rootObject = extractTopLevelConfigObject(content) ?? content;
+	const propertyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*:\\s*(true|false)(?:\\s|$)`);
+	for (const property of splitTopLevelProperties(rootObject)) {
+		const match = property.trim().match(propertyPattern);
+		if (match) return match[1] === "true";
+	}
+}
+function readObjectBooleanProperty(content, key) {
+	const propertyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*:\\s*(true|false)(?:\\s|$)`);
+	for (const property of splitTopLevelProperties(content)) {
+		const match = property.trim().match(propertyPattern);
+		if (match) return match[1] === "true";
+	}
+}
+function resolveFeatureEnabled(config, content, key) {
+	const current = config?.[key];
+	if (typeof current === "boolean") return current;
+	if (current && typeof current === "object") return current.enabled ?? true;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, key);
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, [key]);
+	if (!block) return true;
+	return readBooleanProperty(block, "enabled") ?? true;
+}
+function readSitemapConfigFromStatic(content) {
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "sitemap");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["sitemap"]);
+	if (!block) return void 0;
+	const config = {};
+	const enabled = readObjectBooleanProperty(block, "enabled");
+	const routePrefix = block.match(/\broutePrefix\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+	const baseUrl = block.match(/\bbaseUrl\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+	const manifestPath = block.match(/\bmanifestPath\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+	if (typeof enabled === "boolean") config.enabled = enabled;
+	if (routePrefix) config.routePrefix = routePrefix;
+	if (baseUrl) config.baseUrl = baseUrl;
+	if (manifestPath) config.manifestPath = manifestPath;
+	return config;
+}
+function readRobotsConfigFromStatic(content) {
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "robots");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["robots"]);
+	if (!block) return void 0;
+	const config = {};
+	const enabled = readObjectBooleanProperty(block, "enabled");
+	const pathValue = block.match(/\bpath\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+	const baseUrl = block.match(/\bbaseUrl\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+	const aiString = block.match(/\bai\s*:\s*["'`](allow|disallow)["'`]/)?.[1];
+	const aiBoolean = readObjectBooleanProperty(block, "ai");
+	if (typeof enabled === "boolean") config.enabled = enabled;
+	if (pathValue) config.path = pathValue;
+	if (baseUrl) config.baseUrl = baseUrl;
+	if (aiString) config.ai = aiString;
+	else if (typeof aiBoolean === "boolean") config.ai = aiBoolean;
+	return config;
+}
+function resolvePublicDir(rootDir, framework) {
+	if (framework === "sveltekit") return path.join(rootDir, "static");
+	return path.join(rootDir, "public");
+}
+function resolveRobotsFilePath(rootDir, framework, robots) {
+	if (robots?.path) return path.isAbsolute(robots.path) ? robots.path : path.resolve(rootDir, robots.path);
+	return path.join(resolvePublicDir(rootDir, framework), "robots.txt");
+}
+function resolveStaticExport(config, content) {
+	if (typeof config?.staticExport === "boolean") return config.staticExport;
+	return readTopLevelBooleanProperty(content, "staticExport") ?? false;
+}
+function resolveAgentFeedbackEnabled(config, content) {
+	const feedback = config?.feedback;
+	if (feedback === false) return false;
+	if (feedback === true) return true;
+	if (feedback && typeof feedback === "object") {
+		const agent = feedback.agent;
+		if (typeof agent === "boolean") return agent;
+		if (agent && typeof agent === "object") return agent.enabled ?? true;
+		return true;
+	}
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "feedback");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const feedbackBlock = extractNestedObjectLiteral(content, ["feedback"]);
+	if (!feedbackBlock) return true;
+	const nestedAgentBlock = extractNestedObjectLiteral(content, ["feedback", "agent"]);
+	if (nestedAgentBlock) return readBooleanProperty(nestedAgentBlock, "enabled") ?? true;
+	return readBooleanProperty(feedbackBlock, "agent") ?? true;
+}
+function resolveHumanFeedbackEnabled(config, content) {
+	const feedback = config?.feedback;
+	if (typeof feedback === "boolean") return feedback;
+	if (feedback && typeof feedback === "object") return feedback.enabled ?? true;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "feedback");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const feedbackBlock = extractNestedObjectLiteral(content, ["feedback"]);
+	if (!feedbackBlock) return false;
+	return readBooleanProperty(feedbackBlock, "enabled") ?? true;
+}
+function resolveLastUpdatedEnabled(config, content) {
+	const current = config?.lastUpdated;
+	if (typeof current === "boolean") return current;
+	if (current && typeof current === "object") return current.enabled ?? true;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "lastUpdated");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["lastUpdated"]);
+	if (!block) return true;
+	return readBooleanProperty(block, "enabled") ?? true;
+}
+function hasGithubIntegration(config, content) {
+	if (typeof config?.github === "string") return config.github.trim().length > 0;
+	if (config?.github && typeof config.github === "object") return typeof config.github.url === "string" && config.github.url.trim().length > 0;
+	const topLevelString = readTopLevelStringProperty(content, "github");
+	if (typeof topLevelString === "string" && topLevelString.trim().length > 0) return true;
+	const githubBlock = extractNestedObjectLiteral(content, ["github"]);
+	if (!githubBlock) return false;
+	const urlMatch = githubBlock.match(/\burl\s*:\s*["'`]([^"'`]+)["'`]/);
+	return typeof urlMatch?.[1] === "string" && urlMatch[1].trim().length > 0;
+}
+function hasReadingTimeSurface(config, content) {
+	const current = config?.readingTime;
+	if (current === true) return true;
+	if (current && typeof current === "object") return current.enabled !== false;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "readingTime");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["readingTime"]);
+	if (!block) return false;
+	return readBooleanProperty(block, "enabled") ?? true;
+}
+function hasAgentCompactDefaults(config, content) {
+	if (config?.agent?.compact) return true;
+	return extractNestedObjectLiteral(content, ["agent", "compact"]) !== void 0;
+}
+function listProjectFiles(rootDir) {
+	const files = [];
+	const visit = (dir) => {
+		if (!existsSync(dir)) return;
+		for (const entry of readdirSync(dir).sort()) {
+			const fullPath = path.join(dir, entry);
+			const stat = lstatSync(fullPath);
+			if (stat.isSymbolicLink()) continue;
+			if (stat.isDirectory()) {
+				if (IGNORED_DIRS.has(entry)) continue;
+				visit(fullPath);
+				continue;
+			}
+			files.push(path.relative(rootDir, fullPath).replace(/\\/g, "/"));
+		}
+	};
+	visit(rootDir);
+	return files;
+}
+function buildFileReader(rootDir) {
+	const cache = /* @__PURE__ */ new Map();
+	return (relativePath) => {
+		const cached = cache.get(relativePath);
+		if (cached !== void 0) return cached;
+		const content = readFileSync(path.join(rootDir, relativePath), "utf-8");
+		cache.set(relativePath, content);
+		return content;
+	};
+}
+function formatPathList(paths) {
+	if (paths.length === 0) return "";
+	if (paths.length === 1) return paths[0];
+	return `${paths[0]} (+${paths.length - 1} more)`;
+}
+function findCodeFiles(files, predicate) {
+	return files.filter((relativePath) => CODE_FILE_PATTERN.test(relativePath) && predicate(relativePath));
+}
+function detectFrameworkFromFiles(files) {
+	if (files.some((file) => NEXT_CONFIG_PATTERN.test(path.basename(file)))) return "nextjs";
+	if (files.some((file) => file.startsWith("src/routes/") && file.includes("api.docs"))) return "tanstack-start";
+	if (files.some((file) => file === "src/hooks.server.js" || file === "src/hooks.server.ts")) return "sveltekit";
+	if (files.some((file) => ASTRO_CONFIG_PATTERN.test(path.basename(file)))) return "astro";
+	if (files.some((file) => file.startsWith("server/middleware/"))) return "nuxt";
+	return null;
+}
+function detectRouteSurface(rootDir, framework, staticExport, files) {
+	const read = buildFileReader(rootDir);
+	if (framework === "nextjs") {
+		const withDocsConfigs = files.filter((file) => NEXT_CONFIG_PATTERN.test(path.basename(file))).filter((file) => read(file).includes("withDocs("));
+		const apiRoutes = findCodeFiles(files, (file) => /(?:^|\/)route\.(?:[cm]?js|[cm]?ts|jsx|tsx)$/.test(file) && read(file).includes("createDocsAPI("));
+		if (staticExport) return {
+			apiMounted: false,
+			apiDetail: "Next static export disables /api/docs and the shared agent endpoints.",
+			publicMounted: false,
+			publicDetail: "Public .md, llms.txt, sitemap, AGENTS.md, skill.md, and agent discovery routes depend on /api/docs."
+		};
+		return {
+			apiMounted: apiRoutes.length > 0,
+			apiDetail: apiRoutes.length > 0 ? `Found docs API route at ${formatPathList(apiRoutes)}.` : "Could not find a Next docs API route that uses createDocsAPI().",
+			publicMounted: withDocsConfigs.length > 0,
+			publicDetail: withDocsConfigs.length > 0 ? `Found withDocs() in ${formatPathList(withDocsConfigs)}.` : "Could not find withDocs() in next.config.*, so public docs rewrites are not verified."
+		};
+	}
+	if (framework === "tanstack-start") {
+		const apiRoutes = findCodeFiles(files, (file) => file.startsWith("src/routes/") && read(file).includes("docsServer.GET") && /createFileRoute\((["'])\/api/.test(read(file)));
+		const publicHandlers = findCodeFiles(files, (file) => file.startsWith("src/routes/") && read(file).includes("isDocsPublicGetRequest(") && read(file).includes("isDocsMcpRequest("));
+		return {
+			apiMounted: apiRoutes.length > 0,
+			apiDetail: apiRoutes.length > 0 ? `Found TanStack docs API route at ${formatPathList(apiRoutes)}.` : "Could not find a TanStack route that forwards /api/docs into docsServer.GET.",
+			publicMounted: publicHandlers.length > 0,
+			publicDetail: publicHandlers.length > 0 ? `Found public docs forwarder at ${formatPathList(publicHandlers)}.` : "Could not find a TanStack public docs forwarder using isDocsPublicGetRequest()."
+		};
+	}
+	if (framework === "sveltekit") {
+		const apiRoutes = findCodeFiles(files, (file) => file.startsWith("src/routes/") && path.basename(file).startsWith("+server.") && read(file).includes("docs.server"));
+		const publicHandlers = findCodeFiles(files, (file) => /^src\/hooks\.server\.(?:[cm]?js|[cm]?ts)$/.test(file) && read(file).includes("isDocsPublicGetRequest("));
+		return {
+			apiMounted: apiRoutes.length > 0,
+			apiDetail: apiRoutes.length > 0 ? `Found SvelteKit docs API route at ${formatPathList(apiRoutes)}.` : "Could not find a SvelteKit +server route that re-exports docs.server.",
+			publicMounted: publicHandlers.length > 0,
+			publicDetail: publicHandlers.length > 0 ? `Found SvelteKit public docs hook at ${formatPathList(publicHandlers)}.` : "Could not find hooks.server with isDocsPublicGetRequest()."
+		};
+	}
+	if (framework === "astro") {
+		const apiRoutes = findCodeFiles(files, (file) => file.startsWith("src/pages/") && read(file).includes("docsGET") && read(file).includes("docsPOST"));
+		const publicHandlers = findCodeFiles(files, (file) => /^src\/middleware\.(?:[cm]?js|[cm]?ts)$/.test(file) && read(file).includes("isDocsPublicGetRequest("));
+		return {
+			apiMounted: apiRoutes.length > 0,
+			apiDetail: apiRoutes.length > 0 ? `Found Astro docs API route at ${formatPathList(apiRoutes)}.` : "Could not find an Astro docs API route that forwards to docs.server.",
+			publicMounted: publicHandlers.length > 0,
+			publicDetail: publicHandlers.length > 0 ? `Found Astro middleware forwarder at ${formatPathList(publicHandlers)}.` : "Could not find Astro middleware using isDocsPublicGetRequest()."
+		};
+	}
+	if (framework === "nuxt") {
+		const apiRoutes = findCodeFiles(files, (file) => file.startsWith("server/api/") && read(file).includes("defineDocsHandler("));
+		const publicHandlers = findCodeFiles(files, (file) => file.startsWith("server/middleware/") && read(file).includes("defineDocsPublicHandler("));
+		return {
+			apiMounted: apiRoutes.length > 0,
+			apiDetail: apiRoutes.length > 0 ? `Found Nuxt docs API handler at ${formatPathList(apiRoutes)}.` : "Could not find a Nuxt docs API handler using defineDocsHandler().",
+			publicMounted: publicHandlers.length > 0,
+			publicDetail: publicHandlers.length > 0 ? `Found Nuxt public docs middleware at ${formatPathList(publicHandlers)}.` : "Could not find Nuxt middleware using defineDocsPublicHandler()."
+		};
+	}
+	return {
+		apiMounted: false,
+		apiDetail: "Could not detect a supported framework, so API route inspection was skipped.",
+		publicMounted: false,
+		publicDetail: "Could not detect a supported framework, so public route inspection was skipped."
+	};
+}
+function coverageScore(explicitCoverage) {
+	if (explicitCoverage >= 80) return {
+		status: "pass",
+		score: 10
+	};
+	if (explicitCoverage >= 50) return {
+		status: "pass",
+		score: 8
+	};
+	if (explicitCoverage >= 20) return {
+		status: "warn",
+		score: 5
+	};
+	if (explicitCoverage > 0) return {
+		status: "warn",
+		score: 3
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function metadataScore(descriptionCoverage, relatedCoverage) {
+	if (descriptionCoverage >= 90 && relatedCoverage >= 20) return {
+		status: "pass",
+		score: 5
+	};
+	if (descriptionCoverage >= 75) return {
+		status: "pass",
+		score: 4
+	};
+	if (descriptionCoverage >= 50) return {
+		status: "warn",
+		score: 2
+	};
+	if (descriptionCoverage > 0) return {
+		status: "warn",
+		score: 1
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function descriptionScore(descriptionCoverage) {
+	if (descriptionCoverage >= 90) return {
+		status: "pass",
+		score: 15
+	};
+	if (descriptionCoverage >= 75) return {
+		status: "pass",
+		score: 12
+	};
+	if (descriptionCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (descriptionCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function structureScore(structureCoverage) {
+	if (structureCoverage >= 90) return {
+		status: "pass",
+		score: 15
+	};
+	if (structureCoverage >= 75) return {
+		status: "pass",
+		score: 12
+	};
+	if (structureCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (structureCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function navigationScore(navigationCoverage) {
+	if (navigationCoverage >= 100) return {
+		status: "pass",
+		score: 15
+	};
+	if (navigationCoverage >= 80) return {
+		status: "pass",
+		score: 12
+	};
+	if (navigationCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (navigationCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "fail",
+		score: 0
+	};
+}
+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";
+}
+function gradeForHumanScore(score) {
+	if (score >= 90) return "Human-optimized";
+	if (score >= 75) return "Reader-ready";
+	if (score >= 60) return "Promising";
+	return "Needs work";
+}
+function percentageScore(score, maxScore) {
+	if (maxScore <= 0) return 0;
+	return Math.round(score / maxScore * 100);
+}
+function normalizedDoctorScore(score, maxScore) {
+	return {
+		score: percentageScore(score, maxScore),
+		maxScore: 100
+	};
+}
+function formatStatus(status) {
+	if (status === "pass") return pc.green("PASS");
+	if (status === "warn") return pc.yellow("WARN");
+	return pc.red("FAIL");
+}
+function buildCoverage(pages) {
+	const totalPages = pages.length;
+	const pagesWithAgentFiles = pages.filter((page) => page.agentRawContent !== void 0).length;
+	const pagesWithAgentBlocks = pages.filter((page) => page.agentFallbackRawContent !== void 0).length;
+	const explicitPages = pages.filter((page) => page.agentRawContent !== void 0 || page.agentFallbackRawContent !== void 0).length;
+	return {
+		totalPages,
+		pagesWithAgentFiles,
+		pagesWithAgentBlocks,
+		explicitPages,
+		explicitCoverage: totalPages === 0 ? 0 : Math.round(explicitPages / Math.max(totalPages, 1) * 100),
+		compaction: {
+			freshGeneratedPages: 0,
+			staleGeneratedPages: 0,
+			modifiedGeneratedPages: 0,
+			unknownGeneratedPages: 0,
+			tokenBudgetMissingPages: 0,
+			otherMissingPages: 0
+		}
+	};
+}
+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]));
+	const coverage = {
+		freshGeneratedPages: 0,
+		staleGeneratedPages: 0,
+		modifiedGeneratedPages: 0,
+		unknownGeneratedPages: 0,
+		tokenBudgetMissingPages: 0,
+		otherMissingPages: 0
+	};
+	for (const page of pages) {
+		const target = targetsBySlug.get(page.slug);
+		if (!target) continue;
+		const state = inspectAgentCompactionState(page, target, defaults);
+		switch (state.status) {
+			case "fresh":
+				coverage.freshGeneratedPages += 1;
+				break;
+			case "stale":
+				coverage.staleGeneratedPages += 1;
+				break;
+			case "modified":
+			case "stale-modified":
+				coverage.modifiedGeneratedPages += 1;
+				break;
+			case "unknown":
+				coverage.unknownGeneratedPages += 1;
+				break;
+			case "missing":
+				if (state.tokenBudget !== void 0) coverage.tokenBudgetMissingPages += 1;
+				else coverage.otherMissingPages += 1;
+				break;
+		}
+	}
+	return coverage;
+}
+function compactionFreshnessScore(coverage, compactConfigured) {
+	if (coverage.staleGeneratedPages > 0 || coverage.modifiedGeneratedPages > 0 || coverage.tokenBudgetMissingPages > 0) {
+		const recommendations = [];
+		if (coverage.staleGeneratedPages > 0) recommendations.push("Run docs agent compact --stale to refresh stale generated agent.md files.");
+		if (coverage.modifiedGeneratedPages > 0) recommendations.push("Review modified generated agent.md files before overwriting them; --stale skips manual edits on purpose.");
+		if (coverage.tokenBudgetMissingPages > 0) recommendations.push("Run docs agent compact --stale --include-missing to create generated agent.md files for pages that opted into agent.tokenBudget.");
+		return {
+			status: "warn",
+			score: compactConfigured ? 2 : 0,
+			recommendation: recommendations.join(" ")
+		};
+	}
+	if (coverage.unknownGeneratedPages > 0) return {
+		status: "pass",
+		score: compactConfigured ? 5 : 3
+	};
+	if (coverage.freshGeneratedPages > 0) return {
+		status: "pass",
+		score: compactConfigured ? 5 : 4
+	};
+	if (compactConfigured) return {
+		status: "pass",
+		score: 5
+	};
+	return {
+		status: "warn",
+		score: 0,
+		recommendation: "Add agent.compact defaults if you want docs agent compact and stale detection to run without repeating model and compression settings."
+	};
+}
+function buildMetadataCoverage(pages) {
+	const totalPages = pages.length;
+	const describedPages = pages.filter((page) => typeof page.description === "string" && page.description.trim().length > 0).length;
+	const relatedPages = pages.filter((page) => Array.isArray(page.related) && page.related.length > 0).length;
+	return {
+		describedPages,
+		relatedPages,
+		descriptionCoverage: totalPages === 0 ? 0 : Math.round(describedPages / totalPages * 100),
+		relatedCoverage: totalPages === 0 ? 0 : Math.round(relatedPages / totalPages * 100)
+	};
+}
+function countNavigationPages(node) {
+	const urls = /* @__PURE__ */ new Set();
+	const visit = (current) => {
+		if (current.type === "page" && typeof current.url === "string") urls.add(current.url);
+		if (current.index && typeof current.index === "object") {
+			const indexNode = current.index;
+			if (typeof indexNode.url === "string") urls.add(indexNode.url);
+		}
+		const children = Array.isArray(current.children) ? current.children : [];
+		for (const child of children) {
+			if (!child || typeof child !== "object") continue;
+			visit(child);
+		}
+	};
+	visit(node);
+	return urls.size;
+}
+function estimateWordCount(content) {
+	return content.match(/\b[\p{L}\p{N}][\p{L}\p{N}'’-]*\b/gu)?.length ?? 0;
+}
+function hasSectionHeadings(content) {
+	return /^###{0,1}\s+/m.test(content);
+}
+function buildHumanCoverage(pages, navigationPages) {
+	const totalPages = pages.length;
+	const describedPages = pages.filter((page) => typeof page.description === "string" && page.description.trim().length > 0).length;
+	const longPages = pages.filter((page) => estimateWordCount(page.rawContent ?? "") >= 120).length;
+	const structuredLongPages = pages.filter((page) => {
+		const content = page.rawContent ?? "";
+		return estimateWordCount(content) >= 120 && hasSectionHeadings(content);
+	}).length;
+	return {
+		totalPages,
+		describedPages,
+		descriptionCoverage: totalPages === 0 ? 0 : Math.round(describedPages / totalPages * 100),
+		longPages,
+		structuredLongPages,
+		structureCoverage: longPages === 0 ? 100 : Math.round(structuredLongPages / longPages * 100),
+		navigationPages
+	};
+}
+function normalizeDoctorBaseUrl(value) {
+	const url = new URL(value);
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("URL must use http or https.");
+	url.hash = "";
+	url.search = "";
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	return url.toString().replace(/\/+$/, "");
+}
+function joinDoctorUrl(baseUrl, route) {
+	const base = new URL(baseUrl);
+	const basePath = base.pathname.replace(/\/+$/, "");
+	const routePath = route.startsWith("/") ? route : `/${route}`;
+	return new URL(`${basePath}${routePath}`, base.origin).toString();
+}
+function toMarkdownRoute(pageUrl) {
+	if (!pageUrl) return void 0;
+	const normalized = pageUrl === "/" ? "/index" : pageUrl.replace(/\/+$/, "");
+	return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
+}
+async function fetchWithTimeout(url, init = {}, timeoutMs = 8e3) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, {
+			...init,
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+async function probeTextRoute(baseUrl, route) {
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "text/plain, text/markdown, */*" } });
+		const body = await response.text().catch(() => "");
+		if (!response.ok) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status}.`
+		};
+		if (body.trim().length === 0) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned an empty body.`
+		};
+		return {
+			ok: true,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status} with ${body.length} characters.`,
+			body,
+			linkHeader: response.headers.get("link") ?? void 0
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+function decodeHtmlEntity(value) {
+	const named = {
+		amp: "&",
+		apos: "'",
+		gt: ">",
+		lt: "<",
+		quot: "\""
+	};
+	return value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, raw) => {
+		const lower = raw.toLowerCase();
+		if (lower.startsWith("#x")) {
+			const codePoint = Number.parseInt(lower.slice(2), 16);
+			return Number.isFinite(codePoint) && codePoint >= 0 && codePoint <= 1114111 ? String.fromCodePoint(codePoint) : entity;
+		}
+		if (lower.startsWith("#")) {
+			const codePoint = Number.parseInt(lower.slice(1), 10);
+			return Number.isFinite(codePoint) && codePoint >= 0 && codePoint <= 1114111 ? String.fromCodePoint(codePoint) : entity;
+		}
+		return named[lower] ?? entity;
+	});
+}
+function htmlAttribute(tag, name) {
+	for (const match of tag.matchAll(/([^\s"'<>/=]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g)) {
+		if (match[1]?.toLowerCase() !== name.toLowerCase()) continue;
+		return decodeHtmlEntity(match[2] ?? match[3] ?? match[4] ?? "");
+	}
+}
+function hasJsonLdScript(html) {
+	return /<script\b(?=[^>]*\btype\s*=\s*["']application\/ld\+json["'])[^>]*>/i.test(html);
+}
+function markdownAlternateHref(html) {
+	for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
+		const tag = match[0];
+		const rel = htmlAttribute(tag, "rel") ?? "";
+		const type = htmlAttribute(tag, "type") ?? "";
+		const href = htmlAttribute(tag, "href");
+		const relTokens = rel.toLowerCase().split(/\s+/).filter(Boolean);
+		if (href && relTokens.includes("alternate") && /^text\/markdown(?:\s*;|$)/i.test(type.trim())) return href;
+	}
+}
+function resolveMarkdownAlternateUrl(href, pageUrl) {
+	if (!href) return void 0;
+	try {
+		const url = new URL(href, pageUrl);
+		const page = new URL(pageUrl);
+		return url.origin === page.origin && url.pathname.endsWith(".md") ? url : void 0;
+	} catch {
+		return;
+	}
+}
+function canonicalLinkFromHeader(header) {
+	if (!header) return void 0;
+	for (const match of header.matchAll(/<([^>]+)>\s*((?:;\s*[^,]+)*)/g)) {
+		const rel = (match[2] ?? "").match(/(?:^|;)\s*rel\s*=\s*(?:"([^"]*)"|([^;\s,]+))/i);
+		if ((rel?.[1] ?? rel?.[2] ?? "").toLowerCase().split(/\s+/).includes("canonical")) return match[1];
+	}
+}
+function normalizeCanonicalUrl(value, baseUrl) {
+	try {
+		const url = new URL(value, baseUrl);
+		url.hash = "";
+		url.search = "";
+		return url.toString().replace(/\/+$/, "");
+	} catch {
+		return;
+	}
+}
+function hasCanonicalLinkHeader(header, pageUrl, responseUrl) {
+	const canonical = canonicalLinkFromHeader(header);
+	if (!canonical) return false;
+	return normalizeCanonicalUrl(canonical, responseUrl) === normalizeCanonicalUrl(pageUrl, pageUrl);
+}
+async function probeRobotsRoute(baseUrl, route = DEFAULT_ROBOTS_TXT_ROUTE) {
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "text/plain, */*" } });
+		const body = await response.text().catch(() => "");
+		if (!response.ok) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status}.`
+		};
+		if (body.trim().length === 0) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned an empty body.`
+		};
+		return {
+			ok: true,
+			status: response.status,
+			body,
+			detail: `${route} returned HTTP ${response.status} with ${body.length} characters.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function probeJsonRoute(baseUrl, route) {
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "application/json" } });
+		const text = await response.text().catch(() => "");
+		if (!response.ok) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status}.`
+		};
+		try {
+			const body = JSON.parse(text);
+			return {
+				ok: true,
+				status: response.status,
+				detail: `${route} returned valid JSON.`,
+				body
+			};
+		} catch {
+			return {
+				ok: false,
+				status: response.status,
+				detail: `${route} did not return valid JSON.`
+			};
+		}
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function parseMcpResponse(response) {
+	const contentType = response.headers.get("content-type") ?? "";
+	const body = await response.text();
+	if (contentType.includes("application/json")) return JSON.parse(body);
+	const data = body.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).filter(Boolean).at(-1);
+	if (!data) throw new Error(`Expected MCP JSON-RPC payload, got ${body.slice(0, 120) || "empty body"}.`);
+	return JSON.parse(data);
+}
+async function postMcpJson(baseUrl, route, body, sessionId) {
+	return fetchWithTimeout(joinDoctorUrl(baseUrl, route), {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+			"mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+			...sessionId ? { "mcp-session-id": sessionId } : {}
+		},
+		body: JSON.stringify(body)
+	});
+}
+async function probeMcpRoute(baseUrl, route, expectedTools) {
+	try {
+		const initializeResponse = await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			id: "doctor-initialize",
+			method: "initialize",
+			params: {
+				protocolVersion: LATEST_PROTOCOL_VERSION,
+				capabilities: {},
+				clientInfo: {
+					name: "@farming-labs/docs doctor",
+					version: "0.0.0"
+				}
+			}
+		});
+		if (initializeResponse.status === 401) return await probeProtectedMcpDiscovery(baseUrl, route, initializeResponse);
+		const initializePayload = await parseMcpResponse(initializeResponse);
+		if (!initializeResponse.ok || initializePayload.error) return {
+			ok: false,
+			detail: `${route} initialize returned HTTP ${initializeResponse.status}: ${String(initializePayload.error?.message ?? "unknown MCP error")}.`
+		};
+		const sessionId = initializeResponse.headers.get("mcp-session-id") ?? void 0;
+		if (sessionId) await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			method: "notifications/initialized",
+			params: {}
+		}, sessionId).catch(() => void 0);
+		const toolsResponse = await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			id: "doctor-tools-list",
+			method: "tools/list",
+			params: {}
+		}, sessionId);
+		const toolsPayload = await parseMcpResponse(toolsResponse);
+		if (sessionId) await fetchWithTimeout(joinDoctorUrl(baseUrl, route), {
+			method: "DELETE",
+			headers: {
+				"mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+				"mcp-session-id": sessionId
+			}
+		}).catch(() => void 0);
+		if (!toolsResponse.ok || toolsPayload.error) return {
+			ok: false,
+			detail: `${route} tools/list returned HTTP ${toolsResponse.status}: ${String(toolsPayload.error?.message ?? "unknown MCP error")}.`
+		};
+		const tools = toolsPayload.result?.tools;
+		const toolNames = Array.isArray(tools) ? tools.map((tool) => tool.name).filter((name) => typeof name === "string") : [];
+		const missingTools = expectedTools.filter((tool) => !toolNames.includes(tool));
+		if (missingTools.length > 0) return {
+			ok: false,
+			detail: `${route} connected but is missing tools: ${missingTools.join(", ")}.`
+		};
+		return {
+			ok: true,
+			detail: `${route} initialized ${sessionId ? "with a session" : "statelessly"} and exposed ${toolNames.length} MCP tool${toolNames.length === 1 ? "" : "s"}.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function probeProtectedMcpDiscovery(baseUrl, route, response) {
+	const bearerChallenge = findBearerChallenge(response.headers.get("www-authenticate") ?? "");
+	const rawMetadataUrl = bearerChallenge ? readHttpAuthQuotedParameter(bearerChallenge, "resource_metadata") : void 0;
+	if (!bearerChallenge || !rawMetadataUrl) return {
+		ok: false,
+		detail: `${route} requires authentication but did not return a Bearer resource_metadata challenge.`
+	};
+	const resourceUrl = new URL(joinDoctorUrl(baseUrl, route));
+	let metadataUrl;
+	try {
+		metadataUrl = new URL(rawMetadataUrl);
+	} catch {
+		return {
+			ok: false,
+			detail: `${route} returned an invalid resource_metadata URL.`
+		};
+	}
+	if (metadataUrl.origin !== resourceUrl.origin) return {
+		ok: false,
+		detail: `${route} returned cross-origin protected-resource metadata; the hosted doctor will not fetch it.`
+	};
+	let metadataResponse;
+	try {
+		metadataResponse = await fetchWithTimeout(metadataUrl.href, {
+			headers: { Accept: "application/json" },
+			redirect: "manual"
+		});
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} protected-resource metadata failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+	if (metadataResponse.status !== 200) return {
+		ok: false,
+		detail: `${route} protected-resource metadata returned HTTP ${metadataResponse.status}.`
+	};
+	if (responseMediaType(metadataResponse.headers.get("content-type")) !== "application/json") return {
+		ok: false,
+		detail: `${route} protected-resource metadata did not return application/json.`
+	};
+	let metadata;
+	try {
+		const metadataRecord = asRecord(await metadataResponse.json());
+		if (!metadataRecord) return {
+			ok: false,
+			detail: `${route} protected-resource metadata must be a JSON object.`
+		};
+		metadata = metadataRecord;
+	} catch {
+		return {
+			ok: false,
+			detail: `${route} protected-resource metadata is not valid JSON.`
+		};
+	}
+	if (metadata.resource !== resourceUrl.href) return {
+		ok: false,
+		detail: `${route} protected-resource metadata identifies ${String(metadata.resource ?? "no resource")} instead of ${resourceUrl.href}.`
+	};
+	const authorizationServers = metadata.authorization_servers;
+	if (!Array.isArray(authorizationServers) || authorizationServers.length === 0 || normalizeDocsMcpAuthorizationServerUrls(authorizationServers.filter((issuer) => typeof issuer === "string")).length !== authorizationServers.length) return {
+		ok: false,
+		detail: `${route} protected-resource metadata is missing valid authorization_servers.`
+	};
+	const scopesSupported = metadata.scopes_supported;
+	if (scopesSupported !== void 0 && (!Array.isArray(scopesSupported) || scopesSupported.some((scope) => !isDocsMcpOAuthScopeToken(scope)))) return {
+		ok: false,
+		detail: `${route} protected-resource metadata has invalid scopes_supported.`
+	};
+	const challengeScope = readHttpAuthQuotedParameter(bearerChallenge, "scope");
+	if (challengeScope !== void 0 && challengeScope.split(" ").some((scope) => !isDocsMcpOAuthScopeToken(scope))) return {
+		ok: false,
+		detail: `${route} returned an invalid Bearer scope challenge.`
+	};
+	return {
+		ok: true,
+		detail: `${route} is protected and exposes valid RFC 9728 metadata at ${metadataUrl.pathname}.`
+	};
+}
+function findBearerChallenge(header) {
+	let first = 0;
+	while (first < header.length && /\s/u.test(header[first] ?? "")) first += 1;
+	const starts = [first];
+	let quoted = false;
+	let escaped = false;
+	for (let index = 0; index < header.length; index += 1) {
+		const character = header[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (quoted && character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (character === "\"") {
+			quoted = !quoted;
+			continue;
+		}
+		if (quoted || character !== ",") continue;
+		let candidate = index + 1;
+		while (candidate < header.length && /\s/u.test(header[candidate] ?? "")) candidate += 1;
+		const tokenStart = candidate;
+		while (candidate < header.length && /[!#$%&'*+\-.^_`|~0-9A-Za-z]/u.test(header[candidate] ?? "")) candidate += 1;
+		if (candidate === tokenStart) continue;
+		let afterToken = candidate;
+		while (afterToken < header.length && /\s/u.test(header[afterToken] ?? "")) afterToken += 1;
+		if (header[afterToken] !== "=") starts.push(tokenStart);
+	}
+	for (let index = 0; index < starts.length; index += 1) {
+		const start = starts[index] ?? 0;
+		if ((/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+/u.exec(header.slice(start))?.[0])?.toLowerCase() !== "bearer") continue;
+		const end = starts[index + 1] ?? header.length;
+		return header.slice(start, end).replace(/,\s*$/u, "").trim();
+	}
+}
+function readHttpAuthQuotedParameter(header, name) {
+	return (new RegExp(`(?:^|[,\\s])${name}\\s*=\\s*"((?:\\\\.|[^"\\\\])*)"`, "i").exec(header)?.[1])?.replace(/\\(.)/g, "$1");
+}
+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, expectedTools);
+		return {
+			...probe,
+			detail: `${candidate.label}: ${probe.detail}`
+		};
+	}));
+	return {
+		labels: candidates.map((candidate) => candidate.label),
+		probes
+	};
+}
+function asRecord(value) {
+	return value && typeof value === "object" ? value : void 0;
+}
+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 apiCatalog = asRecord(root?.apiCatalog);
+	const config = asRecord(root?.config);
+	const search = asRecord(root?.search);
+	const skillsDiscovery = asRecord(asRecord(root?.skills)?.discovery);
+	const mcp = asRecord(root?.mcp);
+	const agentContractFields = asRecord(asRecord(root?.agentContract)?.fields);
+	const apiRoute = isNonEmptyString(api?.docs) ? resolveDocsDiscoveryApiRoute(api.docs) : void 0;
+	return Boolean(root && isNonEmptyString(root.version) && isNonEmptyString(root.name) && isNonEmptyString(root.baseUrl) && isNonEmptyString(site?.entry) && typeof capabilities?.search === "boolean" && typeof capabilities?.mcp === "boolean" && capabilities?.apiCatalog === true && capabilities?.agentSkillsDiscovery === true && apiRoute && api?.docs === apiRoute && api?.config === `${apiRoute}?format=config` && api?.apiCatalog === DEFAULT_API_CATALOG_ROUTE && api?.apiCatalogQuery === `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}` && api?.agentSkillsIndex === DEFAULT_AGENT_SKILLS_INDEX_ROUTE && apiCatalog?.enabled === true && apiCatalog?.route === DEFAULT_API_CATALOG_ROUTE && apiCatalog?.api === `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}` && apiCatalog?.mediaType === API_CATALOG_MEDIA_TYPE && apiCatalog?.profile === API_CATALOG_PROFILE_URI && skillsDiscovery?.schema === AGENT_SKILLS_DISCOVERY_SCHEMA_URI && skillsDiscovery?.index === DEFAULT_AGENT_SKILLS_INDEX_ROUTE && skillsDiscovery?.artifact === DEFAULT_AGENT_SKILLS_ROUTE_PATTERN && skillsDiscovery?.apiIndex === `${apiRoute}?format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}` && skillsDiscovery?.apiArtifact === `${apiRoute}?format=${DEFAULT_AGENT_SKILL_FORMAT}&name={name}` && skillsDiscovery?.digest === "sha256" && config?.endpoint === `${apiRoute}?format=config` && typeof search?.enabled === "boolean" && isNonEmptyString(search?.endpoint) && typeof mcp?.enabled === "boolean" && isNonEmptyString(mcp?.endpoint) && isBooleanRecord(mcp?.tools) && agentContractFields && Object.keys(agentContractFields).length > 0);
+}
+function responseMediaType(contentType) {
+	return contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function contentTypeParameter(contentType, name) {
+	if (!contentType) return void 0;
+	const parameterPattern = new RegExp(`(?:^|;)\\s*${name.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\s*=\\s*(?:"([^"]*)"|([^;\\s]+))`, "i");
+	const match = contentType.match(parameterPattern);
+	return match?.[1] ?? match?.[2];
+}
+function isApiCatalogLinkset(value) {
+	const root = asRecord(value);
+	if (!Array.isArray(root?.linkset) || root.linkset.length === 0) return false;
+	let apiLinks = 0;
+	for (const rawContext of root.linkset) {
+		const context = asRecord(rawContext);
+		if (!isNonEmptyString(context?.anchor)) return false;
+		if (!Array.isArray(context.item)) continue;
+		for (const rawItem of context.item) {
+			if (!isNonEmptyString(asRecord(rawItem)?.href)) return false;
+			apiLinks += 1;
+		}
+	}
+	return apiLinks > 0;
+}
+async function probeApiCatalogRoute(baseUrl) {
+	const route = DEFAULT_API_CATALOG_ROUTE;
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const [getResponse, headResponse] = await Promise.all([fetchWithTimeout(url, { headers: { Accept: API_CATALOG_MEDIA_TYPE } }), fetchWithTimeout(url, {
+			method: "HEAD",
+			headers: { Accept: API_CATALOG_MEDIA_TYPE }
+		})]);
+		const text = await getResponse.text().catch(() => "");
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			body = void 0;
+		}
+		const failures = [];
+		if (!getResponse.ok) failures.push(`GET returned HTTP ${getResponse.status}`);
+		if (!headResponse.ok) failures.push(`HEAD returned HTTP ${headResponse.status}`);
+		for (const [method, response] of [["GET", getResponse], ["HEAD", headResponse]]) {
+			const contentType = response.headers.get("content-type");
+			if (responseMediaType(contentType) !== API_CATALOG_MEDIA_TYPE) failures.push(`${method} Content-Type is ${JSON.stringify(contentType ?? "<missing>")}`);
+			else if (contentTypeParameter(contentType, "profile") !== API_CATALOG_PROFILE_URI) failures.push(`${method} Content-Type is missing the RFC 9727 profile`);
+			if (!httpLinkHeaderHasTargetRelation(response.headers.get("link"), DEFAULT_API_CATALOG_ROUTE, "api-catalog", url)) failures.push(`${method} is missing an ${DEFAULT_API_CATALOG_ROUTE} rel="api-catalog" Link value`);
+		}
+		if (!isApiCatalogLinkset(body)) failures.push("GET did not return a JSON Linkset with at least one API item");
+		return failures.length === 0 ? {
+			ok: true,
+			detail: `${route} passed RFC 9727 GET and HEAD checks with a profiled JSON Linkset and api-catalog Link headers.`
+		} : {
+			ok: false,
+			detail: `${route} failed standards validation: ${failures.join("; ")}.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+function isValidAgentSkillEntry(value) {
+	const entry = asRecord(value);
+	return Boolean(entry && typeof entry.name === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(entry.name) && entry.name.length <= 64 && (entry.type === "skill-md" || entry.type === "archive") && isNonEmptyString(entry.description) && entry.description.length <= 1024 && isNonEmptyString(entry.url) && typeof entry.digest === "string" && /^sha256:[0-9a-f]{64}$/u.test(entry.digest));
+}
+async function probeAgentSkillsDiscovery(baseUrl) {
+	const route = DEFAULT_AGENT_SKILLS_INDEX_ROUTE;
+	const indexUrl = joinDoctorUrl(baseUrl, route);
+	try {
+		const [indexResponse, indexHeadResponse] = await Promise.all([fetchWithTimeout(indexUrl, { headers: { Accept: "application/json" } }), fetchWithTimeout(indexUrl, {
+			method: "HEAD",
+			headers: { Accept: "application/json" }
+		})]);
+		const text = await indexResponse.text().catch(() => "");
+		const failures = [];
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			body = void 0;
+		}
+		if (!indexResponse.ok) failures.push(`index returned HTTP ${indexResponse.status}`);
+		if (!indexHeadResponse.ok) failures.push(`index HEAD returned HTTP ${indexHeadResponse.status}`);
+		if (responseMediaType(indexResponse.headers.get("content-type")) !== "application/json") failures.push("index Content-Type is not application/json");
+		if (responseMediaType(indexHeadResponse.headers.get("content-type")) !== "application/json") failures.push("index HEAD Content-Type is not application/json");
+		const root = asRecord(body);
+		if (root?.$schema !== AGENT_SKILLS_DISCOVERY_SCHEMA_URI) failures.push("index $schema is not the Agent Skills discovery 0.2.0 schema");
+		const skills = Array.isArray(root?.skills) ? root.skills : [];
+		if (skills.length === 0) failures.push("index does not publish any skills");
+		if (skills.length > 100) failures.push("index publishes more than 100 skills");
+		const validSkills = skills.filter(isValidAgentSkillEntry);
+		if (validSkills.length !== skills.length) failures.push("one or more index entries have invalid name, type, description, URL, or digest fields");
+		if (new Set(validSkills.map((skill) => skill.name)).size !== validSkills.length) failures.push("index contains duplicate skill names");
+		const baseOrigin = new URL(baseUrl).origin;
+		const artifactDetails = [];
+		if (skills.length <= 100) for (const skill of validSkills) {
+			let artifactUrl;
+			try {
+				artifactUrl = new URL(skill.url, indexUrl);
+			} catch {
+				failures.push(`${skill.name} has an invalid artifact URL`);
+				continue;
+			}
+			const expectedPath = skill.type === "archive" ? `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/${skill.name}.tar.gz` : DEFAULT_AGENT_SKILLS_ROUTE_PATTERN.replace("{name}", skill.name);
+			const expectedMediaType = skill.type === "archive" ? "application/gzip" : "text/markdown";
+			if (artifactUrl.origin !== baseOrigin) {
+				failures.push(`${skill.name} artifact is not same-origin`);
+				continue;
+			}
+			if (!artifactUrl.pathname.endsWith(expectedPath)) {
+				failures.push(`${skill.name} artifact URL does not match ${expectedPath}`);
+				continue;
+			}
+			try {
+				const [artifactResponse, artifactHeadResponse] = await Promise.all([fetchWithTimeout(artifactUrl.toString(), { headers: { Accept: expectedMediaType } }), fetchWithTimeout(artifactUrl.toString(), {
+					method: "HEAD",
+					headers: { Accept: expectedMediaType }
+				})]);
+				const content = Buffer.from(await artifactResponse.arrayBuffer());
+				const computedDigest = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+				if (!artifactResponse.ok) failures.push(`${skill.name} artifact returned HTTP ${artifactResponse.status}`);
+				else if (!artifactHeadResponse.ok) failures.push(`${skill.name} artifact HEAD returned HTTP ${artifactHeadResponse.status}`);
+				else if (responseMediaType(artifactResponse.headers.get("content-type")) !== expectedMediaType) failures.push(`${skill.name} artifact Content-Type is not ${expectedMediaType}`);
+				else if (responseMediaType(artifactHeadResponse.headers.get("content-type")) !== expectedMediaType) failures.push(`${skill.name} artifact HEAD Content-Type is not ${expectedMediaType}`);
+				else if (content.length === 0) failures.push(`${skill.name} artifact is empty`);
+				else if (computedDigest !== skill.digest) failures.push(`${skill.name} artifact digest does not match the index`);
+				else artifactDetails.push(`${skill.name} digest verified`);
+			} catch (error) {
+				failures.push(`${skill.name} artifact failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return failures.length === 0 ? {
+			ok: true,
+			detail: `${route} returned a valid Agent Skills index; ${artifactDetails.join(", ")}.`
+		} : {
+			ok: false,
+			detail: `${route} failed standards validation: ${failures.join("; ")}.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+function readDiscoveryRoute(value) {
+	return typeof value === "string" && value.startsWith("/") ? value : void 0;
+}
+function hostedSitemapRoutes(discoveryBody) {
+	const sitemap = asRecord(asRecord(discoveryBody)?.sitemap);
+	if (sitemap?.enabled === false) return {
+		enabled: false,
+		routes: []
+	};
+	const xml = asRecord(sitemap?.xml);
+	const markdown = asRecord(sitemap?.markdown);
+	const routes = [
+		xml?.enabled === false ? void 0 : readDiscoveryRoute(xml?.route) ?? DEFAULT_SITEMAP_XML_ROUTE,
+		markdown?.enabled === false ? void 0 : readDiscoveryRoute(markdown?.route) ?? DEFAULT_SITEMAP_MD_ROUTE,
+		markdown?.enabled === false ? void 0 : readDiscoveryRoute(markdown?.docsRoute),
+		markdown?.enabled === false ? void 0 : readDiscoveryRoute(markdown?.wellKnownRoute) ?? DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE
+	].filter((route) => typeof route === "string");
+	return {
+		enabled: true,
+		routes: Array.from(new Set(routes))
+	};
+}
+function hostedRobotsRoute(discoveryBody) {
+	const robots = asRecord(asRecord(discoveryBody)?.robots);
+	return {
+		enabled: robots?.enabled === false ? false : true,
+		route: readDiscoveryRoute(robots?.route) ?? DEFAULT_ROBOTS_TXT_ROUTE
+	};
+}
+function hostedMcpRoutes(discoveryBody) {
+	const mcp = asRecord(asRecord(discoveryBody)?.mcp);
+	const publicEndpoints = mcp?.publicEndpoints ?? mcp?.endpoints;
+	const declaredRoutes = Array.isArray(publicEndpoints) ? publicEndpoints.filter((value) => typeof value === "string" && value.startsWith("/")) : [];
+	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];
+	if (typeof capability === "boolean") return capability;
+	const enabled = asRecord(root?.[key])?.enabled;
+	return typeof enabled === "boolean" ? enabled : void 0;
+}
+function hostedRootDocsRoute(discoveryBody) {
+	const site = asRecord(asRecord(discoveryBody)?.site);
+	return `/${(typeof site?.entry === "string" && site.entry.trim() ? site.entry.trim() : "docs").replace(/^\/+|\/+$/g, "") || "docs"}`;
+}
+function hostedPageUrl(baseUrl, pageRoute) {
+	try {
+		const base = new URL(baseUrl);
+		const parsed = new URL(pageRoute, base.origin);
+		if (parsed.origin !== base.origin) return void 0;
+		parsed.hash = "";
+		parsed.search = "";
+		const basePath = base.pathname.replace(/\/+$/, "");
+		const pagePath = parsed.pathname.replace(/\/+$/, "") || "/";
+		const pathname = !basePath || pagePath === basePath || pagePath.startsWith(`${basePath}/`) ? pagePath : `${basePath}${pagePath}`;
+		return new URL(pathname || "/", base.origin).toString().replace(/\/+$/, "");
+	} catch {
+		return;
+	}
+}
+function sampleHostedPageUrls(baseUrl, discoveryBody, pages, limit = 10) {
+	const pageRoutes = pages.map((page) => page.url).filter((route) => route.startsWith("/") && !route.endsWith(".md"));
+	const fallback = hostedRootDocsRoute(discoveryBody);
+	const unique = Array.from(new Set(pageRoutes.length > 0 ? pageRoutes : [fallback])).sort();
+	return (unique.length <= limit ? unique : Array.from({ length: limit }, (_, index) => unique[Math.floor(index * (unique.length / limit))])).map((route) => hostedPageUrl(baseUrl, route)).filter((url) => typeof url === "string");
+}
+async function probeHostedHtmlPage(url) {
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "text/html, */*" } });
+		const body = await response.text().catch(() => "");
+		const pathname = new URL(url).pathname;
+		if (!response.ok) return {
+			ok: false,
+			detail: `${pathname} returned HTTP ${response.status}.`,
+			hasJsonLd: false,
+			hasMarkdownAlternate: false
+		};
+		const alternateUrl = resolveMarkdownAlternateUrl(markdownAlternateHref(body), url);
+		return {
+			ok: true,
+			detail: `${pathname} returned HTML with ${body.length} characters.`,
+			hasJsonLd: hasJsonLdScript(body),
+			hasMarkdownAlternate: Boolean(alternateUrl)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${url} failed: ${error instanceof Error ? error.message : String(error)}.`,
+			hasJsonLd: false,
+			hasMarkdownAlternate: false
+		};
+	}
+}
+function hostedSurfaceScore(probes, predicate) {
+	const total = probes.length;
+	const passed = probes.filter((probe) => probe.ok && predicate(probe)).length;
+	if (total === 0) return {
+		status: "warn",
+		score: 0,
+		passed: 0,
+		total
+	};
+	if (passed === total) return {
+		status: "pass",
+		score: 5,
+		passed,
+		total
+	};
+	if (passed > 0) return {
+		status: "warn",
+		score: Math.round(passed / total * 5),
+		passed,
+		total
+	};
+	return {
+		status: "fail",
+		score: 0,
+		passed,
+		total
+	};
+}
+async function buildHostedAgentChecks(url, pages) {
+	let baseUrl;
+	try {
+		baseUrl = normalizeDoctorBaseUrl(url);
+	} catch (error) {
+		return { checks: [makeCheck("hosted-url", "Hosted URL", "fail", 0, 5, `Could not parse --url "${url}": ${error instanceof Error ? error.message : String(error)}`, "Pass a full hosted URL such as https://docs.example.com.")] };
+	}
+	const checks = [];
+	const discovery = await probeJsonRoute(baseUrl, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE);
+	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 [apiCatalog, agentSkills] = await Promise.all([probeApiCatalogRoute(baseUrl), probeAgentSkillsDiscovery(baseUrl)]);
+	checks.push(makeCheck("hosted-api-catalog", "Hosted RFC 9727 API catalog", apiCatalog.ok ? "pass" : "fail", apiCatalog.ok ? 5 : 0, 5, apiCatalog.detail, apiCatalog.ok ? void 0 : `Publish ${DEFAULT_API_CATALOG_ROUTE} with GET and HEAD support, the profiled ${API_CATALOG_MEDIA_TYPE} content type, a rel="api-catalog" Link header, and API links.`));
+	checks.push(makeCheck("hosted-agent-skills", "Hosted Agent Skills discovery", agentSkills.ok ? "pass" : "fail", agentSkills.ok ? 5 : 0, 5, agentSkills.detail, agentSkills.ok ? void 0 : `Publish ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} and make every indexed SKILL.md artifact match its declared SHA-256 digest.`));
+	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."));
+	const sitemapRoutes = hostedSitemapRoutes(discovery.body);
+	if (sitemapRoutes.enabled && sitemapRoutes.routes.length > 0) {
+		const sitemap = await Promise.all(sitemapRoutes.routes.map((route) => probeTextRoute(baseUrl, route)));
+		const sitemapPassed = sitemap.filter((result) => result.ok).length;
+		checks.push(makeCheck("hosted-sitemap", "Hosted sitemap", sitemapPassed === sitemap.length ? "pass" : sitemapPassed > 0 ? "warn" : "fail", sitemapPassed === sitemap.length ? 5 : sitemapPassed > 0 ? 3 : 0, 5, sitemap.map((result) => result.detail).join(" "), sitemapPassed === sitemap.length ? void 0 : `Verify deployed sitemap routes return non-empty text: ${sitemapRoutes.routes.join(", ")}.`));
+	} else if (sitemapRoutes.enabled) checks.push(makeCheck("hosted-sitemap", "Hosted sitemap", "warn", 0, 5, "The hosted discovery spec reports sitemap support but did not expose sitemap routes.", "Check sitemap.xml and sitemap.markdown config so at least one sitemap route is enabled."));
+	else checks.push(makeCheck("hosted-sitemap", "Hosted sitemap", "warn", 0, 5, "The hosted discovery spec reports sitemap routes as disabled.", "Enable sitemap in docs.config when agents and crawlers should discover canonical URLs and freshness metadata."));
+	const robotsRoute = hostedRobotsRoute(discovery.body);
+	if (robotsRoute.enabled) {
+		const robots = await probeRobotsRoute(baseUrl, robotsRoute.route);
+		const robotsAnalysis = robots.body ? analyzeDocsRobotsTxt(robots.body) : void 0;
+		const robotsBlocked = robotsAnalysis?.blocksAgentRoutes || robotsAnalysis?.blocksAiAgents;
+		const robotsComplete = robotsAnalysis?.hasAgentRoutes && robotsAnalysis?.hasAiPolicy;
+		checks.push(makeCheck("hosted-robots", "Hosted robots.txt", robots.ok && !robotsBlocked && robotsComplete ? "pass" : robots.ok && !robotsBlocked ? "warn" : "fail", robots.ok && !robotsBlocked && robotsComplete ? 5 : robots.ok && !robotsBlocked ? 3 : 0, 5, robots.ok ? robotsBlocked ? `${robotsRoute.route} is reachable but blocks ${robotsAnalysis?.blocksAiAgents ? "common AI crawlers" : "agent-readable docs routes"}.` : robotsComplete ? `${robots.detail} It advertises agent-readable routes and common AI crawler policy.` : `${robots.detail} It is missing ${robotsAnalysis?.missingRoutes.length ? `agent routes (${robotsAnalysis.missingRoutes.join(", ")})` : "common AI crawler policy"}.` : robots.detail, robots.ok && !robotsBlocked && robotsComplete ? void 0 : "Publish an agent-friendly robots.txt with `docs robots generate`, or append the generated block to the existing file."));
+	} else checks.push(makeCheck("hosted-robots", "Hosted robots.txt", "warn", 0, 5, "The hosted discovery spec reports robots.txt as disabled.", "Enable robots and publish an agent-friendly robots.txt with `docs robots generate`."));
+	const skill = await Promise.all([probeTextRoute(baseUrl, DEFAULT_SKILL_MD_ROUTE), probeTextRoute(baseUrl, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE)]);
+	const skillPassed = skill.filter((result) => result.ok).length;
+	checks.push(makeCheck("hosted-skill", "Hosted skill.md", skillPassed === skill.length ? "pass" : skillPassed > 0 ? "warn" : "fail", skillPassed === skill.length ? 5 : skillPassed > 0 ? 3 : 0, 5, skill.map((result) => result.detail).join(" "), skillPassed === skill.length ? void 0 : "Verify deployed /skill.md and /.well-known/skill.md routes return non-empty markdown."));
+	const agents = await Promise.all([probeTextRoute(baseUrl, DEFAULT_AGENTS_MD_ROUTE), probeTextRoute(baseUrl, DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE)]);
+	const agentsPassed = agents.filter((result) => result.ok).length;
+	checks.push(makeCheck("hosted-agents", "Hosted AGENTS.md", agentsPassed === agents.length ? "pass" : agentsPassed > 0 ? "warn" : "fail", agentsPassed === agents.length ? 5 : agentsPassed > 0 ? 3 : 0, 5, agents.map((result) => result.detail).join(" "), agentsPassed === agents.length ? void 0 : "Verify deployed /AGENTS.md and /.well-known/AGENTS.md routes return non-empty markdown."));
+	const markdownRoute = toMarkdownRoute(pages[0]?.url);
+	if (markdownRoute) {
+		const markdownPageUrl = pages[0]?.url ? joinDoctorUrl(baseUrl, pages[0].url) : void 0;
+		const markdownResponseUrl = joinDoctorUrl(baseUrl, markdownRoute);
+		const markdown = await probeTextRoute(baseUrl, markdownRoute);
+		checks.push(makeCheck("hosted-markdown", "Hosted markdown route", markdown.ok ? "pass" : "fail", markdown.ok ? 5 : 0, 5, markdown.detail, markdown.ok ? void 0 : `Verify deployed markdown routes are forwarded, starting with ${markdownRoute}.`));
+		const hasCanonicalHeader = markdown.ok && markdownPageUrl ? hasCanonicalLinkHeader(markdown.linkHeader, markdownPageUrl, markdownResponseUrl) : false;
+		checks.push(makeCheck("hosted-markdown-canonical", "Hosted markdown canonical header", hasCanonicalHeader ? "pass" : "warn", hasCanonicalHeader ? 1 : 0, 1, markdown.ok ? hasCanonicalHeader ? `${markdownRoute} includes a canonical Link header pointing to ${pages[0]?.url}.` : `${markdownRoute} is reachable but is missing a canonical Link response header.` : markdown.detail, hasCanonicalHeader ? void 0 : "Return `Link: <canonical-page-url>; rel=\"canonical\"` on successful markdown page responses so agents can cite the normal docs URL."));
+	} else {
+		checks.push(makeCheck("hosted-markdown", "Hosted markdown route", "warn", 0, 5, "No local docs page was available to choose a sample .md route.", "Add docs pages so the hosted doctor can probe a representative .md route."));
+		checks.push(makeCheck("hosted-markdown-canonical", "Hosted markdown canonical header", "warn", 0, 1, "No local docs page was available to choose a sample .md route.", "Add docs pages so the hosted doctor can probe a markdown canonical Link header."));
+	}
+	const htmlPageUrls = sampleHostedPageUrls(baseUrl, discovery.body, pages);
+	const htmlPageProbes = await Promise.all(htmlPageUrls.map((pageUrl) => probeHostedHtmlPage(pageUrl)));
+	const structuredDataScore = hostedSurfaceScore(htmlPageProbes, (probe) => probe.hasJsonLd);
+	const structuredDataEnabled = hostedCapability(discovery.body, "structuredData");
+	checks.push(makeCheck("hosted-structured-data", "Hosted structured data", structuredDataEnabled === false ? "warn" : structuredDataScore.status, structuredDataEnabled === false ? 0 : structuredDataScore.score, 5, structuredDataEnabled === false ? "The hosted discovery spec reports structured data as disabled." : structuredDataScore.total > 0 ? `${structuredDataScore.passed}/${structuredDataScore.total} sampled hosted docs pages include application/ld+json structured data.` : "No hosted docs pages were available to verify application/ld+json structured data.", structuredDataEnabled === false || structuredDataScore.status === "pass" ? void 0 : "Keep JSON-LD enabled on every docs page so agents can read canonical title, description, URL, breadcrumbs, and freshness hints."));
+	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."));
+	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
+	};
+}
+function makeCheck(id, title, status, score, maxScore, detail, recommendation) {
+	return {
+		id,
+		title,
+		status,
+		score,
+		maxScore,
+		detail,
+		recommendation
+	};
+}
+async function inspectAgentReadiness(options = {}) {
+	const rootDir = process.cwd();
+	const files = listProjectFiles(rootDir);
+	const framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
+	const configCheckMax = 10;
+	let configPath;
+	try {
+		configPath = resolveDocsConfigPath(rootDir, options.configPath);
+	} catch (error) {
+		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, error instanceof Error ? error.message : String(error), "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
+		return {
+			mode: "agent",
+			framework,
+			score: 0,
+			maxScore: 100,
+			grade: gradeForAgentScore(0),
+			checks,
+			coverage: {
+				totalPages: 0,
+				pagesWithAgentFiles: 0,
+				pagesWithAgentBlocks: 0,
+				explicitPages: 0,
+				explicitCoverage: 0,
+				compaction: {
+					freshGeneratedPages: 0,
+					staleGeneratedPages: 0,
+					modifiedGeneratedPages: 0,
+					unknownGeneratedPages: 0,
+					tokenBudgetMissingPages: 0,
+					otherMissingPages: 0
+				}
+			},
+			recommendations: checks.map((check) => check.recommendation).filter(Boolean)
+		};
+	}
+	const configContent = readFileSync(configPath, "utf-8");
+	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;
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const staticExport = resolveStaticExport(config, configContent);
+	const llmsEnabled = resolveFeatureEnabled(config, configContent, "llmsTxt");
+	const searchEnabled = resolveFeatureEnabled(config, configContent, "search");
+	const mcpEnabled = resolveFeatureEnabled(config, configContent, "mcp");
+	const agentFeedbackEnabled = resolveAgentFeedbackEnabled(config, configContent);
+	const compactConfigured = hasAgentCompactDefaults(config, configContent);
+	const skillFileExists = existsSync(path.join(rootDir, "skill.md"));
+	const agentsFileExists = existsSync(path.join(rootDir, "AGENTS.md")) || existsSync(path.join(rootDir, "AGENT.md"));
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle,
+		ordering
+	});
+	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 evaluation = resolveGoldenEvaluationInput(evaluationInput);
+	const evaluationBaseUrl = config ? resolveDocsMetadataBaseUrl(config) : void 0;
+	const evaluationMcp = resolveDocsMcpConfig(config?.mcp, { defaultName: siteTitle });
+	const askAISearch = resolveAskAISearchRequestConfig({
+		search: config?.search,
+		useMcp: config?.ai?.useMcp,
+		mcpEndpoint: evaluationMcp.route,
+		mcpEnabled: evaluationMcp.enabled,
+		mcpSearchEnabled: evaluationMcp.tools.searchDocs,
+		requestUrl: evaluationBaseUrl
+	});
+	const evaluations = await runDocsGoldenTasks(pages, evaluation.tasks, {
+		...evaluation.options,
+		search: config?.search,
+		askAISearch,
+		siteTitle,
+		baseUrl: evaluationBaseUrl,
+		rootDir,
+		codeBlocksValidate: config?.codeBlocks?.validate
+	});
+	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);
+	const robotsInput = config?.robots ?? readRobotsConfigFromStatic(configContent) ?? true;
+	const robotsConfig = robotsInput === false ? resolveDocsRobotsConfig(false) : resolveDocsRobotsConfig(robotsInput, { baseUrl: (typeof robotsInput === "object" ? robotsInput.baseUrl : void 0) ?? sitemapConfig.baseUrl });
+	const robotsPath = resolveRobotsFilePath(rootDir, framework, typeof robotsInput === "object" ? robotsInput : void 0);
+	const feedbackRoute = DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const feedbackSchemaRoute = `${feedbackRoute}/schema`;
+	const apiRoute = resolveDocsDiscoveryApiRoute(config?.cloud?.apiRoute);
+	const discovery = buildDocsAgentDiscoverySpec({
+		origin: "http://localhost",
+		entry,
+		apiRoute,
+		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 === "mcp" || optionPath.startsWith("mcp.") || optionPath === "review" || optionPath.startsWith("review.")) : [];
+	const expectedMcpProtectedResource = mcpConfig.enabled && mcpConfig.security?.authenticate && mcpConfig.security.protectedResource ? {
+		metadataEndpoints: [...getDocsMcpProtectedResourceMetadataRoutes(mcpConfig.route)],
+		authorizationServers: mcpConfig.security.protectedResource.authorizationServers,
+		scopesSupported: mcpConfig.security.protectedResource.scopesSupported,
+		requiredScopes: mcpConfig.security.protectedResource.requiredScopes
+	} : null;
+	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: `${apiRoute}?query={query}`
+			},
+			mcp: {
+				enabled: mcpConfig.enabled,
+				endpoint: mcpConfig.route,
+				tools: mcpConfig.tools,
+				protectedResource: expectedMcpProtectedResource
+			},
+			routes: {
+				"api.docs": apiRoute,
+				"api.config": `${apiRoute}?format=config`,
+				"api.apiCatalog": DEFAULT_API_CATALOG_ROUTE,
+				"api.apiCatalogQuery": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+				"api.agentSkillsIndex": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+				"apiCatalog.route": DEFAULT_API_CATALOG_ROUTE,
+				"apiCatalog.api": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+				"config.endpoint": `${apiRoute}?format=config`,
+				"skills.discovery.index": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+				"skills.discovery.artifact": DEFAULT_AGENT_SKILLS_ROUTE_PATTERN,
+				"skills.discovery.apiIndex": `${apiRoute}?format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}`,
+				"skills.discovery.apiArtifact": `${apiRoute}?format=${DEFAULT_AGENT_SKILL_FORMAT}&name={name}`
+			}
+		}
+	});
+	const checks = [];
+	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 (including API catalog and Agent Skills routes), 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."));
+	checks.push(makeCheck("public-routes", "Public agent routes", routeSurface.publicMounted ? "pass" : "fail", routeSurface.publicMounted ? 10 : 0, 10, routeSurface.publicDetail, routeSurface.publicMounted ? void 0 : "Add the framework public forwarder so /.well-known/api-catalog, /.well-known/agent-skills/*, the other /.well-known/* resources, /llms.txt, /sitemap.xml, /sitemap.md, /docs/sitemap.md, /AGENTS.md, /skill.md, /mcp, and .md routes resolve from the shared docs API."));
+	checks.push(makeCheck("agent-discovery", "Agent discovery spec", routeSurface.apiMounted && routeSurface.publicMounted ? "pass" : "fail", routeSurface.apiMounted && routeSurface.publicMounted ? 5 : 0, 5, routeSurface.apiMounted && routeSurface.publicMounted ? `Expected discovery endpoints are available through ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}, ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}, ${DEFAULT_API_CATALOG_ROUTE}, ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}, and /api/docs?agent=spec.` : "Could not verify the shared agent discovery spec endpoints because docs API/public route wiring is incomplete.", routeSurface.apiMounted && routeSurface.publicMounted ? void 0 : "Make sure both the docs API handler and public docs forwarder expose the custom agent manifest, RFC 9727 API catalog, and Agent Skills discovery routes."));
+	checks.push(llmsEnabled ? makeCheck("llms", "llms.txt discovery", "pass", 5, 5, `Enabled via ${DEFAULT_LLMS_TXT_ROUTE} and ${DEFAULT_LLMS_FULL_TXT_ROUTE}.`) : makeCheck("llms", "llms.txt discovery", "warn", 0, 5, `${DEFAULT_LLMS_TXT_ROUTE} and ${DEFAULT_LLMS_FULL_TXT_ROUTE} are disabled in docs config.`, "Enable llmsTxt so agents and GEO crawlers can discover the docs index and full context surfaces."));
+	checks.push(sitemapConfig.enabled ? makeCheck("sitemap", "Sitemap discovery", "pass", 5, 5, `Enabled via ${[
+		sitemapConfig.xml.route,
+		sitemapConfig.markdown.route,
+		sitemapConfig.markdown.docsRoute,
+		sitemapConfig.markdown.wellKnownRoute
+	].filter(Boolean).join(", ")}.`) : makeCheck("sitemap", "Sitemap discovery", "warn", 0, 5, "Generated sitemap routes are disabled in docs config.", "Enable sitemap so crawlers and agents can discover canonical docs URLs, semantic sections, and lastmod freshness metadata."));
+	const relativeRobotsPath = path.relative(rootDir, robotsPath).replace(/\\/g, "/");
+	if (!robotsConfig.enabled) checks.push(makeCheck("robots", "Robots agent policy", "warn", 0, 5, "Robots generation is disabled in docs config.", "Enable robots and run `docs robots generate` so crawlers can discover agent-readable docs routes."));
+	else if (!existsSync(robotsPath)) if (routeSurface.apiMounted && routeSurface.publicMounted && !staticExport) checks.push(makeCheck("robots", "Robots agent policy", "pass", 5, 5, "Runtime /robots.txt is served by the shared docs handler."));
+	else checks.push(makeCheck("robots", "Robots agent policy", "warn", 0, 5, `No robots.txt found at ${relativeRobotsPath}.`, `Run docs robots generate --path ${relativeRobotsPath} to publish an agent-friendly crawl policy.`));
+	else {
+		const analysis = analyzeDocsRobotsTxt(readFileSync(robotsPath, "utf-8"), {
+			entry,
+			sitemap: sitemapConfig,
+			baseUrl: robotsConfig.baseUrl,
+			robots: robotsConfig
+		});
+		const blocked = analysis.blocksAgentRoutes || analysis.blocksAiAgents;
+		const complete = analysis.hasAgentRoutes && analysis.hasAiPolicy;
+		checks.push(makeCheck("robots", "Robots agent policy", blocked ? "fail" : complete ? "pass" : "warn", blocked ? 0 : complete ? 5 : 3, 5, blocked ? `${relativeRobotsPath} blocks ${analysis.blocksAiAgents ? "common AI crawlers" : "agent-readable docs routes"}.` : complete ? `${relativeRobotsPath} advertises agent-readable routes and common AI crawler policy.` : `${relativeRobotsPath} exists, but is missing ${analysis.missingRoutes.length > 0 ? `agent routes (${analysis.missingRoutes.join(", ")})` : "common AI crawler policy"}.`, blocked || !complete ? `Run docs robots generate --append --path ${relativeRobotsPath} to add the generated agent policy without replacing the existing file.` : void 0));
+	}
+	checks.push(skillFileExists ? makeCheck("skill", "Skill document", "pass", 5, 5, `Found root skill.md for ${DEFAULT_SKILL_MD_ROUTE} and ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}.`) : makeCheck("skill", "Skill document", "pass", 5, 5, `No root skill.md found; the framework will serve the generated fallback at ${DEFAULT_SKILL_MD_ROUTE}.`));
+	checks.push(agentsFileExists ? makeCheck("agents", "Agent instructions", "pass", 5, 5, `Found root AGENTS.md/AGENT.md for ${DEFAULT_AGENTS_MD_ROUTE} and ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}.`) : makeCheck("agents", "Agent instructions", "pass", 5, 5, `No root AGENTS.md found; the framework will serve the generated fallback at ${DEFAULT_AGENTS_MD_ROUTE}.`));
+	checks.push(mcpEnabled ? makeCheck("mcp", "MCP access", "pass", 10, 10, `Enabled with public aliases ${DEFAULT_MCP_PUBLIC_ROUTE} and ${DEFAULT_MCP_WELL_KNOWN_ROUTE} (canonical route ${mcpConfig.route}).`) : makeCheck("mcp", "MCP access", "warn", 0, 10, "MCP is disabled in docs config.", "Enable mcp so agents can use list/search/read tools directly instead of only scraping markdown routes."));
+	checks.push(searchEnabled ? makeCheck("search", "Search surface", "pass", 5, 5, "Search is enabled for the shared docs API and agent flows.") : makeCheck("search", "Search surface", "warn", 0, 5, "Search is disabled in docs config.", "Enable search so agents can narrow retrieval before reading whole markdown pages."));
+	checks.push(agentFeedbackEnabled ? makeCheck("feedback", "Agent feedback", "pass", 5, 5, `Structured agent feedback is enabled at ${feedbackRoute} with schema ${feedbackSchemaRoute}.`) : makeCheck("feedback", "Agent feedback", "warn", 0, 5, "Structured agent feedback is not enabled.", "Enable feedback.agent if you want agents to discover and post feedback through the shared docs API."));
+	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", "Audience-tailored page optimization", coverageResult.status, coverageResult.score, 10, coverage.totalPages > 0 ? `${coverage.explicitPages}/${coverage.totalPages} pages define audience-tailored context (${coverage.pagesWithAgentFiles} page${coverage.pagesWithAgentFiles === 1 ? "" : "s"} with agent.md, ${coverage.pagesWithAgentBlocks} page${coverage.pagesWithAgentBlocks === 1 ? "" : "s"} with embedded audience projections, ${coverage.explicitCoverage}% of pages).` : "No docs pages were available to score audience-tailored page optimization.", coverage.explicitCoverage >= 50 ? void 0 : "Add agent.md files or audience primitives such as <Agent>, <Human>, or <Audience only=\"agent\"> 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-only blocks are specific and non-repetitive (${usefulness.metrics.agentBlocks.duplicate} duplicate, ${usefulness.metrics.agentBlocks.boilerplate} boilerplate, ${usefulness.metrics.agentBlocks.generic} generic).` : "No embedded agent-only 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-only 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));
+	return {
+		mode: "agent",
+		framework,
+		configPath: path.relative(rootDir, configPath).replace(/\\/g, "/"),
+		entry,
+		contentDir,
+		url: hosted?.baseUrl,
+		score,
+		maxScore,
+		grade: gradeForAgentScore(score, checks),
+		checks,
+		coverage,
+		usefulness: usefulness.metrics,
+		evaluations,
+		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
+	};
+}
+async function inspectHumanReadiness(options = {}) {
+	const rootDir = process.cwd();
+	const files = listProjectFiles(rootDir);
+	const framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
+	const configCheckMax = 10;
+	let configPath;
+	try {
+		configPath = resolveDocsConfigPath(rootDir, options.configPath);
+	} catch (error) {
+		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, error instanceof Error ? error.message : String(error), "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
+		return {
+			mode: "human",
+			framework,
+			score: 0,
+			maxScore: 100,
+			grade: gradeForHumanScore(0),
+			checks,
+			coverage: {
+				totalPages: 0,
+				describedPages: 0,
+				descriptionCoverage: 0,
+				longPages: 0,
+				structuredLongPages: 0,
+				structureCoverage: 0,
+				navigationPages: 0
+			},
+			recommendations: checks.map((check) => check.recommendation).filter(Boolean)
+		};
+	}
+	const configContent = readFileSync(configPath, "utf-8");
+	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;
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const searchEnabled = resolveFeatureEnabled(config, configContent, "search");
+	const humanFeedbackEnabled = resolveHumanFeedbackEnabled(config, configContent);
+	const lastUpdatedEnabled = resolveLastUpdatedEnabled(config, configContent);
+	const githubEnabled = hasGithubIntegration(config, configContent);
+	const readingTimeEnabled = hasReadingTimeSurface(config, configContent);
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle,
+		ordering
+	});
+	const coverage = buildHumanCoverage(await Promise.resolve(source.getPages()), countNavigationPages(await Promise.resolve(source.getNavigation())));
+	const descriptionResult = descriptionScore(coverage.descriptionCoverage);
+	const structureResult = structureScore(coverage.structureCoverage);
+	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", 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."));
+	checks.push(makeCheck("descriptions", "Page descriptions", descriptionResult.status, descriptionResult.score, 15, coverage.totalPages > 0 ? `${coverage.describedPages}/${coverage.totalPages} pages include a description (${coverage.descriptionCoverage}% coverage).` : "No docs pages were available to score descriptions.", coverage.descriptionCoverage >= 75 ? void 0 : "Add frontmatter descriptions to more pages so readers get better search snippets, summaries, and page introductions."));
+	checks.push(makeCheck("structure", "Page structure", structureResult.status, structureResult.score, 15, coverage.longPages > 0 ? `${coverage.structuredLongPages}/${coverage.longPages} longer pages include section headings (${coverage.structureCoverage}% coverage).` : "No longer docs pages required section-heading checks.", coverage.structureCoverage >= 75 ? void 0 : "Break longer pages into clearer sections with H2/H3 headings so readers can scan and navigate without hitting a wall of text."));
+	checks.push(searchEnabled ? makeCheck("search", "Search surface", "pass", 10, 10, "Search is enabled for the docs site.") : makeCheck("search", "Search surface", "warn", 0, 10, "Search is disabled in docs config.", "Enable search so readers can jump directly to the right page instead of relying only on sidebar browsing."));
+	const trustScore = (githubEnabled ? 5 : 0) + (lastUpdatedEnabled ? 5 : 0);
+	checks.push(makeCheck("trust", "Trust signals", trustScore === 10 ? "pass" : "warn", trustScore, 10, githubEnabled && lastUpdatedEnabled ? "Edit links and last-updated metadata are configured." : githubEnabled ? "Edit links are configured, but last-updated metadata is not enabled." : lastUpdatedEnabled ? "Last-updated metadata is enabled, but edit links are not configured." : "Edit links and last-updated metadata are not configured.", trustScore === 10 ? void 0 : "Configure GitHub edit links and/or lastUpdated so readers can trust freshness and find the source of truth faster."));
+	checks.push(humanFeedbackEnabled ? makeCheck("feedback", "Reader feedback", "pass", 5, 5, "Built-in page feedback is enabled for the docs site.") : makeCheck("feedback", "Reader feedback", "warn", 0, 5, "Built-in page feedback is not enabled.", "Enable feedback if you want readers to leave quick page-level quality signals without opening an issue."));
+	checks.push(readingTimeEnabled ? makeCheck("reading-time", "Reading-time cues", "pass", 5, 5, "Reading time is configured for the docs site.") : makeCheck("reading-time", "Reading-time cues", "warn", 0, 5, "Reading time is not enabled.", "Enable readingTime if you want readers to get a quick effort estimate before they dive into longer pages."));
+	const { score, maxScore } = normalizedDoctorScore(checks.reduce((total, check) => total + check.score, 0), checks.reduce((total, check) => total + check.maxScore, 0));
+	return {
+		mode: "human",
+		framework,
+		configPath: path.relative(rootDir, configPath).replace(/\\/g, "/"),
+		entry,
+		contentDir,
+		score,
+		maxScore,
+		grade: gradeForHumanScore(score),
+		checks,
+		coverage,
+		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
+	};
+}
+function printAgentDoctorReport(report) {
+	console.log(`${pc.bold("@farming-labs/docs doctor")} ${pc.dim("—")} ${pc.bold("agent")}`);
+	console.log();
+	console.log(`${pc.bold("Score:")} ${pc.cyan(`${report.score}%`)} ${pc.dim(`(${report.grade})`)}`);
+	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("Audience-tailored pages:")} ${report.coverage.explicitPages}/${report.coverage.totalPages} pages ${pc.dim(`(${report.coverage.explicitCoverage}%)`)}`);
+	if (report.usefulness) console.log(`${pc.bold("Useful agent-only 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();
+	for (const check of report.checks) {
+		console.log(`${formatStatus(check.status)} ${check.title} ${pc.dim(`(${check.score}/${check.maxScore})`)}`);
+		console.log(`  ${check.detail}`);
+	}
+	if (report.recommendations.length > 0) {
+		console.log();
+		console.log(pc.bold("Next steps"));
+		for (const recommendation of report.recommendations) console.log(`- ${recommendation}`);
+	}
+	console.log();
+	console.log(pc.dim(`Expected public surfaces: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}, ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_TXT_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_ROUTE}, ${DEFAULT_AGENTS_MD_ROUTE}, ${DEFAULT_SKILL_MD_ROUTE}, ${DEFAULT_MCP_PUBLIC_ROUTE}`));
+}
+function printHumanDoctorReport(report) {
+	console.log(`${pc.bold("@farming-labs/docs doctor")} ${pc.dim("—")} ${pc.bold("site")}`);
+	console.log();
+	console.log(`${pc.bold("Score:")} ${pc.cyan(`${report.score}%`)} ${pc.dim(`(${report.grade})`)}`);
+	console.log(`${pc.bold("Framework:")} ${report.framework} ${pc.dim("•")} ${pc.bold("Entry:")} ${report.entry ?? "docs"} ${pc.dim("•")} ${pc.bold("Content:")} ${report.contentDir ?? "-"}`);
+	console.log(`${pc.bold("Described pages:")} ${report.coverage.describedPages}/${report.coverage.totalPages} pages ${pc.dim(`(${report.coverage.descriptionCoverage}%)`)}`);
+	console.log();
+	for (const check of report.checks) {
+		console.log(`${formatStatus(check.status)} ${check.title} ${pc.dim(`(${check.score}/${check.maxScore})`)}`);
+		console.log(`  ${check.detail}`);
+	}
+	if (report.recommendations.length > 0) {
+		console.log();
+		console.log(pc.bold("Next steps"));
+		for (const recommendation of report.recommendations) console.log(`- ${recommendation}`);
+	}
+}
+function serializeDoctorJsonReport(report) {
+	if (report.mode === "human") return {
+		...report,
+		mode: "site"
+	};
+	return report;
+}
+function printDoctorJsonReport(report) {
+	console.log(JSON.stringify(serializeDoctorJsonReport(report), null, 2));
+}
+function hasNonPassingDoctorCheck(report) {
+	return report.checks.some((check) => check.status !== "pass");
+}
+function hasFailingDoctorCheck(report) {
+	return report.checks.some((check) => check.status === "fail");
+}
+function applyDoctorExitCode(report, options) {
+	const failOn = options.failOn ?? (options.strict ? "warn" : void 0);
+	if (!failOn) return;
+	if (failOn === "warn" ? hasNonPassingDoctorCheck(report) : hasFailingDoctorCheck(report)) process.exitCode = 1;
+}
+async function runAgentDoctorFixes(report, options) {
+	const fixes = [];
+	const compaction = report.coverage.compaction;
+	if (!(compaction.staleGeneratedPages > 0 || compaction.tokenBudgetMissingPages > 0)) {
+		if (compaction.modifiedGeneratedPages > 0 || compaction.unknownGeneratedPages > 0) fixes.push({
+			id: "agent-compact",
+			title: "agent compact",
+			status: "skipped",
+			detail: "Only modified or unknown generated agent.md files need attention; doctor --fix leaves those for manual review."
+		});
+		return fixes;
+	}
+	const runCompaction = () => compactAgentDocs({
+		configPath: options.configPath,
+		stale: true,
+		includeMissing: compaction.tokenBudgetMissingPages > 0
+	});
+	const command = `docs agent compact --stale${compaction.tokenBudgetMissingPages > 0 ? " --include-missing" : ""}`;
+	if (options.dryRun) {
+		const missingOutputDetail = compaction.tokenBudgetMissingPages > 0 ? " and create token-budget missing outputs" : "";
+		fixes.push({
+			id: "agent-compact",
+			title: "agent compact",
+			status: "skipped",
+			detail: `Dry run: would run ${command} to refresh stale generated agent.md files${missingOutputDetail}.`
+		});
+		return fixes;
+	}
+	if (options.json) {
+		const originalLog = console.log;
+		console.log = () => void 0;
+		try {
+			await runCompaction();
+		} finally {
+			console.log = originalLog;
+		}
+	} else {
+		console.log();
+		console.log(pc.bold("Applying doctor --fix"));
+		await runCompaction();
+	}
+	fixes.push({
+		id: "agent-compact",
+		title: "agent compact",
+		status: "applied",
+		detail: compaction.tokenBudgetMissingPages > 0 ? "Ran docs agent compact --stale --include-missing to refresh stale generated agent.md files and create token-budget missing outputs." : "Ran docs agent compact --stale to refresh stale generated agent.md files."
+	});
+	return fixes;
+}
+async function runDoctor(options = {}) {
+	if (options.mode === "human") {
+		if (options.fix) throw new Error("doctor --fix is currently only supported with --agent.");
+		const report = await inspectHumanReadiness(options);
+		applyDoctorExitCode(report, options);
+		if (options.json) {
+			printDoctorJsonReport(report);
+			return report;
+		}
+		printHumanDoctorReport(report);
+		return report;
+	}
+	let report = await inspectAgentReadiness(options);
+	let fixes;
+	if (options.fix) {
+		fixes = await runAgentDoctorFixes(report, options);
+		report = fixes.some((fix) => fix.status === "applied") ? {
+			...await inspectAgentReadiness(options),
+			fixes
+		} : {
+			...report,
+			fixes
+		};
+	}
+	applyDoctorExitCode(report, options);
+	if (options.json) {
+		printDoctorJsonReport(report);
+		return report;
+	}
+	printAgentDoctorReport(report);
+	return report;
+}
+
+//#endregion
+export { parseDoctorArgs, printDoctorHelp, runDoctor };