@farming-labs/theme 0.2.60 → 0.2.62

package/dist/docs-api.d.mts

@@ -78,6 +78,8 @@ interface DocsAPIOptions {
   apiReference?: DocsConfig["apiReference"];
   /** Metadata used in generated OpenAPI documents. */
   metadata?: DocsConfig["metadata"];
+  /** Reusable skill publication and optional real A2A service metadata. */
+  agent?: DocsConfig["agent"];
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;
@@ -92,6 +94,7 @@ interface DocsMCPAPIOptions {
   analytics?: boolean | DocsAnalyticsConfig;
   telemetry?: boolean | DocsTelemetryConfig;
   observability?: boolean | DocsObservabilityConfig;
+  agent?: DocsConfig["agent"];
 }
 type LlmsTxtOptions = LlmsTxtConfig;
 /**

package/dist/docs-api.mjs

@@ -4,8 +4,8 @@ import { BoundedRouteCache } from "./bounded-route-cache.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-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";
+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
 /**
@@ -42,7 +42,6 @@ const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
 const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
 const DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE = "/.well-known/agent";
 const DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE = "/.well-known/agent.json";
-const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
 const DEFAULT_MCP_PUBLIC_ROUTE = "/mcp";
 const DEFAULT_MCP_WELL_KNOWN_ROUTE = "/.well-known/mcp";
 const DEFAULT_LLMS_TXT_ROUTE = "/llms.txt";
@@ -210,7 +209,7 @@ function resolveApiReferenceOpenApiDiscovery(value) {
 		apiReferencePath: `/${apiReference.path}`
 	};
 }
-function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp, feedback, llms, sitemap, robots, openapi, publishedSkills = [], agentCard }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
@@ -218,6 +217,8 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
 	const agentContractMcpTools = resolveDocsAgentContractMcpTools(mcp);
+	const protectedResource = mcp.enabled && mcp.security?.authenticate ? mcp.security.protectedResource : void 0;
+	const protectedResourceMetadataRoutes = protectedResource ? getDocsMcpProtectedResourceMetadataRoutes(mcp.route) : [];
 	const agentSpecRoute = apiRoute === DEFAULT_DOCS_API_ROUTE ? DEFAULT_AGENT_SPEC_ROUTE : `${apiRoute}?agent=spec`;
 	return {
 		version: "1",
@@ -272,7 +273,9 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 				apiCatalog: DEFAULT_API_CATALOG_ROUTE,
 				apiCatalogQuery: `${apiRoute}?format=api-catalog`
 			} : {},
-			agentSkillsIndex: DEFAULT_AGENT_SKILLS_INDEX_ROUTE
+			agentSkillsIndex: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+			legacySkillsIndex: DEFAULT_LEGACY_SKILLS_INDEX_ROUTE,
+			...agentCard ? { agentCard: DEFAULT_A2A_AGENT_CARD_ROUTE } : {}
 		},
 		apiCatalog: {
 			enabled: apiCatalog,
@@ -390,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,
@@ -414,10 +421,26 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 				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`,
+				archive: DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN,
+				file: `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/{name}/{path}`,
+				legacyIndex: DEFAULT_LEGACY_SKILLS_INDEX_ROUTE,
 				apiIndex: `${apiRoute}?format=agent-skills`,
 				apiArtifact: `${apiRoute}?format=agent-skill&name={name}`,
+				apiFile: `${apiRoute}?format=agent-skill-file&name={name}&path={path}`,
 				digest: "sha256"
 			},
+			published: publishedSkills.map((skill) => ({
+				name: skill.name,
+				description: skill.description,
+				type: skill.type,
+				url: skill.url,
+				digest: skill.digest,
+				files: skill.files.map((file) => ({
+					path: file.path,
+					url: file.url,
+					digest: file.digest
+				}))
+			})),
 			registry: "skills.sh",
 			install: "npx skills add farming-labs/docs",
 			recommended: [{
@@ -432,10 +455,16 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			publicEndpoint: DEFAULT_MCP_PUBLIC_ROUTE,
 			wellKnownEndpoint: DEFAULT_MCP_WELL_KNOWN_ROUTE,
 			publicEndpoints: [DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE],
-			canonicalEndpoint: DEFAULT_MCP_ROUTE,
+			canonicalEndpoint: mcp.route,
 			name: mcp.name,
 			version: mcp.version,
-			tools: mcp.tools
+			tools: mcp.tools,
+			...protectedResource ? { protectedResource: {
+				metadataEndpoints: protectedResourceMetadataRoutes,
+				authorizationServers: protectedResource.authorizationServers,
+				scopesSupported: protectedResource.scopesSupported,
+				requiredScopes: protectedResource.requiredScopes
+			} } : {}
 		},
 		feedback: {
 			enabled: feedback.enabled,
@@ -1253,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.`);
@@ -1318,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}.`);
@@ -2434,6 +2463,7 @@ function generateLlmsTxt(indexes, options) {
 */
 function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
+	const publishedAgentSkills = resolveConfiguredAgentSkills(options?.agent?.skills, { rootDir: root });
 	const entry = options?.entry ?? readEntry(root);
 	const docsPath = normalizeDocsPublicPath(options?.docsPath ?? readDocsPath(root), entry);
 	const analytics = options?.analytics;
@@ -2474,7 +2504,10 @@ 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 discoveryLinkHeader = getDocsDiscoveryLinkHeader({
+		includeApiCatalog: apiCatalogEnabled,
+		includeAgentCard: Boolean(options?.agent?.a2a)
+	});
 	const telemetryConfig = {
 		entry,
 		docsPath,
@@ -2710,6 +2743,8 @@ function createDocsAPI(options) {
 			request,
 			preferredSkillDocument: needsSkill ? readRootSkillDocument(root) : null,
 			fallbackSkillDocument,
+			publishedSkills: await publishedAgentSkills,
+			agentCard: options?.agent?.a2a,
 			origin: url.origin,
 			entry,
 			docsPath,
@@ -2787,7 +2822,25 @@ function createDocsAPI(options) {
 					llms: llmsConfig,
 					sitemap: sitemapConfig,
 					robots: robotsConfig,
-					openapi: openapiDiscovery
+					openapi: openapiDiscovery,
+					publishedSkills: [await resolveDocsPublishedAgentSkill({
+						preferredDocument: readRootSkillDocument(root),
+						fallbackDocument: renderSkillDocument({
+							origin: url.origin,
+							entry,
+							apiRoute: requestApiRoute,
+							apiCatalog: apiCatalogEnabled,
+							i18n,
+							search: searchConfig,
+							mcp: mcpConfig,
+							feedback: agentFeedbackConfig,
+							llms: llmsConfig,
+							sitemap: sitemapConfig,
+							robots: robotsConfig,
+							openapi: openapiDiscovery
+						})
+					}), ...await publishedAgentSkills],
+					agentCard: options?.agent?.a2a
 				}), { headers: {
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
 					Link: discoveryLinkHeader,
@@ -2905,6 +2958,7 @@ function createDocsAPI(options) {
 				} });
 			}
 			const robotsResponse = createDocsRobotsResponse({
+				agentCard: Boolean(options?.agent?.a2a),
 				request,
 				entry,
 				apiCatalog: apiCatalogEnabled,
@@ -3063,13 +3117,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",
@@ -3081,6 +3138,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)
@@ -3218,13 +3276,22 @@ function createDocsMCPAPI(options = {}) {
 	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";
 	const handlers = createDocsMcpHttpHandler({
-		source: createFilesystemDocsMcpSource({
-			rootDir,
-			entry,
-			contentDir,
-			siteTitle: navTitle,
-			ordering: options.ordering
-		}),
+		source: {
+			...createFilesystemDocsMcpSource({
+				rootDir,
+				entry,
+				contentDir,
+				siteTitle: navTitle,
+				ordering: options.ordering
+			}),
+			async getSkills() {
+				const configured = await resolveConfiguredAgentSkills(options.agent?.skills, { rootDir });
+				return [await resolveDocsPublishedAgentSkill({
+					preferredDocument: readRootSkillDocument(rootDir),
+					fallbackDocument: `---\nname: docs\ndescription: Use the project documentation through MCP resources and tools.\n---\n\n# Documentation\n`
+				}), ...configured];
+			}
+		},
 		mcp: mcpConfig,
 		search: options.search,
 		analytics: options.analytics,

package/package.json

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