@farming-labs/theme 0.1.102 → 0.1.104

package/dist/code-block-spacing.mjs

@@ -0,0 +1,49 @@
+import * as React$1 from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/code-block-spacing.tsx
+const leadingWhitespacePattern = /^[\t ]+/;
+function whitespaceColumnCount(value) {
+	let columns = 0;
+	for (const char of value) columns += char === "	" ? 4 : 1;
+	return columns;
+}
+function splitLeadingWhitespace(value, key) {
+	const match = value.match(leadingWhitespacePattern);
+	if (!match) return value;
+	const leadingWhitespace = match[0] ?? "";
+	const rest = value.slice(leadingWhitespace.length);
+	if (!rest.startsWith("--")) return value;
+	const isSingleWordGap = leadingWhitespace === " ";
+	return [/* @__PURE__ */ jsx("span", {
+		"data-fd-code-space": isSingleWordGap ? "gap" : "indent",
+		style: { "--fd-code-space-count": whitespaceColumnCount(leadingWhitespace) },
+		children: leadingWhitespace
+	}, `${key}-space`), rest];
+}
+function normalizeNode(node, key) {
+	if (typeof node === "string") return splitLeadingWhitespace(node, key);
+	if (!React$1.isValidElement(node)) return node;
+	const props = node.props;
+	if (props.children === void 0) return node;
+	return React$1.cloneElement(node, void 0, React$1.Children.map(props.children, (child, index) => normalizeNode(child, `${key}-${index}`)));
+}
+function normalizeCodeSpacing(children) {
+	return React$1.Children.map(children, (child, index) => normalizeNode(child, `${index}`));
+}
+function createPreWithCodeSpacing(DefaultPre) {
+	return function PreWithCodeSpacing(props) {
+		const normalizedChildren = normalizeCodeSpacing(props.children);
+		if (typeof DefaultPre === "string") return /* @__PURE__ */ jsx("pre", {
+			...props,
+			children: normalizedChildren
+		});
+		return /* @__PURE__ */ jsx(DefaultPre, {
+			...props,
+			children: normalizedChildren
+		});
+	};
+}
+
+//#endregion
+export { createPreWithCodeSpacing };

package/dist/docs-api.mjs

@@ -13,6 +13,7 @@ import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, create
 * A single route handler that serves **both** search and AI chat:
 *
 * - `GET  /api/docs?query=…` → full-text search over indexed MDX pages
+* - `GET  /api/docs?format=agents` → AGENTS.md for coding-agent instructions
 * - `GET  /api/docs?format=skill` → skill.md for agent discovery
 * - `POST /api/docs` → RAG-powered "Ask AI" (searches relevant docs,
 *   then streams an LLM response using the docs as context)
@@ -46,6 +47,10 @@ const DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms.txt";
 const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
 const DEFAULT_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_ROBOTS_TXT_ROUTE = "/robots.txt";
 const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
@@ -171,6 +176,11 @@ function resolveSkillRequest(url) {
 	if (pathname === DEFAULT_SKILL_MD_ROUTE || pathname === DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE) return true;
 	return url.searchParams.get("format")?.trim() === "skill";
 }
+function resolveAgentsRequest(url) {
+	const pathname = normalizeUrlPath(url.pathname);
+	if (pathname === DEFAULT_AGENTS_MD_ROUTE || pathname === DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE || pathname === DEFAULT_AGENT_MD_ROUTE || pathname === DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE) return true;
+	return url.searchParams.get("format")?.trim() === "agents";
+}
 function isSearchEnabled(search) {
 	if (search === false) return false;
 	if (search && typeof search === "object" && search.enabled === false) return false;
@@ -223,6 +233,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			markdownRoutes: true,
 			agentMdOverrides: true,
 			agentBlocks: true,
+			agents: true,
 			llms: llms.enabled,
 			skills: true,
 			mcp: mcp.enabled,
@@ -243,6 +254,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			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`
 		},
 		markdown: {
@@ -323,6 +335,15 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			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",
@@ -1007,7 +1028,7 @@ 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", `- 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: ${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`);
 	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}`);
@@ -1028,6 +1049,56 @@ 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 }) {
+	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 llmsSections = resolveDocsLlmsTxtSections(llms);
+	const lines = [
+		"# Agent Instructions",
+		"",
+		`Site: ${siteTitle}`,
+		`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.`);
+	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.`);
+	}
+	if (sitemapConfig.enabled) {
+		if (sitemapConfig.markdown.enabled) lines.push(`- Use ${sitemapConfig.markdown.route} for a semantic sitemap with sections.`);
+		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 (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}`);
+	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) {
+			lines.push(`- ${section.title} llms.txt: ${section.route}`);
+			lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
+		}
+	}
+	if (robotsEnabled) lines.push(`- Robots policy: ${DEFAULT_ROBOTS_TXT_ROUTE}`);
+	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 (openapi.enabled && openapi.url) {
+		lines.push(`- OpenAPI schema: ${openapi.url}`);
+		if (openapi.apiReferencePath) lines.push(`- API reference: ${openapi.apiReferencePath}`);
+	}
+	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+	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 readRootSkillDocument(rootDir) {
 	const candidate = path.join(rootDir, "skill.md");
 	try {
@@ -1037,6 +1108,17 @@ function readRootSkillDocument(rootDir) {
 	}
 	return null;
 }
+function readRootAgentsDocument(rootDir) {
+	for (const fileName of ["AGENTS.md", "AGENT.md"]) {
+		const candidate = path.join(rootDir, fileName);
+		try {
+			if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return fs.readFileSync(candidate, "utf-8");
+		} catch {
+			continue;
+		}
+	}
+	return null;
+}
 function compactSkillText(value) {
 	return value.replace(/\s+/g, " ").trim();
 }
@@ -1898,6 +1980,31 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			if (resolveAgentsRequest(url)) {
+				await emitDocsAnalyticsEvent(analytics, {
+					type: "agents_request",
+					source: "server",
+					url: request.url,
+					path: url.pathname,
+					locale: ctx.locale,
+					properties: { method: "GET" }
+				});
+				return new Response(readRootAgentsDocument(root) ?? renderAgentsDocument({
+					origin: url.origin,
+					entry,
+					search: searchConfig,
+					mcp: mcpConfig,
+					feedback: agentFeedbackConfig,
+					llms: llmsConfig,
+					sitemap: sitemapConfig,
+					robots: robotsConfig,
+					openapi: openapiDiscovery
+				}), { headers: {
+					"Content-Type": "text/markdown; charset=utf-8",
+					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					"X-Robots-Tag": "noindex"
+				} });
+			}
 			if (resolveSkillRequest(url)) {
 				await emitDocsAnalyticsEvent(analytics, {
 					type: "skill_request",

package/dist/mdx.mjs

@@ -1,4 +1,5 @@
 import { MDXImg } from "./mdx-img.mjs";
+import { createPreWithCodeSpacing } from "./code-block-spacing.mjs";
 import { createPreWithCopyCallback } from "./code-block-copy-wrapper.mjs";
 import { HoverLink } from "./hover-link.mjs";
 import { extractPromptText } from "./prompt-text.mjs";
@@ -94,6 +95,8 @@ function getMDXComponents(overrides, options) {
 		...applyBuiltInComponentDefaults(options),
 		...overrides
 	};
+	const DefaultPre = base.pre;
+	if (DefaultPre) base.pre = createPreWithCodeSpacing(DefaultPre);
 	if (base.Prompt) {
 		const DefaultPrompt = base.Prompt;
 		base.Prompt = function PromptWithDocsContext(props) {
@@ -108,8 +111,8 @@ function getMDXComponents(overrides, options) {
 		};
 	}
 	if (options?.onCopyClick) {
-		const DefaultPre = base.pre;
-		if (DefaultPre) base.pre = createPreWithCopyCallback(DefaultPre, options.onCopyClick);
+		const CopyPre = base.pre;
+		if (CopyPre) base.pre = createPreWithCopyCallback(CopyPre, options.onCopyClick);
 	}
 	return base;
 }

package/package.json

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

package/styles/base.css

@@ -139,12 +139,38 @@ article small,
 
 figure.shiki pre {
   padding: 0.15rem 0.5rem;
+  white-space: pre;
 }
 
 figure.shiki pre > code {
+  display: block;
+  white-space: inherit;
+}
+
+/* Wrapped Shiki lines can use grid rows; unwrapped token spans need inline flow for spaces. */
+figure.shiki pre > code:has(> .line),
+figure.shiki pre > code:has(> [data-line]) {
   display: grid;
 }
 
+figure.shiki pre > code > .line,
+figure.shiki pre > code > [data-line] {
+  white-space: inherit;
+}
+
+figure.shiki [data-fd-code-space] {
+  display: inline-block;
+  white-space: pre;
+}
+
+figure.shiki [data-fd-code-space="gap"] {
+  width: var(--fd-code-token-gap, 1.75ch);
+}
+
+figure.shiki [data-fd-code-space="indent"] {
+  width: calc(var(--fd-code-space-count, 1) * 1ch);
+}
+
 figure.shiki pre > code > [data-line] {
   padding: 0 0.25rem;
 }