@farming-labs/theme 0.2.70 → 0.2.72

package/dist/docs-api.mjs

@@ -4,7 +4,7 @@ import { BoundedRouteCache } from "./bounded-route-cache.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsSearchAudience, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
+import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsSearchAudience, resolveDocsSearchFilters, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -241,6 +241,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 		},
 		capabilities: {
 			markdownRoutes: true,
+			markdownSectionDiscovery: true,
 			agentMdOverrides: true,
 			agentBlocks: true,
 			structuredAgentContracts: true,
@@ -296,6 +297,14 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			pagePattern: `/${normalizedEntry}/{slug}.md`,
 			rootPage: `/${normalizedEntry}.md`,
 			apiPattern: `${apiRoute}?format=markdown&path={slug}`,
+			sectionDiscovery: {
+				enabled: true,
+				format: DOCS_MARKDOWN_SECTION_INDEX_FORMAT,
+				indexParam: "sections",
+				sectionParam: "section",
+				tokenBudgetParam: "tokenBudget",
+				byteBudgetParam: "byteBudget"
+			},
 			resolutionOrder: [
 				"agent.md",
 				"agent audience projection",
@@ -396,10 +405,27 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			enabled: searchEnabled,
 			endpoint: `${apiRoute}?query={query}`,
 			agentEndpoint: `${apiRoute}?query={query}&audience=agent`,
+			structuredAgentEndpoint: `${apiRoute}?query={query}&audience=agent&response=structured`,
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang",
 			audienceParam: "audience",
+			responseParam: "response",
+			structuredResponseValue: "structured",
+			responseFormat: "docs-search.v1",
+			filterParams: {
+				framework: "framework",
+				version: "version",
+				package: "package",
+				tags: "tags"
+			},
+			repeatedFilterParams: [
+				"framework",
+				"version",
+				"package",
+				"tags"
+			],
+			warningsField: "warnings",
 			defaultAudience: "human",
 			supportedAudiences: ["human", "agent"]
 		},
@@ -969,6 +995,9 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/$
 			if (resolvePageSidebarFolderIndexBehavior(data.sidebar) === "hidden" && hasVisibleDescendantDocsSearchPage(dir)) {} else {
 				const title = data.title || slugParts[slugParts.length - 1]?.replace(/-/g, " ") || "Documentation";
 				const description = data.description;
+				const framework = typeof data.framework === "string" ? data.framework : void 0;
+				const version = typeof data.version === "string" ? data.version : void 0;
+				const tags = Array.isArray(data.tags) ? data.tags.filter((value) => typeof value === "string") : void 0;
 				const { content: fileContent } = matter(raw);
 				const rawContent = resolveDocsAudienceMdxContent(fileContent, "human");
 				const agentRawContent = resolveDocsAudienceMdxContent(fileContent, "agent");
@@ -987,6 +1016,9 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/$
 					sourcePath: pageSource.replace(/\\/g, "/"),
 					lastModified: fs.statSync(pageSource).mtime.toISOString(),
 					locale,
+					framework,
+					version,
+					tags,
 					...agentDoc
 				});
 			}
@@ -1283,8 +1315,8 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	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 ${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}&audience=agent when you do not know the page.`);
+	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.`, `- Fetch /${normalizedEntry}/{slug}.md?sections to list section IDs and size estimates before requesting ?section={id}.`, "- You can also request text/markdown from normal page URLs.");
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; add framework, version, package, or repeated tags filters when scope matters.`);
 	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.`);
@@ -1299,7 +1331,7 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, 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: ${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`);
+	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`, `- Markdown section index: /${normalizedEntry}/{slug}.md?sections`, `- Markdown section fetch: /${normalizedEntry}/{slug}.md?section={id}&tokenBudget={tokens}`);
 	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}`);
@@ -1339,7 +1371,7 @@ function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp
 	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 ${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.`);
+	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.`, `- Read /${normalizedEntry}/{slug}.md?sections before fetching ?section={id} when a full page is larger than needed.`);
 	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.`);
@@ -1349,11 +1381,11 @@ function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp
 		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 ${apiRoute}?query={query}&audience=agent when the route is unknown.`);
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; add framework, version, package, or repeated tags filters when scope matters.`);
 	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: ${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}`);
+	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`, `- Markdown section index: /${normalizedEntry}/{slug}.md?sections`, `- Markdown section fetch: /${normalizedEntry}/{slug}.md?section={id}&tokenBudget={tokens}`, `- 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) {
@@ -3122,19 +3154,35 @@ function createDocsAPI(options) {
 				} });
 			}
 			const query = url.searchParams.get("query")?.trim();
-			if (!query) return new Response(JSON.stringify([]), { headers: { "Content-Type": "application/json" } });
-			const searchStartedAt = Date.now();
 			const audience = resolveDocsSearchAudience(url.searchParams.get("audience"));
-			const results = await performDocsSearch({
+			const filters = resolveDocsSearchFilters(url.searchParams);
+			const structured = url.searchParams.get("response") === "structured";
+			if (!query) {
+				const searchResponse = structured ? {
+					format: "docs-search.v1",
+					query: "",
+					audience,
+					filters,
+					resultCount: 0,
+					results: [],
+					warnings: []
+				} : [];
+				return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
+			}
+			const searchStartedAt = Date.now();
+			const searchOptions = {
 				pages: getIndexes(ctx),
 				query,
 				search: resolveSearchRequestConfig(searchConfig, request.url),
 				audience,
+				filters,
 				locale: ctx.locale,
 				pathname: url.searchParams.get("pathname") ?? void 0,
 				siteTitle: llmsConfig.siteTitle ?? "Documentation",
 				baseUrl: markdownMetadataBaseUrl || url.origin
-			});
+			};
+			const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : await performDocsSearch(searchOptions);
+			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : searchResponse.resultCount;
 			await emitDocsAnalyticsEvent(analytics, {
 				type: "api_search",
 				source: "server",
@@ -3146,12 +3194,12 @@ function createDocsAPI(options) {
 					...requestAnalyticsProperties,
 					queryLength: query.length,
 					audience,
-					resultCount: results.length,
+					resultCount,
 					pathname: url.searchParams.get("pathname") ?? void 0,
 					durationMs: Math.max(0, Date.now() - searchStartedAt)
 				}
 			});
-			return new Response(JSON.stringify(results), { headers: { "Content-Type": "application/json" } });
+			return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
 		},
 		async POST(request) {
 			trackTelemetryRequest(request);

package/package.json

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