@farming-labs/docs 0.2.120 → 0.2.121

package/dist/agent.mjs

@@ -0,0 +1,2729 @@
+import { readDocsJsonBody } from "./http-body.mjs";
+import { filterDocsPagesByAccess, isDocsPageAccessAllowed } from "./access.mjs";
+import { DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN, DOCS_AI_AGENT_USER_AGENT_PATTERNS, DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN, DOCS_BOT_LIKE_USER_AGENT_PATTERN, DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN, DOCS_TRADITIONAL_BOT_USER_AGENT_PATTERNS } from "./agent-detection.mjs";
+import { normalizeDocsUrlPath, toDocsMarkdownUrl } from "./urls.mjs";
+import { resolveDocsOkfConfig, resolveDocsOkfTrustMetadata } from "./okf.mjs";
+import { DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, buildDocsMcpProtectedResourceMetadataRoute, getDocsMcpProtectedResourceMetadataRoutes, getDocsMcpResourcePaths, hasDocsMcpProtectedResourceConfig, isDocsMcpRequest } from "./mcp-auth.mjs";
+import { PAGE_AGENT_CONTRACT_FIELD_SCHEMA, renderPageAgentFrontmatterYamlLines, upsertPageAgentContractMarkdown } from "./agent-contract.mjs";
+import { renderDocsRelatedMarkdownLines } from "./related.mjs";
+import { findDocsMarkdownSection, parseDocsMarkdownSections } from "./markdown-sections.mjs";
+import { resolveDocsAudienceExposure } from "./audience-exposure.mjs";
+import { findDocsAudienceMdxIssues, resolveDocsAgentMdxContent, resolveDocsAudienceMdxContent } from "./audience.mjs";
+import { DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, resolveDocsContentChangesConfig } from "./content-changes.mjs";
+import { createDocsCacheableResponse, resolveDocsHttpDate } from "./http-cache.mjs";
+import { AGENT_SKILL_COMPATIBILITY_MAX_LENGTH, AGENT_SKILL_DESCRIPTION_MAX_LENGTH, AGENT_SKILL_FRONTMATTER_FIELDS, AGENT_SKILL_NAME_MAX_LENGTH, DocsAgentSkillFrontmatterError, isDocsAgentSkillName, parseDocsAgentSkillFrontmatter, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
+import { AGENT_SKILLS_DISCOVERY_SCHEMA_URI, API_CATALOG_MEDIA_TYPE, API_CATALOG_PROFILE_URI, DEFAULT_A2A_AGENT_CARD_FORMAT, DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_A2A_PROTOCOL_BINDING, DEFAULT_A2A_PROTOCOL_VERSION, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_FORMAT, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT, DEFAULT_AGENT_SKILL_FILE_FORMAT, DEFAULT_AGENT_SKILL_FORMAT, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT, DEFAULT_API_CATALOG_FORMAT, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, appendDocsDiscoveryLinkHeader, buildDocsA2AAgentCard, buildDocsAgentSkillsIndex, buildDocsApiCatalog, buildDocsLegacySkillsIndex, createDocsStandardsResponse, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, isDocsStandardsDiscoveryRequest, resolveDocsDiscoveryApiRoute, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, sha256DocsDiscoveryContent } from "./standards-discovery.mjs";
+import { DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, resolveDocsSitemapConfig, resolveDocsSitemapRequest } from "./sitemap.mjs";
+
+//#region src/agent.ts
+const DEFAULT_DOCS_API_ROUTE = "/api/docs";
+const DEFAULT_DOCS_CONFIG_FORMAT = "docs-config-map.v1";
+const DEFAULT_DOCS_CONFIG_ROUTE = `${DEFAULT_DOCS_API_ROUTE}?format=config`;
+const DEFAULT_DOCS_DIAGNOSTICS_FORMAT = "docs-diagnostics.v1";
+const DEFAULT_DOCS_DIAGNOSTICS_ROUTE = `${DEFAULT_DOCS_API_ROUTE}?format=diagnostics`;
+const DEFAULT_OPENAPI_SCHEMA_ROUTE = `${DEFAULT_DOCS_API_ROUTE}?format=openapi`;
+const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
+const DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE = "/.well-known/agent";
+const DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE = "/.well-known/agent.json";
+const DEFAULT_LLMS_TXT_ROUTE = "/llms.txt";
+const DEFAULT_LLMS_FULL_TXT_ROUTE = "/llms-full.txt";
+const DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms.txt";
+const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
+const DEFAULT_LLMS_TXT_MAX_CHARS = 5e4;
+const DEFAULT_SKILL_MD_ROUTE = "/skill.md";
+const DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE = "/.well-known/skill.md";
+const DEFAULT_AGENTS_MD_ROUTE = "/AGENTS.md";
+const DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE = "/.well-known/AGENTS.md";
+const DEFAULT_AGENT_MD_ROUTE = "/AGENT.md";
+const DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE = "/.well-known/AGENT.md";
+const DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE = "/robots.txt";
+const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
+const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		task: {
+			type: "string",
+			description: "Short description of what the agent was trying to do."
+		},
+		understanding: {
+			type: "string",
+			description: "How well the docs supported the task, e.g. \"partial\" or \"clear\"."
+		},
+		outcome: {
+			type: "string",
+			description: "What happened after reading the docs, e.g. \"implemented\" or \"blocked\"."
+		},
+		confidence: {
+			type: "number",
+			minimum: 0,
+			maximum: 1,
+			description: "Confidence score from 0 to 1."
+		},
+		neededCodeReading: {
+			type: "boolean",
+			description: "Whether the agent still needed to inspect repository code."
+		},
+		missingContext: {
+			type: "array",
+			items: { type: "string" },
+			description: "Important details the docs did not provide clearly enough."
+		},
+		docIssues: {
+			type: "array",
+			items: { type: "string" },
+			description: "Specific documentation problems encountered during the task."
+		},
+		suggestedImprovement: {
+			type: "string",
+			description: "Concrete suggestion for improving the docs page or examples."
+		}
+	},
+	required: ["task", "outcome"]
+};
+const DEFAULT_DOCS_DIAGNOSTICS_MCP_TOOLS = {
+	listDocs: true,
+	listPages: true,
+	listPageSections: true,
+	readPage: true,
+	readPages: true,
+	submitFeedback: true,
+	listTasks: true,
+	readTask: true,
+	searchDocs: true,
+	getNavigation: true,
+	getCodeExamples: true,
+	getConfigSchema: true,
+	getContext: true
+};
+const DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER = "Signature-Agent";
+const DOCS_MARKDOWN_SECTION_INDEX_FORMAT = "docs-markdown-sections.v2";
+const DOCS_LLMS_TXT_DIRECTIVE_LINE = "LLM index: /llms.txt";
+const DOCS_MARKDOWN_GENERATED_PREAMBLE_FIELD = "x_farming_labs_generated_preamble";
+const DOCS_MCP_SERVICE_SUBDOMAIN_LABELS = new Set([
+	"api",
+	"developer",
+	"developers",
+	"dev",
+	"docs",
+	"help",
+	"mcp",
+	"reference"
+]);
+const COMMON_SECOND_LEVEL_PUBLIC_SUFFIX_LABELS = new Set([
+	"ac",
+	"co",
+	"com",
+	"edu",
+	"go",
+	"gov",
+	"mil",
+	"ne",
+	"net",
+	"or",
+	"org"
+]);
+const DOCS_CONFIG_MAP_TOP_LEVEL_KEYS = [
+	"entry",
+	"docsPath",
+	"contentDir",
+	"i18n",
+	"staticExport",
+	"theme",
+	"analytics",
+	"telemetry",
+	"cloud",
+	"observability",
+	"github",
+	"nav",
+	"themeToggle",
+	"breadcrumb",
+	"sidebar",
+	"components",
+	"onCopyClick",
+	"codeBlocks",
+	"feedback",
+	"mcp",
+	"icons",
+	"pageActions",
+	"search",
+	"lastUpdated",
+	"readingTime",
+	"ai",
+	"ordering",
+	"llmsTxt",
+	"sitemap",
+	"robots",
+	"changelog",
+	"apiReference",
+	"agent",
+	"review",
+	"metadata",
+	"og"
+];
+const DOCS_MARKDOWN_SECTION_MAX_BUDGET = 1e6;
+function normalizeDocsPathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDocsConfigRequest(url) {
+	return url.searchParams.get("format")?.trim() === "config";
+}
+function isDocsDiagnosticsRequest(url) {
+	return url.searchParams.get("format")?.trim() === "diagnostics";
+}
+/** Prefer an explicitly configured API route; otherwise infer a query-form route from the request. */
+function resolveDocsRequestApiRoute(url, configuredApiRoute) {
+	const configured = configuredApiRoute?.trim();
+	if (configured) return resolveDocsDiscoveryApiRoute(configured);
+	const fallback = resolveDocsDiscoveryApiRoute();
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	const hasPublicRepresentationSuffix = /\.(?:md|txt|xml)$/i.test(pathname);
+	if (pathname.startsWith("/.well-known/") || hasPublicRepresentationSuffix) return fallback;
+	return Boolean(url.searchParams.get("format")?.trim()) || url.searchParams.get("agent")?.trim() === "spec" || url.searchParams.has("query") || url.searchParams.get("feedback")?.trim() === "agent" ? resolveDocsDiscoveryApiRoute(pathname) : fallback;
+}
+function buildDocsConfigMap(config, options = {}) {
+	const pointers = {};
+	const values = serializeDocsConfigMapValue(pickDocsConfigMapValues(config), [], /* @__PURE__ */ new WeakSet(), pointers);
+	const mappedValues = isPlainObject(values) ? values : {};
+	const language = containsDocsConfigKind(mappedValues, "jsx") ? "tsx" : "ts";
+	return {
+		schemaVersion: 1,
+		format: DEFAULT_DOCS_CONFIG_FORMAT,
+		source: {
+			file: options.file ?? (language === "tsx" ? "docs.config.tsx" : "docs.config.ts"),
+			language
+		},
+		serialization: {
+			mode: "json-safe",
+			redacted: "Scalar values under secret-like keys such as apiKey, token, secret, password, authorization, and credential are redacted unless the key ends with Env.",
+			nonSerializable: "described"
+		},
+		values: mappedValues,
+		pointers
+	};
+}
+function buildDocsDiagnostics(config, options = {}) {
+	const input = config;
+	const entry = normalizeDocsPathSegment(stringConfigValue(input.entry) ?? options.entry ?? "docs");
+	const docsRoute = routeFromConfigPath(stringConfigValue(input.docsPath) ?? entry);
+	const cloud = isPlainObject(input.cloud) ? input.cloud : void 0;
+	const apiRoute = resolveDocsDiscoveryApiRoute(options.apiRoute ?? stringConfigValue(cloud?.apiRoute));
+	const apiQueryRoute = (query) => `${apiRoute}?${query}`;
+	const staticExport = input.staticExport === true;
+	const i18n = options.i18n ?? null;
+	const localesEnabled = Boolean(i18n?.locales.length);
+	const search = resolveDocsDiagnosticsSearch(input.search, staticExport);
+	const contentChanges = resolveDocsContentChangesConfig((isPlainObject(input.agent) ? input.agent : void 0)?.contentChanges, { staticExport });
+	const ai = resolveDocsDiagnosticsAi(input.ai, staticExport);
+	const llms = resolveDocsDiagnosticsLlms(input.llmsTxt);
+	const apiCatalog = resolveDocsDiagnosticsApiCatalog(input.llmsTxt, staticExport, options.apiCatalog);
+	const sitemapConfig = resolveDocsSitemapConfig(input.sitemap);
+	const robotsEnabled = isRobotsDiscoveryEnabled(input.robots);
+	const openapiConfig = resolveDocsOpenApiDiscoveryConfig(options.openapi ?? input.apiReference);
+	const openapiUrl = resolveDocsOpenApiDiscoveryUrl(openapiConfig, apiRoute);
+	const apiReferenceRoute = resolveDocsDiagnosticsApiReferenceRoute(input.apiReference);
+	const mcp = options.mcp ?? resolveDocsDiagnosticsMcp(input.mcp);
+	const feedback = options.feedback ?? resolveDocsAgentFeedbackConfig(input.feedback);
+	const agentFeedbackEnabled = feedback.enabled === true;
+	const agentFeedbackRoute = feedback.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const agentFeedbackSchemaRoute = feedback.schemaRoute ?? `${agentFeedbackRoute}/schema`;
+	const humanFeedback = isDocsDiagnosticsHumanFeedbackEnabled(input.feedback);
+	const warnings = [];
+	const errors = [];
+	if (staticExport) warnings.push({
+		severity: "warning",
+		code: "static-export-runtime-api",
+		path: "/staticExport",
+		message: `staticExport is enabled; runtime API-backed capabilities at ${apiRoute} are unavailable in production static export builds.`
+	});
+	if (staticExport && ai.configured) errors.push({
+		severity: "error",
+		code: "ai-static-export",
+		path: "/ai/enabled",
+		message: `Ask AI requires the runtime ${apiRoute} POST handler and will not run in static export builds.`
+	});
+	if (ai.enabled && !search.enabled) warnings.push({
+		severity: "warning",
+		code: "ai-without-search",
+		path: "/ai",
+		message: "Ask AI is enabled while docs search is disabled, so retrieval context may be unavailable."
+	});
+	const adapter = options.adapter?.trim() || null;
+	if (adapter && adapter !== "next") {
+		if (!stringConfigValue(input.contentDir)) warnings.push({
+			severity: "warning",
+			code: "missing-content-dir",
+			path: "/contentDir",
+			message: `${adapter} docs usually need contentDir so the server can find markdown content.`
+		});
+		if (!isPlainObject(input.nav)) warnings.push({
+			severity: "warning",
+			code: "missing-nav",
+			path: "/nav",
+			message: `${adapter} docs usually need nav.title and nav.url for sidebar branding and root navigation.`
+		});
+	}
+	validateDocsDiagnosticsSearchConfig(input.search, errors);
+	return {
+		schemaVersion: 1,
+		format: DEFAULT_DOCS_DIAGNOSTICS_FORMAT,
+		ok: errors.length === 0,
+		adapter,
+		routes: {
+			docs: docsRoute,
+			api: apiRoute,
+			config: apiQueryRoute("format=config"),
+			diagnostics: apiQueryRoute("format=diagnostics"),
+			agentSpec: apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : apiQueryRoute("agent=spec"),
+			apiCatalog: apiCatalog.enabled ? DEFAULT_API_CATALOG_ROUTE : null,
+			agentSkillsIndex: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+			agentSkillsArtifact: DEFAULT_AGENT_SKILLS_ROUTE_PATTERN,
+			agents: apiQueryRoute("format=agents"),
+			skill: apiQueryRoute("format=skill"),
+			search: search.enabled ? apiQueryRoute("query={query}") : null,
+			agentSearch: search.enabled ? apiQueryRoute("query={query}&audience=agent") : null,
+			contentChanges: contentChanges.enabled ? apiQueryRoute(`audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`) : null,
+			askAi: ai.enabled ? apiRoute : null,
+			mcp: mcp.enabled ? mcp.route : null,
+			llmsTxt: llms.enabled ? DEFAULT_LLMS_TXT_ROUTE : null,
+			llmsFullTxt: llms.enabled ? DEFAULT_LLMS_FULL_TXT_ROUTE : null,
+			sitemapXml: sitemapConfig.enabled && sitemapConfig.xml.enabled ? sitemapConfig.xml.route : null,
+			sitemapMarkdown: sitemapConfig.enabled && sitemapConfig.markdown.enabled ? sitemapConfig.markdown.route : null,
+			robots: robotsEnabled ? DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE : null,
+			openapi: openapiConfig.enabled ? openapiUrl ?? apiQueryRoute("format=openapi") : null,
+			apiReference: openapiConfig.enabled ? apiReferenceRoute : null
+		},
+		features: {
+			staticExport: { status: staticExport ? "enabled" : "disabled" },
+			config: {
+				status: "enabled",
+				route: apiQueryRoute("format=config")
+			},
+			diagnostics: {
+				status: "enabled",
+				route: apiQueryRoute("format=diagnostics")
+			},
+			apiCatalog: {
+				status: apiCatalog.enabled ? "enabled" : "disabled",
+				reason: apiCatalog.reason,
+				route: apiCatalog.enabled ? DEFAULT_API_CATALOG_ROUTE : null,
+				transport: "GET/HEAD"
+			},
+			search: {
+				status: search.enabled ? "enabled" : "disabled",
+				reason: search.reason,
+				route: search.enabled ? apiQueryRoute("query={query}") : null,
+				routes: {
+					human: search.enabled ? apiQueryRoute("query={query}") : null,
+					agent: search.enabled ? apiQueryRoute("query={query}&audience=agent") : null,
+					structuredAgent: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured") : null,
+					explainedAgent: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured&explain=true") : null,
+					facets: search.enabled ? apiQueryRoute("audience=agent&response=facets") : null
+				},
+				agentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent") : null,
+				structuredAgentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured") : null,
+				explainedAgentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured&explain=true") : null,
+				facetsEndpoint: search.enabled ? apiQueryRoute("audience=agent&response=facets") : null,
+				audienceParam: "audience",
+				defaultAudience: "human",
+				supportedAudiences: ["human", "agent"],
+				filterParams: {
+					framework: "framework",
+					version: "version",
+					package: "package",
+					tags: "tags"
+				},
+				responseFormat: "docs-search.v1",
+				explainParam: "explain",
+				explainValue: "true",
+				explanationField: "explanation",
+				explanationFormat: "docs-search-explanation.v1",
+				facetsResponseFormat: "docs-search-facets.v1",
+				warningsField: "warnings",
+				facetParam: "facet",
+				limitParam: "limit",
+				cursorParam: "cursor",
+				nextCursorField: "nextCursor",
+				hasMoreField: "hasMore",
+				totalField: "total",
+				provider: search.provider,
+				transport: "GET"
+			},
+			contentChanges: {
+				status: contentChanges.enabled ? "enabled" : "disabled",
+				reason: staticExport ? "Runtime content-change feeds are unavailable in static exports." : contentChanges.enabled ? void 0 : "configured-disabled",
+				route: contentChanges.enabled ? apiQueryRoute(`audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`) : null,
+				transport: "GET",
+				format: DOCS_CONTENT_CHANGES_FORMAT,
+				audienceParam: "audience",
+				defaultAudience: "agent",
+				supportedAudiences: ["human", "agent"],
+				sinceParam: "since",
+				generationField: "indexGeneration",
+				resetRequiredField: "resetRequired"
+			},
+			ai: {
+				status: ai.enabled ? "enabled" : "disabled",
+				reason: ai.reason,
+				route: ai.enabled ? apiRoute : null,
+				mode: ai.mode,
+				transport: "POST"
+			},
+			mcp: {
+				status: mcp.enabled ? "enabled" : "disabled",
+				route: mcp.enabled ? mcp.route : null,
+				transport: "GET/POST",
+				tools: mcp.tools,
+				prompts: mcp.prompts ?? {
+					enabled: false,
+					contracts: false,
+					goldenTasks: []
+				}
+			},
+			feedback: {
+				status: agentFeedbackEnabled || humanFeedback ? "enabled" : "disabled",
+				human: humanFeedback,
+				agent: agentFeedbackEnabled,
+				routes: {
+					agentSubmit: agentFeedbackEnabled ? agentFeedbackRoute : null,
+					agentSchema: agentFeedbackEnabled ? agentFeedbackSchemaRoute : null
+				}
+			},
+			llmsTxt: {
+				status: llms.enabled ? "enabled" : "disabled",
+				reason: llms.reason,
+				routes: {
+					txt: llms.enabled ? DEFAULT_LLMS_TXT_ROUTE : null,
+					full: llms.enabled ? DEFAULT_LLMS_FULL_TXT_ROUTE : null,
+					wellKnownTxt: llms.enabled ? DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE : null,
+					wellKnownFull: llms.enabled ? DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE : null
+				}
+			},
+			sitemap: {
+				status: sitemapConfig.enabled ? "enabled" : "disabled",
+				routes: {
+					xml: sitemapConfig.enabled && sitemapConfig.xml.enabled ? sitemapConfig.xml.route : null,
+					markdown: sitemapConfig.enabled && sitemapConfig.markdown.enabled ? sitemapConfig.markdown.route : null,
+					docsMarkdown: sitemapConfig.enabled && sitemapConfig.markdown.enabled ? sitemapConfig.markdown.docsRoute ?? null : null,
+					wellKnownMarkdown: sitemapConfig.enabled && sitemapConfig.markdown.enabled ? sitemapConfig.markdown.wellKnownRoute : null
+				}
+			},
+			robots: {
+				status: robotsEnabled ? "enabled" : "disabled",
+				route: robotsEnabled ? DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE : null
+			},
+			apiReference: {
+				status: openapiConfig.enabled ? "enabled" : "disabled",
+				route: openapiConfig.enabled ? apiReferenceRoute : null,
+				routes: { openapi: openapiConfig.enabled ? openapiUrl ?? apiQueryRoute("format=openapi") : null },
+				provider: openapiConfig.source
+			},
+			agents: {
+				status: "enabled",
+				routes: {
+					default: DEFAULT_AGENTS_MD_ROUTE,
+					wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+					api: apiQueryRoute("format=agents")
+				}
+			},
+			skills: {
+				status: "enabled",
+				transport: "GET/HEAD",
+				routes: {
+					default: DEFAULT_SKILL_MD_ROUTE,
+					wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
+					api: apiQueryRoute("format=skill"),
+					index: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					artifact: DEFAULT_AGENT_SKILLS_ROUTE_PATTERN
+				}
+			},
+			locales: {
+				status: localesEnabled ? "enabled" : "disabled",
+				provider: localesEnabled ? "query-param" : void 0
+			}
+		},
+		warnings,
+		errors
+	};
+}
+function pickDocsConfigMapValues(config) {
+	const output = {};
+	for (const key of DOCS_CONFIG_MAP_TOP_LEVEL_KEYS) if (Object.prototype.hasOwnProperty.call(config, key)) output[key] = config[key];
+	return output;
+}
+function serializeDocsConfigMapValue(value, path, seen, pointers, depth = 0) {
+	const key = path.at(-1) ?? "";
+	const pointerPath = toDocsConfigJsonPointer(path);
+	const setPointer = (kind) => {
+		if (path.length > 0) pointers[pointerPath] = {
+			path: toDocsConfigDotPath(path),
+			kind
+		};
+	};
+	if (value === void 0) return void 0;
+	if (shouldRedactDocsConfigKey(key) && value !== null && typeof value !== "object") {
+		setPointer("secret");
+		return {
+			$kind: "secret",
+			value: "[redacted]"
+		};
+	}
+	if (value === null || typeof value === "string" || typeof value === "boolean") {
+		setPointer(typeof value);
+		return value;
+	}
+	if (typeof value === "number") {
+		setPointer("number");
+		return Number.isFinite(value) ? value : String(value);
+	}
+	if (typeof value === "bigint") {
+		setPointer("bigint");
+		return {
+			$kind: "bigint",
+			value: value.toString()
+		};
+	}
+	if (typeof value === "symbol") {
+		setPointer("symbol");
+		return {
+			$kind: "symbol",
+			value: String(value)
+		};
+	}
+	if (typeof value === "function") {
+		setPointer("function");
+		return {
+			$kind: "function",
+			name: getDocsConfigFunctionName(value)
+		};
+	}
+	if (value instanceof Date) {
+		setPointer("date");
+		return {
+			$kind: "date",
+			value: value.toISOString()
+		};
+	}
+	if (value instanceof URL) {
+		setPointer("url");
+		return value.toString();
+	}
+	if (depth >= 10) {
+		setPointer("truncated");
+		return {
+			$kind: "truncated",
+			reason: "Exceeded max depth of 10."
+		};
+	}
+	if (Array.isArray(value)) {
+		setPointer("array");
+		return value.map((entry, index) => serializeDocsConfigMapValue(entry, [...path, String(index)], seen, pointers, depth + 1)).filter((entry) => entry !== void 0);
+	}
+	if (isDocsConfigReactElement(value)) {
+		setPointer("jsx");
+		return {
+			$kind: "jsx",
+			component: getDocsConfigReactElementName(value)
+		};
+	}
+	if (seen.has(value)) {
+		setPointer("circular");
+		return { $kind: "circular" };
+	}
+	seen.add(value);
+	const output = {};
+	for (const [childKey, childValue] of Object.entries(value)) {
+		const serialized = serializeDocsConfigMapValue(childValue, [...path, childKey], seen, pointers, depth + 1);
+		if (serialized !== void 0) output[childKey] = serialized;
+	}
+	seen.delete(value);
+	if (path.length === 1 && path[0] === "theme") {
+		setPointer("theme");
+		return {
+			$kind: "theme",
+			...output
+		};
+	}
+	setPointer("object");
+	return output;
+}
+function shouldRedactDocsConfigKey(key) {
+	const normalized = key.replace(/[-_]/g, "").toLowerCase();
+	if (!normalized || normalized === "env" || normalized.endsWith("env")) return false;
+	return normalized.includes("apikey") || normalized.includes("token") || normalized.includes("secret") || normalized.includes("password") || normalized.includes("authorization") || normalized.includes("credential");
+}
+function isDocsConfigReactElement(value) {
+	if (!isPlainObject(value) || !("$$typeof" in value)) return false;
+	return String(value.$$typeof).includes("react.");
+}
+function getDocsConfigReactElementName(value) {
+	const type = value.type;
+	if (typeof type === "string") return type;
+	if (typeof type === "function") return getDocsConfigFunctionName(type);
+	if (isPlainObject(type)) {
+		const displayName = type.displayName;
+		if (typeof displayName === "string") return displayName;
+		const render = type.render;
+		if (typeof render === "function") return getDocsConfigFunctionName(render);
+	}
+	return "unknown";
+}
+function getDocsConfigFunctionName(value) {
+	const displayName = value.displayName;
+	return typeof displayName === "string" ? displayName : value.name || "anonymous";
+}
+function toDocsConfigJsonPointer(path) {
+	return path.length === 0 ? "" : `/${path.map(escapeDocsConfigJsonPointerPart).join("/")}`;
+}
+function escapeDocsConfigJsonPointerPart(value) {
+	return value.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function toDocsConfigDotPath(path) {
+	return path.map((part, index) => /^\d+$/.test(part) ? `[${part}]` : index === 0 ? part : `.${part}`).join("");
+}
+function containsDocsConfigKind(value, kind) {
+	if (!isPlainObject(value)) {
+		if (!Array.isArray(value)) return false;
+	}
+	if (Array.isArray(value)) return value.some((entry) => containsDocsConfigKind(entry, kind));
+	if (value["$kind"] === kind) return true;
+	return Object.values(value).some((entry) => containsDocsConfigKind(entry, kind));
+}
+function stringConfigValue(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function routeFromConfigPath(value) {
+	const normalized = normalizeDocsPathSegment(value);
+	return normalized ? `/${normalized}` : "/";
+}
+function resolveDocsDiagnosticsSearch(search, staticExport) {
+	const provider = isPlainObject(search) ? stringConfigValue(search.provider) : "simple";
+	const configured = search !== false && !(isPlainObject(search) && search.enabled === false);
+	if (staticExport) return {
+		enabled: false,
+		configured,
+		provider,
+		reason: "static-export"
+	};
+	if (!configured) return {
+		enabled: false,
+		configured,
+		provider,
+		reason: "configured-disabled"
+	};
+	return {
+		enabled: true,
+		configured,
+		provider
+	};
+}
+function resolveDocsDiagnosticsAi(ai, staticExport) {
+	const configured = isPlainObject(ai) && ai.enabled === true;
+	const mode = isPlainObject(ai) ? stringConfigValue(ai.mode) : void 0;
+	if (!configured) return {
+		enabled: false,
+		configured,
+		reason: "not-configured"
+	};
+	if (staticExport) return {
+		enabled: false,
+		configured,
+		mode,
+		reason: "static-export"
+	};
+	return {
+		enabled: true,
+		configured,
+		mode
+	};
+}
+function resolveDocsDiagnosticsLlms(llmsTxt) {
+	return llmsTxt !== false && !(isPlainObject(llmsTxt) && llmsTxt.enabled === false) ? { enabled: true } : {
+		enabled: false,
+		reason: "configured-disabled"
+	};
+}
+function resolveDocsDiagnosticsApiCatalog(llmsTxt, staticExport, explicit) {
+	if (staticExport) return {
+		enabled: false,
+		reason: "static-export"
+	};
+	if (explicit !== void 0) return explicit ? { enabled: true } : {
+		enabled: false,
+		reason: "configured-disabled"
+	};
+	if (isPlainObject(llmsTxt) && llmsTxt.apiCatalog === false) return {
+		enabled: false,
+		reason: "llms-txt-api-catalog-disabled"
+	};
+	return { enabled: true };
+}
+function resolveDocsDiagnosticsMcp(mcp) {
+	const config = isPlainObject(mcp) ? mcp : {};
+	const tools = isPlainObject(config.tools) ? config.tools : {};
+	return {
+		enabled: typeof mcp === "boolean" ? mcp : config.enabled !== false,
+		route: normalizeDocsDiagnosticsMcpRoute(config.route),
+		name: stringConfigValue(config.name) ?? "Documentation",
+		version: stringConfigValue(config.version) ?? "0.0.0",
+		tools: {
+			...DEFAULT_DOCS_DIAGNOSTICS_MCP_TOOLS,
+			listDocs: tools.listDocs !== false,
+			listPages: tools.listPages !== false,
+			listPageSections: tools.listPageSections !== false,
+			readPage: tools.readPage !== false,
+			listTasks: tools.listTasks !== false,
+			readTask: tools.readTask !== false,
+			searchDocs: tools.searchDocs !== false,
+			getNavigation: tools.getNavigation !== false,
+			getCodeExamples: tools.getCodeExamples !== false,
+			getConfigSchema: tools.getConfigSchema !== false,
+			getContext: tools.getContext !== false
+		}
+	};
+}
+function normalizeDocsDiagnosticsMcpRoute(route) {
+	const value = stringConfigValue(route);
+	if (!value) return DEFAULT_MCP_ROUTE;
+	const normalized = `/${value}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : DEFAULT_MCP_ROUTE;
+}
+function isDocsDiagnosticsHumanFeedbackEnabled(feedback) {
+	return feedback === true || isPlainObject(feedback) && feedback.enabled !== false;
+}
+function resolveDocsDiagnosticsApiReferenceRoute(apiReference) {
+	if (isPlainObject(apiReference)) return routeFromConfigPath(stringConfigValue(apiReference.path) ?? "api-reference");
+	return "/api-reference";
+}
+function validateDocsDiagnosticsSearchConfig(search, errors) {
+	if (!isPlainObject(search) || search.enabled === false) return;
+	const provider = stringConfigValue(search.provider) ?? "simple";
+	const requireString = (key) => {
+		if (!stringConfigValue(search[key])) errors.push({
+			severity: "error",
+			code: `missing-search-${key.replace(/[A-Z]/g, (value) => `-${value.toLowerCase()}`)}`,
+			path: `/search/${key}`,
+			message: `Search provider "${provider}" requires search.${key}.`
+		});
+	};
+	if (provider === "algolia") {
+		requireString("appId");
+		requireString("indexName");
+		requireString("searchApiKey");
+	}
+	if (provider === "typesense") {
+		requireString("baseUrl");
+		requireString("collection");
+		requireString("apiKey");
+	}
+	if (provider === "mcp") requireString("endpoint");
+	const syncNamespace = stringConfigValue(search.syncNamespace);
+	if (syncNamespace && syncNamespace.length > 1024) errors.push({
+		severity: "error",
+		code: "invalid-search-sync-namespace",
+		path: "/search/syncNamespace",
+		message: "search.syncNamespace must be 1024 characters or fewer."
+	});
+	if (provider === "custom" && !("adapter" in search)) errors.push({
+		severity: "error",
+		code: "missing-search-adapter",
+		path: "/search/adapter",
+		message: "Search provider \"custom\" requires search.adapter."
+	});
+}
+function normalizeDocsAgentFeedbackRoute(route, fallback = DEFAULT_AGENT_FEEDBACK_ROUTE) {
+	if (!route || route.trim().length === 0) return fallback;
+	const normalized = `/${route}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : fallback;
+}
+function buildDocsAgentFeedbackSchema(payloadSchema) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			context: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					page: { type: "string" },
+					url: { type: "string" },
+					slug: { type: "string" },
+					locale: { type: "string" },
+					source: { type: "string" }
+				}
+			},
+			payload: payloadSchema
+		},
+		required: ["payload"]
+	};
+}
+function resolveDocsAgentFeedbackConfig(feedback) {
+	const route = normalizeDocsAgentFeedbackRoute();
+	const enabled = {
+		enabled: true,
+		route,
+		schemaRoute: `${route}/schema`,
+		payloadSchema: DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA,
+		schema: buildDocsAgentFeedbackSchema(DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA)
+	};
+	const disabled = {
+		enabled: false,
+		route,
+		schemaRoute: `${route}/schema`,
+		payloadSchema: DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA,
+		schema: buildDocsAgentFeedbackSchema(DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA)
+	};
+	if (feedback === false) return disabled;
+	if (!feedback || feedback === true || typeof feedback !== "object") return enabled;
+	const agent = feedback.agent;
+	if (agent === false) return disabled;
+	if (!agent) return enabled;
+	if (agent === true) return enabled;
+	const resolvedRoute = normalizeDocsAgentFeedbackRoute(agent.route, route);
+	const resolvedSchemaRoute = normalizeDocsAgentFeedbackRoute(agent.schemaRoute, `${resolvedRoute}/schema`);
+	const payloadSchema = agent.schema ?? DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA;
+	return {
+		enabled: agent.enabled !== false,
+		route: resolvedRoute,
+		schemaRoute: resolvedSchemaRoute,
+		payloadSchema,
+		schema: buildDocsAgentFeedbackSchema(payloadSchema),
+		onFeedback: agent.onFeedback
+	};
+}
+function resolveDocsAgentFeedbackRequest(url, feedback) {
+	if (!feedback.enabled) return null;
+	const feedbackMode = url.searchParams.get("feedback")?.trim();
+	const schemaMode = url.searchParams.get("schema")?.trim();
+	if (feedbackMode === "agent") return { kind: schemaMode === "1" || schemaMode === "true" ? "schema" : "submit" };
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (pathname === feedback.schemaRoute) return { kind: "schema" };
+	if (pathname === feedback.route) return { kind: "submit" };
+	return null;
+}
+function normalizeDocsAgentFeedbackContext(value) {
+	if (!isPlainObject(value)) return void 0;
+	const context = {};
+	if (typeof value.page === "string") context.page = value.page;
+	if (typeof value.url === "string") context.url = value.url;
+	if (typeof value.slug === "string") context.slug = value.slug;
+	if (typeof value.locale === "string") context.locale = value.locale;
+	if (typeof value.source === "string") context.source = value.source;
+	return Object.keys(context).length > 0 ? context : void 0;
+}
+async function parseDocsAgentFeedbackData(request) {
+	const parsed = await readDocsJsonBody(request);
+	if (!parsed.ok) {
+		if (parsed.reason === "request_too_large") return {
+			ok: false,
+			response: Response.json({
+				error: `Request body exceeds the ${parsed.maxBodyBytes} byte limit`,
+				code: parsed.reason,
+				maxBodyBytes: parsed.maxBodyBytes
+			}, { status: 413 })
+		};
+		return {
+			ok: false,
+			response: Response.json({ error: "Agent feedback body must be valid JSON" }, { status: 400 })
+		};
+	}
+	const body = parsed.value;
+	if (!isPlainObject(body)) return {
+		ok: false,
+		response: Response.json({ error: "Agent feedback body must be an object" }, { status: 400 })
+	};
+	if (!isPlainObject(body.payload)) return {
+		ok: false,
+		response: Response.json({ error: "Agent feedback body must include a payload object" }, { status: 400 })
+	};
+	return {
+		ok: true,
+		data: {
+			context: normalizeDocsAgentFeedbackContext(body.context),
+			payload: body.payload
+		}
+	};
+}
+function validateDocsAgentFeedbackPayload(value, schema, valuePath = "payload") {
+	const schemaType = typeof schema.type === "string" ? schema.type : void 0;
+	if (Array.isArray(schema.enum) && !schema.enum.some((entry) => Object.is(entry, value))) return `${valuePath} must be one of the configured enum values`;
+	if (schemaType === "object" || !schemaType && (schema.properties || schema.required)) {
+		if (!isPlainObject(value)) return `${valuePath} must be an object`;
+		const properties = isPlainObject(schema.properties) ? schema.properties : {};
+		const required = Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === "string") : [];
+		for (const key of required) if (!(key in value)) return `${valuePath}.${key} is required`;
+		if (schema.additionalProperties === false) {
+			for (const key of Object.keys(value)) if (!(key in properties)) return `${valuePath}.${key} is not allowed`;
+		}
+		for (const [key, propertySchema] of Object.entries(properties)) {
+			if (!(key in value)) continue;
+			if (!isPlainObject(propertySchema)) continue;
+			const error = validateDocsAgentFeedbackPayload(value[key], propertySchema, `${valuePath}.${key}`);
+			if (error) return error;
+		}
+		return;
+	}
+	if (schemaType === "array") {
+		if (!Array.isArray(value)) return `${valuePath} must be an array`;
+		if (!isPlainObject(schema.items)) return void 0;
+		for (const [index, item] of value.entries()) {
+			const error = validateDocsAgentFeedbackPayload(item, schema.items, `${valuePath}[${index}]`);
+			if (error) return error;
+		}
+		return;
+	}
+	if (schemaType === "string") {
+		if (typeof value !== "string") return `${valuePath} must be a string`;
+		if (typeof schema.minLength === "number" && value.length < schema.minLength) return `${valuePath} must be at least ${schema.minLength} characters`;
+		if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return `${valuePath} must be at most ${schema.maxLength} characters`;
+		return;
+	}
+	if (schemaType === "number") {
+		if (typeof value !== "number" || !Number.isFinite(value)) return `${valuePath} must be a number`;
+		if (typeof schema.minimum === "number" && value < schema.minimum) return `${valuePath} must be >= ${schema.minimum}`;
+		if (typeof schema.maximum === "number" && value > schema.maximum) return `${valuePath} must be <= ${schema.maximum}`;
+		return;
+	}
+	if (schemaType === "boolean") {
+		if (typeof value !== "boolean") return `${valuePath} must be a boolean`;
+		return;
+	}
+}
+function resolveDocsMarkdownCanonicalUrl({ origin, entry = "docs", requestedPath, locale }) {
+	const pathname = normalizeRequestedMarkdownPath(normalizeDocsPathSegment(entry) || "docs", requestedPath);
+	const canonicalUrl = new URL(pathname, origin);
+	if (locale) canonicalUrl.searchParams.set("lang", locale);
+	return canonicalUrl.toString();
+}
+function getDocsMarkdownCanonicalLinkHeader(options) {
+	return `<${resolveDocsMarkdownCanonicalUrl(options)}>; rel="canonical"`;
+}
+function joinDocsPublicRoute(prefix, suffix) {
+	const normalizedPrefix = normalizeDocsUrlPath(`/${normalizeDocsPathSegment(prefix)}`);
+	const normalizedSuffix = `/${normalizeDocsPathSegment(suffix)}`;
+	if (normalizedPrefix === "/") return normalizedSuffix;
+	return normalizeDocsUrlPath(`${normalizedPrefix}${normalizedSuffix}`);
+}
+function normalizeLlmsTxtMatch(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return "/";
+	return normalizeDocsUrlPath(trimmed.startsWith("/") ? trimmed : `/${trimmed}`);
+}
+function llmsTxtMatchPrefix(value) {
+	const normalized = normalizeLlmsTxtMatch(value);
+	const wildcardIndex = normalized.indexOf("*");
+	return normalizeDocsUrlPath((wildcardIndex >= 0 ? normalized.slice(0, wildcardIndex) : normalized).replace(/\/+$/, "") || "/");
+}
+function deriveLlmsTxtSectionRoute(match) {
+	return joinDocsPublicRoute(llmsTxtMatchPrefix(match[0] ?? "/"), "llms.txt");
+}
+function deriveLlmsTxtSectionFullRoute(route) {
+	const normalized = normalizeDocsUrlPath(route);
+	if (normalized.endsWith("/llms.txt")) return `${normalized.slice(0, -9)}/llms-full.txt`;
+	return joinDocsPublicRoute(normalized, "llms-full.txt");
+}
+function resolveDocsBaseLlmsTxtRoute(basePath) {
+	if (!basePath) return null;
+	return joinDocsPublicRoute(normalizeDocsPathSegment(basePath) || "docs", "llms.txt");
+}
+function resolveDocsBaseLlmsFullTxtRoute(basePath) {
+	const route = resolveDocsBaseLlmsTxtRoute(basePath);
+	return route ? deriveLlmsTxtSectionFullRoute(route) : null;
+}
+function normalizeLlmsTxtMaxChars(value, fallback) {
+	const mode = value?.mode ?? fallback?.mode ?? "warn";
+	const chars = value?.chars ?? fallback?.chars ?? DEFAULT_LLMS_TXT_MAX_CHARS;
+	return {
+		mode,
+		chars: Number.isFinite(chars) && chars > 0 ? Math.floor(chars) : DEFAULT_LLMS_TXT_MAX_CHARS
+	};
+}
+function resolveDocsLlmsTxtSections(llms) {
+	if (!llms || typeof llms !== "object" || !Array.isArray(llms.sections)) return [];
+	const rootMaxChars = normalizeLlmsTxtMaxChars(llms.maxChars);
+	return llms.sections.flatMap((section) => {
+		const match = (Array.isArray(section.match) ? section.match : [section.match]).map(normalizeLlmsTxtMatch).filter(Boolean);
+		if (match.length === 0) return [];
+		const route = deriveLlmsTxtSectionRoute(match);
+		const resolved = {
+			title: section.title,
+			match,
+			route,
+			fullRoute: deriveLlmsTxtSectionFullRoute(route),
+			maxChars: normalizeLlmsTxtMaxChars(section.maxChars, rootMaxChars)
+		};
+		if (section.description !== void 0) resolved.description = section.description;
+		return [resolved];
+	});
+}
+function matchesDocsLlmsTxtSection(pageUrl, section) {
+	const pathname = normalizeDocsUrlPath(pageUrl.split(/[?#]/, 1)[0] || "/");
+	return section.match.some((pattern) => {
+		const normalized = normalizeLlmsTxtMatch(pattern);
+		if (normalized.endsWith("/**")) {
+			const prefix = normalizeDocsUrlPath(normalized.slice(0, -3) || "/");
+			if (prefix === "/") return true;
+			return pathname === prefix || pathname.startsWith(`${prefix}/`);
+		}
+		if (normalized.endsWith("/*")) {
+			const prefix = normalizeDocsUrlPath(normalized.slice(0, -2) || "/");
+			if (prefix === "/") {
+				const directChild = pathname.slice(1);
+				return directChild.length > 0 && !directChild.includes("/");
+			}
+			if (!pathname.startsWith(`${prefix}/`)) return false;
+			return !pathname.slice(prefix.length + 1).includes("/");
+		}
+		return pathname === normalized;
+	});
+}
+function resolveDocsLlmsTxtRequest(url, llms, basePath, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	const apiRoute = resolveDocsDiscoveryApiRoute(options.apiRoute);
+	const sections = resolveDocsLlmsTxtSections(llms);
+	for (const section of sections) {
+		if (pathname === section.route) return {
+			format: "llms",
+			section
+		};
+		if (pathname === section.fullRoute) return {
+			format: "llms-full",
+			section
+		};
+	}
+	const format = url.searchParams.get("format");
+	if (pathname === apiRoute && (format === "llms" || format === "llms-full")) {
+		const sectionRoute = url.searchParams.get("section")?.trim();
+		const normalizedSectionRoute = sectionRoute ? normalizeDocsUrlPath(sectionRoute) : void 0;
+		return {
+			format,
+			section: normalizedSectionRoute ? sections.find((candidate) => candidate.route === normalizedSectionRoute || candidate.fullRoute === normalizedSectionRoute) ?? {
+				title: "",
+				match: [],
+				route: normalizedSectionRoute,
+				fullRoute: normalizedSectionRoute,
+				maxChars: normalizeLlmsTxtMaxChars(void 0)
+			} : void 0
+		};
+	}
+	if (pathname === DEFAULT_LLMS_TXT_ROUTE || pathname === DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE) return { format: "llms" };
+	if (pathname === resolveDocsBaseLlmsTxtRoute(basePath)) return { format: "llms" };
+	if (pathname === DEFAULT_LLMS_FULL_TXT_ROUTE || pathname === DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE) return { format: "llms-full" };
+	if (pathname === resolveDocsBaseLlmsFullTxtRoute(basePath)) return { format: "llms-full" };
+	return null;
+}
+function renderLlmsTxtPageList(pages, baseUrl) {
+	let content = "";
+	for (const page of pages) {
+		content += `- [${page.title}](${baseUrl}${page.markdownUrl ?? toDocsMarkdownUrl(page.url)})`;
+		if (page.description) content += `: ${page.description}`;
+		content += "\n";
+	}
+	return content;
+}
+function resolveDocsResourceUrl(baseUrl, url) {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(url)) return url;
+	return `${baseUrl}${url.startsWith("/") ? url : `/${url}`}`;
+}
+function formatOpenApiOperationCount(count) {
+	if (count === void 0) return void 0;
+	return `${count.toLocaleString("en-US")} ${count === 1 ? "operation" : "operations"}`;
+}
+function renderLlmsFullTxtPages(pages, baseUrl) {
+	let content = "";
+	for (const page of pages) {
+		content += `## ${page.title}\n\n`;
+		content += `URL: ${baseUrl}${page.url}\n\n`;
+		if (page.description) content += `${page.description}\n\n`;
+		const agentContent = page.agentRawContent ?? page.agentFallbackRawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content;
+		content += `${agentContent}\n\n---\n\n`;
+	}
+	return content;
+}
+function renderDocsLlmsTxt(pages, options = {}) {
+	pages = filterDocsPagesByAccess(pages);
+	const siteTitle = options.siteTitle ?? "Documentation";
+	const siteDescription = options.siteDescription;
+	const baseUrl = options.baseUrl ?? "";
+	const maxChars = normalizeLlmsTxtMaxChars(options.maxChars);
+	const apiCatalogEnabled = options.apiCatalog ?? true;
+	const sections = resolveDocsLlmsTxtSections(options);
+	const openapi = resolveDocsOpenApiDiscoveryConfig(options.openapi);
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(options.apiRoute);
+	const openapiUrl = resolveDocsOpenApiDiscoveryUrl(openapi, resolvedApiRoute);
+	const matchedPageUrls = /* @__PURE__ */ new Set();
+	const generatedSections = sections.map((section) => {
+		const sectionPages = pages.filter((page) => matchesDocsLlmsTxtSection(page.url, section));
+		for (const page of sectionPages) matchedPageUrls.add(normalizeDocsUrlPath(page.url));
+		let llmsTxt = `# ${siteTitle} - ${section.title}\n\n`;
+		if (section.description) llmsTxt += `> ${section.description}\n\n`;
+		else if (siteDescription) llmsTxt += `> ${siteDescription}\n\n`;
+		llmsTxt += "## Pages\n\n";
+		llmsTxt += renderLlmsTxtPageList(sectionPages, baseUrl);
+		let llmsFullTxt = `# ${siteTitle} - ${section.title}\n\n`;
+		if (section.description) llmsFullTxt += `> ${section.description}\n\n`;
+		else if (siteDescription) llmsFullTxt += `> ${siteDescription}\n\n`;
+		llmsFullTxt += renderLlmsFullTxtPages(sectionPages, baseUrl);
+		return {
+			...section,
+			llmsTxt,
+			llmsFullTxt
+		};
+	});
+	const rootPages = generatedSections.length > 0 ? pages.filter((page) => !matchedPageUrls.has(normalizeDocsUrlPath(page.url))) : pages;
+	let llmsTxt = `# ${siteTitle}\n\n`;
+	if (siteDescription) llmsTxt += `> ${siteDescription}\n\n`;
+	llmsTxt += "## Agent Discovery\n\n";
+	llmsTxt += `- [Agent manifest](${resolveDocsResourceUrl(baseUrl, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE)}): Farming Labs discovery manifest\n`;
+	if (apiCatalogEnabled) llmsTxt += `- [API catalog](${resolveDocsResourceUrl(baseUrl, DEFAULT_API_CATALOG_ROUTE)}): RFC 9727 API catalog\n`;
+	llmsTxt += `- [Agent Skills index](${resolveDocsResourceUrl(baseUrl, DEFAULT_AGENT_SKILLS_INDEX_ROUTE)}): Hashed Agent Skills discovery\n\n`;
+	if (generatedSections.length > 0) {
+		llmsTxt += "## Sections\n\n";
+		for (const section of generatedSections) {
+			llmsTxt += `- [${section.title}](${baseUrl}${section.route})`;
+			if (section.description) llmsTxt += `: ${section.description}`;
+			llmsTxt += "\n";
+		}
+		llmsTxt += "\n";
+	}
+	if (openapi.enabled && openapiUrl) {
+		llmsTxt += "## API Schemas\n\n";
+		llmsTxt += `- [OpenAPI schema](${resolveDocsResourceUrl(baseUrl, openapiUrl)}): Machine-readable API schema for tool use and API clients`;
+		const operationCount = formatOpenApiOperationCount(openapi.operationCount);
+		if (operationCount) llmsTxt += `; ${operationCount}`;
+		if (openapi.apiReferencePath) llmsTxt += `; rendered API reference at ${resolveDocsResourceUrl(baseUrl, openapi.apiReferencePath)}`;
+		llmsTxt += "\n";
+		for (const version of openapi.versions ?? []) {
+			const versionOperationCount = formatOpenApiOperationCount(version.operationCount);
+			llmsTxt += `- [OpenAPI schema – ${version.label}](${resolveDocsResourceUrl(baseUrl, resolveDocsOpenApiVersionUrl(openapi, version, resolvedApiRoute))}): Version \`${version.id}\`${version.default ? " (default)" : ""}${versionOperationCount ? `; ${versionOperationCount}` : ""}; rendered API reference at ${resolveDocsResourceUrl(baseUrl, version.apiReferencePath)}\n`;
+		}
+		llmsTxt += "\n";
+	}
+	if (rootPages.length > 0 || generatedSections.length === 0) {
+		llmsTxt += "## Pages\n\n";
+		llmsTxt += renderLlmsTxtPageList(rootPages, baseUrl);
+	}
+	let llmsFullTxt = `# ${siteTitle}\n\n`;
+	if (siteDescription) llmsFullTxt += `> ${siteDescription}\n\n`;
+	llmsFullTxt += renderLlmsFullTxtPages(pages, baseUrl);
+	return {
+		llmsTxt,
+		llmsFullTxt,
+		maxChars,
+		sections: generatedSections
+	};
+}
+function selectDocsLlmsTxtContent(content, request) {
+	if (request.section) {
+		const section = content.sections.find((candidate) => candidate.route === request.section?.route);
+		if (!section) return null;
+		return {
+			content: request.format === "llms-full" ? section.llmsFullTxt : section.llmsTxt,
+			label: request.format === "llms-full" ? section.fullRoute : section.route,
+			maxChars: request.format === "llms-full" ? {
+				...section.maxChars,
+				mode: "off"
+			} : section.maxChars
+		};
+	}
+	return {
+		content: request.format === "llms-full" ? content.llmsFullTxt : content.llmsTxt,
+		label: request.format === "llms-full" ? DEFAULT_LLMS_FULL_TXT_ROUTE : DEFAULT_LLMS_TXT_ROUTE,
+		maxChars: request.format === "llms-full" ? {
+			...content.maxChars,
+			mode: "off"
+		} : content.maxChars
+	};
+}
+function getDocsLlmsTxtMaxCharsIssue(label, content, maxChars) {
+	if (maxChars.mode === "off" || content.length <= maxChars.chars) return null;
+	return {
+		mode: maxChars.mode,
+		chars: maxChars.chars,
+		actual: content.length,
+		label,
+		message: `${label} is ${content.length.toLocaleString()} chars, above the configured ${maxChars.chars.toLocaleString()} char llms.txt budget.`
+	};
+}
+function resolveDocsStandardsOrigin(preferred, fallback) {
+	for (const candidate of [preferred, fallback]) {
+		if (!candidate) continue;
+		try {
+			const url = new URL(candidate);
+			if (url.protocol === "http:" || url.protocol === "https:") return url.origin;
+		} catch {}
+	}
+	return new URL(fallback).origin;
+}
+/** Build and serve standards-based discovery without replacing the custom agent manifest. */
+async function createDocsStandardsDiscoveryResponse({ request, preferredSkillDocument, fallbackSkillDocument, origin, entry = "docs", docsPath, apiCatalog: explicitApiCatalog, apiRoute, i18n: _i18n, search: _search, mcp, feedback, llms, sitemap, robots, openapi, markdown: _markdown, publishedSkills, agentCard, lastModified }) {
+	const url = new URL(request.url);
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(apiRoute);
+	if (!isDocsStandardsDiscoveryRequest(url, { apiRoute: resolvedApiRoute })) return null;
+	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const normalizedDocsPath = normalizeDocsPathSegment(docsPath ?? normalizedEntry);
+	const apiCatalogEnabled = explicitApiCatalog ?? llms?.apiCatalog ?? true;
+	const catalogOrigin = resolveDocsStandardsOrigin(llms?.baseUrl, origin || url.origin);
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms?.baseUrl });
+	const openapiConfig = resolveDocsOpenApiDiscoveryConfig(openapi);
+	const openapiUrl = resolveDocsOpenApiDiscoveryUrl(openapiConfig, resolvedApiRoute);
+	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const feedbackSchemaRoute = feedback?.schemaRoute ?? `${feedbackRoute}/schema`;
+	const llmsEnabled = llms?.enabled ?? true;
+	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const llmsSections = resolveDocsLlmsTxtSections(llms);
+	const llmsRoutes = llmsEnabled ? [
+		DEFAULT_LLMS_TXT_ROUTE,
+		DEFAULT_LLMS_FULL_TXT_ROUTE,
+		DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
+		DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE,
+		...llmsSections.flatMap((section) => [section.route, section.fullRoute])
+	] : [];
+	const sitemapRoutes = sitemapConfig.enabled ? [...sitemapConfig.xml.enabled ? [sitemapConfig.xml.route] : [], ...sitemapConfig.markdown.enabled ? [
+		sitemapConfig.markdown.route,
+		sitemapConfig.markdown.docsRoute,
+		sitemapConfig.markdown.wellKnownRoute
+	].filter((route) => Boolean(route)) : []] : [];
+	const protectedResourceMetadataRoutes = mcp.enabled && mcp.security?.authenticate && mcp.security.protectedResource ? getDocsMcpProtectedResourceMetadataRoutes(mcp.route) : [];
+	return createDocsStandardsResponse({
+		request,
+		apiCatalogEnabled,
+		apiRoute: resolvedApiRoute,
+		preferredSkillDocument,
+		fallbackSkillDocument,
+		publishedSkills,
+		agentCard,
+		lastModified,
+		apiCatalog: apiCatalogEnabled ? buildDocsApiCatalog({
+			origin: catalogOrigin,
+			docsRoute: normalizedDocsPath ? `/${normalizedDocsPath}` : "/",
+			apiRoute: resolvedApiRoute,
+			configRoute: `${resolvedApiRoute}?format=config`,
+			diagnosticsRoute: `${resolvedApiRoute}?format=diagnostics`,
+			agentManifestRoute: DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
+			agentSkillsIndexRoute: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+			legacySkillsIndexRoute: DEFAULT_LEGACY_SKILLS_INDEX_ROUTE,
+			agentCardRoute: agentCard ? DEFAULT_A2A_AGENT_CARD_ROUTE : null,
+			agentsRoute: DEFAULT_AGENTS_MD_ROUTE,
+			skillRoute: DEFAULT_SKILL_MD_ROUTE,
+			markdownRootRoute: `/${normalizedEntry}.md`,
+			llmsRoutes,
+			sitemapRoutes,
+			robotsRoute: robotsEnabled ? DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE : null,
+			mcpRoute: mcp.enabled ? mcp.route : null,
+			protectedResourceMetadataRoutes,
+			feedbackRoutes: feedback?.enabled ? [feedbackRoute, feedbackSchemaRoute] : [],
+			openapiDefinitions: openapiConfig.enabled && openapiConfig.catalogTargets?.length ? (openapiConfig.versions?.length ? openapiConfig.versions : [{
+				id: "default",
+				label: "Product API",
+				default: true,
+				url: openapiUrl ?? `${resolvedApiRoute}?format=openapi`,
+				apiReferencePath: openapiConfig.apiReferencePath ?? "/api-reference",
+				operationCount: openapiConfig.operationCount
+			}]).map((version) => ({
+				route: resolveDocsOpenApiVersionUrl(openapiConfig, version, resolvedApiRoute),
+				title: `${openapiConfig.versions?.length ? `OpenAPI schema – ${version.label}` : "OpenAPI schema"}${formatOpenApiOperationCount(version.operationCount) ? ` — ${formatOpenApiOperationCount(version.operationCount)}` : ""}`,
+				targets: openapiConfig.catalogTargets.map((route) => ({
+					route,
+					title: "Product API"
+				}))
+			})) : [],
+			apiReferenceRoute: openapiConfig.enabled && openapiConfig.apiReferencePath ? openapiConfig.apiReferencePath : null
+		}) : void 0
+	});
+}
+function isDocsAgentDiscoveryRequest(url, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (pathname === resolveDocsDiscoveryApiRoute(options.apiRoute) && url.searchParams.get("agent")?.trim() === "spec") return true;
+	return pathname === DEFAULT_AGENT_SPEC_ROUTE || pathname === DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE || pathname === DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE;
+}
+function buildDocsMcpEndpointCandidates(baseUrl, routes = [DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE], options = {}) {
+	const includeOriginFallback = options.includeOriginFallback !== false;
+	const includeRootDomainFallback = options.includeRootDomainFallback !== false;
+	const includeMcpSubdomainFallback = options.includeMcpSubdomainFallback !== false;
+	const base = new URL(baseUrl);
+	const primaryOrigin = base.origin;
+	const seen = /* @__PURE__ */ new Set();
+	const candidates = [];
+	const addCandidate = (candidateBaseUrl, route) => {
+		const resolved = resolveDocsMcpCandidateUrl(candidateBaseUrl, route);
+		if (seen.has(resolved.url)) return;
+		seen.add(resolved.url);
+		candidates.push({
+			...resolved,
+			label: formatDocsMcpCandidateLabel(resolved.url, primaryOrigin)
+		});
+	};
+	for (const route of routes) addCandidate(baseUrl, route);
+	const originBaseUrl = primaryOrigin;
+	if (includeOriginFallback && originBaseUrl !== baseUrl.replace(/\/+$/, "")) for (const route of routes) addCandidate(originBaseUrl, route);
+	if (includeRootDomainFallback) for (const rootDomainBaseUrl of toDocsRootDomainBaseUrls(base)) for (const route of routes) addCandidate(rootDomainBaseUrl, route);
+	if (includeMcpSubdomainFallback) for (const mcpBaseUrl of toDocsMcpSubdomainBaseUrls(base)) {
+		addCandidate(mcpBaseUrl, DEFAULT_MCP_PUBLIC_ROUTE);
+		addCandidate(mcpBaseUrl, "/");
+	}
+	return candidates;
+}
+function resolveDocsMcpCandidateUrl(baseUrl, route) {
+	if (/^https?:\/\//i.test(route)) {
+		const parsed = new URL(route);
+		const path = `${parsed.pathname || "/"}${parsed.search}`;
+		return {
+			baseUrl: parsed.origin,
+			route: path,
+			url: parsed.toString()
+		};
+	}
+	const base = new URL(baseUrl);
+	const basePath = base.pathname.replace(/\/+$/, "");
+	const routePath = route.startsWith("/") ? route : `/${route}`;
+	const parsed = new URL(`${basePath}${routePath}`, base.origin);
+	return {
+		baseUrl: parsed.origin,
+		route: `${parsed.pathname}${parsed.search}`,
+		url: parsed.toString()
+	};
+}
+function formatDocsMcpCandidateLabel(url, primaryOrigin) {
+	const parsed = new URL(url);
+	const path = `${parsed.pathname}${parsed.search}`;
+	return parsed.origin === primaryOrigin ? path : `${parsed.origin}${path}`;
+}
+function toDocsMcpSubdomainBaseUrls(base) {
+	return getDocsMcpRootDomainCandidates(base.hostname).map((rootDomain) => `${base.protocol}//mcp.${rootDomain}${base.port ? `:${base.port}` : ""}`);
+}
+function toDocsRootDomainBaseUrls(base) {
+	return getDocsMcpRootDomainCandidates(base.hostname).map((rootDomain) => `${base.protocol}//${rootDomain}${base.port ? `:${base.port}` : ""}`);
+}
+function getDocsMcpRootDomainCandidates(hostname) {
+	const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+	if (!normalized || !normalized.includes(".") || isDocsIpHostname(normalized)) return [];
+	const labels = normalized.split(".").filter(Boolean);
+	if (labels.length < 2) return [];
+	const candidates = [];
+	const addCandidate = (candidateLabels) => {
+		if (candidateLabels.length < 2) return;
+		const candidate = candidateLabels.join(".");
+		if (!candidates.includes(candidate)) candidates.push(candidate);
+	};
+	if (labels.length >= 3 && DOCS_MCP_SERVICE_SUBDOMAIN_LABELS.has(labels[0] ?? "")) addCandidate(labels.slice(1));
+	const tld = labels.at(-1) ?? "";
+	const secondLevel = labels.at(-2) ?? "";
+	if (labels.length >= 3 && tld.length === 2 && COMMON_SECOND_LEVEL_PUBLIC_SUFFIX_LABELS.has(secondLevel)) addCandidate(labels.slice(-3));
+	else addCandidate(labels.slice(-2));
+	return candidates;
+}
+function isDocsIpHostname(hostname) {
+	return /^(\d{1,3}\.){3}\d{1,3}$/.test(hostname) || hostname.includes(":");
+}
+function isDocsSkillRequest(url, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (pathname === DEFAULT_SKILL_MD_ROUTE || pathname === DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE) return true;
+	return pathname === resolveDocsDiscoveryApiRoute(options.apiRoute) && resolveDocsSkillFormat(url) === "skill";
+}
+function resolveDocsSkillFormat(url) {
+	return url.searchParams.get("format")?.trim() === "skill" ? "skill" : null;
+}
+function isDocsAgentsPath(pathname) {
+	return pathname === DEFAULT_AGENTS_MD_ROUTE || pathname === DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE || pathname === DEFAULT_AGENT_MD_ROUTE || pathname === DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE;
+}
+function isDocsAgentsRequest(url, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (isDocsAgentsPath(pathname)) return true;
+	return pathname === resolveDocsDiscoveryApiRoute(options.apiRoute) && resolveDocsAgentsFormat(url) === "agents";
+}
+function resolveDocsAgentsFormat(url) {
+	return url.searchParams.get("format")?.trim() === "agents" ? "agents" : null;
+}
+function isDocsPublicGetRequest(entry, url, request, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	const apiRoute = resolveDocsDiscoveryApiRoute(options.apiRoute);
+	if (pathname === apiRoute || pathname === DEFAULT_MCP_ROUTE) return false;
+	return isDocsStandardsDiscoveryRequest(url, { apiRoute }) || isDocsAgentDiscoveryRequest(url, { apiRoute }) || isDocsAgentsRequest(url, { apiRoute }) || isDocsSkillRequest(url, { apiRoute }) || pathname === DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE && isRobotsDiscoveryEnabled(options.robots) || resolveDocsLlmsTxtRequest(url, options.llms, entry, { apiRoute }) !== null || resolveDocsSitemapRequest(url, options.sitemap, { apiRoute }) !== null || resolveDocsMarkdownRequest(entry, url, request, { apiRoute }) !== null;
+}
+function isDocsLlmsTxtPublicRequest(url, llms, basePath, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	const apiRoute = resolveDocsDiscoveryApiRoute(options.apiRoute);
+	return pathname !== apiRoute && resolveDocsLlmsTxtRequest(url, llms, basePath, { apiRoute }) !== null;
+}
+function resolveDocsLlmsTxtFormat(url, basePath, options = {}) {
+	return resolveDocsLlmsTxtRequest(url, void 0, basePath, options)?.format ?? null;
+}
+function resolveDocsMarkdownRequest(entry, url, request, options = {}) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	const format = url.searchParams.get("format")?.trim();
+	if (pathname === resolveDocsDiscoveryApiRoute(options.apiRoute) && format === "markdown") return { requestedPath: url.searchParams.get("path")?.trim() ?? "" };
+	const normalizedEntry = `/${normalizeDocsPathSegment(entry) || "docs"}`;
+	if (pathname === `${normalizedEntry}.md`) return { requestedPath: "" };
+	const slugPrefix = `${normalizedEntry}/`;
+	if (pathname.startsWith(slugPrefix) && pathname.endsWith(".md")) return { requestedPath: pathname.slice(slugPrefix.length, -3) };
+	if (acceptsDocsMarkdown(request) || hasDocsMarkdownSignatureAgent(request) || detectDocsMarkdownAgentRequest(request).detected) {
+		if (pathname === normalizedEntry) return { requestedPath: "" };
+		if (pathname.startsWith(slugPrefix)) return { requestedPath: pathname.slice(slugPrefix.length) };
+	}
+	return null;
+}
+function hasDocsMarkdownSignatureAgent(request) {
+	return Boolean(request.headers.get(DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER)?.trim());
+}
+function detectDocsMarkdownAgentRequest(request) {
+	if (hasDocsMarkdownSignatureAgent(request)) return {
+		detected: true,
+		method: "signature_agent"
+	};
+	const userAgent = request.headers.get("user-agent")?.trim().toLowerCase() ?? "";
+	if (!userAgent) return {
+		detected: false,
+		method: null
+	};
+	if (DOCS_AI_AGENT_USER_AGENT_PATTERNS.some((pattern) => userAgent.includes(pattern))) return {
+		detected: true,
+		method: "user_agent"
+	};
+	if (!request.headers.get("sec-fetch-mode") && DOCS_BOT_LIKE_USER_AGENT_PATTERN.test(userAgent)) {
+		if (!DOCS_TRADITIONAL_BOT_USER_AGENT_PATTERNS.some((pattern) => userAgent.includes(pattern))) return {
+			detected: true,
+			method: "heuristic"
+		};
+	}
+	return {
+		detected: false,
+		method: null
+	};
+}
+function getDocsMarkdownVaryHeader(request) {
+	const values = /* @__PURE__ */ new Set();
+	if (acceptsDocsMarkdown(request)) values.add("Accept");
+	if (hasDocsMarkdownSignatureAgent(request)) {
+		values.add("Accept");
+		values.add(DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER);
+	}
+	const agentDetection = detectDocsMarkdownAgentRequest(request);
+	if (agentDetection.detected && agentDetection.method !== "signature_agent") {
+		values.add("User-Agent");
+		if (agentDetection.method === "heuristic") values.add("Sec-Fetch-Mode");
+	}
+	return values.size > 0 ? Array.from(values).join(", ") : null;
+}
+const DOCS_MARKDOWN_RECOVERY_MATCH_LIMIT = 5;
+const DOCS_MARKDOWN_RECOVERY_REDIRECT_CONFIDENCE = .99;
+const DOCS_MARKDOWN_RECOVERY_SLUG_MAX_LENGTH = 256;
+function normalizeDocsRecoveryText(value) {
+	return value.toLowerCase().replace(/\.md$/i, "").replace(/[#?].*$/g, "").replace(/['"`]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+}
+function normalizeDocsRecoverySlug(entry, value) {
+	const withoutHash = value.split("#", 1)[0] ?? value;
+	const withoutMarkdown = (withoutHash.split("?", 1)[0] ?? withoutHash).replace(/\.md$/i, "");
+	const normalizedPath = normalizeDocsUrlPath(withoutMarkdown.startsWith("/") ? withoutMarkdown : `/${withoutMarkdown}`);
+	const normalizedEntry = `/${normalizeDocsPathSegment(entry) || "docs"}`;
+	if (normalizedPath === normalizedEntry) return "";
+	if (normalizedPath.startsWith(`${normalizedEntry}/`)) return normalizeDocsPathSegment(normalizedPath.slice(normalizedEntry.length + 1));
+	return normalizeDocsPathSegment(normalizedPath);
+}
+function limitDocsRecoverySlug(value) {
+	return value.slice(0, DOCS_MARKDOWN_RECOVERY_SLUG_MAX_LENGTH);
+}
+function tokenizeDocsRecoveryText(value) {
+	return normalizeDocsRecoveryText(value).split(/\s+/).filter((token) => token.length > 1);
+}
+function levenshteinDistance(a, b) {
+	if (a === b) return 0;
+	if (!a) return b.length;
+	if (!b) return a.length;
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	let current = new Array(b.length + 1);
+	for (let i = 1; i <= a.length; i += 1) {
+		current[0] = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+			current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, substitution);
+		}
+		[previous, current] = [current, previous];
+	}
+	return previous[b.length] ?? Math.max(a.length, b.length);
+}
+function normalizedEditSimilarity(a, b) {
+	if (!a || !b) return 0;
+	if (a === b) return 1;
+	const maxLength = Math.max(a.length, b.length);
+	if (maxLength === 0) return 1;
+	return Math.max(0, 1 - levenshteinDistance(a, b) / maxLength);
+}
+function tokenOverlapScore(requestedTokens, candidateTokens) {
+	if (requestedTokens.length === 0 || candidateTokens.length === 0) return 0;
+	const candidates = new Set(candidateTokens);
+	return requestedTokens.filter((token) => candidates.has(token)).length / requestedTokens.length;
+}
+function sameDocsRecoveryParent(a, b) {
+	const aParts = a.split("/").filter(Boolean);
+	const bParts = b.split("/").filter(Boolean);
+	if (aParts.length !== bParts.length || aParts.length === 0) return false;
+	return aParts.slice(0, -1).join("/") === bParts.slice(0, -1).join("/");
+}
+function scoreDocsMarkdownRecoveryMatch({ entry, requestedPath, page }) {
+	const requestedSlug = limitDocsRecoverySlug(normalizeDocsRecoverySlug(entry, requestedPath));
+	const pageSlug = limitDocsRecoverySlug(normalizeDocsRecoverySlug(entry, page.url));
+	const requestedLast = requestedSlug.split("/").filter(Boolean).at(-1) ?? requestedSlug;
+	const pageLast = pageSlug.split("/").filter(Boolean).at(-1) ?? pageSlug;
+	const title = normalizeDocsRecoveryText(page.title);
+	const requestedText = normalizeDocsRecoveryText(requestedSlug.replace(/\//g, " "));
+	const requestedTokens = tokenizeDocsRecoveryText(requestedText);
+	const candidateTokens = tokenizeDocsRecoveryText([
+		pageSlug.replace(/\//g, " "),
+		page.title,
+		page.description ?? ""
+	].join(" "));
+	const pathDistance = levenshteinDistance(requestedSlug, pageSlug);
+	const segmentDistance = levenshteinDistance(requestedLast, pageLast);
+	if (requestedSlug && pageSlug && (sameDocsRecoveryParent(requestedSlug, pageSlug) && segmentDistance <= 1 || pathDistance <= 1)) return .995;
+	const pathSimilarity = normalizedEditSimilarity(requestedSlug, pageSlug);
+	const segmentSimilarity = normalizedEditSimilarity(requestedLast, pageLast);
+	const titleSimilarity = normalizedEditSimilarity(requestedText, title);
+	const overlap = tokenOverlapScore(requestedTokens, candidateTokens);
+	const substringBoost = requestedText && (pageSlug.includes(requestedSlug) || title.includes(requestedText) || requestedText.includes(title)) ? .12 : 0;
+	return Math.min(.98, Math.max(pathSimilarity * .86, segmentSimilarity * .8, titleSimilarity * .72, overlap * .75) + substringBoost);
+}
+function resolveDocsMarkdownRecovery({ entry = "docs", requestedPath, pages = [] }) {
+	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const matches = pages.map((page) => ({
+		page,
+		confidence: scoreDocsMarkdownRecoveryMatch({
+			entry: normalizedEntry,
+			requestedPath,
+			page
+		})
+	})).filter((item) => item.confidence >= .35).sort((a, b) => {
+		if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+		return a.page.url.localeCompare(b.page.url);
+	}).slice(0, DOCS_MARKDOWN_RECOVERY_MATCH_LIMIT).map(({ page, confidence }) => ({
+		title: page.title,
+		url: normalizeDocsUrlPath(page.url),
+		markdownUrl: toDocsMarkdownUrl(page.url),
+		description: page.description,
+		confidence
+	}));
+	return {
+		matches,
+		redirect: matches[0] && matches[0].confidence >= DOCS_MARKDOWN_RECOVERY_REDIRECT_CONFIDENCE ? matches[0] : void 0
+	};
+}
+function renderDocsMarkdownSitemapFooter(sitemap) {
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap);
+	const lines = ["## Sitemap", ""];
+	if (sitemapConfig.enabled && sitemapConfig.markdown.enabled) {
+		lines.push(`See the full [sitemap](${sitemapConfig.markdown.route}) for all pages.`);
+		if (sitemapConfig.markdown.docsRoute) lines.push(`Docs-scoped sitemap: [${sitemapConfig.markdown.docsRoute}](${sitemapConfig.markdown.docsRoute}).`);
+		lines.push(`Well-known sitemap: [${sitemapConfig.markdown.wellKnownRoute}](${sitemapConfig.markdown.wellKnownRoute}).`);
+	} else if (sitemapConfig.enabled && sitemapConfig.xml.enabled) lines.push(`See the XML [sitemap](${sitemapConfig.xml.route}) for all pages.`);
+	else lines.push("Sitemap discovery is not enabled for this deployment.");
+	return lines.join("\n");
+}
+function appendDocsMarkdownSitemapFooter(markdown, sitemap) {
+	if (/^##\s+Sitemap\s*$/im.test(markdown)) return markdown;
+	return `${markdown.replace(/\s+$/g, "")}\n\n${renderDocsMarkdownSitemapFooter(sitemap)}\n`;
+}
+function normalizeDocsMarkdownLastUpdated(value) {
+	if (!value) return void 0;
+	const trimmed = value.trim();
+	const dateOnly = trimmed.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+	if (dateOnly) return dateOnly;
+	const date = new Date(trimmed);
+	if (Number.isNaN(date.getTime())) return void 0;
+	return date.toISOString().slice(0, 10);
+}
+function resolveDocsMarkdownMetadataUrl(value, origin) {
+	if (!origin) return value;
+	try {
+		return new URL(value, origin).toString();
+	} catch {
+		return value;
+	}
+}
+function renderDocsMarkdownFrontmatter({ title, description, canonicalUrl, markdownUrl, lastUpdated, trust, agent, generatedPreamble }) {
+	return [
+		"---",
+		`title: ${toYamlString(title)}`,
+		...description ? [`description: ${toYamlString(description)}`] : [],
+		`canonical_url: ${toYamlString(canonicalUrl)}`,
+		`markdown_url: ${toYamlString(markdownUrl)}`,
+		...lastUpdated ? [`last_updated: ${toYamlString(lastUpdated)}`] : [],
+		...trust ? [`okf: ${JSON.stringify(trust)}`] : [],
+		...generatedPreamble ? [`${DOCS_MARKDOWN_GENERATED_PREAMBLE_FIELD}: true`] : [],
+		...renderPageAgentFrontmatterYamlLines(agent),
+		"---"
+	].join("\n");
+}
+function hasDocsMarkdownFrontmatter(markdown) {
+	return /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.test(markdown);
+}
+function prependDocsMarkdownFrontmatter(markdown, metadata) {
+	if (hasDocsMarkdownFrontmatter(markdown)) return markdown;
+	return `${renderDocsMarkdownFrontmatter(metadata)}\n\n${markdown.replace(/^\r?\n+/, "")}`;
+}
+function stripDocsMarkdownFrontmatter(markdown) {
+	const match = markdown.match(/^(---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$))([\s\S]*)$/);
+	if (!match) return {
+		frontmatter: "",
+		body: markdown
+	};
+	return {
+		frontmatter: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+function resolveDocsMarkdownSectionBody(document) {
+	const stripped = stripDocsMarkdownFrontmatter(document);
+	const hasGeneratedPreamble = stripped.frontmatter.split(/\r?\n/u).some((line) => line.trim() === `${DOCS_MARKDOWN_GENERATED_PREAMBLE_FIELD}: true`);
+	const lines = stripped.body.split(/\r?\n/u);
+	let generatedPreambleStart = 0;
+	while (generatedPreambleStart < lines.length && (lines[generatedPreambleStart] ?? "").trim() === "") generatedPreambleStart += 1;
+	if (hasGeneratedPreamble && /^#(?:\s+|$)/u.test(lines[generatedPreambleStart] ?? "") && /^URL:\s+\S/u.test(lines[generatedPreambleStart + 1] ?? "")) {
+		lines[generatedPreambleStart] = "";
+		let metadataEnd = generatedPreambleStart + 2;
+		while (/^(?:LLM index|Description|Related):\s*/u.test(lines[metadataEnd] ?? "")) metadataEnd += 1;
+		for (let index = generatedPreambleStart + 1; index < metadataEnd; index += 1) lines[index] = "";
+	}
+	return {
+		body: lines.join("\n").replace(/\n{2,}## Sitemap\n\n(?:(?:See the (?:full|XML) \[sitemap\]\()|Sitemap discovery is not enabled)[\s\S]*$/u, ""),
+		lineOffset: 0
+	};
+}
+function estimateDocsMarkdownTokens(value) {
+	if (!value) return 0;
+	return Math.max(1, Math.ceil(docsMarkdownUtf8Bytes(value) / 4));
+}
+function docsMarkdownUtf8Bytes(value) {
+	return new TextEncoder().encode(value).byteLength;
+}
+function trimDocsMarkdownToByteBudget(value, byteBudget) {
+	if (docsMarkdownUtf8Bytes(value) <= byteBudget) return value;
+	let output = "";
+	let bytes = 0;
+	const encoder = new TextEncoder();
+	for (const character of value) {
+		const characterBytes = encoder.encode(character).byteLength;
+		if (bytes + characterBytes > byteBudget) break;
+		output += character;
+		bytes += characterBytes;
+	}
+	return output.trimEnd();
+}
+function truncateDocsMarkdownSectionContent(content, request) {
+	const budgets = [typeof request.byteBudget === "number" ? request.byteBudget : void 0, typeof request.tokenBudget === "number" ? request.tokenBudget * 4 : void 0].filter((budget) => budget !== void 0 && Number.isSafeInteger(budget) && budget > 0);
+	const byteBudget = budgets.length > 0 ? Math.min(...budgets) : void 0;
+	if (!byteBudget || docsMarkdownUtf8Bytes(content) <= byteBudget) return {
+		document: content,
+		truncated: false
+	};
+	const fullMarker = "\n\n<!-- section truncated: increase tokenBudget or byteBudget for more. -->";
+	const marker = docsMarkdownUtf8Bytes(fullMarker) <= byteBudget ? fullMarker : "\n\n<!-- section truncated -->";
+	if (docsMarkdownUtf8Bytes(marker) > byteBudget) return {
+		document: trimDocsMarkdownToByteBudget(marker.trimStart(), byteBudget),
+		truncated: true
+	};
+	let truncated = trimDocsMarkdownToByteBudget(content, Math.max(0, byteBudget - docsMarkdownUtf8Bytes(marker)));
+	const paragraphBoundary = truncated.lastIndexOf("\n\n");
+	if (paragraphBoundary > 0 && paragraphBoundary > truncated.length * .45) truncated = truncated.slice(0, paragraphBoundary).trimEnd();
+	return {
+		document: `${truncated}${marker}`,
+		truncated: true
+	};
+}
+function parsePositiveDocsMarkdownBudget(value) {
+	if (!value) return null;
+	const parsed = Number.parseInt(value.replace(/_/g, ""), 10);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) return null;
+	return Math.min(parsed, DOCS_MARKDOWN_SECTION_MAX_BUDGET);
+}
+function resolveDocsMarkdownSectionRequest(url) {
+	const section = url.searchParams.get("section")?.trim() || null;
+	const tokenBudget = parsePositiveDocsMarkdownBudget(url.searchParams.get("tokenBudget")) ?? parsePositiveDocsMarkdownBudget(url.searchParams.get("tokens"));
+	const byteBudget = parsePositiveDocsMarkdownBudget(url.searchParams.get("byteBudget")) ?? parsePositiveDocsMarkdownBudget(url.searchParams.get("bytes"));
+	if (!section && tokenBudget === null && byteBudget === null) return null;
+	return {
+		section,
+		tokenBudget,
+		byteBudget
+	};
+}
+function isDocsMarkdownSectionIndexRequest(url) {
+	if (!url.searchParams.has("sections")) return false;
+	const value = url.searchParams.get("sections")?.trim().toLowerCase();
+	return value === void 0 || ![
+		"0",
+		"false",
+		"no",
+		"off"
+	].includes(value);
+}
+function collectDocsMarkdownSections(document) {
+	const { body, lineOffset } = resolveDocsMarkdownSectionBody(document);
+	return parseDocsMarkdownSections(body).map((section) => ({
+		id: section.anchor,
+		heading: section.title,
+		level: section.level,
+		content: section.content,
+		startLine: section.startLine + lineOffset,
+		endLine: section.endLine + lineOffset
+	}));
+}
+function updateDocsMarkdownUrl(value, update) {
+	const isAbsolute = /^[a-z][a-z\d+.-]*:/iu.test(value);
+	try {
+		const url = new URL(value, "https://docs.invalid");
+		update(url);
+		return (isAbsolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`).replace(/([?&])sections=(?=&|$)/u, "$1sections");
+	} catch {
+		return value;
+	}
+}
+function resolveDocsMarkdownSectionCanonicalUrl(canonicalUrl, sectionId) {
+	return updateDocsMarkdownUrl(canonicalUrl, (url) => {
+		url.hash = encodeURIComponent(sectionId);
+	});
+}
+function resolveDocsMarkdownSectionFetchUrl(markdownUrl, sectionId, request) {
+	return updateDocsMarkdownUrl(markdownUrl, (url) => {
+		url.searchParams.delete("sections");
+		url.searchParams.delete("section");
+		url.searchParams.delete("tokens");
+		url.searchParams.delete("bytes");
+		url.searchParams.delete("tokenBudget");
+		url.searchParams.delete("byteBudget");
+		url.searchParams.set("section", sectionId);
+		if (request.tokenBudget) url.searchParams.set("tokenBudget", String(request.tokenBudget));
+		if (request.byteBudget) url.searchParams.set("byteBudget", String(request.byteBudget));
+	});
+}
+function resolveDocsMarkdownSectionIndexUrl(markdownUrl, request) {
+	return updateDocsMarkdownUrl(markdownUrl, (url) => {
+		url.searchParams.delete("sections");
+		url.searchParams.delete("section");
+		url.searchParams.delete("tokens");
+		url.searchParams.delete("bytes");
+		url.searchParams.delete("tokenBudget");
+		url.searchParams.delete("byteBudget");
+		url.searchParams.set("sections", "");
+		if (request.tokenBudget) url.searchParams.set("tokenBudget", String(request.tokenBudget));
+		if (request.byteBudget) url.searchParams.set("byteBudget", String(request.byteBudget));
+	});
+}
+function buildDocsMarkdownSectionIndex(document, options) {
+	const request = {
+		tokenBudget: options.tokenBudget ?? void 0,
+		byteBudget: options.byteBudget ?? void 0
+	};
+	const sections = collectDocsMarkdownSections(document);
+	const ancestors = [];
+	const metadata = sections.map((section) => {
+		while (ancestors.length > 0 && (ancestors[ancestors.length - 1]?.level ?? Number.NEGATIVE_INFINITY) >= section.level) ancestors.pop();
+		const parentId = ancestors.at(-1)?.id;
+		const item = {
+			id: section.id,
+			heading: section.heading,
+			level: section.level,
+			...parentId ? { parentId } : {},
+			startLine: section.startLine,
+			endLine: section.endLine,
+			estimatedTokens: estimateDocsMarkdownTokens(section.content),
+			utf8Bytes: docsMarkdownUtf8Bytes(section.content),
+			canonicalUrl: resolveDocsMarkdownSectionCanonicalUrl(options.canonicalUrl, section.id),
+			markdownUrl: resolveDocsMarkdownSectionFetchUrl(options.markdownUrl, section.id, request)
+		};
+		ancestors.push(section);
+		return item;
+	});
+	const fetchBudget = request.tokenBudget || request.byteBudget ? {
+		...request.tokenBudget ? { tokenBudget: request.tokenBudget } : {},
+		...request.byteBudget ? { byteBudget: request.byteBudget } : {}
+	} : void 0;
+	return {
+		schemaVersion: 2,
+		format: DOCS_MARKDOWN_SECTION_INDEX_FORMAT,
+		canonicalUrl: options.canonicalUrl,
+		markdownUrl: options.markdownUrl,
+		sectionIndexUrl: options.sectionIndexUrl ?? resolveDocsMarkdownSectionIndexUrl(options.markdownUrl, request),
+		lineNumbering: "body",
+		sectionCount: metadata.length,
+		estimatedTokens: estimateDocsMarkdownTokens(document),
+		utf8Bytes: docsMarkdownUtf8Bytes(document),
+		...fetchBudget ? { fetchBudget } : {},
+		sections: metadata
+	};
+}
+function normalizeRequestedDocsMarkdownSectionId(requestedSection) {
+	let selector = requestedSection.trim();
+	const hashIndex = selector.indexOf("#");
+	if (hashIndex >= 0) selector = selector.slice(hashIndex + 1);
+	try {
+		selector = decodeURIComponent(selector);
+	} catch {}
+	return selector;
+}
+function selectDocsMarkdownSection(document, request) {
+	const availableSections = collectDocsMarkdownSections(document);
+	const requestedSection = request.section?.trim();
+	if (!requestedSection) {
+		const { document: budgetedDocument, truncated } = truncateDocsMarkdownSectionContent(document, request);
+		return {
+			found: true,
+			document: budgetedDocument,
+			truncated,
+			tokenBudget: request.tokenBudget ?? void 0,
+			byteBudget: request.byteBudget ?? void 0,
+			estimatedTokens: estimateDocsMarkdownTokens(budgetedDocument),
+			utf8Bytes: docsMarkdownUtf8Bytes(budgetedDocument),
+			availableSections
+		};
+	}
+	const rawRequestedId = requestedSection.trim();
+	const rawExactSection = availableSections.find((candidate) => candidate.id === rawRequestedId);
+	const requestedId = normalizeRequestedDocsMarkdownSectionId(requestedSection);
+	const exactSection = rawExactSection ?? availableSections.find((candidate) => candidate.id === requestedId);
+	const caseInsensitiveSections = exactSection ? [] : availableSections.filter((candidate) => candidate.id.toLowerCase() === requestedId.toLowerCase());
+	const directSection = exactSection ?? (caseInsensitiveSections.length === 1 ? caseInsensitiveSections[0] : void 0);
+	const { body, lineOffset } = resolveDocsMarkdownSectionBody(document);
+	const selectedSharedSection = directSection ? void 0 : findDocsMarkdownSection(body, requestedSection);
+	const sharedAliasSection = selectedSharedSection ? availableSections.find((candidate) => candidate.startLine === selectedSharedSection.startLine + lineOffset) : void 0;
+	const section = directSection ?? sharedAliasSection;
+	if (!section) {
+		const lines = [
+			"# Markdown Section Not Found",
+			"",
+			requestedSection ? `Could not find section \`${requestedSection}\`.` : "No Markdown sections were available in this page."
+		];
+		if (availableSections.length > 0) lines.push("", "## Available Sections", "", ...availableSections.map((candidate) => `- ${candidate.heading} (#${candidate.id})`));
+		const notFoundDocument = lines.join("\n");
+		return {
+			found: false,
+			requestedSection,
+			document: notFoundDocument,
+			truncated: false,
+			tokenBudget: request.tokenBudget ?? void 0,
+			byteBudget: request.byteBudget ?? void 0,
+			estimatedTokens: estimateDocsMarkdownTokens(notFoundDocument),
+			utf8Bytes: docsMarkdownUtf8Bytes(notFoundDocument),
+			availableSections
+		};
+	}
+	const { document: selectedDocument, truncated } = truncateDocsMarkdownSectionContent(section.content, request);
+	return {
+		found: true,
+		requestedSection,
+		section,
+		document: selectedDocument,
+		truncated,
+		tokenBudget: request.tokenBudget ?? void 0,
+		byteBudget: request.byteBudget ?? void 0,
+		estimatedTokens: estimateDocsMarkdownTokens(selectedDocument),
+		utf8Bytes: docsMarkdownUtf8Bytes(selectedDocument),
+		availableSections
+	};
+}
+function resolveDocsMarkdownPageMetadata(page, options) {
+	const canonicalUrl = resolveDocsMarkdownMetadataUrl(page.url, options?.origin);
+	const okfEnabled = resolveDocsOkfConfig(options?.okf).enabled || page.okf !== void 0;
+	return {
+		title: page.title,
+		description: page.description,
+		canonicalUrl,
+		markdownUrl: resolveDocsMarkdownMetadataUrl(page.markdownUrl ?? toDocsMarkdownUrl(page.url), options?.origin),
+		lastUpdated: normalizeDocsMarkdownLastUpdated(page.lastmod ?? page.lastModified),
+		agent: page.agent,
+		...okfEnabled ? { trust: resolveDocsOkfTrustMetadata({
+			...page,
+			canonicalUrl
+		}, options?.okf) } : {}
+	};
+}
+function renderDocsMarkdownNotFound({ entry = "docs", apiRoute, requestedPath, origin, pages, sitemap }) {
+	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(apiRoute);
+	const agentSpecApiRoute = resolvedApiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${resolvedApiRoute}?agent=spec`;
+	const normalizedRequest = normalizeRequestedMarkdownPath(normalizedEntry, requestedPath);
+	const slugPrefix = `/${normalizedEntry}/`;
+	const requestedSlug = normalizedRequest === `/${normalizedEntry}` ? "" : normalizedRequest.slice(slugPrefix.length);
+	const encodedRequestedSlug = requestedSlug.split("/").map(encodeURIComponent).join("/");
+	const requestedMarkdownRoute = toDocsMarkdownUrl(normalizedRequest);
+	const requestedApiRoute = requestedSlug ? `${resolvedApiRoute}?format=markdown&path=${encodedRequestedSlug}` : `${resolvedApiRoute}?format=markdown`;
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap);
+	const recovery = resolveDocsMarkdownRecovery({
+		entry: normalizedEntry,
+		requestedPath,
+		pages
+	});
+	const lines = [
+		"# Docs Page Not Found",
+		"",
+		`Could not find a markdown page for \`${requestedMarkdownRoute}\`.`
+	];
+	if (recovery.matches.length > 0) {
+		lines.push("", "## Closest Matches", "");
+		for (const match of recovery.matches) {
+			const confidence = `${Math.round(match.confidence * 1e3) / 10}%`;
+			lines.push(`- [${match.title}](${match.markdownUrl}) (${confidence} confidence)${match.description ? ` - ${match.description}` : ""}`);
+		}
+	}
+	lines.push("", "## Recovery", "", "- If a closest match looks right, fetch that markdown URL directly.", "- If the match is uncertain, search the docs first and then fetch the smallest page that answers the task.", "- Use the sitemap routes below to browse the full docs index before guessing another slug.", "", "## Discovery Routes", "", "Use these discovery routes to find the right page:", "", `- Agent discovery spec: \`${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}\``, `- Agent discovery fallback: \`${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}\``, `- Agent discovery API: \`${agentSpecApiRoute}\``, `- API catalog: \`${DEFAULT_API_CATALOG_ROUTE}\``, `- Agent Skills index: \`${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}\``, `- Agent instructions: \`${DEFAULT_AGENTS_MD_ROUTE}\``, `- Search scope facets: \`${resolvedApiRoute}?audience=agent&response=facets\` (discover valid \`framework\`, \`version\`, \`package\`, and \`tags\` values without page bodies; continue large fields with \`facet={field}&limit={limit}&cursor={nextCursor}\`).`, `- Structured agent search: \`${resolvedApiRoute}?query={query}&audience=agent&response=structured\` (optionally repeat \`framework\`, \`version\`, \`package\`, or \`tags\`).`, `- Docs index markdown: \`/${normalizedEntry}.md\``, `- Requested markdown API route: \`${requestedApiRoute}\``);
+	if (sitemapConfig.enabled) {
+		if (sitemapConfig.markdown.enabled) {
+			lines.push(`- Semantic sitemap: \`${sitemapConfig.markdown.route}\``);
+			if (sitemapConfig.markdown.docsRoute) lines.push(`- Docs-scoped sitemap alias: \`${sitemapConfig.markdown.docsRoute}\``);
+			lines.push(`- Semantic sitemap well-known alias: \`${sitemapConfig.markdown.wellKnownRoute}\``);
+		}
+		if (sitemapConfig.xml.enabled) lines.push(`- XML sitemap: \`${sitemapConfig.xml.route}\``);
+	} else lines.push(`- Sitemap discovery, if enabled: \`${DEFAULT_SITEMAP_MD_ROUTE}\`, \`${DEFAULT_SITEMAP_MD_DOCS_ROUTE}\`, \`${DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE}\`, or \`${DEFAULT_SITEMAP_XML_ROUTE}\``);
+	lines.push("", "The agent discovery spec is the safest first step because it lists the active markdown, sitemap, robots, search, MCP, and feedback routes for this deployment.");
+	return appendDocsMarkdownSitemapFooter(prependDocsMarkdownFrontmatter(lines.join("\n"), {
+		title: "Docs Page Not Found",
+		description: `Could not find a markdown page for ${requestedMarkdownRoute}.`,
+		canonicalUrl: resolveDocsMarkdownMetadataUrl(normalizedRequest, origin),
+		markdownUrl: resolveDocsMarkdownMetadataUrl(requestedMarkdownRoute, origin)
+	}), sitemap);
+}
+function extractDocsMarkdownLastModified(document) {
+	const frontmatter = document.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+	if (!frontmatter) return void 0;
+	const raw = frontmatter.match(/^last_updated:\s*(.+?)\s*$/m)?.[1]?.trim();
+	if (!raw) return void 0;
+	if (raw.startsWith("\"") && raw.endsWith("\"") || raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+	return raw;
+}
+function resolveDocsMarkdownContentLocation(canonicalUrl) {
+	const url = new URL(canonicalUrl);
+	url.pathname = toDocsMarkdownUrl(url.pathname);
+	return url.toString();
+}
+function appendDocsMarkdownSectionQuery(value, sectionRequest) {
+	try {
+		const url = new URL(value);
+		if (sectionRequest.section) url.searchParams.set("section", sectionRequest.section);
+		if (sectionRequest.tokenBudget) url.searchParams.set("tokenBudget", String(sectionRequest.tokenBudget));
+		if (sectionRequest.byteBudget) url.searchParams.set("byteBudget", String(sectionRequest.byteBudget));
+		return url.toString();
+	} catch {
+		return value;
+	}
+}
+/** Build one standards-aware Markdown response for every framework adapter. */
+function createDocsMarkdownResponse(options) {
+	const { request, document, entry = "docs", requestedPath, origin = new URL(request.url).origin, pages: rawPages, sitemap, locale } = options;
+	const canonicalUrl = options.canonicalUrl ?? resolveDocsMarkdownCanonicalUrl({
+		origin,
+		entry,
+		requestedPath,
+		locale
+	});
+	const contentLocation = options.contentLocation ?? resolveDocsMarkdownContentLocation(canonicalUrl);
+	const varyHeader = getDocsMarkdownVaryHeader(request);
+	const llmsTxtUrl = new URL(DEFAULT_LLMS_TXT_ROUTE, origin).toString();
+	const discoveryLink = `<${llmsTxtUrl}>; rel="describedby"; type="text/plain"`;
+	const baseSharedHeaders = {
+		"X-Robots-Tag": "noindex",
+		"X-Llms-Txt": llmsTxtUrl,
+		...locale ? { "Content-Language": locale } : {},
+		...varyHeader ? { Vary: varyHeader } : {}
+	};
+	const pages = rawPages ? filterDocsPagesByAccess(rawPages, options.principal) : void 0;
+	if (!isDocsPageAccessAllowed(options.access, options.principal)) return new Response("Not Found", {
+		status: 404,
+		headers: {
+			...baseSharedHeaders,
+			"Cache-Control": "private, no-store",
+			"Content-Type": "text/plain; charset=utf-8"
+		}
+	});
+	if (!document) {
+		const recovery = resolveDocsMarkdownRecovery({
+			entry,
+			requestedPath,
+			pages,
+			sitemap
+		});
+		if (recovery.redirect) return new Response(null, {
+			status: 307,
+			headers: {
+				...baseSharedHeaders,
+				"Content-Location": contentLocation,
+				Link: `<${canonicalUrl}>; rel="canonical", ${discoveryLink}`,
+				"Cache-Control": "no-store",
+				Location: new URL(recovery.redirect.markdownUrl, request.url).toString()
+			}
+		});
+		return new Response(renderDocsMarkdownNotFound({
+			entry,
+			apiRoute: options.apiRoute,
+			requestedPath,
+			origin,
+			pages,
+			sitemap
+		}), {
+			status: 404,
+			headers: {
+				...baseSharedHeaders,
+				"Content-Location": contentLocation,
+				Link: `<${canonicalUrl}>; rel="canonical", ${discoveryLink}`,
+				"Cache-Control": "no-store",
+				"Content-Type": "text/markdown; charset=utf-8"
+			}
+		});
+	}
+	const requestUrl = new URL(request.url);
+	const sectionRequest = resolveDocsMarkdownSectionRequest(requestUrl);
+	if (isDocsMarkdownSectionIndexRequest(requestUrl)) {
+		const sectionIndexRequest = sectionRequest ?? {};
+		const sectionIndexContentLocation = resolveDocsMarkdownSectionIndexUrl(contentLocation, sectionIndexRequest);
+		const sectionIndex = buildDocsMarkdownSectionIndex(document, {
+			canonicalUrl,
+			markdownUrl: contentLocation,
+			sectionIndexUrl: sectionIndexContentLocation,
+			tokenBudget: sectionIndexRequest.tokenBudget,
+			byteBudget: sectionIndexRequest.byteBudget
+		});
+		const responseDocument = JSON.stringify(sectionIndex);
+		const lastModified = resolveDocsHttpDate(options.lastModified ?? extractDocsMarkdownLastModified(document));
+		return createDocsCacheableResponse({
+			request,
+			content: responseDocument,
+			lastModified,
+			headers: {
+				...baseSharedHeaders,
+				"Content-Location": sectionIndexContentLocation,
+				Link: `<${canonicalUrl}>; rel="canonical", <${contentLocation}>; rel="alternate"; type="text/markdown", ${discoveryLink}`,
+				"Cache-Control": options.cacheControl ?? "public, max-age=0, s-maxage=3600",
+				"Content-Type": "application/json; charset=utf-8",
+				"X-Docs-Markdown-Section-Index": DOCS_MARKDOWN_SECTION_INDEX_FORMAT,
+				"X-Docs-Markdown-Section-Count": String(sectionIndex.sectionCount),
+				"X-Docs-Markdown-Source-Estimated-Tokens": String(sectionIndex.estimatedTokens),
+				"X-Docs-Markdown-Source-Utf8-Bytes": String(sectionIndex.utf8Bytes),
+				"X-Docs-Markdown-Estimated-Tokens": String(estimateDocsMarkdownTokens(responseDocument)),
+				"X-Docs-Markdown-Utf8-Bytes": String(docsMarkdownUtf8Bytes(responseDocument)),
+				...sectionIndexRequest.tokenBudget ? { "X-Docs-Markdown-Token-Budget": String(sectionIndexRequest.tokenBudget) } : {},
+				...sectionIndexRequest.byteBudget ? { "X-Docs-Markdown-Byte-Budget": String(sectionIndexRequest.byteBudget) } : {},
+				...lastModified ? { "Last-Modified": lastModified } : {}
+			}
+		});
+	}
+	const sectionResult = sectionRequest ? selectDocsMarkdownSection(document, sectionRequest) : void 0;
+	const responseDocument = sectionResult?.document ?? document;
+	const sectionCanonicalUrl = sectionResult?.found && sectionResult.section ? resolveDocsMarkdownSectionCanonicalUrl(canonicalUrl, sectionResult.section.id) : canonicalUrl;
+	const sectionContentLocation = sectionRequest ? appendDocsMarkdownSectionQuery(contentLocation, sectionRequest) : contentLocation;
+	const sectionHeaders = sectionResult ? {
+		"X-Docs-Markdown-Section": sectionResult.section ? encodeURIComponent(sectionResult.section.id) : "",
+		"X-Docs-Markdown-Section-Found": sectionResult.found ? "true" : "false",
+		"X-Docs-Markdown-Section-Truncated": sectionResult.truncated ? "true" : "false",
+		"X-Docs-Markdown-Estimated-Tokens": String(sectionResult.estimatedTokens),
+		"X-Docs-Markdown-Utf8-Bytes": String(sectionResult.utf8Bytes),
+		...sectionResult.tokenBudget ? { "X-Docs-Markdown-Token-Budget": String(sectionResult.tokenBudget) } : {},
+		...sectionResult.byteBudget ? { "X-Docs-Markdown-Byte-Budget": String(sectionResult.byteBudget) } : {}
+	} : {};
+	const lastModified = resolveDocsHttpDate(options.lastModified ?? extractDocsMarkdownLastModified(document));
+	const responseHeaders = {
+		...baseSharedHeaders,
+		"Content-Location": sectionContentLocation,
+		Link: `<${sectionCanonicalUrl}>; rel="canonical", ${discoveryLink}`,
+		"Cache-Control": sectionResult?.found === false ? "no-store" : options.cacheControl ?? "public, max-age=0, s-maxage=3600",
+		"Content-Type": "text/markdown; charset=utf-8",
+		...sectionHeaders,
+		...lastModified ? { "Last-Modified": lastModified } : {}
+	};
+	return createDocsCacheableResponse({
+		request,
+		content: responseDocument,
+		status: sectionResult?.found === false ? 404 : 200,
+		lastModified,
+		headers: responseHeaders
+	});
+}
+function findDocsMarkdownPage(entry, pages, requestedPath) {
+	const normalizedRequest = normalizeRequestedMarkdownPath(entry, requestedPath);
+	for (const page of pages) if (normalizeDocsUrlPath(page.url) === normalizedRequest) return page;
+	const normalizedSlug = normalizeDocsPathSegment(requestedPath.replace(/^\//, "").replace(/\.md$/i, ""));
+	for (const page of pages) if (page.slug !== void 0 && normalizeDocsPathSegment(page.slug) === normalizedSlug) return page;
+	return null;
+}
+function shouldRenderLlmsDirective(options) {
+	if (options?.llms === false) return false;
+	if (options?.llms && typeof options.llms === "object" && options.llms.enabled === false) return false;
+	return true;
+}
+function resolveDocsAgentDocumentContext({ entry = "docs", apiRoute, apiCatalog: explicitApiCatalog, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi, markdown }) {
+	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(apiRoute);
+	const openapiConfig = resolveDocsOpenApiDiscoveryConfig(openapi);
+	return {
+		apiRoute: resolvedApiRoute,
+		normalizedEntry: normalizeDocsPathSegment(entry) || "docs",
+		siteTitle: compactSkillText(llms?.siteTitle ?? "Documentation"),
+		siteDescription: llms?.siteDescription ? compactSkillText(llms.siteDescription) : void 0,
+		llmsEnabled: llms?.enabled ?? true,
+		searchEnabled: isSearchEnabled(search),
+		contentChangesEnabled: resolveDocsContentChangesConfig(contentChanges).enabled,
+		mcpEnabled: mcp.enabled,
+		feedbackEnabled: feedback?.enabled ?? false,
+		sitemapConfig: resolveDocsSitemapConfig(sitemap),
+		robotsEnabled: isRobotsDiscoveryEnabled(robots),
+		openapiConfig: {
+			...openapiConfig,
+			url: resolveDocsOpenApiDiscoveryUrl(openapiConfig, resolvedApiRoute)
+		},
+		feedbackRoute,
+		feedbackSchemaRoute: feedback?.schemaRoute ?? `${feedbackRoute}/schema`,
+		llmsSections: resolveDocsLlmsTxtSections(llms),
+		markdownAcceptHeader: markdown?.acceptHeader === false ? null : "text/markdown",
+		markdownSignatureAgentHeader: markdown?.signatureAgentHeader === false ? null : DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER,
+		markdownSectionDiscoveryEnabled: markdown?.sectionDiscovery !== false,
+		apiCatalogEnabled: explicitApiCatalog ?? llms?.apiCatalog ?? true
+	};
+}
+function appendDocsMarkdownNegotiationStartLines(lines, context, variant) {
+	if (context.markdownAcceptHeader) lines.push(variant === "skill" ? `- You can also request ${context.markdownAcceptHeader} from normal page URLs.` : `- Normal docs pages can return markdown with Accept: ${context.markdownAcceptHeader}.`);
+	if (context.markdownSignatureAgentHeader) lines.push(variant === "skill" ? `- Requests with ${context.markdownSignatureAgentHeader} on normal page URLs receive markdown automatically.` : `- Normal docs pages can also return markdown when ${context.markdownSignatureAgentHeader} is present.`);
+}
+function appendDocsSearchStartLine(lines, context, variant) {
+	if (!context.searchEnabled) return;
+	lines.push(`- Discover valid search filters with ${context.apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tags values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, variant === "skill" ? `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; optionally repeat framework, version, package, or tags filters and add explain=true for retrieval evidence.` : `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; optionally repeat framework, version, package, or tags filters and add explain=true for retrieval evidence.`);
+}
+function appendDocsContentChangesStartLine(lines, context) {
+	if (!context.contentChangesEnabled) return;
+	lines.push(`- Synchronize changed documents with ${context.apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}; pass the returned indexGeneration as since on the next request and clear stale state when resetRequired is true.`);
+}
+function appendDocsOpenApiStartLine(lines, context, variant) {
+	if (!context.openapiConfig.enabled || !context.openapiConfig.url) return;
+	lines.push(variant === "skill" ? `- Fetch ${context.openapiConfig.url} for the machine-readable OpenAPI schema before scraping API reference pages.` : `- Fetch ${context.openapiConfig.url} before scraping API reference pages; prefer schemas over prose.`);
+}
+function appendDocsLlmsStartLines(lines, context, variant) {
+	if (!context.llmsEnabled) return;
+	lines.push(variant === "skill" ? `- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.` : `- Use ${DEFAULT_LLMS_TXT_ROUTE} as the compact docs map.`, variant === "skill" ? `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.` : `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} when you need the full markdown bundle.`);
+	for (const section of context.llmsSections) lines.push(variant === "skill" ? `- Use ${section.route} for the ${section.title} llms.txt section.` : `- Use ${section.route} for the ${section.title} section map.`);
+}
+function appendDocsSitemapStartLines(lines, context, variant) {
+	if (!context.sitemapConfig.enabled) return;
+	if (variant === "skill") {
+		if (context.sitemapConfig.xml.enabled) lines.push(`- Use ${context.sitemapConfig.xml.route} to check canonical page freshness.`);
+		if (context.sitemapConfig.markdown.enabled) lines.push(`- Use ${context.sitemapConfig.markdown.route} for a semantic docs map.`);
+		return;
+	}
+	if (context.sitemapConfig.markdown.enabled) lines.push(`- Use ${context.sitemapConfig.markdown.route} for a semantic sitemap with sections.`);
+	if (context.sitemapConfig.xml.enabled) lines.push(`- Use ${context.sitemapConfig.xml.route} for canonical URLs and freshness metadata.`);
+}
+function appendDocsRobotsStartLine(lines, context, variant) {
+	if (!context.robotsEnabled) return;
+	lines.push(variant === "skill" ? `- Check ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE} for crawler and AI-agent access policy.` : `- Check ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE} before crawling broadly.`);
+}
+function appendDocsMcpStartLine(lines, context, variant) {
+	if (!context.mcpEnabled) return;
+	lines.push(variant === "skill" ? `- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools, resources, and configured prompts.` : `- Use MCP at ${DEFAULT_MCP_PUBLIC_ROUTE} or ${DEFAULT_MCP_WELL_KNOWN_ROUTE} when your environment supports MCP capabilities.`);
+}
+function appendDocsFeedbackStartLine(lines, context, variant) {
+	if (!context.feedbackEnabled) return;
+	lines.push(variant === "skill" ? `- Read ${context.feedbackSchemaRoute} before posting agent feedback to ${context.feedbackRoute}.` : `- Read ${context.feedbackSchemaRoute} before posting feedback to ${context.feedbackRoute}.`);
+}
+function appendDocsAgentStartHereLines(lines, context, variant) {
+	const agentSpecFallback = context.apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${context.apiRoute}?agent=spec`;
+	lines.push(variant === "skill" ? `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecFallback}.` : `- Read ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} first; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecFallback}.`);
+	if (context.apiCatalogEnabled) lines.push(variant === "skill" ? `- Use ${DEFAULT_API_CATALOG_ROUTE} for standards-based API discovery.` : `- Use ${DEFAULT_API_CATALOG_ROUTE} for RFC 9727 API discovery.`);
+	lines.push(variant === "skill" ? `- Use ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} for hashed skill discovery.` : `- Use ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} for integrity-checked skills.`, variant === "skill" ? `- Fetch /${context.normalizedEntry}.md for the root docs page.` : `- Read /${context.normalizedEntry}.md for the root docs page.`, variant === "skill" ? `- Fetch /${context.normalizedEntry}/{slug}.md for page-specific context.` : `- Read /${context.normalizedEntry}/{slug}.md for page-specific context.`);
+	if (context.markdownSectionDiscoveryEnabled) lines.push(variant === "skill" ? `- Fetch /${context.normalizedEntry}/{slug}.md?sections to list section IDs and size estimates before requesting ?section={id}.` : `- Read /${context.normalizedEntry}/{slug}.md?sections before fetching ?section={id} when a full page is larger than needed.`);
+	if (variant === "skill") {
+		appendDocsMarkdownNegotiationStartLines(lines, context, variant);
+		appendDocsSearchStartLine(lines, context, variant);
+		appendDocsContentChangesStartLine(lines, context);
+		appendDocsOpenApiStartLine(lines, context, variant);
+		appendDocsLlmsStartLines(lines, context, variant);
+		appendDocsSitemapStartLines(lines, context, variant);
+		appendDocsRobotsStartLine(lines, context, variant);
+		appendDocsMcpStartLine(lines, context, variant);
+		appendDocsFeedbackStartLine(lines, context, variant);
+		return;
+	}
+	appendDocsLlmsStartLines(lines, context, variant);
+	appendDocsSitemapStartLines(lines, context, variant);
+	appendDocsRobotsStartLine(lines, context, variant);
+	appendDocsSearchStartLine(lines, context, variant);
+	appendDocsContentChangesStartLine(lines, context);
+	appendDocsOpenApiStartLine(lines, context, variant);
+	appendDocsMcpStartLine(lines, context, variant);
+	appendDocsFeedbackStartLine(lines, context, variant);
+	appendDocsMarkdownNegotiationStartLines(lines, context, variant);
+}
+function appendDocsLlmsRouteLines(lines, context) {
+	if (!context.llmsEnabled) return;
+	lines.push(`- llms.txt: ${DEFAULT_LLMS_TXT_ROUTE}`, `- llms-full.txt: ${DEFAULT_LLMS_FULL_TXT_ROUTE}`, `- llms well-known aliases: ${DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE}`);
+	for (const section of context.llmsSections) {
+		lines.push(`- ${section.title} llms.txt: ${section.route}`);
+		lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
+	}
+}
+function appendDocsOpenApiRouteLines(lines, context) {
+	if (!context.openapiConfig.enabled || !context.openapiConfig.url) return;
+	lines.push(`- OpenAPI schema: ${context.openapiConfig.url}`);
+	if (context.openapiConfig.apiReferencePath) lines.push(`- API reference: ${context.openapiConfig.apiReferencePath}`);
+	for (const version of context.openapiConfig.versions ?? []) lines.push(`- OpenAPI ${version.label}${version.default ? " (default)" : ""}: ${version.url}`, `- API reference ${version.label}: ${version.apiReferencePath}`);
+}
+function appendDocsSitemapRouteLines(lines, context) {
+	if (!context.sitemapConfig.enabled) return;
+	if (context.sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${context.sitemapConfig.xml.route}`);
+	if (context.sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${context.sitemapConfig.markdown.route}`, ...context.sitemapConfig.markdown.docsRoute ? [`- Sitemap docs alias: ${context.sitemapConfig.markdown.docsRoute}`] : [], `- Sitemap well-known alias: ${context.sitemapConfig.markdown.wellKnownRoute}`);
+}
+function appendDocsMcpRouteLines(lines, context) {
+	if (!context.mcpEnabled) return;
+	lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+}
+function appendDocsAgentPublicRouteLines(lines, context, variant) {
+	if (variant === "skill") {
+		lines.push(`- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${context.apiRoute}?format=agents`, `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${context.apiRoute}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`);
+		if (context.apiCatalogEnabled) lines.push(`- API catalog (RFC 9727): ${DEFAULT_API_CATALOG_ROUTE}`);
+		lines.push(`- Agent Skills index: ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}`, `- Agent Skills artifacts: ${DEFAULT_AGENT_SKILLS_ROUTE_PATTERN}`, `- Markdown root: /${context.normalizedEntry}.md`, `- Markdown pages: /${context.normalizedEntry}/{slug}.md`);
+		if (context.markdownSectionDiscoveryEnabled) lines.push(`- Markdown section index: /${context.normalizedEntry}/{slug}.md?sections`, `- Markdown section fetch: /${context.normalizedEntry}/{slug}.md?section={id}&tokenBudget={tokens}`);
+		if (context.robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
+		appendDocsLlmsRouteLines(lines, context);
+		appendDocsOpenApiRouteLines(lines, context);
+		appendDocsSitemapRouteLines(lines, context);
+		appendDocsMcpRouteLines(lines, context);
+		if (context.contentChangesEnabled) lines.push(`- Content changes: ${context.apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`);
+		return;
+	}
+	lines.push(`- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${context.apiRoute}?format=agents`, `- Agent instructions aliases: ${DEFAULT_AGENT_MD_ROUTE}, ${DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE}`, `- Site skill: ${DEFAULT_SKILL_MD_ROUTE}`, `- Site skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Site skill API format: ${context.apiRoute}?format=skill`, `- Markdown root: /${context.normalizedEntry}.md`, `- Markdown pages: /${context.normalizedEntry}/{slug}.md`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`);
+	if (context.markdownSectionDiscoveryEnabled) lines.push(`- Markdown section index: /${context.normalizedEntry}/{slug}.md?sections`, `- Markdown section fetch: /${context.normalizedEntry}/{slug}.md?section={id}&tokenBudget={tokens}`);
+	if (context.apiCatalogEnabled) lines.push(`- API catalog (RFC 9727): ${DEFAULT_API_CATALOG_ROUTE}`);
+	lines.push(`- Agent Skills index: ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}`, `- Agent Skills artifacts: ${DEFAULT_AGENT_SKILLS_ROUTE_PATTERN}`);
+	appendDocsLlmsRouteLines(lines, context);
+	if (context.robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
+	appendDocsSitemapRouteLines(lines, context);
+	appendDocsOpenApiRouteLines(lines, context);
+	appendDocsMcpRouteLines(lines, context);
+	if (context.contentChangesEnabled) lines.push(`- Content changes: ${context.apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`);
+}
+function renderDocsMarkdownDocument(page, options) {
+	const explicitAgentContent = page.agentRawContent ?? page.agentContent;
+	if (explicitAgentContent !== void 0) return appendDocsMarkdownSitemapFooter(prependDocsMarkdownFrontmatter(upsertPageAgentContractMarkdown(explicitAgentContent, page.agent), resolveDocsMarkdownPageMetadata(page, options)), options?.sitemap);
+	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
+	const lines = [`# ${page.title}`, `URL: ${page.url}`];
+	if (shouldRenderLlmsDirective(options)) lines.push(DOCS_LLMS_TXT_DIRECTIVE_LINE);
+	if (page.description) lines.push(`Description: ${page.description}`);
+	lines.push(...relatedLines);
+	lines.push("", upsertPageAgentContractMarkdown(page.agentFallbackRawContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content, page.agent));
+	return appendDocsMarkdownSitemapFooter(prependDocsMarkdownFrontmatter(lines.join("\n"), {
+		...resolveDocsMarkdownPageMetadata(page, options),
+		generatedPreamble: true
+	}), options?.sitemap);
+}
+function renderDocsSkillDocument(options) {
+	const { origin } = options;
+	const context = resolveDocsAgentDocumentContext(options);
+	const lines = [
+		"---",
+		"name: docs",
+		`description: ${toYamlString(truncateSkillDescription(`Use ${context.siteTitle} through markdown routes, llms.txt, robots.txt, agent discovery, search, and MCP when available.`))}`,
+		"---",
+		"",
+		`# ${context.siteTitle} Skill`,
+		"",
+		`Base URL: ${origin}`
+	];
+	if (context.siteDescription) lines.push(`Description: ${context.siteDescription}`);
+	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here");
+	appendDocsAgentStartHereLines(lines, context, "skill");
+	lines.push("", "## Routes");
+	appendDocsAgentPublicRouteLines(lines, context, "skill");
+	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
+	return lines.join("\n");
+}
+function renderDocsAgentsDocument(options) {
+	const { origin } = options;
+	const context = resolveDocsAgentDocumentContext(options);
+	const lines = [
+		"# Agent Instructions",
+		"",
+		`Site: ${context.siteTitle}`,
+		`Base URL: ${origin}`
+	];
+	if (context.siteDescription) lines.push(`Description: ${context.siteDescription}`);
+	lines.push("", "## Start Here");
+	appendDocsAgentStartHereLines(lines, context, "agents");
+	lines.push("", "## Working Rules", "- Prefer markdown routes, llms.txt, sitemap.md, OpenAPI schemas, and MCP capabilities over scraping rendered HTML.", "- Treat generated context files as discovery aids, then fetch the smallest page or section that answers the task.", "- Preserve canonical docs URLs when citing pages back to humans.", "- If a markdown route returns a recovery page, use its closest matches, sitemap, and discovery spec before guessing another slug.", "", "## Public Routes");
+	appendDocsAgentPublicRouteLines(lines, context, "agents");
+	lines.push("", "## Framework Maintenance", "- For @farming-labs/docs projects, keep the framework package current before debugging missing agent surfaces.", "", "```sh", "npx @farming-labs/docs@latest upgrade --latest", "```", "", "- For framework setup, configuration, CLI, Ask AI, page actions, or theme work, install the reusable Skills pack:", "", "```sh", "npx skills add farming-labs/docs", "```");
+	return lines.join("\n");
+}
+/** Resolve only the task tools that the advertised MCP endpoint actually exposes. */
+function resolveDocsAgentContractMcpTools(mcp) {
+	if (!mcp.enabled) return void 0;
+	const tools = {};
+	if (mcp.tools.listTasks !== false) tools.list = "list_tasks";
+	if (mcp.tools.readTask !== false) tools.read = "read_task";
+	return tools.list || tools.read ? tools : void 0;
+}
+function buildDocsAgentDiscoverySpec({ origin, entry = "docs", apiRoute, apiCatalog: explicitApiCatalog, i18n = null, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi, markdown, publishedSkills = [], agentCard }) {
+	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(apiRoute);
+	const apiQueryRoute = (query) => `${resolvedApiRoute}?${query}`;
+	const localesEnabled = i18n !== null;
+	const searchEnabled = isSearchEnabled(search);
+	const contentChangesEnabled = resolveDocsContentChangesConfig(contentChanges).enabled;
+	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const feedbackSchemaRoute = feedback?.schemaRoute ?? `${feedbackRoute}/schema`;
+	const llmsEnabled = llms?.enabled ?? true;
+	const llmsSections = resolveDocsLlmsTxtSections(llms);
+	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms?.baseUrl });
+	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const openapiConfig = resolveDocsOpenApiDiscoveryConfig(openapi);
+	const defaultOpenapiRoute = apiQueryRoute("format=openapi");
+	const openapiUrl = resolveDocsOpenApiDiscoveryUrl(openapiConfig, resolvedApiRoute);
+	const agentContractMcpTools = resolveDocsAgentContractMcpTools(mcp);
+	const apiCatalogEnabled = explicitApiCatalog ?? llms?.apiCatalog ?? true;
+	const markdownSectionDiscoveryEnabled = markdown?.sectionDiscovery !== false;
+	const protectedResource = mcp.enabled && mcp.security?.authenticate ? mcp.security.protectedResource : void 0;
+	const protectedResourceMetadataRoutes = protectedResource ? getDocsMcpProtectedResourceMetadataRoutes(mcp.route) : [];
+	return {
+		$schema: DOCS_AGENT_MANIFEST_SCHEMA_URI,
+		format: DOCS_AGENT_MANIFEST_FORMAT,
+		version: DOCS_AGENT_MANIFEST_VERSION,
+		name: "@farming-labs/docs",
+		profile: "full",
+		profiles: {
+			default: "full",
+			full: DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
+			compact: `${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}?profile=compact`
+		},
+		baseUrl: origin,
+		site: {
+			title: llms?.siteTitle ?? "Documentation",
+			description: llms?.siteDescription,
+			entry: normalizedEntry,
+			baseUrl: llms?.baseUrl ?? origin
+		},
+		locales: {
+			enabled: localesEnabled,
+			available: i18n?.locales ?? [],
+			default: i18n?.defaultLocale ?? null,
+			queryParam: "lang",
+			fallbackQueryParam: "locale"
+		},
+		capabilities: {
+			markdownRoutes: true,
+			markdownSectionDiscovery: markdownSectionDiscoveryEnabled,
+			agentMdOverrides: true,
+			agentBlocks: true,
+			structuredAgentContracts: true,
+			agents: true,
+			llms: llmsEnabled,
+			skills: true,
+			apiCatalog: apiCatalogEnabled,
+			agentSkillsDiscovery: true,
+			mcp: mcp.enabled,
+			search: searchEnabled,
+			contentChanges: contentChangesEnabled,
+			sitemap: sitemapConfig.enabled,
+			robots: robotsEnabled,
+			structuredData: true,
+			apiReference: openapiConfig.enabled,
+			openapi: openapiConfig.enabled,
+			agentFeedback: feedback?.enabled ?? false,
+			locales: localesEnabled
+		},
+		api: {
+			docs: resolvedApiRoute,
+			config: apiQueryRoute("format=config"),
+			diagnostics: apiQueryRoute("format=diagnostics"),
+			agentSpec: resolvedApiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : apiQueryRoute("agent=spec"),
+			agentSpecDefault: DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
+			agentSpecFallback: DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
+			agentSpecWellKnown: DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
+			agentSpecWellKnownJson: DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
+			agentSpecQuery: apiQueryRoute("agent=spec"),
+			agents: apiQueryRoute("format=agents"),
+			...apiCatalogEnabled ? {
+				apiCatalog: DEFAULT_API_CATALOG_ROUTE,
+				apiCatalogQuery: apiQueryRoute(`format=${DEFAULT_API_CATALOG_FORMAT}`)
+			} : {},
+			agentSkillsIndex: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+			legacySkillsIndex: DEFAULT_LEGACY_SKILLS_INDEX_ROUTE,
+			...agentCard ? { agentCard: DEFAULT_A2A_AGENT_CARD_ROUTE } : {},
+			openapi: defaultOpenapiRoute,
+			...contentChangesEnabled ? { contentChanges: apiQueryRoute(`audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`) } : {}
+		},
+		apiCatalog: {
+			enabled: apiCatalogEnabled,
+			route: apiCatalogEnabled ? DEFAULT_API_CATALOG_ROUTE : null,
+			api: apiCatalogEnabled ? apiQueryRoute(`format=${DEFAULT_API_CATALOG_FORMAT}`) : null,
+			mediaType: API_CATALOG_MEDIA_TYPE,
+			profile: API_CATALOG_PROFILE_URI
+		},
+		config: {
+			format: DEFAULT_DOCS_CONFIG_FORMAT,
+			endpoint: apiQueryRoute("format=config")
+		},
+		markdown: {
+			enabled: true,
+			acceptHeader: markdown?.acceptHeader === false ? null : "text/markdown",
+			signatureAgentHeader: markdown?.signatureAgentHeader === false ? null : DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER,
+			pagePattern: `/${normalizedEntry}/{slug}.md`,
+			rootPage: `/${normalizedEntry}.md`,
+			apiPattern: apiQueryRoute("format=markdown&path={slug}"),
+			sectionDiscovery: {
+				enabled: markdownSectionDiscoveryEnabled,
+				...markdownSectionDiscoveryEnabled ? {
+					format: DOCS_MARKDOWN_SECTION_INDEX_FORMAT,
+					indexParam: "sections",
+					sectionParam: "section",
+					tokenBudgetParam: "tokenBudget",
+					byteBudgetParam: "byteBudget"
+				} : {}
+			},
+			resolutionOrder: [
+				"agent.md",
+				"agent audience projection",
+				"shared page markdown"
+			]
+		},
+		agentContract: {
+			enabled: true,
+			schemaVersion: "page-agent-contract.v1",
+			source: "page-frontmatter",
+			frontmatterPath: "agent",
+			markdownSection: "Agent Contract",
+			mcpField: "agent",
+			...agentContractMcpTools ? { mcpTools: agentContractMcpTools } : {},
+			usefulContractFields: ["task", "outcome"],
+			fields: PAGE_AGENT_CONTRACT_FIELD_SCHEMA
+		},
+		llms: {
+			enabled: llmsEnabled,
+			defaultTxt: DEFAULT_LLMS_TXT_ROUTE,
+			defaultFull: DEFAULT_LLMS_FULL_TXT_ROUTE,
+			txt: apiQueryRoute("format=llms"),
+			full: apiQueryRoute("format=llms-full"),
+			publicTxt: DEFAULT_LLMS_TXT_ROUTE,
+			publicFull: DEFAULT_LLMS_FULL_TXT_ROUTE,
+			wellKnownTxt: DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
+			wellKnownFull: DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE,
+			...llmsSections.length > 0 ? { sections: llmsSections.map((section) => ({
+				title: section.title,
+				description: section.description,
+				match: section.match,
+				txt: section.route,
+				full: section.fullRoute
+			})) } : {}
+		},
+		sitemap: {
+			enabled: sitemapConfig.enabled,
+			xml: {
+				enabled: sitemapConfig.xml.enabled,
+				route: sitemapConfig.xml.route,
+				api: apiQueryRoute("format=sitemap-xml"),
+				defaultRoute: DEFAULT_SITEMAP_XML_ROUTE
+			},
+			markdown: {
+				enabled: sitemapConfig.markdown.enabled,
+				route: sitemapConfig.markdown.route,
+				docsRoute: sitemapConfig.markdown.docsRoute,
+				wellKnownRoute: sitemapConfig.markdown.wellKnownRoute,
+				api: apiQueryRoute("format=sitemap-md"),
+				defaultRoute: DEFAULT_SITEMAP_MD_ROUTE,
+				defaultDocsRoute: DEFAULT_SITEMAP_MD_DOCS_ROUTE,
+				defaultWellKnownRoute: DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE
+			}
+		},
+		robots: {
+			enabled: robotsEnabled,
+			route: DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE,
+			defaultRoute: DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE
+		},
+		structuredData: {
+			enabled: true,
+			format: "application/ld+json",
+			schema: "https://schema.org/TechArticle",
+			fields: [
+				"headline",
+				"description",
+				"url",
+				"dateModified",
+				"breadcrumb",
+				"mainEntity"
+			],
+			canonicalUrlField: "url",
+			breadcrumbType: "BreadcrumbList",
+			agentContractType: "HowTo"
+		},
+		openapi: {
+			enabled: openapiConfig.enabled,
+			url: openapiUrl ?? null,
+			source: openapiConfig.source ?? null,
+			specUrl: openapiConfig.specUrl ?? null,
+			apiReferencePath: openapiConfig.apiReferencePath ?? null,
+			...openapiConfig.operationCount !== void 0 ? { operationCount: openapiConfig.operationCount } : {},
+			versions: openapiConfig.versions?.map((version) => ({
+				...version,
+				url: resolveDocsOpenApiVersionUrl(openapiConfig, version, resolvedApiRoute)
+			})) ?? [],
+			format: "OpenAPI 3.1"
+		},
+		search: {
+			enabled: searchEnabled,
+			endpoint: apiQueryRoute("query={query}"),
+			agentEndpoint: apiQueryRoute("query={query}&audience=agent"),
+			structuredAgentEndpoint: apiQueryRoute("query={query}&audience=agent&response=structured"),
+			explainedAgentEndpoint: apiQueryRoute("query={query}&audience=agent&response=structured&explain=true"),
+			facetsEndpoint: apiQueryRoute("audience=agent&response=facets"),
+			method: "GET",
+			queryParam: "query",
+			localeParam: "lang",
+			audienceParam: "audience",
+			defaultAudience: "human",
+			supportedAudiences: ["human", "agent"],
+			responseParam: "response",
+			structuredResponseValue: "structured",
+			facetsResponseValue: "facets",
+			responseFormat: "docs-search.v1",
+			explainParam: "explain",
+			explainValue: "true",
+			explanationField: "explanation",
+			explanationFormat: "docs-search-explanation.v1",
+			facetsResponseFormat: "docs-search-facets.v1",
+			filterParams: {
+				framework: "framework",
+				version: "version",
+				package: "package",
+				tags: "tags"
+			},
+			repeatedFilterParams: [
+				"framework",
+				"version",
+				"package",
+				"tags"
+			],
+			warningsField: "warnings",
+			facetParam: "facet",
+			limitParam: "limit",
+			cursorParam: "cursor",
+			nextCursorField: "nextCursor",
+			hasMoreField: "hasMore",
+			totalField: "total"
+		},
+		contentChanges: {
+			enabled: contentChangesEnabled,
+			endpoint: contentChangesEnabled ? apiQueryRoute(`audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}`) : null,
+			method: "GET",
+			audienceParam: "audience",
+			defaultAudience: "agent",
+			supportedAudiences: ["human", "agent"],
+			responseParam: "response",
+			responseValue: DOCS_CONTENT_CHANGES_RESPONSE_VALUE,
+			sinceParam: "since",
+			format: DOCS_CONTENT_CHANGES_FORMAT,
+			generationField: "indexGeneration",
+			resetRequiredField: "resetRequired",
+			modes: [
+				"snapshot",
+				"delta",
+				"reset"
+			],
+			bodyFree: true,
+			etag: true
+		},
+		agents: {
+			enabled: true,
+			file: "AGENTS.md",
+			route: DEFAULT_AGENTS_MD_ROUTE,
+			wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+			api: apiQueryRoute("format=agents"),
+			generatedFallback: true,
+			aliases: [DEFAULT_AGENT_MD_ROUTE, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE]
+		},
+		skills: {
+			enabled: true,
+			file: "skill.md",
+			route: DEFAULT_SKILL_MD_ROUTE,
+			wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
+			api: apiQueryRoute("format=skill"),
+			generatedFallback: true,
+			registry: "skills.sh",
+			install: "npx skills add farming-labs/docs",
+			discovery: {
+				schema: AGENT_SKILLS_DISCOVERY_SCHEMA_URI,
+				index: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+				artifact: DEFAULT_AGENT_SKILLS_ROUTE_PATTERN,
+				archive: DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN,
+				file: `${DEFAULT_AGENT_SKILLS_ROUTE_PATTERN.replace("/SKILL.md", "/{path}")}`,
+				legacyIndex: DEFAULT_LEGACY_SKILLS_INDEX_ROUTE,
+				apiIndex: apiQueryRoute(`format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}`),
+				apiArtifact: apiQueryRoute("format=agent-skill&name={name}"),
+				apiFile: apiQueryRoute("format=agent-skill-file&name={name}&path={path}"),
+				digest: "sha256"
+			},
+			published: publishedSkills.map((skill) => ({
+				name: skill.name,
+				description: skill.description,
+				type: skill.type,
+				url: skill.url,
+				digest: skill.digest,
+				files: skill.files.map((file) => ({
+					path: file.path,
+					url: file.url,
+					digest: file.digest
+				}))
+			})),
+			recommended: [{
+				name: "getting-started",
+				description: "Use for installation, init, framework setup, theme CSS, and first docs.config wiring."
+			}]
+		},
+		mcp: {
+			enabled: mcp.enabled,
+			endpoint: mcp.route,
+			defaultEndpoint: DEFAULT_MCP_PUBLIC_ROUTE,
+			publicEndpoint: DEFAULT_MCP_PUBLIC_ROUTE,
+			wellKnownEndpoint: DEFAULT_MCP_WELL_KNOWN_ROUTE,
+			publicEndpoints: [DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE],
+			canonicalEndpoint: mcp.route,
+			name: mcp.name,
+			version: mcp.version,
+			tools: mcp.tools,
+			prompts: mcp.prompts ?? {
+				enabled: false,
+				contracts: false,
+				goldenTasks: []
+			},
+			...protectedResource ? { protectedResource: {
+				metadataEndpoints: protectedResourceMetadataRoutes,
+				authorizationServers: protectedResource.authorizationServers,
+				scopesSupported: protectedResource.scopesSupported,
+				requiredScopes: protectedResource.requiredScopes
+			} } : {}
+		},
+		feedback: {
+			enabled: feedback?.enabled ?? false,
+			schema: feedbackSchemaRoute,
+			submit: feedbackRoute,
+			schemaQuery: apiQueryRoute("feedback=agent&schema=1"),
+			submitQuery: apiQueryRoute("feedback=agent")
+		},
+		instructions: {
+			preferMarkdownRoutes: true,
+			useMcpWhenAvailable: true,
+			useOpenApiWhenAvailable: true,
+			readFeedbackSchemaBeforeSubmitting: true,
+			doNotAssumeFeedbackPayloadShape: true
+		}
+	};
+}
+/** Remove first-hop file inventories while retaining every discovery route and capability. */
+function compactDocsAgentDiscoverySpec(spec) {
+	return {
+		...spec,
+		profile: "compact",
+		skills: {
+			...spec.skills,
+			published: spec.skills.published.map((skill) => ({
+				...skill,
+				fileCount: skill.files.length,
+				files: []
+			}))
+		}
+	};
+}
+function acceptsDocsMarkdown(request) {
+	const accept = request.headers.get("accept");
+	if (!accept) return false;
+	const ranges = accept.split(",").map((value) => {
+		const [rawMediaType = "", ...params] = value.split(";").map((part) => part.trim().toLowerCase());
+		const qualityParam = params.find((param) => param.split("=", 1)[0]?.trim() === "q");
+		const parsedQuality = qualityParam ? Number.parseFloat(qualityParam.slice(qualityParam.indexOf("=") + 1).trim()) : 1;
+		return {
+			mediaType: rawMediaType,
+			quality: Number.isFinite(parsedQuality) ? Math.min(1, Math.max(0, parsedQuality)) : 0
+		};
+	});
+	const qualityFor = (mediaType) => {
+		const matches = ranges.filter((range) => range.mediaType === mediaType);
+		return matches.length > 0 ? Math.max(...matches.map((range) => range.quality)) : void 0;
+	};
+	const markdownQuality = qualityFor("text/markdown");
+	if (!markdownQuality || markdownQuality <= 0) return false;
+	const htmlQuality = qualityFor("text/html") ?? qualityFor("text/*") ?? qualityFor("*/*");
+	return htmlQuality === void 0 || htmlQuality <= markdownQuality;
+}
+function normalizeRequestedMarkdownPath(entry, requestedPath) {
+	const normalizedEntry = `/${normalizeDocsPathSegment(entry) || "docs"}`;
+	const trimmed = requestedPath.trim().replace(/\.md$/i, "");
+	if (!trimmed) return normalizedEntry;
+	const normalized = normalizeDocsUrlPath(trimmed.startsWith("/") ? trimmed : `/${trimmed}`);
+	if (normalized === normalizedEntry || normalized.startsWith(`${normalizedEntry}/`)) return normalized;
+	const slug = normalizeDocsPathSegment(trimmed);
+	return slug ? normalizeDocsUrlPath(`${normalizedEntry}/${slug}`) : normalizedEntry;
+}
+function isSearchEnabled(search) {
+	if (search === false) return false;
+	if (search && typeof search === "object" && search.enabled === false) return false;
+	return true;
+}
+function isRobotsDiscoveryEnabled(robots) {
+	if (robots === false) return false;
+	if (robots && typeof robots === "object" && robots.enabled === false) return false;
+	return true;
+}
+function resolveDocsOpenApiDiscoveryConfig(openapi) {
+	if (openapi === false || openapi === void 0) return { enabled: false };
+	if (openapi === true) return {
+		enabled: true,
+		url: DEFAULT_OPENAPI_SCHEMA_ROUTE,
+		urlSource: "default",
+		source: "generated",
+		catalogTargets: ["/"]
+	};
+	if (openapi.enabled === false) return { enabled: false };
+	const specUrl = openapi.specUrl?.trim();
+	const source = openapi.source ?? (specUrl ? "configured" : "generated");
+	const requestRelativeSpecUrl = specUrl?.startsWith("/") && !specUrl.startsWith("//");
+	const catalogTargets = openapi.catalogTargets === void 0 ? source === "generated" || requestRelativeSpecUrl ? ["/"] : void 0 : Array.from(new Set(openapi.catalogTargets.filter((target) => typeof target === "string").map((target) => target.trim()).filter(Boolean)));
+	return {
+		enabled: true,
+		url: openapi.url ?? DEFAULT_OPENAPI_SCHEMA_ROUTE,
+		urlSource: openapi.urlSource ?? (openapi.url === void 0 ? "default" : "configured"),
+		source,
+		specUrl: openapi.specUrl,
+		apiReferencePath: openapi.apiReferencePath,
+		catalogTargets,
+		operationCount: openapi.operationCount,
+		versions: openapi.versions?.map((version) => ({ ...version }))
+	};
+}
+/** Attach operation totals from the same normalized pages used by search and Markdown. */
+function withDocsOpenApiOperationCounts(openapi, operationPages) {
+	const resolved = resolveDocsOpenApiDiscoveryConfig(openapi);
+	if (!resolved.enabled) return resolved;
+	return {
+		...resolved,
+		operationCount: operationPages.length,
+		versions: resolved.versions?.map((version) => ({
+			...version,
+			operationCount: operationPages.filter((page) => page.version === version.id).length
+		}))
+	};
+}
+function resolveDocsOpenApiDiscoveryUrl(openapi, apiRoute) {
+	return openapi.urlSource === "default" && openapi.url === DEFAULT_OPENAPI_SCHEMA_ROUTE ? `${apiRoute}?format=openapi` : openapi.url;
+}
+function resolveDocsOpenApiVersionUrl(openapi, version, apiRoute) {
+	if (openapi.urlSource === "default" && openapi.url === DEFAULT_OPENAPI_SCHEMA_ROUTE && version.url.startsWith(`${DEFAULT_OPENAPI_SCHEMA_ROUTE}&`)) return `${apiRoute}?format=openapi&${version.url.slice(DEFAULT_OPENAPI_SCHEMA_ROUTE.length + 1)}`;
+	return version.url;
+}
+function compactSkillText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function truncateSkillDescription(value) {
+	const normalized = compactSkillText(value);
+	if (normalized.length <= 1024) return normalized;
+	return `${normalized.slice(0, 1021).trimEnd()}...`;
+}
+function toYamlString(value) {
+	return JSON.stringify(value);
+}
+
+//#endregion
+export { DEFAULT_AGENTS_MD_ROUTE, DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA, DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_MD_ROUTE, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, DEFAULT_AGENT_SPEC_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, DEFAULT_DOCS_API_ROUTE, DEFAULT_DOCS_CONFIG_FORMAT, DEFAULT_DOCS_CONFIG_ROUTE, DEFAULT_DOCS_DIAGNOSTICS_FORMAT, DEFAULT_DOCS_DIAGNOSTICS_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, DEFAULT_LLMS_TXT_MAX_CHARS, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, DEFAULT_OPENAPI_SCHEMA_ROUTE, DEFAULT_SKILL_MD_ROUTE, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER, acceptsDocsMarkdown, buildDocsAgentDiscoverySpec, buildDocsAgentFeedbackSchema, buildDocsConfigMap, buildDocsDiagnostics, buildDocsMarkdownSectionIndex, buildDocsMcpEndpointCandidates, collectDocsMarkdownSections, compactDocsAgentDiscoverySpec, createDocsMarkdownResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownCanonicalLinkHeader, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsLlmsTxtPublicRequest, isDocsMarkdownSectionIndexRequest, isDocsPublicGetRequest, isDocsSkillRequest, matchesDocsLlmsTxtSection, normalizeDocsPathSegment, parseDocsAgentFeedbackData, renderDocsAgentsDocument, renderDocsLlmsTxt, renderDocsMarkdownDocument, renderDocsMarkdownNotFound, renderDocsSkillDocument, resolveDocsAgentContractMcpTools, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolveDocsAgentsFormat, resolveDocsLlmsTxtFormat, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsMarkdownCanonicalUrl, resolveDocsMarkdownRecovery, resolveDocsMarkdownRequest, resolveDocsMarkdownSectionRequest, resolveDocsOpenApiDiscoveryConfig, resolveDocsRequestApiRoute, resolveDocsSkillFormat, selectDocsLlmsTxtContent, selectDocsMarkdownSection, validateDocsAgentFeedbackPayload, withDocsOpenApiOperationCounts };