@farming-labs/docs 0.2.57 → 0.2.59

package/dist/{review-DZ81wm7h.mjs → review-NC-sOdXn.mjs}

@@ -1,11 +1,12 @@
-import { Jt as getPageAgentFrontmatterIssues, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, St as findDocsAudienceMdxIssues, Wt as PAGE_AGENT_CONTRACT_FIELDS, Xt as normalizePageAgentFrontmatter, Yt as hasStructuredPageAgentContract, f as DEFAULT_DOCS_CONFIG_ROUTE, u as DEFAULT_DOCS_API_ROUTE } from "./agent-CxDzPqtl.mjs";
-import "./search-OHp36znm.mjs";
-import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-BD17jOqL.mjs";
+import { Jt as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, Kt as DEFAULT_AGENT_SKILLS_INDEX_FORMAT, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, Qt as DEFAULT_API_CATALOG_ROUTE, Xt as DEFAULT_AGENT_SKILL_FORMAT, Zt as DEFAULT_API_CATALOG_FORMAT, _n as hasStructuredPageAgentContract, an as resolveDocsDiscoveryApiRoute, fn as PAGE_AGENT_CONTRACT_FIELDS, gn as getPageAgentFrontmatterIssues, qt as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, vn as normalizePageAgentFrontmatter, wt as findDocsAudienceMdxIssues } from "./agent-BFqyqEnC.mjs";
+import { d as resolveAskAISearchRequestConfig } from "./search-D57JXQLj.mjs";
+import { a as resolveDocsMetadataBaseUrl } from "./metadata-BDuewuzq.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-kJs2Y9xR.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-C9awWzEQ.mjs";
-import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, m as resolveDocsConfigPath, p as readTopLevelStringProperty } from "./config-DZbZiYEa.mjs";
-import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
-import { i as extractAgentBlocks, n as analyzeAgentUsefulness, r as createAgentUsefulnessPagesFromMcp, t as analyzeAgentSurfaceDrift } from "./agent-surface-drift-rGFS38Ak.mjs";
+import "./code-blocks-qe0T8-xe.mjs";
+import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, m as resolveDocsConfigPath, p as readTopLevelStringProperty } from "./config-DASewQ0x.mjs";
+import { t as detectFramework } from "./utils-6UCLxv4B.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-BN9u2wxw.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -25,26 +26,6 @@ const IGNORED_DIRS = new Set([
 	"node_modules",
 	"out"
 ]);
-function isPlainRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function resolveGoldenEvaluationTasks(evaluationInput) {
-	if (evaluationInput === void 0 || typeof evaluationInput === "boolean") return void 0;
-	if (!isPlainRecord(evaluationInput)) return { evaluationConfig: evaluationInput };
-	if (evaluationInput.enabled === false) return void 0;
-	if ("enabled" in evaluationInput && typeof evaluationInput.enabled !== "boolean") return evaluationInput;
-	if (!("tasks" in evaluationInput)) return void 0;
-	const runtimeTasks = evaluationInput.tasks;
-	if (!Array.isArray(runtimeTasks)) return runtimeTasks;
-	return runtimeTasks.map((task) => {
-		if (!isPlainRecord(task)) return task;
-		return {
-			...task,
-			tokenBudget: task.tokenBudget ?? evaluationInput.tokenBudget,
-			topK: task.topK ?? evaluationInput.topK
-		};
-	});
-}
 function parseReviewArgs(argv) {
 	const parsed = {};
 	for (let index = 0; index < argv.length; index += 1) {
@@ -182,7 +163,27 @@ async function runReview(options = {}) {
 		});
 	}
 	const evaluationInput = config?.agent?.evaluations;
-	const evaluations = await runDocsGoldenTasks(corpusPages, resolveGoldenEvaluationTasks(evaluationInput));
+	const evaluation = resolveGoldenEvaluationInput(evaluationInput);
+	const evaluationBaseUrl = config ? resolveDocsMetadataBaseUrl(config) : void 0;
+	const evaluationSiteTitle = typeof config?.nav?.title === "string" ? config.nav.title : void 0;
+	const evaluationMcp = resolveDocsMcpConfig(config?.mcp, { defaultName: evaluationSiteTitle });
+	const askAISearch = resolveAskAISearchRequestConfig({
+		search: config?.search,
+		useMcp: config?.ai?.useMcp,
+		mcpEndpoint: evaluationMcp.route,
+		mcpEnabled: evaluationMcp.enabled,
+		mcpSearchEnabled: evaluationMcp.tools.searchDocs,
+		requestUrl: evaluationBaseUrl
+	});
+	const evaluations = await runDocsGoldenTasks(corpusPages, evaluation.tasks, {
+		...evaluation.options,
+		search: config?.search,
+		askAISearch,
+		siteTitle: evaluationSiteTitle,
+		baseUrl: evaluationBaseUrl,
+		rootDir,
+		codeBlocksValidate: config?.codeBlocks?.validate
+	});
 	if (relevantFiles.length > 0 && evaluations.status === "unmeasured") pushFinding(findings, review, {
 		rule: "goldenTasks",
 		code: "golden-tasks-unmeasured",
@@ -208,9 +209,11 @@ async function runReview(options = {}) {
 		const evaluatedConfig = configLoad.config;
 		const searchEnabled = evaluatedConfig.search !== false && !(typeof evaluatedConfig.search === "object" && evaluatedConfig.search?.enabled === false);
 		const mcp = resolveDocsMcpConfig(evaluatedConfig.mcp, { defaultName: typeof evaluatedConfig.nav?.title === "string" ? evaluatedConfig.nav.title : void 0 });
+		const apiRoute = resolveDocsDiscoveryApiRoute(evaluatedConfig.cloud?.apiRoute);
 		const discovery = buildDocsAgentDiscoverySpec({
 			origin: "http://localhost",
 			entry,
+			apiRoute,
 			search: evaluatedConfig.search,
 			mcp
 		});
@@ -224,7 +227,7 @@ async function runReview(options = {}) {
 				entry,
 				search: {
 					enabled: searchEnabled,
-					endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`
+					endpoint: `${apiRoute}?query={query}`
 				},
 				mcp: {
 					enabled: mcp.enabled,
@@ -232,9 +235,18 @@ async function runReview(options = {}) {
 					tools: mcp.tools
 				},
 				routes: {
-					"api.docs": DEFAULT_DOCS_API_ROUTE,
-					"api.config": DEFAULT_DOCS_CONFIG_ROUTE,
-					"config.endpoint": DEFAULT_DOCS_CONFIG_ROUTE
+					"api.docs": apiRoute,
+					"api.config": `${apiRoute}?format=config`,
+					"api.apiCatalog": DEFAULT_API_CATALOG_ROUTE,
+					"api.apiCatalogQuery": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+					"api.agentSkillsIndex": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					"apiCatalog.route": DEFAULT_API_CATALOG_ROUTE,
+					"apiCatalog.api": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+					"config.endpoint": `${apiRoute}?format=config`,
+					"skills.discovery.index": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					"skills.discovery.artifact": DEFAULT_AGENT_SKILLS_ROUTE_PATTERN,
+					"skills.discovery.apiIndex": `${apiRoute}?format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}`,
+					"skills.discovery.apiArtifact": `${apiRoute}?format=${DEFAULT_AGENT_SKILL_FORMAT}&name={name}`
 				}
 			}
 		});

package/dist/{robots-mSc98PMp.mjs → robots-DskPvGPw.mjs}

@@ -1,7 +1,7 @@
-import "./agent-CxDzPqtl.mjs";
-import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-DRpoiYAV.mjs";
-import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-DZbZiYEa.mjs";
-import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
+import "./agent-BFqyqEnC.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-ltltiLJF.mjs";
+import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-DASewQ0x.mjs";
+import { t as detectFramework } from "./utils-6UCLxv4B.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{robots-DRpoiYAV.mjs → robots-ltltiLJF.mjs}

@@ -1,4 +1,4 @@
-import { $ as normalizeDocsPathSegment, Lt as resolveDocsSitemapConfig, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-CxDzPqtl.mjs";
+import { Qt as DEFAULT_API_CATALOG_ROUTE, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Yt as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, et as normalizeDocsPathSegment, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, qt as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, zt as resolveDocsSitemapConfig } from "./agent-BFqyqEnC.mjs";
 
 //#region src/robots.ts
 const DEFAULT_ROBOTS_TXT_ROUTE = "/robots.txt";
@@ -79,6 +79,9 @@ function getDocsRobotsAllowRoutes(options = {}) {
 		DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE,
 		DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
 		DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
+		...options.apiCatalog === false ? [] : [DEFAULT_API_CATALOG_ROUTE],
+		DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+		`${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/*/SKILL.md`,
 		DEFAULT_MCP_PUBLIC_ROUTE,
 		DEFAULT_MCP_WELL_KNOWN_ROUTE
 	];

package/dist/{search-9uEaC23e.d.mts → search-C1JitPwi.d.mts}

@@ -1,4 +1,4 @@
-import { $t as McpDocsSearchConfig, An as TypesenseDocsSearchConfig, At as DocsSearchDocument, D as DocsAnalyticsEventInput, Dt as DocsSearchAdapterFactory, E as DocsAnalyticsEvent, Ft as DocsSearchSourcePage, It as DocsSitemapConfig, L as DocsAskAIMcpConfig, Nt as DocsSearchResult, Ot as DocsSearchChunkingConfig, S as DocsAgentTraceEventInput, T as DocsAnalyticsConfig, Tt as DocsSearchAdapter, an as OpenDocsTarget, bn as ResolvedDocsRelatedLink, f as CustomDocsSearchConfig, ht as DocsObservabilityEventInput, kt as DocsSearchConfig, mt as DocsObservabilityEvent, nn as OpenDocsProvider, pt as DocsObservabilityConfig, r as AlgoliaDocsSearchConfig } from "./types-R-DN23yw.mjs";
+import { An as ResolvedDocsRelatedLink, Bn as TypesenseDocsSearchConfig, Bt as DocsSearchDocument, Ct as DocsObservabilityConfig, F as DocsAnalyticsConfig, Ft as DocsSearchAdapter, Gt as DocsSearchSourcePage, I as DocsAnalyticsEvent, Kt as DocsSitemapConfig, L as DocsAnalyticsEventInput, Lt as DocsSearchAdapterFactory, M as DocsAgentTraceEventInput, Rt as DocsSearchChunkingConfig, Tt as DocsObservabilityEventInput, Ut as DocsSearchResult, f as CustomDocsSearchConfig, fn as OpenDocsProvider, hn as OpenDocsTarget, ln as McpDocsSearchConfig, q as DocsAskAIMcpConfig, r as AlgoliaDocsSearchConfig, wt as DocsObservabilityEvent, zt as DocsSearchConfig } from "./types-XHABMh_f.mjs";
 
 //#region src/analytics.d.ts
 declare const DOCS_AGENT_TRACE_EVENT_TYPES: readonly ["run.start", "run.end", "run.error", "user.input", "prompt.build", "retrieval.query", "retrieval.result", "retrieval.error", "model.call", "model.response", "model.stream", "model.error", "tool.call", "tool.result", "tool.error", "retry", "timeout", "error", "agent.final"];
@@ -29,6 +29,130 @@ declare function emitDocsAnalyticsEvent(analytics: boolean | DocsAnalyticsConfig
 declare function emitDocsObservabilityEvent(observability: boolean | DocsObservabilityConfig | undefined, event: DocsObservabilityEventInput): Promise<void>;
 declare function emitDocsAgentTraceEvent(observability: boolean | DocsObservabilityConfig | undefined, event: DocsAgentTraceEventInput): Promise<void>;
 //#endregion
+//#region src/standards-discovery.d.ts
+declare const DEFAULT_API_CATALOG_ROUTE = "/.well-known/api-catalog";
+declare const DEFAULT_API_CATALOG_FORMAT = "api-catalog";
+declare const API_CATALOG_PROFILE_URI = "https://www.rfc-editor.org/info/rfc9727";
+declare const API_CATALOG_MEDIA_TYPE = "application/linkset+json";
+declare const DEFAULT_AGENT_SKILLS_INDEX_ROUTE = "/.well-known/agent-skills/index.json";
+declare const DEFAULT_AGENT_SKILLS_ROUTE_PREFIX = "/.well-known/agent-skills";
+declare const DEFAULT_AGENT_SKILLS_ROUTE_PATTERN = "/.well-known/agent-skills/{name}/SKILL.md";
+declare const DEFAULT_AGENT_SKILLS_INDEX_FORMAT = "agent-skills";
+declare const DEFAULT_AGENT_SKILL_FORMAT = "agent-skill";
+declare const AGENT_SKILLS_DISCOVERY_SCHEMA_URI = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+interface DocsAgentSkillIndexEntry {
+  name: string;
+  type: "skill-md";
+  description: string;
+  url: string;
+  digest: `sha256:${string}`;
+}
+interface DocsAgentSkillsIndex {
+  $schema: typeof AGENT_SKILLS_DISCOVERY_SCHEMA_URI;
+  skills: DocsAgentSkillIndexEntry[];
+}
+interface DocsPublishedAgentSkill extends DocsAgentSkillIndexEntry {
+  content: string;
+  sha256: string;
+}
+interface DocsPublishedAgentSkillOptions {
+  preferredDocument?: string | null;
+  fallbackDocument: string;
+}
+interface DocsApiCatalogLinkTarget {
+  href: string;
+  type?: string;
+  title?: string;
+}
+interface DocsApiCatalogLinkContext {
+  anchor: string;
+  item?: DocsApiCatalogLinkTarget[];
+  "api-catalog"?: DocsApiCatalogLinkTarget[];
+  "service-desc"?: DocsApiCatalogLinkTarget[];
+  "service-doc"?: DocsApiCatalogLinkTarget[];
+  "service-meta"?: DocsApiCatalogLinkTarget[];
+}
+interface DocsApiCatalog {
+  linkset: DocsApiCatalogLinkContext[];
+}
+interface DocsApiCatalogOptions {
+  origin: string;
+  docsRoute?: string;
+  apiRoute?: string | null;
+  /** Additional HTTP API endpoints to list as RFC 9727 `item` links. */
+  apiRoutes?: readonly {
+    route: string;
+    type?: string;
+    title?: string;
+  }[];
+  configRoute?: string | null;
+  diagnosticsRoute?: string | null;
+  agentManifestRoute?: string | null;
+  agentSkillsIndexRoute?: string | null;
+  agentsRoute?: string | null;
+  skillRoute?: string | null;
+  markdownRootRoute?: string | null;
+  llmsRoutes?: readonly string[];
+  sitemapRoutes?: readonly string[];
+  robotsRoute?: string | null;
+  mcpRoute?: string | null;
+  feedbackRoutes?: readonly string[];
+  openapiRoute?: string | null;
+  apiReferenceRoute?: string | null;
+}
+type DocsStandardsDiscoveryRequest = {
+  kind: "api-catalog";
+} | {
+  kind: "agent-skills-index";
+} | {
+  kind: "agent-skill";
+  name: string;
+};
+interface DocsDiscoveryApiRouteOptions {
+  /** Same-origin Docs API pathname used by query-form discovery. @default "/api/docs" */
+  apiRoute?: string;
+}
+interface DocsStandardsDiscoveryRouteOptions extends DocsDiscoveryApiRouteOptions {}
+interface CreateDocsStandardsResponseOptions {
+  request: Request;
+  apiCatalog?: DocsApiCatalog;
+  /** Whether the RFC 9727 catalog is exposed. Defaults to true. */
+  apiCatalogEnabled?: boolean;
+  /** Internal docs API route used for query-form forwarding. */
+  apiRoute?: string;
+  preferredSkillDocument?: string | null;
+  fallbackSkillDocument: string;
+}
+/** Resolve the same-origin Docs API pathname used by query-form discovery routes. */
+declare function resolveDocsDiscoveryApiRoute(apiRoute?: string): string;
+/** Build an RFC 9727 API Catalog using the RFC 9264 JSON Linkset representation. */
+declare function buildDocsApiCatalog(options: DocsApiCatalogOptions): DocsApiCatalog;
+declare function sha256DocsDiscoveryContent(content: string): Promise<string>;
+/** Select a valid public skill and hash the exact bytes returned by its standards route. */
+declare function resolveDocsPublishedAgentSkill({
+  preferredDocument,
+  fallbackDocument
+}: DocsPublishedAgentSkillOptions): Promise<DocsPublishedAgentSkill>;
+declare function buildDocsAgentSkillsIndex(skills: DocsPublishedAgentSkill | readonly DocsPublishedAgentSkill[]): DocsAgentSkillsIndex;
+declare function resolveDocsStandardsDiscoveryRequest(url: URL, options?: DocsStandardsDiscoveryRouteOptions): DocsStandardsDiscoveryRequest | null;
+declare function isDocsStandardsDiscoveryRequest(url: URL, options?: DocsStandardsDiscoveryRouteOptions): boolean;
+/** Cross-link the standards endpoints without replacing an existing canonical Link value. */
+declare function getDocsDiscoveryLinkHeader(options?: {
+  includeApiCatalog?: boolean;
+  includeManifest?: boolean;
+  includeSkills?: boolean;
+}): string;
+declare function appendDocsDiscoveryLinkHeader(headers: Headers, value?: string): Headers;
+/** Return one RFC 9727 or Agent Skills discovery response, or null for unrelated requests. */
+declare function createDocsStandardsResponse({
+  request,
+  apiCatalog,
+  apiCatalogEnabled,
+  apiRoute,
+  preferredSkillDocument,
+  fallbackSkillDocument
+}: CreateDocsStandardsResponseOptions): Promise<Response | null>;
+//#endregion
 //#region src/audience.d.ts
 /** The two content projections emitted by the docs framework. */
 type DocsContentAudience = "human" | "agent";
@@ -144,7 +268,7 @@ interface DocsSitemapResolvedConfig {
     wellKnownRoute: string;
   };
 }
-interface CreateDocsSitemapResponseOptions {
+interface CreateDocsSitemapResponseOptions extends DocsDiscoveryApiRouteOptions {
   request: Request;
   sitemap?: boolean | DocsSitemapConfig;
   entry?: string;
@@ -156,7 +280,7 @@ interface CreateDocsSitemapResponseOptions {
 declare function resolveDocsSitemapConfig(sitemap?: boolean | DocsSitemapConfig, defaults?: {
   baseUrl?: string;
 }): DocsSitemapResolvedConfig;
-declare function resolveDocsSitemapRequest(url: URL, sitemap?: boolean | DocsSitemapConfig): DocsSitemapFormat | null;
+declare function resolveDocsSitemapRequest(url: URL, sitemap?: boolean | DocsSitemapConfig, options?: DocsDiscoveryApiRouteOptions): DocsSitemapFormat | null;
 declare function toDocsSitemapMarkdownUrl(url: string): string;
 declare function buildDocsSitemapManifest(options: {
   pages: DocsSitemapPageInput[];
@@ -183,6 +307,7 @@ declare function readDocsSitemapManifestFromContentMap(contentMap?: Record<strin
 declare function resolveDocsSitemapPageLastmod(manifest: DocsSitemapManifest | null | undefined, url: string): string | undefined;
 declare function createDocsSitemapResponse({
   request,
+  apiRoute,
   sitemap,
   entry,
   siteTitle,
@@ -198,6 +323,11 @@ interface DocsAskAIContextResult extends DocsSearchResult {
 }
 interface DocsAskAIContext {
   context: string;
+  /** Structured production context blocks; avoids reparsing markdown horizontal rules. */
+  blocks: Array<{
+    text: string;
+    result: DocsAskAIContextResult;
+  }>;
   results: DocsAskAIContextResult[];
   searchResults: DocsSearchResult[];
   packageHints: DocsAskAIPackageHints;
@@ -230,8 +360,22 @@ declare function performDocsSearch(options: {
   audience?: DocsContentAudience;
   locale?: string;
   pathname?: string;
-  siteTitle?: string;
+  siteTitle?: string; /** Canonical docs URL used to distinguish same-site absolute hits from foreign MCP results. */
+  baseUrl?: string;
   limit?: number;
+  /**
+   * Controls provider failures. Runtime search keeps the resilient `fallback` default;
+   * diagnostics can request `throw` so a broken configured provider cannot be scored as
+   * successful simple search.
+   */
+  failureMode?: "fallback" | "throw";
+  /**
+   * Whether non-simple provider hits are supplemented with exact/local simple results.
+   * Runtime search defaults to true; provider diagnostics can disable supplementation.
+   */
+  supplementExternalResults?: boolean; /** Fail closed on absolute provider hits when no canonical docs origin is available. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to adapters and their managed requests. */
+  signal?: AbortSignal;
 }): Promise<DocsSearchResult[]>;
 declare function buildDocsAskAIContext(options: {
   pages: DocsSearchSourcePage[];
@@ -243,8 +387,11 @@ declare function buildDocsAskAIContext(options: {
   baseUrl?: string;
   limit?: number;
   maxContextChars?: number;
-  maxResultChars?: number;
+  maxResultChars?: number; /** See `performDocsSearch.failureMode`. Defaults to resilient runtime fallback. */
+  searchFailureMode?: "fallback" | "throw"; /** See `performDocsSearch.strictExternalOrigins`. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to the configured search provider. */
+  signal?: AbortSignal;
 }): Promise<DocsAskAIContext>;
 declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory): CustomDocsSearchConfig;
 //#endregion
-export { resolveDocsAudienceMdxContent as $, resolveDocsSitemapRequest as A, normalizePromptProviderName as B, buildDocsSitemapManifest as C, renderDocsSitemapXml as D, renderDocsSitemapMarkdown as E, DEFAULT_PROMPT_PROVIDER_TEMPLATES as F, serializeDocsIconRegistry as G, resolvePromptProviderChoices as H, PromptAction as I, DocsAudienceMdxIssue as J, serializeOpenDocsProvider as K, PromptProviderChoice as L, DEFAULT_OPEN_DOCS_PROMPT as M, DEFAULT_OPEN_DOCS_PROVIDER_IDS as N, resolveDocsSitemapConfig as O, DEFAULT_OPEN_DOCS_TARGET as P, resolveDocsAudienceExposure as Q, SerializeOpenDocsProviderOptions as R, DocsSitemapResolvedConfig as S, readDocsSitemapManifestFromContentMap as T, sanitizePromptText as U, parsePromptStringArray as V, serializeDocsIcon as W, findDocsAudienceMdxIssues as X, DocsContentAudience as Y, resolveDocsAgentMdxContent as Z, DEFAULT_SITEMAP_XML_ROUTE as _, createMcpSearchAdapter as a, createDocsAgentTraceId as at, DocsSitemapManifestPage as b, formatDocsAskAIPackageHints as c, emitDocsObservabilityEvent as ct, resolveAskAISearchRequestConfig as d, resolveDocsObservabilityConfig as dt, DOCS_AGENT_TRACE_EVENT_TYPES as et, resolveSearchRequestConfig as f, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE as g, DEFAULT_SITEMAP_MD_ROUTE as h, createCustomSearchAdapter as i, createDocsAgentTraceContext as it, toDocsSitemapMarkdownUrl as j, resolveDocsSitemapPageLastmod as k, inferDocsAskAIPackageHints as l, getDocsRequestAnalyticsProperties as lt, DEFAULT_SITEMAP_MD_DOCS_ROUTE as m, buildDocsSearchDocuments as n, ResolvedDocsAnalyticsConfig as nt, createSimpleSearchAdapter as o, emitDocsAgentTraceEvent as ot, DEFAULT_SITEMAP_MANIFEST_PATH as p, serializeOpenDocsProviders as q, createAlgoliaSearchAdapter as r, ResolvedDocsObservabilityConfig as rt, createTypesenseSearchAdapter as s, emitDocsAnalyticsEvent as st, buildDocsAskAIContext as t, DocsAgentTraceContext as tt, performDocsSearch as u, resolveDocsAnalyticsConfig as ut, DocsSitemapFormat as v, createDocsSitemapResponse as w, DocsSitemapPageInput as x, DocsSitemapManifest as y, SerializedOpenDocsProvider as z };
+export { resolveDocsAudienceMdxContent as $, resolveDocsSitemapRequest as A, resolveDocsStandardsDiscoveryRequest as At, normalizePromptProviderName as B, emitDocsObservabilityEvent as Bt, buildDocsSitemapManifest as C, buildDocsAgentSkillsIndex as Ct, renderDocsSitemapXml as D, isDocsStandardsDiscoveryRequest as Dt, renderDocsSitemapMarkdown as E, getDocsDiscoveryLinkHeader as Et, DEFAULT_PROMPT_PROVIDER_TEMPLATES as F, ResolvedDocsObservabilityConfig as Ft, serializeDocsIconRegistry as G, resolvePromptProviderChoices as H, resolveDocsAnalyticsConfig as Ht, PromptAction as I, createDocsAgentTraceContext as It, DocsAudienceMdxIssue as J, serializeOpenDocsProvider as K, PromptProviderChoice as L, createDocsAgentTraceId as Lt, DEFAULT_OPEN_DOCS_PROMPT as M, DOCS_AGENT_TRACE_EVENT_TYPES as Mt, DEFAULT_OPEN_DOCS_PROVIDER_IDS as N, DocsAgentTraceContext as Nt, resolveDocsSitemapConfig as O, resolveDocsDiscoveryApiRoute as Ot, DEFAULT_OPEN_DOCS_TARGET as P, ResolvedDocsAnalyticsConfig as Pt, resolveDocsAudienceExposure as Q, SerializeOpenDocsProviderOptions as R, emitDocsAgentTraceEvent as Rt, DocsSitemapResolvedConfig as S, appendDocsDiscoveryLinkHeader as St, readDocsSitemapManifestFromContentMap as T, createDocsStandardsResponse as Tt, sanitizePromptText as U, resolveDocsObservabilityConfig as Ut, parsePromptStringArray as V, getDocsRequestAnalyticsProperties as Vt, serializeDocsIcon as W, findDocsAudienceMdxIssues as X, DocsContentAudience as Y, resolveDocsAgentMdxContent as Z, DEFAULT_SITEMAP_XML_ROUTE as _, DocsDiscoveryApiRouteOptions as _t, createMcpSearchAdapter as a, DEFAULT_AGENT_SKILLS_INDEX_ROUTE as at, DocsSitemapManifestPage as b, DocsStandardsDiscoveryRequest as bt, formatDocsAskAIPackageHints as c, DEFAULT_AGENT_SKILL_FORMAT as ct, resolveAskAISearchRequestConfig as d, DocsAgentSkillIndexEntry as dt, AGENT_SKILLS_DISCOVERY_SCHEMA_URI as et, resolveSearchRequestConfig as f, DocsAgentSkillsIndex as ft, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE as g, DocsApiCatalogOptions as gt, DEFAULT_SITEMAP_MD_ROUTE as h, DocsApiCatalogLinkTarget as ht, createCustomSearchAdapter as i, DEFAULT_AGENT_SKILLS_INDEX_FORMAT as it, toDocsSitemapMarkdownUrl as j, sha256DocsDiscoveryContent as jt, resolveDocsSitemapPageLastmod as k, resolveDocsPublishedAgentSkill as kt, inferDocsAskAIPackageHints as l, DEFAULT_API_CATALOG_FORMAT as lt, DEFAULT_SITEMAP_MD_DOCS_ROUTE as m, DocsApiCatalogLinkContext as mt, buildDocsSearchDocuments as n, API_CATALOG_PROFILE_URI as nt, createSimpleSearchAdapter as o, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN as ot, DEFAULT_SITEMAP_MANIFEST_PATH as p, DocsApiCatalog as pt, serializeOpenDocsProviders as q, createAlgoliaSearchAdapter as r, CreateDocsStandardsResponseOptions as rt, createTypesenseSearchAdapter as s, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX as st, buildDocsAskAIContext as t, API_CATALOG_MEDIA_TYPE as tt, performDocsSearch as u, DEFAULT_API_CATALOG_ROUTE as ut, DocsSitemapFormat as v, DocsPublishedAgentSkill as vt, createDocsSitemapResponse as w, buildDocsApiCatalog as wt, DocsSitemapPageInput as x, DocsStandardsDiscoveryRouteOptions as xt, DocsSitemapManifest as y, DocsPublishedAgentSkillOptions as yt, SerializedOpenDocsProvider as z, emitDocsAnalyticsEvent as zt };