@farming-labs/theme 0.2.61 → 0.2.63

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, DocsTelemetryConfig, FeedbackConfig, LlmsTxtConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsPublishedAgentSkill, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, DocsTelemetryConfig, FeedbackConfig, LlmsTxtConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -80,6 +80,8 @@ interface DocsAPIOptions {
   metadata?: DocsConfig["metadata"];
   /** Reusable skill publication and optional real A2A service metadata. */
   agent?: DocsConfig["agent"];
+  /** @internal Build-time Agent Skills snapshot supplied by framework adapters. */
+  _preloadedAgentSkills?: readonly DocsPublishedAgentSkill[];
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;
@@ -95,6 +97,8 @@ interface DocsMCPAPIOptions {
   telemetry?: boolean | DocsTelemetryConfig;
   observability?: boolean | DocsObservabilityConfig;
   agent?: DocsConfig["agent"];
+  /** @internal Build-time Agent Skills snapshot supplied by framework adapters. */
+  _preloadedAgentSkills?: readonly DocsPublishedAgentSkill[];
 }
 type LlmsTxtOptions = LlmsTxtConfig;
 /**

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, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, 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, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, 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 { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -393,9 +393,13 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 		search: {
 			enabled: searchEnabled,
 			endpoint: `${apiRoute}?query={query}`,
+			agentEndpoint: `${apiRoute}?query={query}&audience=agent`,
 			method: "GET",
 			queryParam: "query",
-			localeParam: "lang"
+			localeParam: "lang",
+			audienceParam: "audience",
+			defaultAudience: "human",
+			supportedAudiences: ["human", "agent"]
 		},
 		agents: {
 			enabled: true,
@@ -1278,7 +1282,7 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	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 (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent 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.`);
@@ -1343,7 +1347,7 @@ 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} when the route is unknown.`);
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent 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}.`);
@@ -2459,7 +2463,11 @@ function generateLlmsTxt(indexes, options) {
 */
 function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
-	const publishedAgentSkills = resolveConfiguredAgentSkills(options?.agent?.skills, { rootDir: root });
+	let publishedAgentSkills;
+	function getPublishedAgentSkills() {
+		if (!publishedAgentSkills) publishedAgentSkills = Array.isArray(options?._preloadedAgentSkills) ? Promise.resolve([...options._preloadedAgentSkills]) : resolveConfiguredAgentSkills(options?.agent?.skills, { rootDir: root });
+		return publishedAgentSkills;
+	}
 	const entry = options?.entry ?? readEntry(root);
 	const docsPath = normalizeDocsPublicPath(options?.docsPath ?? readDocsPath(root), entry);
 	const analytics = options?.analytics;
@@ -2739,7 +2747,7 @@ function createDocsAPI(options) {
 			request,
 			preferredSkillDocument: needsSkill ? readRootSkillDocument(root) : null,
 			fallbackSkillDocument,
-			publishedSkills: await publishedAgentSkills,
+			publishedSkills: needsSkill ? await getPublishedAgentSkills() : [],
 			agentCard: options?.agent?.a2a,
 			origin: url.origin,
 			entry,
@@ -2835,7 +2843,7 @@ function createDocsAPI(options) {
 							robots: robotsConfig,
 							openapi: openapiDiscovery
 						})
-					}), ...await publishedAgentSkills],
+					}), ...await getPublishedAgentSkills()],
 					agentCard: options?.agent?.a2a
 				}), { headers: {
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -3113,13 +3121,16 @@ 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({
 				pages: getIndexes(ctx),
 				query,
 				search: resolveSearchRequestConfig(searchConfig, request.url),
+				audience,
 				locale: ctx.locale,
 				pathname: url.searchParams.get("pathname") ?? void 0,
-				siteTitle: llmsConfig.siteTitle ?? "Documentation"
+				siteTitle: llmsConfig.siteTitle ?? "Documentation",
+				baseUrl: markdownMetadataBaseUrl || url.origin
 			});
 			await emitDocsAnalyticsEvent(analytics, {
 				type: "api_search",
@@ -3131,6 +3142,7 @@ function createDocsAPI(options) {
 				properties: {
 					...requestAnalyticsProperties,
 					queryLength: query.length,
+					audience,
 					resultCount: results.length,
 					pathname: url.searchParams.get("pathname") ?? void 0,
 					durationMs: Math.max(0, Date.now() - searchStartedAt)
@@ -3267,6 +3279,11 @@ function createDocsMCPAPI(options = {}) {
 	const contentDir = options.contentDir ?? path.join(appDir, entry);
 	const mcpConfig = options.mcp ?? readMcpConfig(rootDir, { rejectRuntimeSecurity: true });
 	const navTitle = typeof options.nav?.title === "string" && options.nav.title.trim().length > 0 ? options.nav.title : "Documentation";
+	let configuredAgentSkills;
+	function getConfiguredAgentSkills() {
+		if (!configuredAgentSkills) configuredAgentSkills = Array.isArray(options._preloadedAgentSkills) ? Promise.resolve([...options._preloadedAgentSkills]) : resolveConfiguredAgentSkills(options.agent?.skills, { rootDir });
+		return configuredAgentSkills;
+	}
 	const handlers = createDocsMcpHttpHandler({
 		source: {
 			...createFilesystemDocsMcpSource({
@@ -3277,7 +3294,7 @@ function createDocsMCPAPI(options = {}) {
 				ordering: options.ordering
 			}),
 			async getSkills() {
-				const configured = await resolveConfiguredAgentSkills(options.agent?.skills, { rootDir });
+				const configured = await getConfiguredAgentSkills();
 				return [await resolveDocsPublishedAgentSkill({
 					preferredDocument: readRootSkillDocument(rootDir),
 					fallbackDocument: `---\nname: docs\ndescription: Use the project documentation through MCP resources and tools.\n---\n\n# Documentation\n`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "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.61"
+    "@farming-labs/docs": "0.2.63"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",