@farming-labs/docs 0.1.101 → 0.1.103

package/dist/{robots-D8IQoKv1.mjs → agent-BK7q65dn.mjs}

@@ -17,6 +17,10 @@ const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
 const DEFAULT_LLMS_TXT_MAX_CHARS = 5e4;
 const DEFAULT_SKILL_MD_ROUTE = "/skill.md";
 const DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE = "/.well-known/skill.md";
+const DEFAULT_AGENTS_MD_ROUTE = "/AGENTS.md";
+const DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE = "/.well-known/AGENTS.md";
+const DEFAULT_AGENT_MD_ROUTE = "/AGENT.md";
+const DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE = "/.well-known/AGENT.md";
 const DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE = "/robots.txt";
 const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
@@ -580,10 +584,21 @@ function isDocsSkillRequest(url) {
 function resolveDocsSkillFormat(url) {
 	return url.searchParams.get("format")?.trim() === "skill" ? "skill" : null;
 }
+function isDocsAgentsPath(pathname) {
+	return pathname === DEFAULT_AGENTS_MD_ROUTE || pathname === DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE || pathname === DEFAULT_AGENT_MD_ROUTE || pathname === DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE;
+}
+function isDocsAgentsRequest(url) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (isDocsAgentsPath(pathname)) return true;
+	return pathname === DEFAULT_DOCS_API_ROUTE && 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) || isDocsSkillRequest(url) || pathname === DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE && isRobotsDiscoveryEnabled(options.robots) || resolveDocsLlmsTxtRequest(url, options.llms) !== null || resolveDocsSitemapRequest(url, options.sitemap) !== null || resolveDocsMarkdownRequest(entry, url, request) !== null;
+	return isDocsAgentDiscoveryRequest(url) || isDocsAgentsRequest(url) || isDocsSkillRequest(url) || pathname === DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE && isRobotsDiscoveryEnabled(options.robots) || resolveDocsLlmsTxtRequest(url, options.llms) !== null || resolveDocsSitemapRequest(url, options.sitemap) !== null || resolveDocsMarkdownRequest(entry, url, request) !== null;
 }
 function isDocsLlmsTxtPublicRequest(url, llms) {
 	return normalizeDocsUrlPath(url.pathname) !== DEFAULT_DOCS_API_ROUTE && resolveDocsLlmsTxtRequest(url, llms) !== null;
@@ -631,6 +646,7 @@ function renderDocsMarkdownNotFound({ entry = "docs", requestedPath, sitemap })
 		`- 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}\``
@@ -657,6 +673,126 @@ 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 }) {
+	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	return {
+		normalizedEntry: normalizeDocsPathSegment(entry) || "docs",
+		siteTitle: compactSkillText(llms?.siteTitle ?? "Documentation"),
+		siteDescription: llms?.siteDescription ? compactSkillText(llms.siteDescription) : void 0,
+		llmsEnabled: llms?.enabled ?? true,
+		searchEnabled: isSearchEnabled(search),
+		mcpEnabled: mcp.enabled,
+		feedbackEnabled: feedback?.enabled ?? false,
+		sitemapConfig: resolveDocsSitemapConfig(sitemap),
+		robotsEnabled: isRobotsDiscoveryEnabled(robots),
+		openapiConfig: resolveDocsOpenApiDiscoveryConfig(openapi),
+		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
+	};
+}
+function appendDocsMarkdownNegotiationStartLines(lines, context, variant) {
+	if (context.markdownAcceptHeader) lines.push(variant === "skill" ? `- You can also request ${context.markdownAcceptHeader} from normal page URLs.` : `- Normal docs pages can return markdown with Accept: ${context.markdownAcceptHeader}.`);
+	if (context.markdownSignatureAgentHeader) lines.push(variant === "skill" ? `- Requests with ${context.markdownSignatureAgentHeader} on normal page URLs receive markdown automatically.` : `- Normal docs pages can also return markdown when ${context.markdownSignatureAgentHeader} is present.`);
+}
+function appendDocsSearchStartLine(lines, context, variant) {
+	if (!context.searchEnabled) return;
+	lines.push(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.`);
+}
+function appendDocsOpenApiStartLine(lines, context, variant) {
+	if (!context.openapiConfig.enabled || !context.openapiConfig.url) return;
+	lines.push(variant === "skill" ? `- Fetch ${context.openapiConfig.url} for the machine-readable OpenAPI schema before scraping API reference pages.` : `- Fetch ${context.openapiConfig.url} before scraping API reference pages; prefer schemas over prose.`);
+}
+function appendDocsLlmsStartLines(lines, context, variant) {
+	if (!context.llmsEnabled) return;
+	lines.push(variant === "skill" ? `- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.` : `- Use ${DEFAULT_LLMS_TXT_ROUTE} as the compact docs map.`, variant === "skill" ? `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.` : `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} when you need the full markdown bundle.`);
+	for (const section of context.llmsSections) lines.push(variant === "skill" ? `- Use ${section.route} for the ${section.title} llms.txt section.` : `- Use ${section.route} for the ${section.title} section map.`);
+}
+function appendDocsSitemapStartLines(lines, context, variant) {
+	if (!context.sitemapConfig.enabled) return;
+	if (variant === "skill") {
+		if (context.sitemapConfig.xml.enabled) lines.push(`- Use ${context.sitemapConfig.xml.route} to check canonical page freshness.`);
+		if (context.sitemapConfig.markdown.enabled) lines.push(`- Use ${context.sitemapConfig.markdown.route} for a semantic docs map.`);
+		return;
+	}
+	if (context.sitemapConfig.markdown.enabled) lines.push(`- Use ${context.sitemapConfig.markdown.route} for a semantic sitemap with sections.`);
+	if (context.sitemapConfig.xml.enabled) lines.push(`- Use ${context.sitemapConfig.xml.route} for canonical URLs and freshness metadata.`);
+}
+function appendDocsRobotsStartLine(lines, context, variant) {
+	if (!context.robotsEnabled) return;
+	lines.push(variant === "skill" ? `- Check ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE} for crawler and AI-agent access policy.` : `- Check ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE} before crawling broadly.`);
+}
+function appendDocsMcpStartLine(lines, context, variant) {
+	if (!context.mcpEnabled) return;
+	lines.push(variant === "skill" ? `- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools when your environment supports MCP.` : `- Use MCP at ${DEFAULT_MCP_PUBLIC_ROUTE} or ${DEFAULT_MCP_WELL_KNOWN_ROUTE} when your environment supports MCP tools.`);
+}
+function appendDocsFeedbackStartLine(lines, context, variant) {
+	if (!context.feedbackEnabled) return;
+	lines.push(variant === "skill" ? `- Read ${context.feedbackSchemaRoute} before posting agent feedback to ${context.feedbackRoute}.` : `- Read ${context.feedbackSchemaRoute} before posting feedback to ${context.feedbackRoute}.`);
+}
+function appendDocsAgentStartHereLines(lines, context, variant) {
+	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.`);
+	if (variant === "skill") {
+		appendDocsMarkdownNegotiationStartLines(lines, context, variant);
+		appendDocsSearchStartLine(lines, context, variant);
+		appendDocsOpenApiStartLine(lines, context, variant);
+		appendDocsLlmsStartLines(lines, context, variant);
+		appendDocsSitemapStartLines(lines, context, variant);
+		appendDocsRobotsStartLine(lines, context, variant);
+		appendDocsMcpStartLine(lines, context, variant);
+		appendDocsFeedbackStartLine(lines, context, variant);
+		return;
+	}
+	appendDocsLlmsStartLines(lines, context, variant);
+	appendDocsSitemapStartLines(lines, context, variant);
+	appendDocsRobotsStartLine(lines, context, variant);
+	appendDocsSearchStartLine(lines, context, variant);
+	appendDocsOpenApiStartLine(lines, context, variant);
+	appendDocsMcpStartLine(lines, context, variant);
+	appendDocsFeedbackStartLine(lines, context, variant);
+	appendDocsMarkdownNegotiationStartLines(lines, context, variant);
+}
+function appendDocsLlmsRouteLines(lines, context) {
+	if (!context.llmsEnabled) return;
+	lines.push(`- llms.txt: ${DEFAULT_LLMS_TXT_ROUTE}`, `- llms-full.txt: ${DEFAULT_LLMS_FULL_TXT_ROUTE}`, `- llms well-known aliases: ${DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE}`);
+	for (const section of context.llmsSections) {
+		lines.push(`- ${section.title} llms.txt: ${section.route}`);
+		lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
+	}
+}
+function appendDocsOpenApiRouteLines(lines, context) {
+	if (!context.openapiConfig.enabled || !context.openapiConfig.url) return;
+	lines.push(`- OpenAPI schema: ${context.openapiConfig.url}`);
+	if (context.openapiConfig.apiReferencePath) lines.push(`- API reference: ${context.openapiConfig.apiReferencePath}`);
+}
+function appendDocsSitemapRouteLines(lines, context) {
+	if (!context.sitemapConfig.enabled) return;
+	if (context.sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${context.sitemapConfig.xml.route}`);
+	if (context.sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${context.sitemapConfig.markdown.route}`, `- Sitemap well-known alias: ${context.sitemapConfig.markdown.wellKnownRoute}`);
+}
+function appendDocsMcpRouteLines(lines, context) {
+	if (!context.mcpEnabled) return;
+	lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+}
+function appendDocsAgentPublicRouteLines(lines, context, variant) {
+	if (variant === "skill") {
+		lines.push(`- Agent instructions: ${DEFAULT_AGENTS_MD_ROUTE}`, `- Agent instructions well-known alias: ${DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE}`, `- Agent instructions API format: ${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`);
+		if (context.robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
+		appendDocsLlmsRouteLines(lines, context);
+		appendDocsOpenApiRouteLines(lines, context);
+		appendDocsSitemapRouteLines(lines, context);
+		appendDocsMcpRouteLines(lines, context);
+		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}`);
+	appendDocsLlmsRouteLines(lines, context);
+	if (context.robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
+	appendDocsSitemapRouteLines(lines, context);
+	appendDocsOpenApiRouteLines(lines, context);
+	appendDocsMcpRouteLines(lines, context);
+}
 function renderDocsMarkdownDocument(page, options) {
 	if (page.agentRawContent !== void 0) return page.agentRawContent;
 	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
@@ -667,70 +803,44 @@ function renderDocsMarkdownDocument(page, options) {
 	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
 	return lines.join("\n");
 }
-function renderDocsSkillDocument({ origin, entry = "docs", search, mcp, feedback, llms, sitemap, robots, openapi, markdown }) {
-	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
-	const siteTitle = compactSkillText(llms?.siteTitle ?? "Documentation");
-	const siteDescription = llms?.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
-	const llmsEnabled = llms?.enabled ?? true;
-	const searchEnabled = isSearchEnabled(search);
-	const feedbackEnabled = feedback?.enabled ?? false;
-	const sitemapConfig = resolveDocsSitemapConfig(sitemap);
-	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
-	const openapiConfig = resolveDocsOpenApiDiscoveryConfig(openapi);
-	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
-	const feedbackSchemaRoute = feedback?.schemaRoute ?? `${feedbackRoute}/schema`;
-	const llmsSections = resolveDocsLlmsTxtSections(llms);
-	const description = truncateSkillDescription(`Use ${siteTitle} through markdown routes, llms.txt, robots.txt, agent discovery, search, and MCP when available.`);
-	const markdownAcceptHeader = markdown?.acceptHeader === false ? null : "text/markdown";
-	const markdownSignatureAgentHeader = markdown?.signatureAgentHeader === false ? null : DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER;
+function renderDocsSkillDocument(options) {
+	const { origin } = options;
+	const context = resolveDocsAgentDocumentContext(options);
 	const lines = [
 		"---",
 		"name: docs",
-		`description: ${toYamlString(description)}`,
+		`description: ${toYamlString(truncateSkillDescription(`Use ${context.siteTitle} through markdown routes, llms.txt, robots.txt, agent discovery, search, and MCP when available.`))}`,
 		"---",
 		"",
-		`# ${siteTitle} Skill`,
+		`# ${context.siteTitle} Skill`,
 		"",
 		`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.`);
-	if (markdownAcceptHeader) lines.push(`- You can also request ${markdownAcceptHeader} from normal page URLs.`);
-	if (markdownSignatureAgentHeader) lines.push(`- Requests with ${markdownSignatureAgentHeader} on normal page URLs receive markdown automatically.`);
-	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
-	if (openapiConfig.enabled && openapiConfig.url) lines.push(`- Fetch ${openapiConfig.url} for the machine-readable OpenAPI schema before scraping API reference pages.`);
-	if (llmsEnabled) {
-		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.`);
-	}
-	if (sitemapConfig.enabled) {
-		if (sitemapConfig.xml.enabled) lines.push(`- Use ${sitemapConfig.xml.route} to check canonical page freshness.`);
-		if (sitemapConfig.markdown.enabled) lines.push(`- Use ${sitemapConfig.markdown.route} for a semantic docs map.`);
-	}
-	if (robotsEnabled) lines.push(`- Check ${DEFAULT_AGENT_DISCOVERY_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 (feedbackEnabled) lines.push(`- Read ${feedbackSchemaRoute} before posting agent feedback to ${feedbackRoute}.`);
-	lines.push("", "## Routes", `- 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`);
-	if (robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_AGENT_DISCOVERY_ROBOTS_TXT_ROUTE}`);
-	if (llmsEnabled) {
-		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) {
-			lines.push(`- ${section.title} llms.txt: ${section.route}`);
-			lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
-		}
-	}
-	if (openapiConfig.enabled && openapiConfig.url) {
-		lines.push(`- OpenAPI schema: ${openapiConfig.url}`);
-		if (openapiConfig.apiReferencePath) lines.push(`- API reference: ${openapiConfig.apiReferencePath}`);
-	}
-	if (sitemapConfig.enabled) {
-		if (sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${sitemapConfig.xml.route}`);
-		if (sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${sitemapConfig.markdown.route}`, `- Sitemap well-known alias: ${sitemapConfig.markdown.wellKnownRoute}`);
-	}
-	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+	if (context.siteDescription) lines.push(`Description: ${context.siteDescription}`);
+	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here");
+	appendDocsAgentStartHereLines(lines, context, "skill");
+	lines.push("", "## Routes");
+	appendDocsAgentPublicRouteLines(lines, context, "skill");
 	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
 	return lines.join("\n");
 }
+function renderDocsAgentsDocument(options) {
+	const { origin } = options;
+	const context = resolveDocsAgentDocumentContext(options);
+	const lines = [
+		"# Agent Instructions",
+		"",
+		`Site: ${context.siteTitle}`,
+		`Base URL: ${origin}`
+	];
+	if (context.siteDescription) lines.push(`Description: ${context.siteDescription}`);
+	lines.push("", "## Start Here");
+	appendDocsAgentStartHereLines(lines, context, "agents");
+	lines.push("", "## Working Rules", "- Prefer markdown routes, llms.txt, sitemap.md, OpenAPI schemas, and MCP 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");
+	appendDocsAgentPublicRouteLines(lines, context, "agents");
+	lines.push("", "## Framework Maintenance", "- For @farming-labs/docs projects, keep the framework package current before debugging missing agent surfaces.", "", "```sh", "npx @farming-labs/docs@latest upgrade --latest", "```", "", "- For framework setup, configuration, CLI, Ask AI, page actions, or theme work, install the reusable Skills pack:", "", "```sh", "npx skills add farming-labs/docs", "```");
+	return lines.join("\n");
+}
 function resolveDocsAgentMdxContent(content, audience) {
 	const lines = content.split("\n");
 	const output = [];
@@ -810,6 +920,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			markdownRoutes: true,
 			agentMdOverrides: true,
 			agentBlocks: true,
+			agents: true,
 			llms: llmsEnabled,
 			skills: true,
 			mcp: mcp.enabled,
@@ -830,6 +941,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			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
 		},
 		markdown: {
@@ -914,6 +1026,15 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 			queryParam: "query",
 			localeParam: "lang"
 		},
+		agents: {
+			enabled: true,
+			file: "AGENTS.md",
+			route: DEFAULT_AGENTS_MD_ROUTE,
+			wellKnown: DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+			api: `${DEFAULT_DOCS_API_ROUTE}?format=agents`,
+			generatedFallback: true,
+			aliases: [DEFAULT_AGENT_MD_ROUTE, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE]
+		},
 		skills: {
 			enabled: true,
 			file: "skill.md",
@@ -1017,187 +1138,4 @@ function toYamlString(value) {
 }
 
 //#endregion
-//#region src/robots.ts
-const DEFAULT_ROBOTS_TXT_ROUTE = "/robots.txt";
-const DOCS_ROBOTS_GENERATED_BLOCK_START = "# BEGIN @farming-labs/docs robots";
-const DOCS_ROBOTS_GENERATED_BLOCK_END = "# END @farming-labs/docs robots";
-const DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS = [
-	"GPTBot",
-	"ChatGPT-User",
-	"OAI-SearchBot",
-	"ClaudeBot",
-	"Claude-User",
-	"anthropic-ai",
-	"CCBot",
-	"Google-Extended"
-];
-function normalizeRoute(value) {
-	const trimmed = value.trim();
-	if (!trimmed) return "/";
-	return trimmed.startsWith("/") ? trimmed.replace(/\/{2,}/g, "/") : `/${trimmed}`;
-}
-function normalizeBaseUrl(value) {
-	if (!value) return void 0;
-	try {
-		const url = new URL(value);
-		url.pathname = url.pathname.replace(/\/+$/, "");
-		url.search = "";
-		url.hash = "";
-		return url.toString().replace(/\/+$/, "");
-	} catch {
-		return;
-	}
-}
-function normalizeStringArray(value) {
-	if (Array.isArray(value)) return value;
-	return value ? [value] : [];
-}
-function normalizeAiPolicy(value) {
-	return value === false || value === "disallow" ? "disallow" : "allow";
-}
-function unique(values) {
-	return [...new Set(values.filter(Boolean))];
-}
-function resolveDocsRobotsConfig(input, options = {}) {
-	if (input === false) return {
-		enabled: false,
-		ai: "allow",
-		userAgents: [...DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS],
-		extraRules: []
-	};
-	const config = typeof input === "object" ? input : {};
-	return {
-		enabled: config.enabled ?? true,
-		path: config.path,
-		baseUrl: normalizeBaseUrl(config.baseUrl) ?? normalizeBaseUrl(options.baseUrl),
-		ai: normalizeAiPolicy(config.ai),
-		userAgents: unique([...DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS, ...normalizeStringArray(config.aiUserAgents)]),
-		extraRules: config.extraRules ?? []
-	};
-}
-function getDocsRobotsAllowRoutes(options = {}) {
-	const normalizedEntry = normalizeDocsPathSegment(options.entry ?? "docs") || "docs";
-	const sitemapConfig = resolveDocsSitemapConfig(options.sitemap);
-	const routes = [
-		"/",
-		`/${normalizedEntry}`,
-		`/${normalizedEntry}/`,
-		`/${normalizedEntry}.md`,
-		`/${normalizedEntry}/*.md`,
-		DEFAULT_LLMS_TXT_ROUTE,
-		DEFAULT_LLMS_FULL_TXT_ROUTE,
-		DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE,
-		DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE,
-		DEFAULT_SKILL_MD_ROUTE,
-		DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
-		DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
-		DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
-		DEFAULT_MCP_PUBLIC_ROUTE,
-		DEFAULT_MCP_WELL_KNOWN_ROUTE
-	];
-	if (sitemapConfig.enabled) {
-		if (sitemapConfig.xml.enabled) routes.push(sitemapConfig.xml.route);
-		if (sitemapConfig.markdown.enabled) routes.push(sitemapConfig.markdown.route, sitemapConfig.markdown.wellKnownRoute);
-	}
-	return unique(routes.map(normalizeRoute));
-}
-function sitemapUrls(robots, sitemap) {
-	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: robots.baseUrl });
-	if (!robots.baseUrl || !sitemapConfig.enabled || !sitemapConfig.xml.enabled) return [];
-	try {
-		return [new URL(sitemapConfig.xml.route, `${robots.baseUrl}/`).toString()];
-	} catch {
-		return [];
-	}
-}
-function appendRule(lines, rule) {
-	const userAgents = normalizeStringArray(rule.userAgent);
-	if (userAgents.length === 0) return;
-	lines.push("");
-	for (const userAgent of userAgents) lines.push(`User-agent: ${userAgent}`);
-	for (const route of normalizeStringArray(rule.allow)) lines.push(`Allow: ${normalizeRoute(route)}`);
-	for (const route of normalizeStringArray(rule.disallow)) lines.push(`Disallow: ${normalizeRoute(route)}`);
-	if (typeof rule.crawlDelay === "number" && Number.isFinite(rule.crawlDelay)) lines.push(`Crawl-delay: ${rule.crawlDelay}`);
-}
-function renderDocsRobotsTxt(options = {}) {
-	const robots = resolveDocsRobotsConfig(options.robots, { baseUrl: options.baseUrl });
-	if (!robots.enabled) return "";
-	const lines = [
-		"# Generated by @farming-labs/docs.",
-		"# Edit docs.config or rerun `docs robots generate --append` / `--force`.",
-		"",
-		"User-agent: *"
-	];
-	for (const route of getDocsRobotsAllowRoutes(options)) lines.push(`Allow: ${route}`);
-	for (const userAgent of robots.userAgents) {
-		lines.push("", `User-agent: ${userAgent}`);
-		lines.push(robots.ai === "allow" ? "Allow: /" : "Disallow: /");
-	}
-	for (const rule of robots.extraRules) appendRule(lines, rule);
-	const sitemap = sitemapUrls(robots, options.sitemap);
-	if (sitemap.length > 0) {
-		lines.push("");
-		for (const url of sitemap) lines.push(`Sitemap: ${url}`);
-	}
-	return `${lines.join("\n")}\n`;
-}
-function resolveDocsRobotsRequest(url, robots) {
-	const pathname = normalizeRoute(url.pathname);
-	const format = url.searchParams.get("format")?.trim();
-	if (pathname === "/api/docs" && format === "robots") return "robots";
-	if (!resolveDocsRobotsConfig(robots).enabled) return null;
-	return pathname === DEFAULT_ROBOTS_TXT_ROUTE ? "robots" : null;
-}
-function createDocsRobotsResponse({ request, ...options }) {
-	const url = new URL(request.url);
-	if (!resolveDocsRobotsRequest(url, options.robots)) return null;
-	const content = renderDocsRobotsTxt({
-		...options,
-		baseUrl: options.baseUrl ?? url.origin
-	});
-	if (!content) return null;
-	return new Response(content, { headers: {
-		"Content-Type": "text/plain; charset=utf-8",
-		"Cache-Control": "public, max-age=0, s-maxage=3600"
-	} });
-}
-function renderDocsRobotsGeneratedBlock(options = {}) {
-	return `${DOCS_ROBOTS_GENERATED_BLOCK_START}\n${renderDocsRobotsTxt(options).trimEnd()}\n${DOCS_ROBOTS_GENERATED_BLOCK_END}\n`;
-}
-function upsertDocsRobotsGeneratedBlock(existing, block) {
-	const escapedStart = DOCS_ROBOTS_GENERATED_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	const escapedEnd = DOCS_ROBOTS_GENERATED_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	const pattern = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}\\n?`);
-	if (pattern.test(existing)) return existing.replace(pattern, block);
-	const prefix = existing.trimEnd();
-	return `${prefix}${prefix ? "\n\n" : ""}${block}`;
-}
-function blockForUserAgent(content, userAgent) {
-	const escaped = userAgent.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	return content.match(new RegExp(`(?:^|\\n)\\s*User-agent:\\s*${escaped}\\s*(?:\\n[ \\t]*(?!User-agent:).*)*`, "i"))?.[0] ?? "";
-}
-function disallowsRoute(content, route) {
-	const escapedRoute = route.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	return new RegExp(`^\\s*Disallow:\\s*${escapedRoute}(?:\\s|$)`, "im").test(content);
-}
-function analyzeDocsRobotsTxt(content, options = {}) {
-	const expectedRoutes = getDocsRobotsAllowRoutes(options).filter((route) => [
-		DEFAULT_LLMS_TXT_ROUTE,
-		DEFAULT_LLMS_FULL_TXT_ROUTE,
-		DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
-		DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
-		DEFAULT_SKILL_MD_ROUTE,
-		DEFAULT_MCP_PUBLIC_ROUTE
-	].includes(route) || route.includes("sitemap"));
-	const missingRoutes = expectedRoutes.filter((route) => !content.includes(route));
-	return {
-		blocksAgentRoutes: /Disallow:\s*\/(?:\s|$)/i.test(blockForUserAgent(content, "*")) || expectedRoutes.some((route) => disallowsRoute(content, route)),
-		blocksAiAgents: DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS.some((userAgent) => /Disallow:\s*\/(?:\s|$)/i.test(blockForUserAgent(content, userAgent))),
-		hasAgentRoutes: missingRoutes.length === 0,
-		hasAiPolicy: DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS.some((userAgent) => content.includes(userAgent)),
-		missingRoutes
-	};
-}
-
-//#endregion
-export { resolveDocsAgentFeedbackRequest as $, DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER as A, isDocsLlmsTxtPublicRequest as B, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as C, DEFAULT_OPENAPI_SCHEMA_ROUTE as D, DEFAULT_MCP_WELL_KNOWN_ROUTE as E, getDocsLlmsTxtMaxCharsIssue as F, normalizeDocsPathSegment as G, isDocsPublicGetRequest as H, getDocsMarkdownCanonicalLinkHeader as I, renderDocsLlmsTxt as J, normalizeDocsUrlPath as K, getDocsMarkdownVaryHeader as L, buildDocsAgentFeedbackSchema as M, buildDocsMcpEndpointCandidates as N, DEFAULT_SKILL_MD_ROUTE as O, findDocsMarkdownPage as P, resolveDocsAgentFeedbackConfig as Q, hasDocsMarkdownSignatureAgent as R, DEFAULT_LLMS_TXT_ROUTE as S, DEFAULT_MCP_ROUTE as T, isDocsSkillRequest as U, isDocsMcpRequest as V, matchesDocsLlmsTxtSection as W, renderDocsMarkdownNotFound as X, renderDocsMarkdownDocument as Y, renderDocsSkillDocument as Z, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as _, analyzeDocsRobotsTxt as a, resolveDocsMarkdownRequest as at, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as b, renderDocsRobotsGeneratedBlock as c, selectDocsLlmsTxtContent as ct, resolveDocsRobotsRequest as d, resolveDocsAgentMdxContent as et, upsertDocsRobotsGeneratedBlock as f, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as g, DEFAULT_AGENT_SPEC_ROUTE as h, DOCS_ROBOTS_GENERATED_BLOCK_START as i, resolveDocsMarkdownCanonicalUrl as it, buildDocsAgentDiscoverySpec as j, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as k, renderDocsRobotsTxt as l, toDocsMarkdownUrl as lt, DEFAULT_AGENT_FEEDBACK_ROUTE as m, DEFAULT_ROBOTS_TXT_ROUTE as n, resolveDocsLlmsTxtRequest as nt, createDocsRobotsResponse as o, resolveDocsOpenApiDiscoveryConfig as ot, DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA as p, parseDocsAgentFeedbackData as q, DOCS_ROBOTS_GENERATED_BLOCK_END as r, resolveDocsLlmsTxtSections as rt, getDocsRobotsAllowRoutes as s, resolveDocsSkillFormat as st, DEFAULT_DOCS_AI_ROBOTS_USER_AGENTS as t, resolveDocsLlmsTxtFormat as tt, resolveDocsRobotsConfig as u, validateDocsAgentFeedbackPayload as ut, DEFAULT_DOCS_API_ROUTE as v, DEFAULT_MCP_PUBLIC_ROUTE as w, DEFAULT_LLMS_TXT_MAX_CHARS as x, DEFAULT_LLMS_FULL_TXT_ROUTE as y, isDocsAgentDiscoveryRequest as z };
+export { resolveDocsMarkdownCanonicalUrl as $, hasDocsMarkdownSignatureAgent as A, parseDocsAgentFeedbackData as B, buildDocsAgentDiscoverySpec as C, getDocsLlmsTxtMaxCharsIssue as D, findDocsMarkdownPage as E, isDocsPublicGetRequest as F, renderDocsSkillDocument as G, renderDocsLlmsTxt as H, isDocsSkillRequest as I, resolveDocsAgentMdxContent as J, resolveDocsAgentFeedbackConfig as K, matchesDocsLlmsTxtSection as L, isDocsAgentsRequest as M, isDocsLlmsTxtPublicRequest as N, getDocsMarkdownCanonicalLinkHeader as O, isDocsMcpRequest as P, resolveDocsLlmsTxtSections as Q, normalizeDocsPathSegment as R, DOCS_MARKDOWN_SIGNATURE_AGENT_HEADER as S, buildDocsMcpEndpointCandidates as T, renderDocsMarkdownDocument as U, renderDocsAgentsDocument as V, renderDocsMarkdownNotFound as W, resolveDocsLlmsTxtFormat as X, resolveDocsAgentsFormat as Y, resolveDocsLlmsTxtRequest as Z, DEFAULT_MCP_ROUTE as _, DEFAULT_AGENT_MD_ROUTE as a, validateDocsAgentFeedbackPayload as at, DEFAULT_SKILL_MD_ROUTE as b, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE as c, DEFAULT_LLMS_FULL_TXT_ROUTE as d, resolveDocsMarkdownRequest as et, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE as f, DEFAULT_MCP_PUBLIC_ROUTE as g, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE as h, DEFAULT_AGENT_FEEDBACK_ROUTE as i, toDocsMarkdownUrl as it, isDocsAgentDiscoveryRequest as j, getDocsMarkdownVaryHeader as k, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE as l, DEFAULT_LLMS_TXT_ROUTE as m, DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE as n, resolveDocsSkillFormat as nt, DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE as o, DEFAULT_LLMS_TXT_MAX_CHARS as p, resolveDocsAgentFeedbackRequest as q, DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA as r, selectDocsLlmsTxtContent as rt, DEFAULT_AGENT_SPEC_ROUTE as s, DEFAULT_AGENTS_MD_ROUTE as t, resolveDocsOpenApiDiscoveryConfig as tt, DEFAULT_DOCS_API_ROUTE as u, DEFAULT_MCP_WELL_KNOWN_ROUTE as v, buildDocsAgentFeedbackSchema as w, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE as x, DEFAULT_OPENAPI_SCHEMA_ROUTE as y, normalizeDocsUrlPath as z };

package/dist/agent-sUT6Bsop.mjs

@@ -0,0 +1,9 @@
+import "./reading-time-CbbHNg9V.mjs";
+import "./search-BL7o2rXk.mjs";
+import "./agent-BK7q65dn.mjs";
+import "./robots-DDrj6Cpo.mjs";
+import "./sitemap-server-DJvxOqX2.mjs";
+import "./config-Cio3byUJ.mjs";
+import { a as readPageTokenBudget, i as printAgentCompactHelp, n as inspectAgentCompactionState, o as scanDocsPageTargets, r as parseAgentCompactArgs, t as compactAgentDocs } from "./agents-B04j1KsE.mjs";
+
+export { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp };