@farming-labs/docs 0.2.58 → 0.2.59

package/dist/{agent-CxDzPqtl.mjs → agent-BFqyqEnC.mjs}

@@ -637,6 +637,325 @@ function normalizeInlineText(value) {
 	return value.replace(/\s+/g, " ").trim();
 }
 
+//#endregion
+//#region src/standards-discovery.ts
+const DEFAULT_API_CATALOG_ROUTE = "/.well-known/api-catalog";
+const DEFAULT_API_CATALOG_FORMAT = "api-catalog";
+const API_CATALOG_PROFILE_URI = "https://www.rfc-editor.org/info/rfc9727";
+const API_CATALOG_MEDIA_TYPE = "application/linkset+json";
+const DEFAULT_AGENT_SKILLS_INDEX_ROUTE = "/.well-known/agent-skills/index.json";
+const DEFAULT_AGENT_SKILLS_ROUTE_PREFIX = "/.well-known/agent-skills";
+const DEFAULT_AGENT_SKILLS_ROUTE_PATTERN = `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/{name}/SKILL.md`;
+const DEFAULT_AGENT_SKILLS_INDEX_FORMAT = "agent-skills";
+const DEFAULT_AGENT_SKILL_FORMAT = "agent-skill";
+const AGENT_SKILLS_DISCOVERY_SCHEMA_URI = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+const DEFAULT_DOCS_API_ROUTE$1 = "/api/docs";
+const DEFAULT_AGENT_MANIFEST_ROUTE = "/.well-known/agent.json";
+const AGENT_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const AGENT_SKILL_NAME_MAX_LENGTH = 64;
+const AGENT_SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+const DISCOVERY_CACHE_CONTROL = "public, max-age=0, s-maxage=3600";
+function normalizeDocsRoute(value) {
+	const normalized = `/${value.trim()}`.replace(/\/{2,}/g, "/");
+	return normalized === "/" ? normalized : normalized.replace(/\/+$/, "");
+}
+/** Resolve the same-origin Docs API pathname used by query-form discovery routes. */
+function resolveDocsDiscoveryApiRoute(apiRoute) {
+	const candidate = apiRoute?.trim().split(/[?#]/, 1)[0];
+	return normalizeDocsRoute(candidate || DEFAULT_DOCS_API_ROUTE$1);
+}
+function resolveHttpUrl(value, origin) {
+	if (!value) return null;
+	try {
+		const base = new URL(origin);
+		const resolved = new URL(value, `${base.origin}/`);
+		if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
+		return resolved.toString();
+	} catch {
+		return null;
+	}
+}
+function compactUniqueTargets(targets) {
+	const seen = /* @__PURE__ */ new Set();
+	return targets.filter((target) => {
+		if (!target) return false;
+		const key = `${target.href}\u0000${target.type ?? ""}\u0000${target.title ?? ""}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+function toTarget(route, origin, type, title) {
+	const href = resolveHttpUrl(route, origin);
+	return href ? {
+		href,
+		...type ? { type } : {},
+		...title ? { title } : {}
+	} : null;
+}
+/** Build an RFC 9727 API Catalog using the RFC 9264 JSON Linkset representation. */
+function buildDocsApiCatalog(options) {
+	const catalogUrl = resolveHttpUrl(DEFAULT_API_CATALOG_ROUTE, options.origin);
+	if (!catalogUrl) throw new Error(`Invalid HTTP(S) docs origin for API catalog: ${options.origin}`);
+	const apiRoute = options.apiRoute === null ? null : resolveDocsDiscoveryApiRoute(options.apiRoute);
+	const agentManifestRoute = options.agentManifestRoute === void 0 ? DEFAULT_AGENT_MANIFEST_ROUTE : options.agentManifestRoute;
+	const agentSkillsIndexRoute = options.agentSkillsIndexRoute === void 0 ? DEFAULT_AGENT_SKILLS_INDEX_ROUTE : options.agentSkillsIndexRoute;
+	const apiTargets = compactUniqueTargets([
+		toTarget(apiRoute, options.origin, "application/json", "Documentation API"),
+		...(options.apiRoutes ?? []).map((target) => toTarget(target.route, options.origin, target.type, target.title)),
+		toTarget(options.mcpRoute, options.origin, "application/json", "Documentation MCP endpoint"),
+		...(options.feedbackRoutes ?? []).map((route, index) => toTarget(route, options.origin, index === 0 ? "application/json" : "application/schema+json", index === 0 ? "Agent feedback endpoint" : "Agent feedback schema"))
+	]);
+	const serviceDocs = compactUniqueTargets([
+		toTarget(options.docsRoute ?? "/docs", options.origin, "text/html", "Documentation"),
+		toTarget(options.markdownRootRoute, options.origin, "text/markdown", "Documentation Markdown"),
+		toTarget(options.agentsRoute, options.origin, "text/markdown", "Agent instructions"),
+		toTarget(options.skillRoute, options.origin, "text/markdown", "Site skill"),
+		...(options.llmsRoutes ?? []).map((route) => toTarget(route, options.origin, "text/plain", "LLM documentation index")),
+		...(options.sitemapRoutes ?? []).map((route) => toTarget(route, options.origin, route.endsWith(".xml") ? "application/xml" : "text/markdown", "Documentation sitemap")),
+		toTarget(options.apiReferenceRoute, options.origin, "text/html", "API reference")
+	]);
+	const serviceMetadata = compactUniqueTargets([
+		toTarget(agentManifestRoute, options.origin, "application/json", "Agent discovery manifest"),
+		toTarget(agentSkillsIndexRoute, options.origin, "application/json", "Agent Skills discovery index"),
+		toTarget(options.configRoute, options.origin, "application/json", "Docs configuration map"),
+		toTarget(options.diagnosticsRoute, options.origin, "application/json", "Docs diagnostics"),
+		toTarget(options.robotsRoute, options.origin, "text/plain", "Robots policy")
+	]);
+	const serviceDescriptions = compactUniqueTargets([toTarget(options.openapiRoute, options.origin, "application/vnd.oai.openapi+json;version=3.1", "OpenAPI schema")]);
+	const catalogContext = {
+		anchor: catalogUrl,
+		"api-catalog": [{
+			href: catalogUrl,
+			type: API_CATALOG_MEDIA_TYPE,
+			title: "API catalog"
+		}]
+	};
+	if (apiTargets.length > 0) catalogContext.item = apiTargets;
+	if (serviceDocs.length > 0) catalogContext["service-doc"] = serviceDocs;
+	if (serviceMetadata.length > 0) catalogContext["service-meta"] = serviceMetadata;
+	if (serviceDescriptions.length > 0) catalogContext["service-desc"] = serviceDescriptions;
+	const linkset = [catalogContext];
+	for (const target of apiTargets) {
+		const context = { anchor: target.href };
+		if (serviceDocs.length > 0) context["service-doc"] = serviceDocs;
+		if (serviceMetadata.length > 0) context["service-meta"] = serviceMetadata;
+		if (serviceDescriptions.length > 0 && target.href === resolveHttpUrl(apiRoute, options.origin)) context["service-desc"] = serviceDescriptions;
+		linkset.push(context);
+	}
+	return { linkset };
+}
+function unquoteFrontmatterScalar(value) {
+	const trimmed = value.trim();
+	if (!trimmed || trimmed === ">" || trimmed === "|" || trimmed.startsWith("[") || trimmed.startsWith("{")) return null;
+	if (trimmed.startsWith("\"") && trimmed.endsWith("\"")) try {
+		const parsed = JSON.parse(trimmed);
+		return typeof parsed === "string" ? parsed.trim() : null;
+	} catch {
+		return null;
+	}
+	if (trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1).replace(/''/g, "'").trim();
+	return trimmed.replace(/\s+#.*$/, "").trim();
+}
+function readAgentSkillFrontmatter(document) {
+	const match = (document.startsWith("") ? document.slice(1) : document).match(/^---[\t ]*\r?\n([\s\S]*?)\r?\n---(?:[\t ]*\r?\n|$)/);
+	if (!match) return null;
+	const values = /* @__PURE__ */ new Map();
+	for (const line of match[1].split(/\r?\n/)) {
+		const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/);
+		if (!field) continue;
+		const value = unquoteFrontmatterScalar(field[2]);
+		if (value !== null) values.set(field[1], value);
+	}
+	const name = values.get("name") ?? "";
+	const description = values.get("description") ?? "";
+	if (!name || name.length > AGENT_SKILL_NAME_MAX_LENGTH || !AGENT_SKILL_NAME_PATTERN.test(name) || !description || description.length > AGENT_SKILL_DESCRIPTION_MAX_LENGTH) return null;
+	return {
+		name,
+		description
+	};
+}
+async function sha256DocsDiscoveryContent(content) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("Web Crypto SHA-256 support is required for Agent Skills discovery.");
+	const digest = await subtle.digest("SHA-256", new TextEncoder().encode(content));
+	return [...new Uint8Array(digest)].map((value) => value.toString(16).padStart(2, "0")).join("");
+}
+/** Select a valid public skill and hash the exact bytes returned by its standards route. */
+async function resolveDocsPublishedAgentSkill({ preferredDocument, fallbackDocument }) {
+	const preferredMetadata = preferredDocument ? readAgentSkillFrontmatter(preferredDocument) : null;
+	const fallbackMetadata = readAgentSkillFrontmatter(fallbackDocument);
+	const content = preferredMetadata ? preferredDocument : fallbackDocument;
+	const metadata = preferredMetadata ?? fallbackMetadata;
+	if (!metadata) throw new Error("The generated Agent Skills fallback must contain valid name and description frontmatter.");
+	const sha256 = await sha256DocsDiscoveryContent(content);
+	return {
+		name: metadata.name,
+		type: "skill-md",
+		description: metadata.description,
+		url: `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/${metadata.name}/SKILL.md`,
+		digest: `sha256:${sha256}`,
+		content,
+		sha256
+	};
+}
+function buildDocsAgentSkillsIndex(skills) {
+	return {
+		$schema: AGENT_SKILLS_DISCOVERY_SCHEMA_URI,
+		skills: (Array.isArray(skills) ? skills : [skills]).map(({ name, type, description, url, digest }) => ({
+			name,
+			type,
+			description,
+			url,
+			digest
+		})).sort((left, right) => left.name.localeCompare(right.name))
+	};
+}
+function resolveDocsStandardsDiscoveryRequest(url, options = {}) {
+	const pathname = normalizeDocsRoute(url.pathname);
+	if (pathname === DEFAULT_API_CATALOG_ROUTE) return { kind: "api-catalog" };
+	if (pathname === DEFAULT_AGENT_SKILLS_INDEX_ROUTE) return { kind: "agent-skills-index" };
+	const artifactMatch = pathname.match(/^\/\.well-known\/agent-skills\/([^/]+)\/SKILL\.md$/);
+	if (artifactMatch) try {
+		return {
+			kind: "agent-skill",
+			name: decodeURIComponent(artifactMatch[1])
+		};
+	} catch {
+		return {
+			kind: "agent-skill",
+			name: ""
+		};
+	}
+	if (pathname !== resolveDocsDiscoveryApiRoute(options.apiRoute)) return null;
+	const format = url.searchParams.get("format")?.trim();
+	if (format === DEFAULT_API_CATALOG_FORMAT) return { kind: "api-catalog" };
+	if (format === DEFAULT_AGENT_SKILLS_INDEX_FORMAT) return { kind: "agent-skills-index" };
+	if (format === DEFAULT_AGENT_SKILL_FORMAT) return {
+		kind: "agent-skill",
+		name: url.searchParams.get("name")?.trim() ?? ""
+	};
+	return null;
+}
+function isDocsStandardsDiscoveryRequest(url, options = {}) {
+	return resolveDocsStandardsDiscoveryRequest(url, options) !== null;
+}
+function formatLinkTarget(href, relation, options = {}) {
+	return [
+		`<${href}>`,
+		`rel="${relation}"`,
+		...options.type ? [`type="${options.type}"`] : [],
+		...options.profile ? [`profile="${options.profile}"`] : []
+	].join("; ");
+}
+/** Cross-link the standards endpoints without replacing an existing canonical Link value. */
+function getDocsDiscoveryLinkHeader(options = {}) {
+	return [
+		...options.includeApiCatalog === false ? [] : [formatLinkTarget(DEFAULT_API_CATALOG_ROUTE, "api-catalog", {
+			type: API_CATALOG_MEDIA_TYPE,
+			profile: API_CATALOG_PROFILE_URI
+		})],
+		...options.includeManifest === false ? [] : [formatLinkTarget(DEFAULT_AGENT_MANIFEST_ROUTE, "service-meta", { type: "application/json" })],
+		...options.includeSkills === false ? [] : [formatLinkTarget(DEFAULT_AGENT_SKILLS_INDEX_ROUTE, "service-meta", { type: "application/json" })]
+	].join(", ");
+}
+function appendDocsDiscoveryLinkHeader(headers, value) {
+	const next = new Headers(headers);
+	const discoveryLinks = value ?? getDocsDiscoveryLinkHeader();
+	const existing = next.get("Link");
+	next.set("Link", existing ? `${existing}, ${discoveryLinks}` : discoveryLinks);
+	return next;
+}
+function requestMatchesEtag(request, etag) {
+	const value = request.headers.get("if-none-match");
+	if (!value) return false;
+	if (value.trim() === "*") return true;
+	return value.split(",").some((candidate) => candidate.trim().replace(/^W\//i, "") === etag);
+}
+async function createHashedDiscoveryResponse(options) {
+	const etag = `"${options.sha256 ?? await sha256DocsDiscoveryContent(options.content)}"`;
+	const headers = {
+		"Access-Control-Allow-Origin": "*",
+		"Access-Control-Expose-Headers": "ETag, Link",
+		Allow: "GET, HEAD",
+		"Cache-Control": DISCOVERY_CACHE_CONTROL,
+		"Content-Type": options.contentType,
+		ETag: etag,
+		Link: options.linkHeader,
+		"X-Robots-Tag": "noindex"
+	};
+	if (requestMatchesEtag(options.request, etag)) {
+		const { "Content-Type": _contentType, ...notModifiedHeaders } = headers;
+		return new Response(null, {
+			status: 304,
+			headers: notModifiedHeaders
+		});
+	}
+	return new Response(options.request.method.toUpperCase() === "HEAD" ? null : options.content, { headers });
+}
+function standardsNotFoundResponse(request, linkHeader) {
+	return new Response(request.method.toUpperCase() === "HEAD" ? null : "Not Found", {
+		status: 404,
+		headers: {
+			"Access-Control-Allow-Origin": "*",
+			"Access-Control-Expose-Headers": "Link",
+			"Cache-Control": "no-store",
+			"Content-Type": "text/plain; charset=utf-8",
+			Link: linkHeader,
+			"X-Robots-Tag": "noindex"
+		}
+	});
+}
+function standardsMethodNotAllowedResponse(linkHeader) {
+	return new Response("Method Not Allowed", {
+		status: 405,
+		headers: {
+			"Access-Control-Allow-Origin": "*",
+			"Access-Control-Expose-Headers": "Link",
+			Allow: "GET, HEAD",
+			"Cache-Control": "no-store",
+			"Content-Type": "text/plain; charset=utf-8",
+			Link: linkHeader,
+			"X-Robots-Tag": "noindex"
+		}
+	});
+}
+/** Return one RFC 9727 or Agent Skills discovery response, or null for unrelated requests. */
+async function createDocsStandardsResponse({ request, apiCatalog, apiCatalogEnabled = true, apiRoute, preferredSkillDocument, fallbackSkillDocument }) {
+	const resolved = resolveDocsStandardsDiscoveryRequest(new URL(request.url), { apiRoute });
+	if (!resolved) return null;
+	const linkHeader = getDocsDiscoveryLinkHeader({ includeApiCatalog: apiCatalogEnabled });
+	if (resolved.kind === "api-catalog" && (!apiCatalogEnabled || !apiCatalog)) return standardsNotFoundResponse(request, linkHeader);
+	const method = request.method.toUpperCase();
+	if (method !== "GET" && method !== "HEAD") return standardsMethodNotAllowedResponse(linkHeader);
+	if (resolved.kind === "api-catalog") return createHashedDiscoveryResponse({
+		request,
+		content: `${JSON.stringify(apiCatalog, null, 2)}\n`,
+		contentType: `${API_CATALOG_MEDIA_TYPE}; profile="${API_CATALOG_PROFILE_URI}"; charset=utf-8`,
+		linkHeader
+	});
+	const skill = await resolveDocsPublishedAgentSkill({
+		preferredDocument: preferredSkillDocument,
+		fallbackDocument: fallbackSkillDocument
+	});
+	if (resolved.kind === "agent-skill") {
+		if (resolved.name !== skill.name) return standardsNotFoundResponse(request, linkHeader);
+		return createHashedDiscoveryResponse({
+			request,
+			content: skill.content,
+			contentType: "text/markdown; charset=utf-8",
+			sha256: skill.sha256,
+			linkHeader: [linkHeader, formatLinkTarget(DEFAULT_AGENT_SKILLS_INDEX_ROUTE, "collection", { type: "application/json" })].join(", ")
+		});
+	}
+	return createHashedDiscoveryResponse({
+		request,
+		content: `${JSON.stringify(buildDocsAgentSkillsIndex(skill), null, 2)}\n`,
+		contentType: "application/json; charset=utf-8",
+		linkHeader: [linkHeader, formatLinkTarget(skill.url, "item", { type: "text/markdown" })].join(", ")
+	});
+}
+
 //#endregion
 //#region src/sitemap.ts
 const DEFAULT_SITEMAP_XML_ROUTE = "/sitemap.xml";
@@ -705,10 +1024,10 @@ function resolveDocsSitemapConfig(sitemap, defaults = {}) {
 		}
 	};
 }
-function resolveDocsSitemapRequest(url, sitemap) {
+function resolveDocsSitemapRequest(url, sitemap, options = {}) {
 	const pathname = normalizeUrlPath(url.pathname);
 	const format = url.searchParams.get("format")?.trim();
-	if (pathname === "/api/docs") {
+	if (pathname === resolveDocsDiscoveryApiRoute(options.apiRoute)) {
 		if (format === "sitemap-xml") return "xml";
 		if (format === "sitemap-md" || format === "sitemap-markdown") return "markdown";
 	}
@@ -850,9 +1169,9 @@ function resolveDocsSitemapPageLastmod(manifest, url) {
 	const normalizedUrl = normalizeUrlPath(url);
 	return normalizeDateOnly(manifest.pages.find((entry) => normalizeUrlPath(entry.url) === normalizedUrl)?.lastmod);
 }
-function createDocsSitemapResponse({ request, sitemap, entry = "docs", siteTitle, baseUrl, pages, manifest }) {
+function createDocsSitemapResponse({ request, apiRoute, sitemap, entry = "docs", siteTitle, baseUrl, pages, manifest }) {
 	const url = new URL(request.url);
-	const format = resolveDocsSitemapRequest(url, sitemap);
+	const format = resolveDocsSitemapRequest(url, sitemap, { apiRoute });
 	if (!format) return null;
 	const resolved = resolveDocsSitemapConfig(sitemap, { baseUrl });
 	if (!resolved.enabled) return null;
@@ -2228,6 +2547,16 @@ function isDocsConfigRequest(url) {
 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);
@@ -2253,15 +2582,20 @@ 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 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);
@@ -2275,13 +2609,13 @@ function buildDocsDiagnostics(config, options = {}) {
 		severity: "warning",
 		code: "static-export-runtime-api",
 		path: "/staticExport",
-		message: "staticExport is enabled; runtime API-backed capabilities are unavailable in production static export builds."
+		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 /api/docs POST handler and will not run in static export builds."
+		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",
@@ -2312,44 +2646,53 @@ function buildDocsDiagnostics(config, options = {}) {
 		adapter,
 		routes: {
 			docs: docsRoute,
-			api: DEFAULT_DOCS_API_ROUTE,
-			config: DEFAULT_DOCS_CONFIG_ROUTE,
-			diagnostics: DEFAULT_DOCS_DIAGNOSTICS_ROUTE,
-			agentSpec: DEFAULT_AGENT_SPEC_ROUTE,
-			agents: `${DEFAULT_DOCS_API_ROUTE}?format=agents`,
-			skill: `${DEFAULT_DOCS_API_ROUTE}?format=skill`,
-			search: search.enabled ? `${DEFAULT_DOCS_API_ROUTE}?query={query}` : null,
-			askAi: ai.enabled ? DEFAULT_DOCS_API_ROUTE : null,
+			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,
+			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 ? openapiConfig.url ?? DEFAULT_OPENAPI_SCHEMA_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: DEFAULT_DOCS_CONFIG_ROUTE
+				route: apiQueryRoute("format=config")
 			},
 			diagnostics: {
 				status: "enabled",
-				route: DEFAULT_DOCS_DIAGNOSTICS_ROUTE
+				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 ? `${DEFAULT_DOCS_API_ROUTE}?query={query}` : null,
+				route: search.enabled ? apiQueryRoute("query={query}") : null,
 				provider: search.provider,
 				transport: "GET"
 			},
 			ai: {
 				status: ai.enabled ? "enabled" : "disabled",
 				reason: ai.reason,
-				route: ai.enabled ? DEFAULT_DOCS_API_ROUTE : null,
+				route: ai.enabled ? apiRoute : null,
 				mode: ai.mode,
 				transport: "POST"
 			},
@@ -2394,7 +2737,7 @@ function buildDocsDiagnostics(config, options = {}) {
 			apiReference: {
 				status: openapiConfig.enabled ? "enabled" : "disabled",
 				route: openapiConfig.enabled ? apiReferenceRoute : null,
-				routes: { openapi: openapiConfig.enabled ? openapiConfig.url ?? DEFAULT_OPENAPI_SCHEMA_ROUTE : null },
+				routes: { openapi: openapiConfig.enabled ? openapiUrl ?? apiQueryRoute("format=openapi") : null },
 				provider: openapiConfig.source
 			},
 			agents: {
@@ -2402,15 +2745,18 @@ function buildDocsDiagnostics(config, options = {}) {
 				routes: {
 					default: DEFAULT_AGENTS_MD_ROUTE,
 					wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
-					api: `${DEFAULT_DOCS_API_ROUTE}?format=agents`
+					api: apiQueryRoute("format=agents")
 				}
 			},
 			skills: {
 				status: "enabled",
+				transport: "GET/HEAD",
 				routes: {
 					default: DEFAULT_SKILL_MD_ROUTE,
 					wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
-					api: `${DEFAULT_DOCS_API_ROUTE}?format=skill`
+					api: apiQueryRoute("format=skill"),
+					index: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					artifact: DEFAULT_AGENT_SKILLS_ROUTE_PATTERN
 				}
 			},
 			locales: {
@@ -2619,6 +2965,21 @@ function resolveDocsDiagnosticsLlms(llmsTxt) {
 		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 : {};
@@ -2933,8 +3294,9 @@ function matchesDocsLlmsTxtSection(pageUrl, section) {
 		return pathname === normalized;
 	});
 }
-function resolveDocsLlmsTxtRequest(url, llms, basePath) {
+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 {
@@ -2947,7 +3309,7 @@ function resolveDocsLlmsTxtRequest(url, llms, basePath) {
 		};
 	}
 	const format = url.searchParams.get("format");
-	if (pathname === DEFAULT_DOCS_API_ROUTE && (format === "llms" || format === "llms-full")) {
+	if (pathname === apiRoute && (format === "llms" || format === "llms-full")) {
 		const sectionRoute = url.searchParams.get("section")?.trim();
 		const normalizedSectionRoute = sectionRoute ? normalizeDocsUrlPath(sectionRoute) : void 0;
 		return {
@@ -2996,8 +3358,10 @@ function renderDocsLlmsTxt(pages, options = {}) {
 	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 openapiUrl = resolveDocsOpenApiDiscoveryUrl(openapi, resolveDocsDiscoveryApiRoute(options.apiRoute));
 	const matchedPageUrls = /* @__PURE__ */ new Set();
 	const generatedSections = sections.map((section) => {
 		const sectionPages = pages.filter((page) => matchesDocsLlmsTxtSection(page.url, section));
@@ -3020,6 +3384,10 @@ function renderDocsLlmsTxt(pages, options = {}) {
 	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) {
@@ -3029,9 +3397,9 @@ function renderDocsLlmsTxt(pages, options = {}) {
 		}
 		llmsTxt += "\n";
 	}
-	if (openapi.enabled && openapi.url) {
+	if (openapi.enabled && openapiUrl) {
 		llmsTxt += "## API Schemas\n\n";
-		llmsTxt += `- [OpenAPI schema](${resolveDocsResourceUrl(baseUrl, openapi.url)}): Machine-readable API schema for tool use and API clients`;
+		llmsTxt += `- [OpenAPI schema](${resolveDocsResourceUrl(baseUrl, openapiUrl)}): Machine-readable API schema for tool use and API clients`;
 		if (openapi.apiReferencePath) llmsTxt += `; rendered API reference at ${resolveDocsResourceUrl(baseUrl, openapi.apiReferencePath)}`;
 		llmsTxt += "\n\n";
 	}
@@ -3081,9 +3449,75 @@ function getDocsLlmsTxtMaxCharsIssue(label, content, maxChars) {
 		message: `${label} is ${content.length.toLocaleString()} chars, above the configured ${maxChars.chars.toLocaleString()} char llms.txt budget.`
 	};
 }
-function isDocsAgentDiscoveryRequest(url) {
+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 }) {
+	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)) : []] : [];
+	return createDocsStandardsResponse({
+		request,
+		apiCatalogEnabled,
+		apiRoute: resolvedApiRoute,
+		preferredSkillDocument,
+		fallbackSkillDocument,
+		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,
+			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,
+			feedbackRoutes: feedback?.enabled ? [feedbackRoute, feedbackSchemaRoute] : [],
+			openapiRoute: openapiConfig.enabled ? openapiUrl ?? `${resolvedApiRoute}?format=openapi` : null,
+			apiReferenceRoute: openapiConfig.enabled && openapiConfig.apiReferencePath ? openapiConfig.apiReferencePath : null
+		}) : void 0
+	});
+}
+function isDocsAgentDiscoveryRequest(url, options = {}) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
-	if (pathname === DEFAULT_DOCS_API_ROUTE && url.searchParams.get("agent")?.trim() === "spec") return true;
+	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 isDocsMcpRequest(url) {
@@ -3169,10 +3603,10 @@ function getDocsMcpRootDomainCandidates(hostname) {
 function isDocsIpHostname(hostname) {
 	return /^(\d{1,3}\.){3}\d{1,3}$/.test(hostname) || hostname.includes(":");
 }
-function isDocsSkillRequest(url) {
+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 === DEFAULT_DOCS_API_ROUTE && resolveDocsSkillFormat(url) === "skill";
+	return pathname === resolveDocsDiscoveryApiRoute(options.apiRoute) && resolveDocsSkillFormat(url) === "skill";
 }
 function resolveDocsSkillFormat(url) {
 	return url.searchParams.get("format")?.trim() === "skill" ? "skill" : null;
@@ -3180,29 +3614,32 @@ function resolveDocsSkillFormat(url) {
 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) {
+function isDocsAgentsRequest(url, options = {}) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
 	if (isDocsAgentsPath(pathname)) return true;
-	return pathname === DEFAULT_DOCS_API_ROUTE && resolveDocsAgentsFormat(url) === "agents";
+	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);
-	if (pathname === DEFAULT_DOCS_API_ROUTE || pathname === DEFAULT_MCP_ROUTE) return false;
-	return isDocsAgentDiscoveryRequest(url) || isDocsAgentsRequest(url) || isDocsSkillRequest(url) || pathname === DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE && isRobotsDiscoveryEnabled(options.robots) || resolveDocsLlmsTxtRequest(url, options.llms, entry) !== null || resolveDocsSitemapRequest(url, options.sitemap) !== null || resolveDocsMarkdownRequest(entry, url, request) !== null;
+	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) {
-	return normalizeDocsUrlPath(url.pathname) !== DEFAULT_DOCS_API_ROUTE && resolveDocsLlmsTxtRequest(url, llms, basePath) !== 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) {
-	return resolveDocsLlmsTxtRequest(url, void 0, basePath)?.format ?? null;
+function resolveDocsLlmsTxtFormat(url, basePath, options = {}) {
+	return resolveDocsLlmsTxtRequest(url, void 0, basePath, options)?.format ?? null;
 }
-function resolveDocsMarkdownRequest(entry, url, request) {
+function resolveDocsMarkdownRequest(entry, url, request, options = {}) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
 	const format = url.searchParams.get("format")?.trim();
-	if (pathname === DEFAULT_DOCS_API_ROUTE && format === "markdown") return { requestedPath: url.searchParams.get("path")?.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}/`;
@@ -3418,14 +3855,16 @@ function resolveDocsMarkdownPageMetadata(page, options) {
 		agent: page.agent
 	};
 }
-function renderDocsMarkdownNotFound({ entry = "docs", requestedPath, origin, pages, sitemap }) {
+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 ? `${DEFAULT_DOCS_API_ROUTE}?format=markdown&path=${encodedRequestedSlug}` : `${DEFAULT_DOCS_API_ROUTE}?format=markdown`;
+	const requestedApiRoute = requestedSlug ? `${resolvedApiRoute}?format=markdown&path=${encodedRequestedSlug}` : `${resolvedApiRoute}?format=markdown`;
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap);
 	const recovery = resolveDocsMarkdownRecovery({
 		entry: normalizedEntry,
@@ -3444,7 +3883,7 @@ function renderDocsMarkdownNotFound({ entry = "docs", requestedPath, origin, pag
 			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: \`${DEFAULT_AGENT_SPEC_ROUTE}\``, `- Agent instructions: \`${DEFAULT_AGENTS_MD_ROUTE}\``, `- Search endpoint: \`${DEFAULT_DOCS_API_ROUTE}?query={query}\``, `- Docs index markdown: \`/${normalizedEntry}.md\``, `- Requested markdown API route: \`${requestedApiRoute}\``);
+	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 endpoint: \`${resolvedApiRoute}?query={query}\``, `- Docs index markdown: \`/${normalizedEntry}.md\``, `- Requested markdown API route: \`${requestedApiRoute}\``);
 	if (sitemapConfig.enabled) {
 		if (sitemapConfig.markdown.enabled) {
 			lines.push(`- Semantic sitemap: \`${sitemapConfig.markdown.route}\``);
@@ -3545,6 +3984,7 @@ function createDocsMarkdownResponse(options) {
 		});
 		return new Response(renderDocsMarkdownNotFound({
 			entry,
+			apiRoute: options.apiRoute,
 			requestedPath,
 			origin,
 			pages,
@@ -3588,9 +4028,12 @@ function shouldRenderLlmsDirective(options) {
 	if (options?.llms && typeof options.llms === "object" && options.llms.enabled === false) return false;
 	return true;
 }
-function resolveDocsAgentDocumentContext({ entry = "docs", search, mcp, feedback, llms, sitemap, robots, openapi, markdown }) {
+function resolveDocsAgentDocumentContext({ entry = "docs", apiRoute, apiCatalog: explicitApiCatalog, search, 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,
@@ -3600,12 +4043,16 @@ function resolveDocsAgentDocumentContext({ entry = "docs", search, mcp, feedback
 		feedbackEnabled: feedback?.enabled ?? false,
 		sitemapConfig: resolveDocsSitemapConfig(sitemap),
 		robotsEnabled: isRobotsDiscoveryEnabled(robots),
-		openapiConfig: resolveDocsOpenApiDiscoveryConfig(openapi),
+		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
+		markdownSignatureAgentHeader: markdown?.signatureAgentHeader === false ? null : DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER,
+		apiCatalogEnabled: explicitApiCatalog ?? llms?.apiCatalog ?? true
 	};
 }
 function appendDocsMarkdownNegotiationStartLines(lines, context, variant) {
@@ -3614,7 +4061,7 @@ function appendDocsMarkdownNegotiationStartLines(lines, context, variant) {
 }
 function appendDocsSearchStartLine(lines, context, variant) {
 	if (!context.searchEnabled) return;
-	lines.push(variant === "skill" ? `- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.` : `- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when the route is unknown.`);
+	lines.push(variant === "skill" ? `- Search with ${context.apiRoute}?query={query} when you do not know the page.` : `- Search with ${context.apiRoute}?query={query} when the route is unknown.`);
 }
 function appendDocsOpenApiStartLine(lines, context, variant) {
 	if (!context.openapiConfig.enabled || !context.openapiConfig.url) return;
@@ -3648,7 +4095,10 @@ function appendDocsFeedbackStartLine(lines, context, variant) {
 	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) {
-	lines.push(variant === "skill" ? `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.` : `- Read ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} first; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, 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.`);
+	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 (variant === "skill") {
 		appendDocsMarkdownNegotiationStartLines(lines, context, variant);
 		appendDocsSearchStartLine(lines, context, variant);
@@ -3693,7 +4143,9 @@ function appendDocsMcpRouteLines(lines, context) {
 }
 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: ${DEFAULT_DOCS_API_ROUTE}?format=agents`, `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${DEFAULT_DOCS_API_ROUTE}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`, `- Markdown root: /${context.normalizedEntry}.md`, `- Markdown pages: /${context.normalizedEntry}/{slug}.md`);
+		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.robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
 		appendDocsLlmsRouteLines(lines, context);
 		appendDocsOpenApiRouteLines(lines, context);
@@ -3701,7 +4153,9 @@ function appendDocsAgentPublicRouteLines(lines, context, variant) {
 		appendDocsMcpRouteLines(lines, context);
 		return;
 	}
-	lines.push(`- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${DEFAULT_DOCS_API_ROUTE}?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: ${DEFAULT_DOCS_API_ROUTE}?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}`);
+	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.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);
@@ -3765,8 +4219,10 @@ function resolveDocsAgentContractMcpTools(mcp) {
 	if (mcp.tools.readTask !== false) tools.read = "read_task";
 	return tools.list || tools.read ? tools : void 0;
 }
-function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, search, mcp, feedback, llms, sitemap, robots, openapi, markdown }) {
+function buildDocsAgentDiscoverySpec({ origin, entry = "docs", apiRoute, apiCatalog: explicitApiCatalog, i18n = null, search, mcp, feedback, llms, sitemap, robots, openapi, markdown }) {
 	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const resolvedApiRoute = resolveDocsDiscoveryApiRoute(apiRoute);
+	const apiQueryRoute = (query) => `${resolvedApiRoute}?${query}`;
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
 	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
@@ -3776,7 +4232,10 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 	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;
 	return {
 		version: "1",
 		name: "@farming-labs/docs",
@@ -3802,6 +4261,8 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			agents: true,
 			llms: llmsEnabled,
 			skills: true,
+			apiCatalog: apiCatalogEnabled,
+			agentSkillsDiscovery: true,
 			mcp: mcp.enabled,
 			search: searchEnabled,
 			sitemap: sitemapConfig.enabled,
@@ -3813,21 +4274,33 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			locales: localesEnabled
 		},
 		api: {
-			docs: DEFAULT_DOCS_API_ROUTE,
-			config: DEFAULT_DOCS_CONFIG_ROUTE,
-			diagnostics: DEFAULT_DOCS_DIAGNOSTICS_ROUTE,
-			agentSpec: DEFAULT_AGENT_SPEC_ROUTE,
+			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: `${DEFAULT_DOCS_API_ROUTE}?agent=spec`,
-			agents: `${DEFAULT_DOCS_API_ROUTE}?format=agents`,
-			openapi: DEFAULT_OPENAPI_SCHEMA_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,
+			openapi: defaultOpenapiRoute
+		},
+		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: DEFAULT_DOCS_CONFIG_ROUTE
+			endpoint: apiQueryRoute("format=config")
 		},
 		markdown: {
 			enabled: true,
@@ -3835,7 +4308,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			signatureAgentHeader: markdown?.signatureAgentHeader === false ? null : DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER,
 			pagePattern: `/${normalizedEntry}/{slug}.md`,
 			rootPage: `/${normalizedEntry}.md`,
-			apiPattern: `${DEFAULT_DOCS_API_ROUTE}?format=markdown&path={slug}`,
+			apiPattern: apiQueryRoute("format=markdown&path={slug}"),
 			resolutionOrder: [
 				"agent.md",
 				"agent audience projection",
@@ -3857,8 +4330,8 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			enabled: llmsEnabled,
 			defaultTxt: DEFAULT_LLMS_TXT_ROUTE,
 			defaultFull: DEFAULT_LLMS_FULL_TXT_ROUTE,
-			txt: `${DEFAULT_DOCS_API_ROUTE}?format=llms`,
-			full: `${DEFAULT_DOCS_API_ROUTE}?format=llms-full`,
+			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,
@@ -3876,7 +4349,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			xml: {
 				enabled: sitemapConfig.xml.enabled,
 				route: sitemapConfig.xml.route,
-				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-xml`,
+				api: apiQueryRoute("format=sitemap-xml"),
 				defaultRoute: DEFAULT_SITEMAP_XML_ROUTE
 			},
 			markdown: {
@@ -3884,7 +4357,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 				route: sitemapConfig.markdown.route,
 				docsRoute: sitemapConfig.markdown.docsRoute,
 				wellKnownRoute: sitemapConfig.markdown.wellKnownRoute,
-				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-md`,
+				api: apiQueryRoute("format=sitemap-md"),
 				defaultRoute: DEFAULT_SITEMAP_MD_ROUTE,
 				defaultDocsRoute: DEFAULT_SITEMAP_MD_DOCS_ROUTE,
 				defaultWellKnownRoute: DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE
@@ -3913,7 +4386,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 		},
 		openapi: {
 			enabled: openapiConfig.enabled,
-			url: openapiConfig.url ?? null,
+			url: openapiUrl ?? null,
 			source: openapiConfig.source ?? null,
 			specUrl: openapiConfig.specUrl ?? null,
 			apiReferencePath: openapiConfig.apiReferencePath ?? null,
@@ -3921,7 +4394,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 		},
 		search: {
 			enabled: searchEnabled,
-			endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`,
+			endpoint: apiQueryRoute("query={query}"),
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang"
@@ -3931,7 +4404,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			file: "AGENTS.md",
 			route: DEFAULT_AGENTS_MD_ROUTE,
 			wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
-			api: `${DEFAULT_DOCS_API_ROUTE}?format=agents`,
+			api: apiQueryRoute("format=agents"),
 			generatedFallback: true,
 			aliases: [DEFAULT_AGENT_MD_ROUTE, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE]
 		},
@@ -3940,10 +4413,18 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			file: "skill.md",
 			route: DEFAULT_SKILL_MD_ROUTE,
 			wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
-			api: `${DEFAULT_DOCS_API_ROUTE}?format=skill`,
+			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,
+				apiIndex: apiQueryRoute(`format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}`),
+				apiArtifact: apiQueryRoute("format=agent-skill&name={name}"),
+				digest: "sha256"
+			},
 			recommended: [{
 				name: "getting-started",
 				description: "Use for installation, init, framework setup, theme CSS, and first docs.config wiring."
@@ -3965,8 +4446,8 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			enabled: feedback?.enabled ?? false,
 			schema: feedbackSchemaRoute,
 			submit: feedbackRoute,
-			schemaQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent&schema=1`,
-			submitQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent`
+			schemaQuery: apiQueryRoute("feedback=agent&schema=1"),
+			submitQuery: apiQueryRoute("feedback=agent")
 		},
 		instructions: {
 			preferMarkdownRoutes: true,
@@ -4034,17 +4515,22 @@ function resolveDocsOpenApiDiscoveryConfig(openapi) {
 	if (openapi === true) return {
 		enabled: true,
 		url: DEFAULT_OPENAPI_SCHEMA_ROUTE,
+		urlSource: "default",
 		source: "generated"
 	};
 	if (openapi.enabled === false) return { enabled: false };
 	return {
 		enabled: true,
 		url: openapi.url ?? DEFAULT_OPENAPI_SCHEMA_ROUTE,
+		urlSource: openapi.urlSource ?? (openapi.url === void 0 ? "default" : "configured"),
 		source: openapi.source ?? "generated",
 		specUrl: openapi.specUrl,
 		apiReferencePath: openapi.apiReferencePath
 	};
 }
+function resolveDocsOpenApiDiscoveryUrl(openapi, apiRoute) {
+	return openapi.urlSource === "default" && openapi.url === DEFAULT_OPENAPI_SCHEMA_ROUTE ? `${apiRoute}?format=openapi` : openapi.url;
+}
 function compactSkillText(value) {
 	return value.replace(/\s+/g, " ").trim();
 }
@@ -4058,4 +4544,4 @@ function toYamlString(value) {
 }
 
 //#endregion
-export { normalizeDocsPathSegment as $, stripGeneratedPageAgentContractMarkdown as $t, DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN as A, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE as At, getDocsLlmsTxtMaxCharsIssue as B, toDocsSitemapMarkdownUrl as Bt, DEFAULT_OPENAPI_SCHEMA_ROUTE as C, findDocsAudienceMdxTags as Ct, DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN as D, DEFAULT_SITEMAP_MANIFEST_PATH as Dt, DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN as E, resolveDocsAudienceMdxContent as Et, buildDocsDiagnostics as F, renderDocsSitemapMarkdown as Ft, isDocsAgentsRequest as G, PAGE_AGENT_CONTRACT_FIELD_SCHEMA as Gt, getDocsMarkdownVaryHeader as H, renderDocsRelatedMarkdownLines as Ht, buildDocsMcpEndpointCandidates as I, renderDocsSitemapXml as It, isDocsLlmsTxtPublicRequest as J, getPageAgentFrontmatterIssues as Jt, isDocsConfigRequest as K, PAGE_AGENT_CONTRACT_START_MARKER as Kt, createDocsMarkdownResponse as L, resolveDocsSitemapConfig as Lt, buildDocsAgentDiscoverySpec as M, buildDocsSitemapManifest as Mt, buildDocsAgentFeedbackSchema as N, createDocsSitemapResponse as Nt, DOCS_CONFIG_MAP_TOP_LEVEL_KEYS as O, DEFAULT_SITEMAP_MD_DOCS_ROUTE as Ot, buildDocsConfigMap as P, readDocsSitemapManifestFromContentMap as Pt, matchesDocsLlmsTxtSection as Q, renderPageAgentFrontmatterYamlLines as Qt, detectDocsMarkdownAgentRequest as R, resolveDocsSitemapPageLastmod as Rt, DEFAULT_MCP_WELL_KNOWN_ROUTE as S, findDocsAudienceMdxIssues as St, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as T, resolveDocsAudienceExposure as Tt, hasDocsMarkdownSignatureAgent as U, PAGE_AGENT_CONTRACT_END_MARKER as Ut, getDocsMarkdownCanonicalLinkHeader as V, normalizeDocsRelated as Vt, isDocsAgentDiscoveryRequest as W, PAGE_AGENT_CONTRACT_FIELDS as Wt, isDocsPublicGetRequest as X, normalizePageAgentFrontmatter as Xt, isDocsMcpRequest as Y, hasStructuredPageAgentContract as Yt, isDocsSkillRequest as Z, renderPageAgentContractMarkdown as Zt, DEFAULT_LLMS_TXT_MAX_CHARS as _, resolveDocsOpenApiDiscoveryConfig as _t, DEFAULT_AGENT_MD_ROUTE as a, renderDocsMarkdownNotFound as at, DEFAULT_MCP_PUBLIC_ROUTE as b, toDocsMarkdownUrl as bt, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as c, resolveDocsAgentFeedbackConfig as ct, DEFAULT_DOCS_CONFIG_FORMAT as d, resolveDocsLlmsTxtFormat as dt, upsertPageAgentContractMarkdown as en, normalizeDocsUrlPath as et, DEFAULT_DOCS_CONFIG_ROUTE as f, resolveDocsLlmsTxtRequest as ft, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as g, resolveDocsMarkdownRequest as gt, DEFAULT_LLMS_FULL_TXT_ROUTE as h, resolveDocsMarkdownRecovery as ht, DEFAULT_AGENT_FEEDBACK_ROUTE as i, renderDocsMarkdownDocument as it, acceptsDocsMarkdown as j, DEFAULT_SITEMAP_XML_ROUTE as jt, DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER as k, DEFAULT_SITEMAP_MD_ROUTE as kt, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as l, resolveDocsAgentFeedbackRequest as lt, DEFAULT_DOCS_DIAGNOSTICS_ROUTE as m, resolveDocsMarkdownCanonicalUrl as mt, DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE as n, renderDocsAgentsDocument as nt, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE as o, renderDocsSkillDocument as ot, DEFAULT_DOCS_DIAGNOSTICS_FORMAT as p, resolveDocsLlmsTxtSections as pt, isDocsDiagnosticsRequest as q, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS as qt, DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA as r, renderDocsLlmsTxt as rt, DEFAULT_AGENT_SPEC_ROUTE as s, resolveDocsAgentContractMcpTools as st, DEFAULT_AGENTS_MD_ROUTE as t, parseDocsAgentFeedbackData as tt, DEFAULT_DOCS_API_ROUTE as u, resolveDocsAgentsFormat as ut, DEFAULT_LLMS_TXT_ROUTE as v, resolveDocsSkillFormat as vt, DEFAULT_SKILL_MD_ROUTE as w, resolveDocsAgentMdxContent as wt, DEFAULT_MCP_ROUTE as x, validateDocsAgentFeedbackPayload as xt, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as y, selectDocsLlmsTxtContent as yt, findDocsMarkdownPage as z, resolveDocsSitemapRequest as zt };
+export { matchesDocsLlmsTxtSection as $, appendDocsDiscoveryLinkHeader as $t, DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN as A, DEFAULT_SITEMAP_MD_DOCS_ROUTE as At, findDocsMarkdownPage as B, resolveDocsSitemapPageLastmod as Bt, DEFAULT_OPENAPI_SCHEMA_ROUTE as C, validateDocsAgentFeedbackPayload as Ct, DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN as D, resolveDocsAudienceExposure as Dt, DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN as E, resolveDocsAgentMdxContent as Et, buildDocsDiagnostics as F, createDocsSitemapResponse as Ft, isDocsAgentDiscoveryRequest as G, API_CATALOG_PROFILE_URI as Gt, getDocsMarkdownCanonicalLinkHeader as H, toDocsSitemapMarkdownUrl as Ht, buildDocsMcpEndpointCandidates as I, readDocsSitemapManifestFromContentMap as It, isDocsDiagnosticsRequest as J, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN as Jt, isDocsAgentsRequest as K, DEFAULT_AGENT_SKILLS_INDEX_FORMAT as Kt, createDocsMarkdownResponse as L, renderDocsSitemapMarkdown as Lt, buildDocsAgentDiscoverySpec as M, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE as Mt, buildDocsAgentFeedbackSchema as N, DEFAULT_SITEMAP_XML_ROUTE as Nt, DOCS_CONFIG_MAP_TOP_LEVEL_KEYS as O, resolveDocsAudienceMdxContent as Ot, buildDocsConfigMap as P, buildDocsSitemapManifest as Pt, isDocsSkillRequest as Q, DEFAULT_API_CATALOG_ROUTE as Qt, createDocsStandardsDiscoveryResponse as R, renderDocsSitemapXml as Rt, DEFAULT_MCP_WELL_KNOWN_ROUTE as S, upsertPageAgentContractMarkdown as Sn, toDocsMarkdownUrl as St, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as T, findDocsAudienceMdxTags as Tt, getDocsMarkdownVaryHeader as U, AGENT_SKILLS_DISCOVERY_SCHEMA_URI as Ut, getDocsLlmsTxtMaxCharsIssue as V, resolveDocsSitemapRequest as Vt, hasDocsMarkdownSignatureAgent as W, API_CATALOG_MEDIA_TYPE as Wt, isDocsMcpRequest as X, DEFAULT_AGENT_SKILL_FORMAT as Xt, isDocsLlmsTxtPublicRequest as Y, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX as Yt, isDocsPublicGetRequest as Z, DEFAULT_API_CATALOG_FORMAT as Zt, DEFAULT_LLMS_TXT_MAX_CHARS as _, hasStructuredPageAgentContract as _n, resolveDocsMarkdownRequest as _t, DEFAULT_AGENT_MD_ROUTE as a, resolveDocsDiscoveryApiRoute as an, renderDocsMarkdownDocument as at, DEFAULT_MCP_PUBLIC_ROUTE as b, renderPageAgentFrontmatterYamlLines as bn, resolveDocsSkillFormat as bt, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as c, sha256DocsDiscoveryContent as cn, resolveDocsAgentContractMcpTools as ct, DEFAULT_DOCS_CONFIG_FORMAT as d, PAGE_AGENT_CONTRACT_END_MARKER as dn, resolveDocsAgentsFormat as dt, buildDocsAgentSkillsIndex as en, normalizeDocsPathSegment as et, DEFAULT_DOCS_CONFIG_ROUTE as f, PAGE_AGENT_CONTRACT_FIELDS as fn, resolveDocsLlmsTxtFormat as ft, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as g, getPageAgentFrontmatterIssues as gn, resolveDocsMarkdownRecovery as gt, DEFAULT_LLMS_FULL_TXT_ROUTE as h, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS as hn, resolveDocsMarkdownCanonicalUrl as ht, DEFAULT_AGENT_FEEDBACK_ROUTE as i, isDocsStandardsDiscoveryRequest as in, renderDocsLlmsTxt as it, acceptsDocsMarkdown as j, DEFAULT_SITEMAP_MD_ROUTE as jt, DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER as k, DEFAULT_SITEMAP_MANIFEST_PATH as kt, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as l, normalizeDocsRelated as ln, resolveDocsAgentFeedbackConfig as lt, DEFAULT_DOCS_DIAGNOSTICS_ROUTE as m, PAGE_AGENT_CONTRACT_START_MARKER as mn, resolveDocsLlmsTxtSections as mt, DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE as n, createDocsStandardsResponse as nn, parseDocsAgentFeedbackData as nt, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE as o, resolveDocsPublishedAgentSkill as on, renderDocsMarkdownNotFound as ot, DEFAULT_DOCS_DIAGNOSTICS_FORMAT as p, PAGE_AGENT_CONTRACT_FIELD_SCHEMA as pn, resolveDocsLlmsTxtRequest as pt, isDocsConfigRequest as q, DEFAULT_AGENT_SKILLS_INDEX_ROUTE as qt, DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA as r, getDocsDiscoveryLinkHeader as rn, renderDocsAgentsDocument as rt, DEFAULT_AGENT_SPEC_ROUTE as s, resolveDocsStandardsDiscoveryRequest as sn, renderDocsSkillDocument as st, DEFAULT_AGENTS_MD_ROUTE as t, buildDocsApiCatalog as tn, normalizeDocsUrlPath as tt, DEFAULT_DOCS_API_ROUTE as u, renderDocsRelatedMarkdownLines as un, resolveDocsAgentFeedbackRequest as ut, DEFAULT_LLMS_TXT_ROUTE as v, normalizePageAgentFrontmatter as vn, resolveDocsOpenApiDiscoveryConfig as vt, DEFAULT_SKILL_MD_ROUTE as w, findDocsAudienceMdxIssues as wt, DEFAULT_MCP_ROUTE as x, stripGeneratedPageAgentContractMarkdown as xn, selectDocsLlmsTxtContent as xt, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as y, renderPageAgentContractMarkdown as yn, resolveDocsRequestApiRoute as yt, detectDocsMarkdownAgentRequest as z, resolveDocsSitemapConfig as zt };