@farming-labs/theme 0.2.58 → 0.2.59

package/dist/bounded-route-cache.mjs

@@ -0,0 +1,40 @@
+//#region src/bounded-route-cache.ts
+/**
+* A small per-locale LRU cache for request-derived route variants.
+*
+* Locales come from the configured i18n locale list, while routes can be
+* inferred from request URLs. Bounding each locale prevents arbitrary request
+* paths from growing the cache indefinitely.
+*/
+var BoundedRouteCache = class {
+	entries = /* @__PURE__ */ new Map();
+	constructor(maxRoutesPerLocale) {
+		this.maxRoutesPerLocale = maxRoutesPerLocale;
+		if (!Number.isInteger(maxRoutesPerLocale) || maxRoutesPerLocale < 1) throw new RangeError("maxRoutesPerLocale must be a positive integer");
+	}
+	get(locale, route) {
+		const routes = this.entries.get(locale);
+		if (!routes?.has(route)) return void 0;
+		const value = routes.get(route);
+		routes.delete(route);
+		routes.set(route, value);
+		return value;
+	}
+	set(locale, route, value) {
+		let routes = this.entries.get(locale);
+		if (!routes) {
+			routes = /* @__PURE__ */ new Map();
+			this.entries.set(locale, routes);
+		}
+		routes.delete(route);
+		routes.set(route, value);
+		while (routes.size > this.maxRoutesPerLocale) {
+			const oldestRoute = routes.keys().next().value;
+			if (oldestRoute === void 0) break;
+			routes.delete(oldestRoute);
+		}
+	}
+};
+
+//#endregion
+export { BoundedRouteCache };

package/dist/docs-api.d.mts

@@ -34,6 +34,8 @@ interface AIOptions {
 }
 interface DocsAPIOptions {
   rootDir?: string;
+  /** Internal docs API route used by query-form discovery endpoints. */
+  apiRoute?: string;
   /** Docs entry folder (default: read from docs.config) */
   entry?: string;
   /** Public docs route prefix. Defaults to the docs entry path. */
@@ -66,6 +68,8 @@ interface DocsAPIOptions {
   mcp?: boolean | DocsMcpConfig;
   /** llms.txt configuration. Enabled by default; set false to opt out. */
   llmsTxt?: boolean | LlmsTxtOptions;
+  /** Override RFC 9727 API catalog discovery without disabling Agent Skills discovery. */
+  apiCatalog?: boolean;
   /** Sitemap configuration used for sitemap.xml, sitemap.md, and docs/sitemap.md. */
   sitemap?: boolean | DocsSitemapConfig;
   /** Robots.txt generation policy used for the agent discovery spec. */
@@ -93,7 +97,7 @@ type LlmsTxtOptions = LlmsTxtConfig;
 /**
  * Create a unified docs API route handler.
  *
- * Returns `{ GET, POST }` for use in a Next.js route handler:
+ * Returns `{ GET, HEAD, POST }` for use in a Next.js route handler:
  * - **GET  ?query=…**        → full-text search
  * - **GET  ?format=llms**     → llms.txt (concise page listing)
  * - **GET  ?format=llms-full** → llms-full.txt (full page content)
@@ -104,7 +108,7 @@ type LlmsTxtOptions = LlmsTxtConfig;
  * ```ts
  * // app/api/docs/route.ts (auto-generated by withDocs)
  * import { createDocsAPI } from "@farming-labs/next/api";
- * export const { GET, POST } = createDocsAPI();
+ * export const { GET, HEAD, POST } = createDocsAPI();
  * export const revalidate = false;
  * ```
  *
@@ -115,6 +119,7 @@ type LlmsTxtOptions = LlmsTxtConfig;
  * The `@farming-labs/theme/api` path is kept for compatibility and will be phased out.
  */
 declare function createDocsAPI(options?: DocsAPIOptions): {
+  HEAD(request: Request): Promise<Response>;
   /**
    * GET handler — search, markdown, llms.txt, llms-full.txt, or skill.md.
    */

package/dist/docs-api.mjs

@@ -1,9 +1,10 @@
 import { withLangInUrl } from "./i18n.mjs";
 import { getNextAppDir } from "./get-app-dir.mjs";
+import { BoundedRouteCache } from "./bounded-route-cache.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { DEFAULT_SITEMAP_MD_DOCS_ROUTE, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsLlmsTxtMaxCharsIssue, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
+import { DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsRequestApiRoute, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -24,7 +25,7 @@ import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, create
 * ```ts
 * // app/api/docs/route.ts (auto-generated by withDocs)
 * import { createDocsAPI } from "@farming-labs/next/api";
-* export const { GET, POST } = createDocsAPI();
+* export const { GET, HEAD, POST } = createDocsAPI();
 * export const revalidate = false;
 * ```
 */
@@ -35,6 +36,7 @@ const FILE_EXTS = [
 	"js"
 ];
 const DEFAULT_DOCS_API_ROUTE = "/api/docs";
+const MAX_LLMS_CACHE_ROUTES_PER_LOCALE = 8;
 const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";
 const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
 const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
@@ -202,12 +204,13 @@ function resolveApiReferenceOpenApiDiscovery(value) {
 	return {
 		enabled: true,
 		url: `${DEFAULT_DOCS_API_ROUTE}?format=openapi`,
+		urlSource: "default",
 		source: apiReference.specUrl ? "configured" : "generated",
 		specUrl: apiReference.specUrl,
 		apiReferencePath: `/${apiReference.path}`
 	};
 }
-function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
@@ -215,6 +218,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	const agentContractMcpTools = resolveDocsAgentContractMcpTools(mcp);
+	const agentSpecRoute = apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${apiRoute}?agent=spec`;
 	return {
 		version: "1",
 		name: "@farming-labs/docs",
@@ -247,32 +251,46 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			structuredData: true,
 			apiReference: openapi.enabled,
 			openapi: openapi.enabled,
+			apiCatalog,
+			agentSkillsDiscovery: true,
 			agentFeedback: feedback.enabled,
 			locales: localesEnabled
 		},
 		api: {
-			docs: DEFAULT_DOCS_API_ROUTE,
-			config: `${DEFAULT_DOCS_API_ROUTE}?format=config`,
-			diagnostics: `${DEFAULT_DOCS_API_ROUTE}?format=diagnostics`,
-			agentSpec: DEFAULT_AGENT_SPEC_ROUTE,
+			docs: apiRoute,
+			config: `${apiRoute}?format=config`,
+			diagnostics: `${apiRoute}?format=diagnostics`,
+			agentSpec: agentSpecRoute,
 			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_DOCS_API_ROUTE}?format=openapi`
+			agentSpecQuery: `${apiRoute}?agent=spec`,
+			agents: `${apiRoute}?format=agents`,
+			openapi: `${apiRoute}?format=openapi`,
+			...apiCatalog ? {
+				apiCatalog: DEFAULT_API_CATALOG_ROUTE,
+				apiCatalogQuery: `${apiRoute}?format=api-catalog`
+			} : {},
+			agentSkillsIndex: DEFAULT_AGENT_SKILLS_INDEX_ROUTE
+		},
+		apiCatalog: {
+			enabled: apiCatalog,
+			route: apiCatalog ? DEFAULT_API_CATALOG_ROUTE : null,
+			api: apiCatalog ? `${apiRoute}?format=api-catalog` : null,
+			mediaType: "application/linkset+json",
+			profile: "https://www.rfc-editor.org/info/rfc9727"
 		},
 		config: {
 			format: "docs-config-map.v1",
-			endpoint: `${DEFAULT_DOCS_API_ROUTE}?format=config`
+			endpoint: `${apiRoute}?format=config`
 		},
 		markdown: {
 			enabled: true,
 			acceptHeader: "text/markdown",
 			pagePattern: `/${normalizedEntry}/{slug}.md`,
 			rootPage: `/${normalizedEntry}.md`,
-			apiPattern: `${DEFAULT_DOCS_API_ROUTE}?format=markdown&path={slug}`,
+			apiPattern: `${apiRoute}?format=markdown&path={slug}`,
 			resolutionOrder: [
 				"agent.md",
 				"agent audience projection",
@@ -310,8 +328,8 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			enabled: llms.enabled,
 			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: `${apiRoute}?format=llms`,
+			full: `${apiRoute}?format=llms-full`,
 			publicTxt: DEFAULT_LLMS_TXT_ROUTE,
 			publicFull: DEFAULT_LLMS_FULL_TXT_ROUTE,
 			wellKnownTxt: DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
@@ -329,14 +347,14 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			xml: {
 				enabled: sitemapConfig.xml.enabled,
 				route: sitemapConfig.xml.route,
-				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-xml`
+				api: `${apiRoute}?format=sitemap-xml`
 			},
 			markdown: {
 				enabled: sitemapConfig.markdown.enabled,
 				route: sitemapConfig.markdown.route,
 				docsRoute: sitemapConfig.markdown.docsRoute,
 				wellKnownRoute: sitemapConfig.markdown.wellKnownRoute,
-				api: `${DEFAULT_DOCS_API_ROUTE}?format=sitemap-md`,
+				api: `${apiRoute}?format=sitemap-md`,
 				defaultDocsRoute: DEFAULT_SITEMAP_MD_DOCS_ROUTE
 			}
 		},
@@ -363,7 +381,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 		},
 		openapi: {
 			enabled: openapi.enabled,
-			url: openapi.url ?? null,
+			url: openapi.enabled ? `${apiRoute}?format=openapi` : null,
 			source: openapi.source ?? null,
 			specUrl: openapi.specUrl ?? null,
 			apiReferencePath: openapi.apiReferencePath ?? null,
@@ -371,7 +389,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 		},
 		search: {
 			enabled: searchEnabled,
-			endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`,
+			endpoint: `${apiRoute}?query={query}`,
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang"
@@ -381,7 +399,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			file: "AGENTS.md",
 			route: DEFAULT_AGENTS_MD_ROUTE,
 			wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
-			api: `${DEFAULT_DOCS_API_ROUTE}?format=agents`,
+			api: `${apiRoute}?format=agents`,
 			generatedFallback: true,
 			aliases: [DEFAULT_AGENT_MD_ROUTE, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE]
 		},
@@ -390,8 +408,16 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			file: "skill.md",
 			route: DEFAULT_SKILL_MD_ROUTE,
 			wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
-			api: `${DEFAULT_DOCS_API_ROUTE}?format=skill`,
+			api: `${apiRoute}?format=skill`,
 			generatedFallback: true,
+			discovery: {
+				schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+				index: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+				artifact: `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/{name}/SKILL.md`,
+				apiIndex: `${apiRoute}?format=agent-skills`,
+				apiArtifact: `${apiRoute}?format=agent-skill&name={name}`,
+				digest: "sha256"
+			},
 			registry: "skills.sh",
 			install: "npx skills add farming-labs/docs",
 			recommended: [{
@@ -415,8 +441,8 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			enabled: feedback.enabled,
 			schema: feedback.schemaRoute,
 			submit: feedback.route,
-			schemaQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent&schema=1`,
-			submitQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent`
+			schemaQuery: `${apiRoute}?feedback=agent&schema=1`,
+			submitQuery: `${apiRoute}?feedback=agent`
 		},
 		instructions: {
 			preferMarkdownRoutes: true,
@@ -618,9 +644,14 @@ function readCloudConfig(root) {
 			const configObject = extractRootConfigObject(content, sanitized);
 			const cloudBlock = extractObjectLiteral(configObject?.content ?? content, configObject?.sanitized ?? sanitized, "cloud");
 			if (!cloudBlock) continue;
-			const apiKeyBlock = extractObjectLiteral(cloudBlock, stripCommentsAndStrings(cloudBlock), "apiKey");
+			const cloudBlockSanitized = stripCommentsAndStrings(cloudBlock);
+			const apiKeyBlock = extractObjectLiteral(cloudBlock, cloudBlockSanitized, "apiKey");
 			const apiKeyEnv = apiKeyBlock ? readStringFromBlock(apiKeyBlock, "env") : void 0;
-			return apiKeyEnv ? { apiKey: { env: apiKeyEnv } } : {};
+			const apiRoute = readTopLevelString(cloudBlock, cloudBlockSanitized, "apiRoute");
+			return {
+				...apiKeyEnv ? { apiKey: { env: apiKeyEnv } } : {},
+				...apiRoute ? { apiRoute } : {}
+			};
 		} catch {}
 	}
 }
@@ -702,6 +733,14 @@ function readTopLevelBoolean(content, key) {
 	if (!match) return void 0;
 	return match[1] === "true";
 }
+function readTopLevelString(content, sanitized, key) {
+	const keyIndex = findTopLevelPropertyIndex(sanitized, key);
+	if (keyIndex === -1) return void 0;
+	const colonIndex = sanitized.indexOf(":", keyIndex + key.length);
+	if (colonIndex === -1) return void 0;
+	const match = content.slice(colonIndex + 1).match(/^\s*(?:"([^"]*)"|'([^']*)')/s);
+	return match?.[1] ?? match?.[2];
+}
 function findTopLevelPropertyIndex(content, key) {
 	let depth = 0;
 	for (let index = 0; index < content.length; index += 1) {
@@ -726,11 +765,11 @@ function findTopLevelPropertyIndex(content, key) {
 	return -1;
 }
 function extractRootConfigObject(content, sanitized) {
-	const defineDocsIndex = sanitized.indexOf("defineDocs");
+	const defineDocsIndex = sanitized.match(/\bdefineDocs\s*\(/)?.index ?? -1;
 	const exportDefaultIndex = sanitized.indexOf("export default");
 	let braceStart = -1;
 	if (defineDocsIndex !== -1) {
-		const parenIndex = sanitized.indexOf("(", defineDocsIndex);
+		const parenIndex = sanitized.indexOf("(", defineDocsIndex + 10);
 		if (parenIndex !== -1) braceStart = sanitized.indexOf("{", parenIndex);
 	}
 	if (braceStart === -1 && exportDefaultIndex !== -1) braceStart = sanitized.indexOf("{", exportDefaultIndex);
@@ -1005,6 +1044,10 @@ function normalizeUrlPath(value) {
 	if (normalized === "/") return normalized;
 	return normalized.replace(/\/+$/, "");
 }
+function normalizeDocsApiRoute(value) {
+	const route = value?.trim().split(/[?#]/, 1)[0] || DEFAULT_DOCS_API_ROUTE;
+	return normalizeUrlPath(route.startsWith("/") ? route : `/${route}`);
+}
 function normalizeRequestedMarkdownPath(entry, requestedPath) {
 	const trimmed = requestedPath.trim().replace(/\.md$/i, "");
 	if (!trimmed) return `/${entry}`;
@@ -1186,13 +1229,15 @@ function renderMarkdownDocument(page, options = {}) {
 		sitemap: options.sitemap
 	});
 }
-function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
 	const searchEnabled = isSearchEnabled(search);
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const agentSpecRoute = apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${apiRoute}?agent=spec`;
+	const openapiUrl = openapi.urlSource === "default" && openapi.url === `${DEFAULT_DOCS_API_ROUTE}?format=openapi` ? `${apiRoute}?format=openapi` : openapi.url;
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	const lines = [
 		"---",
@@ -1205,9 +1250,11 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 		`Base URL: ${origin}`
 	];
 	if (siteDescription) lines.push(`Description: ${siteDescription}`);
-	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, "- You can also request text/markdown from normal page URLs.");
-	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
-	if (openapi.enabled && openapi.url) lines.push(`- Fetch ${openapi.url} for the machine-readable OpenAPI schema before scraping API reference pages.`);
+	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecRoute}.`);
+	if (apiCatalog) lines.push(`- Fetch ${DEFAULT_API_CATALOG_ROUTE} for the standards-based API catalog.`);
+	lines.push(`- Fetch ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} to discover the published site skill and verify its SHA-256 digest.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, "- You can also request text/markdown from normal page URLs.");
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query} when you do not know the page.`);
+	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} for the machine-readable OpenAPI schema before scraping API reference pages.`);
 	if (llms.enabled) {
 		lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
 		for (const section of llmsSections) lines.push(`- Use ${section.route} for the ${section.title} llms.txt section.`);
@@ -1219,7 +1266,9 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	if (robotsEnabled) lines.push(`- Check ${DEFAULT_ROBOTS_TXT_ROUTE} for crawler and AI-agent access policy.`);
 	if (mcp.enabled) lines.push(`- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools when your environment supports MCP.`);
 	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting agent feedback to ${feedback.route}.`);
-	lines.push("", "## Routes", `- 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: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`);
+	lines.push("", "## Routes", `- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${apiRoute}?format=agents`, `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${apiRoute}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`);
+	if (apiCatalog) lines.push(`- API catalog: ${DEFAULT_API_CATALOG_ROUTE}`);
+	lines.push(`- Agent Skills index: ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}`, `- Agent Skills artifacts: ${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/{name}/SKILL.md`, `- Markdown root: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`);
 	if (robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_ROBOTS_TXT_ROUTE}`);
 	if (llms.enabled) {
 		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}`);
@@ -1228,8 +1277,8 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 			lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
 		}
 	}
-	if (openapi.enabled && openapi.url) {
-		lines.push(`- OpenAPI schema: ${openapi.url}`);
+	if (openapi.enabled && openapiUrl) {
+		lines.push(`- OpenAPI schema: ${openapiUrl}`);
 		if (openapi.apiReferencePath) lines.push(`- API reference: ${openapi.apiReferencePath}`);
 	}
 	if (sitemapConfig.enabled) {
@@ -1240,13 +1289,15 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	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 renderAgentsDocument({ origin, entry, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
 	const searchEnabled = isSearchEnabled(search);
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
+	const agentSpecRoute = apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${apiRoute}?agent=spec`;
+	const openapiUrl = openapi.urlSource === "default" && openapi.url === `${DEFAULT_DOCS_API_ROUTE}?format=openapi` ? `${apiRoute}?format=openapi` : openapi.url;
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	const lines = [
 		"# Agent Instructions",
@@ -1255,7 +1306,9 @@ function renderAgentsDocument({ origin, entry, search, mcp, feedback, llms, site
 		`Base URL: ${origin}`
 	];
 	if (siteDescription) lines.push(`Description: ${siteDescription}`);
-	lines.push("", "## Start Here", `- Read ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} first; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Read /${normalizedEntry}.md for the root docs page.`, `- Read /${normalizedEntry}/{slug}.md for page-specific context.`);
+	lines.push("", "## Start Here", `- Read ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} first; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecRoute}.`);
+	if (apiCatalog) lines.push(`- Read ${DEFAULT_API_CATALOG_ROUTE} for the standards-based API catalog.`);
+	lines.push(`- Read ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} to discover the published site skill and verify its SHA-256 digest.`, `- Read /${normalizedEntry}.md for the root docs page.`, `- Read /${normalizedEntry}/{slug}.md for page-specific context.`);
 	if (llms.enabled) {
 		lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} as the compact docs map.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} when you need the full markdown bundle.`);
 		for (const section of llmsSections) lines.push(`- Use ${section.route} for the ${section.title} section map.`);
@@ -1265,11 +1318,13 @@ function renderAgentsDocument({ origin, entry, search, mcp, feedback, llms, site
 		if (sitemapConfig.xml.enabled) lines.push(`- Use ${sitemapConfig.xml.route} for canonical URLs and freshness metadata.`);
 	}
 	if (robotsEnabled) lines.push(`- Check ${DEFAULT_ROBOTS_TXT_ROUTE} before crawling broadly.`);
-	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when the route is unknown.`);
-	if (openapi.enabled && openapi.url) lines.push(`- Fetch ${openapi.url} before scraping API reference pages; prefer schemas over prose.`);
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query} when the route is unknown.`);
+	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} before scraping API reference pages; prefer schemas over prose.`);
 	if (mcp.enabled) lines.push(`- Use MCP at ${DEFAULT_MCP_PUBLIC_ROUTE} or ${DEFAULT_MCP_WELL_KNOWN_ROUTE} when your environment supports MCP tools.`);
 	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting feedback to ${feedback.route}.`);
-	lines.push("", "## Working Rules", "- Prefer markdown routes, llms.txt, sitemap.md, OpenAPI schemas, and MCP tools 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 route returns a markdown 404, use the sitemap and discovery spec before guessing a slug.", "", "## Public Routes", `- 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: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`);
+	lines.push("", "## Working Rules", "- Prefer markdown routes, llms.txt, sitemap.md, OpenAPI schemas, and MCP tools 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 route returns a markdown 404, use the sitemap and discovery spec before guessing a slug.", "", "## Public Routes", `- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${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: ${apiRoute}?format=skill`, `- Markdown root: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`);
+	if (apiCatalog) lines.push(`- API catalog: ${DEFAULT_API_CATALOG_ROUTE}`);
+	lines.push(`- Agent Skills index: ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE}`, `- Agent Skills artifacts: ${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/{name}/SKILL.md`);
 	if (llms.enabled) {
 		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 llmsSections) {
@@ -1282,8 +1337,8 @@ function renderAgentsDocument({ origin, entry, search, mcp, feedback, llms, site
 		if (sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${sitemapConfig.xml.route}`);
 		if (sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${sitemapConfig.markdown.route}`, ...sitemapConfig.markdown.docsRoute ? [`- Sitemap docs alias: ${sitemapConfig.markdown.docsRoute}`] : [], `- Sitemap well-known alias: ${sitemapConfig.markdown.wellKnownRoute}`);
 	}
-	if (openapi.enabled && openapi.url) {
-		lines.push(`- OpenAPI schema: ${openapi.url}`);
+	if (openapi.enabled && openapiUrl) {
+		lines.push(`- OpenAPI schema: ${openapiUrl}`);
 		if (openapi.apiReferencePath) lines.push(`- API reference: ${openapi.apiReferencePath}`);
 	}
 	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
@@ -2223,26 +2278,35 @@ function readLlmsTxtConfig(root) {
 		const configPath = path.join(root, `docs.config.${ext}`);
 		if (fs.existsSync(configPath)) try {
 			const content = fs.readFileSync(configPath, "utf-8");
-			const navTitleMatch = content.match(/nav\s*:\s*\{[^}]*title\s*:\s*["']([^"']+)["']/s);
-			if (!content.includes("llmsTxt")) return {
+			const sanitized = stripCommentsAndStrings(content);
+			const configObject = extractRootConfigObject(content, sanitized);
+			const scopedContent = configObject?.content ?? content;
+			const scopedSanitized = configObject?.sanitized ?? sanitized;
+			const navBlock = extractObjectLiteral(scopedContent, scopedSanitized, "nav");
+			const navTitle = navBlock ? readTopLevelString(navBlock, stripCommentsAndStrings(navBlock), "title") : void 0;
+			const llmsTxtBoolean = readTopLevelBoolean(scopedSanitized, "llmsTxt");
+			if (llmsTxtBoolean === true) return {
 				enabled: true,
-				siteTitle: navTitleMatch?.[1]
+				siteTitle: navTitle
 			};
-			if (/llmsTxt\s*:\s*true/.test(content)) return {
+			if (llmsTxtBoolean === false) return { enabled: false };
+			const llmsTxtBlock = extractObjectLiteral(scopedContent, scopedSanitized, "llmsTxt");
+			if (!llmsTxtBlock) return {
 				enabled: true,
-				siteTitle: navTitleMatch?.[1]
+				siteTitle: navTitle
 			};
-			if (/llmsTxt\s*:\s*false/.test(content)) return { enabled: false };
-			const enabledMatch = content.match(/llmsTxt\s*:\s*\{[^}]*enabled\s*:\s*(true|false)/s);
-			if (enabledMatch && enabledMatch[1] === "false") return { enabled: false };
-			const baseUrlMatch = content.match(/llmsTxt\s*:\s*\{[^}]*baseUrl\s*:\s*["']([^"']+)["']/s);
-			const siteTitleMatch = content.match(/llmsTxt\s*:\s*\{[^}]*siteTitle\s*:\s*["']([^"']+)["']/s);
-			const siteDescMatch = content.match(/llmsTxt\s*:\s*\{[^}]*siteDescription\s*:\s*["']([^"']+)["']/s);
+			const llmsTxtSanitized = stripCommentsAndStrings(llmsTxtBlock);
+			if (readTopLevelBoolean(llmsTxtSanitized, "enabled") === false) return { enabled: false };
+			const apiCatalog = readTopLevelBoolean(llmsTxtSanitized, "apiCatalog");
+			const baseUrl = readTopLevelString(llmsTxtBlock, llmsTxtSanitized, "baseUrl");
+			const siteTitle = readTopLevelString(llmsTxtBlock, llmsTxtSanitized, "siteTitle");
+			const siteDescription = readTopLevelString(llmsTxtBlock, llmsTxtSanitized, "siteDescription");
 			return {
 				enabled: true,
-				baseUrl: baseUrlMatch?.[1],
-				siteTitle: siteTitleMatch?.[1] ?? navTitleMatch?.[1],
-				siteDescription: siteDescMatch?.[1]
+				apiCatalog,
+				baseUrl,
+				siteTitle: siteTitle ?? navTitle,
+				siteDescription
 			};
 		} catch {}
 	}
@@ -2347,7 +2411,7 @@ function generateLlmsTxt(indexes, options) {
 /**
 * Create a unified docs API route handler.
 *
-* Returns `{ GET, POST }` for use in a Next.js route handler:
+* Returns `{ GET, HEAD, POST }` for use in a Next.js route handler:
 * - **GET  ?query=…**        → full-text search
 * - **GET  ?format=llms**     → llms.txt (concise page listing)
 * - **GET  ?format=llms-full** → llms-full.txt (full page content)
@@ -2358,7 +2422,7 @@ function generateLlmsTxt(indexes, options) {
 * ```ts
 * // app/api/docs/route.ts (auto-generated by withDocs)
 * import { createDocsAPI } from "@farming-labs/next/api";
-* export const { GET, POST } = createDocsAPI();
+* export const { GET, HEAD, POST } = createDocsAPI();
 * export const revalidate = false;
 * ```
 *
@@ -2382,8 +2446,15 @@ function createDocsAPI(options) {
 	const i18n = resolveDocsI18n(i18nConfig);
 	const aiConfig = options?.ai ?? readAIConfig(root);
 	const cloudConfig = options?.cloud ?? readCloudConfig(root);
+	const configuredApiRouteInput = options?.apiRoute ?? cloudConfig?.apiRoute;
+	const configuredApiRoute = normalizeDocsApiRoute(configuredApiRouteInput);
+	const effectiveCloudConfig = options?.apiRoute !== void 0 || cloudConfig?.apiRoute !== void 0 ? {
+		...cloudConfig,
+		apiRoute: configuredApiRoute
+	} : cloudConfig;
 	const searchConfig = options?.search;
 	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
+	const apiCatalogEnabled = options?.apiCatalog ?? llmsConfig.apiCatalog ?? true;
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
 	const robotsConfig = options?.robots ?? readRobotsConfig(root);
 	const markdownMetadataBaseUrl = resolveDocsMetadataBaseUrl({
@@ -2403,6 +2474,7 @@ function createDocsAPI(options) {
 	const openapiDiscovery = resolveApiReferenceOpenApiDiscovery(apiReferenceConfig);
 	const rawMcpConfig = options?.mcp ?? readMcpConfig(root);
 	const mcpConfig = resolveDocsMcpConfig(rawMcpConfig, { defaultName: llmsConfig.siteTitle ?? "Documentation" });
+	const discoveryLinkHeader = getDocsDiscoveryLinkHeader({ includeApiCatalog: apiCatalogEnabled });
 	const telemetryConfig = {
 		entry,
 		docsPath,
@@ -2410,7 +2482,7 @@ function createDocsAPI(options) {
 		telemetry: options?.telemetry,
 		search: searchConfig,
 		ai: aiConfig,
-		cloud: cloudConfig,
+		cloud: effectiveCloudConfig,
 		i18n: i18nConfig ?? void 0,
 		feedback: options?.feedback,
 		mcp: rawMcpConfig,
@@ -2420,15 +2492,15 @@ function createDocsAPI(options) {
 		apiReference: apiReferenceConfig,
 		metadata: options?.metadata
 	};
-	const { rootDir: _rootDir, language: _language, ...docsConfigMapOptions } = options ?? {};
+	const { rootDir: _rootDir, language: _language, apiRoute: _apiRoute, ...docsConfigMapOptions } = options ?? {};
 	const docsConfigMapInput = { ...docsConfigMapOptions };
+	if (effectiveCloudConfig !== void 0) docsConfigMapInput.cloud = effectiveCloudConfig;
 	const setConfigMapFallback = (key, value) => {
 		if (Object.prototype.hasOwnProperty.call(docsConfigMapInput, key) || value === void 0) return;
 		docsConfigMapInput[key] = value;
 	};
 	setConfigMapFallback("entry", entry);
 	setConfigMapFallback("ai", Object.keys(aiConfig).length > 0 ? aiConfig : void 0);
-	setConfigMapFallback("cloud", cloudConfig);
 	setConfigMapFallback("search", searchConfig);
 	setConfigMapFallback("i18n", i18nConfig ?? void 0);
 	setConfigMapFallback("mcp", rawMcpConfig);
@@ -2437,8 +2509,12 @@ function createDocsAPI(options) {
 		...docsConfigMapInput,
 		docsPath: docsConfigMapInput.docsPath ?? docsPath,
 		contentDir: docsConfigMapInput.contentDir ?? contentDir,
+		cloud: effectiveCloudConfig,
 		feedback: docsConfigMapInput.feedback ?? options?.feedback,
-		llmsTxt: docsConfigMapInput.llmsTxt ?? llmsConfig,
+		llmsTxt: {
+			...llmsConfig,
+			apiCatalog: apiCatalogEnabled
+		},
 		sitemap: docsConfigMapInput.sitemap ?? sitemapConfig,
 		robots: docsConfigMapInput.robots ?? robotsConfig,
 		staticExport: docsConfigMapInput.staticExport ?? options?.staticExport
@@ -2521,7 +2597,7 @@ function createDocsAPI(options) {
 		};
 	}
 	const indexesByLocale = /* @__PURE__ */ new Map();
-	const llmsCacheByLocale = /* @__PURE__ */ new Map();
+	const llmsCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
 	const markdownSourcesByLocale = /* @__PURE__ */ new Map();
 	function getIndexes(ctx) {
 		const key = ctx.locale ?? "__default__";
@@ -2594,26 +2670,73 @@ function createDocsAPI(options) {
 		};
 		return null;
 	}
-	function getLlmsContent(ctx) {
-		const key = ctx.locale ?? "__default__";
-		const cached = llmsCacheByLocale.get(key);
+	function getLlmsContent(ctx, apiRoute) {
+		const cached = llmsCache.get(ctx.locale, apiRoute);
 		if (cached) return cached;
 		const next = generateLlmsTxt(getIndexes(ctx), {
 			siteTitle: llmsConfig.siteTitle ?? "Documentation",
 			siteDescription: llmsConfig.siteDescription,
 			baseUrl: llmsConfig.baseUrl ?? "",
+			apiRoute,
 			maxChars: llmsConfig.maxChars,
 			sections: llmsConfig.sections,
+			apiCatalog: apiCatalogEnabled,
 			openapi: openapiDiscovery
 		});
-		llmsCacheByLocale.set(key, next);
+		llmsCache.set(ctx.locale, apiRoute, next);
 		return next;
 	}
-	return {
+	async function resolveStandardsResponse(request, url) {
+		const apiRoute = resolveDocsRequestApiRoute(url, configuredApiRouteInput);
+		const resolved = resolveDocsStandardsDiscoveryRequest(url, { apiRoute });
+		if (!resolved) return null;
+		const method = request.method.toUpperCase();
+		const needsSkill = (method === "GET" || method === "HEAD") && resolved.kind !== "api-catalog";
+		const fallbackSkillDocument = needsSkill ? renderSkillDocument({
+			origin: url.origin,
+			entry,
+			apiRoute,
+			apiCatalog: apiCatalogEnabled,
+			i18n,
+			search: searchConfig,
+			mcp: mcpConfig,
+			feedback: agentFeedbackConfig,
+			llms: llmsConfig,
+			sitemap: sitemapConfig,
+			robots: robotsConfig,
+			openapi: openapiDiscovery
+		}) : "";
+		return createDocsStandardsDiscoveryResponse({
+			request,
+			preferredSkillDocument: needsSkill ? readRootSkillDocument(root) : null,
+			fallbackSkillDocument,
+			origin: url.origin,
+			entry,
+			docsPath,
+			apiCatalog: apiCatalogEnabled,
+			apiRoute,
+			i18n,
+			search: searchConfig,
+			mcp: mcpConfig,
+			feedback: agentFeedbackConfig,
+			llms: llmsConfig,
+			sitemap: sitemapConfig,
+			robots: robotsConfig,
+			openapi: openapiDiscovery,
+			markdown: {
+				acceptHeader: true,
+				signatureAgentHeader: true
+			}
+		});
+	}
+	const handlers = {
 		async GET(request) {
 			trackTelemetryRequest(request);
 			const ctx = resolveContextFromRequest(request);
 			const url = new URL(request.url);
+			const requestMethod = request.method.toUpperCase();
+			const isHeadRequest = requestMethod === "HEAD";
+			const requestApiRoute = resolveDocsRequestApiRoute(url, configuredApiRouteInput);
 			const requestAnalyticsProperties = getRequestAnalyticsProperties(request);
 			if (isDocsConfigRequest(url)) return Response.json(buildDocsConfigMap(docsConfigMapInput), { headers: {
 				"Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -2621,7 +2744,9 @@ function createDocsAPI(options) {
 			} });
 			if (isDocsDiagnosticsRequest(url)) return Response.json(buildDocsDiagnostics(docsDiagnosticsInput, {
 				adapter: "next",
+				apiCatalog: apiCatalogEnabled,
 				entry,
+				apiRoute: requestApiRoute,
 				i18n,
 				mcp: mcpConfig,
 				feedback: agentFeedbackConfig,
@@ -2630,6 +2755,8 @@ function createDocsAPI(options) {
 				"Cache-Control": "public, max-age=0, s-maxage=3600",
 				"X-Robots-Tag": "noindex"
 			} });
+			const standardsResponse = await resolveStandardsResponse(request, url);
+			if (standardsResponse) return standardsResponse;
 			if (resolveAgentSpecRequest(url)) {
 				await emitDocsAnalyticsEvent(analytics, {
 					type: "agent_spec_request",
@@ -2639,12 +2766,20 @@ function createDocsAPI(options) {
 					locale: ctx.locale,
 					properties: {
 						...requestAnalyticsProperties,
-						method: "GET"
+						method: requestMethod
 					}
 				});
+				if (isHeadRequest) return new Response(null, { headers: {
+					"Content-Type": "application/json",
+					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					Link: discoveryLinkHeader,
+					"X-Robots-Tag": "noindex"
+				} });
 				return Response.json(buildAgentSpec({
 					origin: url.origin,
 					entry,
+					apiRoute: requestApiRoute,
+					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
 					mcp: mcpConfig,
@@ -2655,6 +2790,7 @@ function createDocsAPI(options) {
 					openapi: openapiDiscovery
 				}), { headers: {
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					Link: discoveryLinkHeader,
 					"X-Robots-Tag": "noindex"
 				} });
 			}
@@ -2666,6 +2802,11 @@ function createDocsAPI(options) {
 						"X-Robots-Tag": "noindex"
 					}
 				});
+				if (isHeadRequest) return new Response(null, { headers: {
+					"Content-Type": "application/json; charset=utf-8",
+					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					"X-Robots-Tag": "noindex"
+				} });
 				const document = await buildApiReferenceOpenApiDocumentAsync(apiReferenceDocsConfig, {
 					framework: "next",
 					rootDir: root,
@@ -2691,10 +2832,10 @@ function createDocsAPI(options) {
 					locale: ctx.locale,
 					properties: {
 						...requestAnalyticsProperties,
-						method: "GET"
+						method: requestMethod
 					}
 				});
-				return new Response(JSON.stringify(agentFeedbackConfig.schema, null, 2), { headers: {
+				return new Response(isHeadRequest ? null : JSON.stringify(agentFeedbackConfig.schema, null, 2), { headers: {
 					"Content-Type": "application/schema+json; charset=utf-8",
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
 					"X-Robots-Tag": "noindex"
@@ -2709,12 +2850,14 @@ function createDocsAPI(options) {
 					locale: ctx.locale,
 					properties: {
 						...requestAnalyticsProperties,
-						method: "GET"
+						method: requestMethod
 					}
 				});
-				return new Response(readRootAgentsDocument(root) ?? renderAgentsDocument({
+				return new Response(isHeadRequest ? null : readRootAgentsDocument(root) ?? renderAgentsDocument({
 					origin: url.origin,
 					entry,
+					apiRoute: requestApiRoute,
+					apiCatalog: apiCatalogEnabled,
 					search: searchConfig,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
@@ -2725,6 +2868,7 @@ function createDocsAPI(options) {
 				}), { headers: {
 					"Content-Type": "text/markdown; charset=utf-8",
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					Link: discoveryLinkHeader,
 					"X-Robots-Tag": "noindex"
 				} });
 			}
@@ -2737,12 +2881,14 @@ function createDocsAPI(options) {
 					locale: ctx.locale,
 					properties: {
 						...requestAnalyticsProperties,
-						method: "GET"
+						method: requestMethod
 					}
 				});
-				return new Response(readRootSkillDocument(root) ?? renderSkillDocument({
+				return new Response(isHeadRequest ? null : readRootSkillDocument(root) ?? renderSkillDocument({
 					origin: url.origin,
 					entry,
+					apiRoute: requestApiRoute,
+					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
 					mcp: mcpConfig,
@@ -2754,12 +2900,14 @@ function createDocsAPI(options) {
 				}), { headers: {
 					"Content-Type": "text/markdown; charset=utf-8",
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					Link: discoveryLinkHeader,
 					"X-Robots-Tag": "noindex"
 				} });
 			}
 			const robotsResponse = createDocsRobotsResponse({
 				request,
 				entry,
+				apiCatalog: apiCatalogEnabled,
 				sitemap: sitemapConfig,
 				baseUrl: llmsConfig.baseUrl ?? url.origin,
 				robots: robotsConfig
@@ -2767,6 +2915,7 @@ function createDocsAPI(options) {
 			if (robotsResponse) return robotsResponse;
 			const sitemapResponse = createDocsSitemapResponse({
 				request,
+				apiRoute: requestApiRoute,
 				sitemap: sitemapConfig,
 				entry,
 				siteTitle: llmsConfig.siteTitle ?? "Documentation",
@@ -2815,6 +2964,7 @@ function createDocsAPI(options) {
 					});
 					return createDocsMarkdownResponse({
 						request,
+						apiRoute: requestApiRoute,
 						document: null,
 						entry,
 						requestedPath: markdownRequest.requestedPath,
@@ -2855,6 +3005,7 @@ function createDocsAPI(options) {
 				});
 				return createDocsMarkdownResponse({
 					request,
+					apiRoute: requestApiRoute,
 					document,
 					entry,
 					requestedPath: markdownRequest.requestedPath,
@@ -2865,7 +3016,7 @@ function createDocsAPI(options) {
 					sitemap: sitemapConfig
 				});
 			}
-			const llmsRequest = resolveDocsLlmsTxtRequest(url, llmsConfig, docsPath);
+			const llmsRequest = resolveDocsLlmsTxtRequest(url, llmsConfig, docsPath, { apiRoute: requestApiRoute });
 			if (llmsRequest) {
 				if (!llmsConfig.enabled) return new Response("Not Found", {
 					status: 404,
@@ -2874,7 +3025,7 @@ function createDocsAPI(options) {
 						"X-Robots-Tag": "noindex"
 					}
 				});
-				const selected = selectDocsLlmsTxtContent(getLlmsContent(ctx), llmsRequest);
+				const selected = selectDocsLlmsTxtContent(getLlmsContent(ctx, requestApiRoute), llmsRequest);
 				if (!selected) return new Response("Not Found", {
 					status: 404,
 					headers: {
@@ -2941,6 +3092,8 @@ function createDocsAPI(options) {
 			trackTelemetryRequest(request);
 			const url = new URL(request.url);
 			const requestAnalyticsProperties = getRequestAnalyticsProperties(request);
+			const standardsResponse = await resolveStandardsResponse(request, url);
+			if (standardsResponse) return standardsResponse;
 			const agentFeedbackRequest = resolveAgentFeedbackRequest(url, agentFeedbackConfig);
 			if (agentFeedbackRequest) {
 				if (agentFeedbackRequest.kind === "schema") return Response.json({ error: "Method Not Allowed" }, {
@@ -3036,6 +3189,17 @@ function createDocsAPI(options) {
 			}), analytics, observability, { locale: ctx.locale });
 		}
 	};
+	return {
+		...handlers,
+		async HEAD(request) {
+			const response = await handlers.GET(request);
+			return new Response(null, {
+				status: response.status,
+				statusText: response.statusText,
+				headers: response.headers
+			});
+		}
+	};
 }
 /**
 * Create MCP route handlers for `/api/docs/mcp`.

package/dist/search.d.mts

@@ -27,6 +27,7 @@ declare function createDocsSearchAPI(options?: {
   entry?: string;
   language?: string;
 }): {
+  HEAD(request: Request): Promise<Response>;
   GET(request: Request): Promise<Response>;
   POST(request: Request): Promise<Response>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.2.58",
+  "version": "0.2.59",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -146,7 +146,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/docs": "0.2.58"
+    "@farming-labs/docs": "0.2.59"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",