@farming-labs/docs 0.2.53 → 0.2.55

package/dist/{package-version-DxnTZH4m.mjs → package-version-DRIc08EU.mjs}

@@ -1,4 +1,4 @@
-import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-CMZTjRQT.mjs";
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-DBCCkkJS.mjs";
 import pc from "picocolors";
 import * as p from "@clack/prompts";
 

package/dist/{reading-time-BuK2YL23.mjs → reading-time-BrTd3DIh.mjs}

@@ -1,6 +1,5 @@
-import { a as normalizePageAgentFrontmatter, i as hasStructuredPageAgentContract } from "./agent-contract-b0akaPcg.mjs";
-import { Et as DEFAULT_SITEMAP_XML_ROUTE, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, wt as DEFAULT_SITEMAP_MD_ROUTE } from "./agent-BMxMpEa0.mjs";
-import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-C6uQG-fS.mjs";
+import { Dt as DEFAULT_SITEMAP_XML_ROUTE, Gt as hasStructuredPageAgentContract, Kt as normalizePageAgentFrontmatter, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, Tt as DEFAULT_SITEMAP_MD_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE } from "./agent-DXkXi-pS.mjs";
+import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-DAptQnkx.mjs";
 import matter from "gray-matter";
 
 //#region src/define-docs.ts

package/dist/{review-BEsbm0l2.mjs → review-Dlb8dRRx.mjs}

@@ -1,14 +1,19 @@
-import { a as normalizePageAgentFrontmatter, i as hasStructuredPageAgentContract, r as getPageAgentFrontmatterIssues } from "./agent-contract-b0akaPcg.mjs";
-import { a as ensureDocsReviewWorkflow, o as readDocsReviewConfigFromSource, s as resolveDocsReviewConfig } from "./review-BHdy75TE.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, p as resolveDocsConfigPath } from "./config-DhIyFsy9.mjs";
+import { Bt as PAGE_AGENT_CONTRACT_FIELDS, Gt as hasStructuredPageAgentContract, Kt as normalizePageAgentFrontmatter, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, Wt as getPageAgentFrontmatterIssues, f as DEFAULT_DOCS_CONFIG_ROUTE, u as DEFAULT_DOCS_API_ROUTE } from "./agent-DXkXi-pS.mjs";
+import "./search-CEg1omHv.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-BD17jOqL.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-CydaZ5PB.mjs";
+import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
+import { n as analyzeAgentUsefulness, r as createAgentUsefulnessPagesFromMcp, t as analyzeAgentSurfaceDrift } from "./agent-surface-drift-LS8zQgbq.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
-import pc from "picocolors";
 import { execFileSync } from "node:child_process";
+import pc from "picocolors";
 
 //#region src/cli/review.ts
-const DOCS_FILE_PATTERN = /\.(?:md|mdx)$/;
+const DOCS_FILE_PATTERN = /\.(?:md|mdx|svx)$/;
 const IGNORED_DIRS = new Set([
 	".git",
 	".next",
@@ -20,6 +25,26 @@ 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) {
@@ -85,7 +110,8 @@ async function runReview(options = {}) {
 	const rootDir = process.cwd();
 	const configPath = resolveDocsConfigPath(rootDir, options.configPath);
 	const configContent = readFileSync(configPath, "utf-8");
-	const config = (await loadDocsConfigModule(rootDir, options.configPath))?.config;
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	const review = withReviewOptionOverrides(resolveDocsReviewConfig(config?.review ?? readDocsReviewConfigFromSource(configContent)), options.mode, options.scoreThreshold);
 	if (options.setup) {
 		const result = ensureDocsReviewWorkflow({
@@ -101,7 +127,8 @@ async function runReview(options = {}) {
 	}
 	if (!review.enabled) {
 		const report = {
-			score: 100,
+			status: "disabled",
+			score: null,
 			threshold: review.score.threshold,
 			mode: options.ci ? review.ci.mode : "local",
 			reviewedFiles: [],
@@ -123,6 +150,18 @@ async function runReview(options = {}) {
 		rootDir,
 		contentDir
 	});
+	const mcpSource = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle: typeof config?.nav?.title === "string" ? config.nav.title : "Documentation"
+	});
+	const corpusPages = await Promise.resolve(mcpSource.getPages());
+	const usefulness = analyzeAgentUsefulness({
+		rootDir,
+		pages: createAgentUsefulnessPagesFromMcp(rootDir, corpusPages),
+		projectFramework: detectFramework(rootDir) ?? void 0
+	});
 	const findings = collectReviewFindings({
 		rootDir,
 		entry,
@@ -130,15 +169,95 @@ async function runReview(options = {}) {
 		files: relevantFiles,
 		review
 	});
+	const relevantSet = new Set(relevantFiles);
+	for (const issue of usefulness.findings) {
+		if (!relevantSet.has(issue.file)) continue;
+		pushFinding(findings, review, {
+			rule: issue.category === "command" ? "commandHealth" : issue.category === "related" ? "relatedCoverage" : "agentContext",
+			code: issue.code,
+			severity: issue.severity === "warning" ? "warn" : issue.severity === "error" ? "error" : "suggestion",
+			file: issue.file,
+			line: issue.line,
+			message: issue.message
+		});
+	}
+	const evaluationInput = config?.agent?.evaluations;
+	const evaluations = await runDocsGoldenTasks(corpusPages, resolveGoldenEvaluationTasks(evaluationInput));
+	if (relevantFiles.length > 0 && evaluations.status === "unmeasured") pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-tasks-unmeasured",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: evaluationInput === false || typeof evaluationInput === "object" && evaluationInput.enabled === false ? "Golden agent tasks are disabled, so retrieval usefulness is unmeasured." : "No golden agent tasks are configured; retrieval, citations, version selection, executable examples, and token usage are unmeasured."
+	});
+	for (const task of evaluations.tasks.filter((task) => !task.passed)) pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-task-failed",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `Golden task ${JSON.stringify(task.id)} scored ${task.score}/100: ${task.issues.join(" ")}`
+	});
+	if (configLoad.status === "static-fallback") pushFinding(findings, review, {
+		rule: "configConfidence",
+		code: "config-static-fallback",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `docs.config could not be evaluated; review used partial static parsing. ${configLoad.error}`
+	});
+	else {
+		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 discovery = buildDocsAgentDiscoverySpec({
+			origin: "http://localhost",
+			entry,
+			search: evaluatedConfig.search,
+			mcp
+		});
+		const configuredAgentReviewPaths = Object.values(buildDocsConfigMap(evaluatedConfig).pointers).map((pointer) => pointer.path).filter((optionPath) => optionPath === "agent" || optionPath.startsWith("agent.") || optionPath === "review" || optionPath.startsWith("review."));
+		const drift = analyzeAgentSurfaceDrift({
+			configOptionPaths: [...new Set([...DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, ...configuredAgentReviewPaths])],
+			schemaOptions: getDocsConfigSchema().options,
+			agentContractFields: PAGE_AGENT_CONTRACT_FIELDS,
+			discovery,
+			expected: {
+				entry,
+				search: {
+					enabled: searchEnabled,
+					endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`
+				},
+				mcp: {
+					enabled: mcp.enabled,
+					endpoint: mcp.route,
+					tools: mcp.tools
+				},
+				routes: {
+					"api.docs": DEFAULT_DOCS_API_ROUTE,
+					"api.config": DEFAULT_DOCS_CONFIG_ROUTE,
+					"config.endpoint": DEFAULT_DOCS_CONFIG_ROUTE
+				}
+			}
+		});
+		for (const issue of drift) pushFinding(findings, review, {
+			rule: "agentSurfaceDrift",
+			code: issue.code,
+			severity: "error",
+			file: toPosixPath(path.relative(rootDir, configPath)),
+			message: issue.message
+		});
+	}
 	const score = calculateReviewScore(findings, review);
 	const mode = options.ci ? review.ci.mode : "local";
 	const report = {
+		status: "measured",
 		score,
 		threshold: review.score.threshold,
 		mode,
 		reviewedFiles: relevantFiles,
 		changedFiles,
-		findings
+		findings,
+		usefulness: usefulness.metrics,
+		evaluations
 	};
 	if (options.json) console.log(JSON.stringify(report, null, 2));
 	else printReviewReport(report);
@@ -367,11 +486,17 @@ function printReviewReport(report) {
 	console.log(`Changed files: ${report.changedFiles.length}`);
 	console.log(`Reviewed docs files: ${report.reviewedFiles.length}`);
 	console.log(`Findings: ${counts.error} error${counts.error === 1 ? "" : "s"}, ${counts.warn} warning${counts.warn === 1 ? "" : "s"}, ${counts.suggestion} suggestion${counts.suggestion === 1 ? "" : "s"}`);
-	if (report.reviewedFiles.length === 0) {
+	if (report.usefulness) console.log(`Useful Agent blocks: ${report.usefulness.agentBlocks.useful}/${report.usefulness.agentBlocks.total}; task-complete pages: ${report.usefulness.taskCompleteness.completePages}/${report.usefulness.actionablePages}`);
+	if (report.evaluations) console.log(`Golden tasks: ${report.evaluations.status === "unmeasured" ? "unmeasured" : `${report.evaluations.passedTaskCount}/${report.evaluations.taskCount} passed (${report.evaluations.score}/100)`}`);
+	if (report.reviewedFiles.length === 0 && report.findings.length === 0) {
 		console.log("");
 		console.log(pc.green("No docs changes detected. Skipping review."));
 		return;
 	}
+	if (report.reviewedFiles.length === 0) {
+		console.log("");
+		console.log(pc.yellow("No docs files changed; reporting project-wide findings."));
+	}
 	if (report.findings.length === 0) {
 		console.log("");
 		console.log(pc.green("No docs review findings."));
@@ -411,7 +536,17 @@ function selectReviewFiles(options) {
 	const pageFiles = new Set(options.pages.map((page) => page.relativePath));
 	const normalizedConfigPath = toPosixPath(options.configPath);
 	if (options.changedFiles.includes(normalizedConfigPath)) return Array.from(pageFiles).sort();
-	return options.changedFiles.map(toPosixPath).filter((file) => pageFiles.has(file)).sort();
+	const selected = /* @__PURE__ */ new Set();
+	for (const changedFile of options.changedFiles.map(toPosixPath)) {
+		if (pageFiles.has(changedFile)) {
+			selected.add(changedFile);
+			continue;
+		}
+		if (!changedFile.endsWith("/agent.md") && changedFile !== "agent.md") continue;
+		const sibling = options.pages.find((page) => path.posix.dirname(page.relativePath) === path.posix.dirname(changedFile));
+		if (sibling) selected.add(sibling.relativePath);
+	}
+	return Array.from(selected).sort();
 }
 function getChangedFiles(rootDir, options) {
 	const ranges = [
@@ -439,7 +574,7 @@ function getChangedFiles(rootDir, options) {
 function scanDocsPages(rootDir, contentDir, entry) {
 	const contentRoot = path.isAbsolute(contentDir) ? contentDir : path.join(rootDir, contentDir);
 	if (!existsSync(contentRoot)) return [];
-	return listFiles(contentRoot).filter((file) => DOCS_FILE_PATTERN.test(file)).map((absolutePath) => {
+	return listFiles(contentRoot).filter((file) => DOCS_FILE_PATTERN.test(file) && path.basename(file) !== "agent.md").map((absolutePath) => {
 		const relativeToContent = toPosixPath(path.relative(contentRoot, absolutePath));
 		const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
 		const slug = docsSlugFromFile(relativeToContent);
@@ -469,9 +604,9 @@ function listFiles(dir) {
 	return files;
 }
 function docsSlugFromFile(relativePath) {
-	const withoutExt = relativePath.replace(/\.(?:md|mdx)$/, "");
-	if (withoutExt === "page" || withoutExt === "index") return "";
-	if (withoutExt.endsWith("/page") || withoutExt.endsWith("/index")) return withoutExt.replace(/\/(?:page|index)$/, "");
+	const withoutExt = relativePath.replace(/\.(?:md|mdx|svx)$/, "");
+	if (withoutExt === "page" || withoutExt === "+page" || withoutExt === "index") return "";
+	if (withoutExt.endsWith("/page") || withoutExt.endsWith("/+page") || withoutExt.endsWith("/index")) return withoutExt.replace(/\/(?:\+?page|index)$/, "");
 	return withoutExt;
 }
 function normalizeInternalHref(href) {

package/dist/{robots-BOwkq9du.mjs → robots-4BUJxlvV.mjs}

@@ -1,8 +1,7 @@
-import "./agent-contract-b0akaPcg.mjs";
-import "./agent-BMxMpEa0.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-C6uQG-fS.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, o as readBooleanProperty, p as resolveDocsConfigPath, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-DhIyFsy9.mjs";
-import { t as detectFramework } from "./utils-CMZTjRQT.mjs";
+import "./agent-DXkXi-pS.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-DAptQnkx.mjs";
+import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-CydaZ5PB.mjs";
+import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{robots-C6uQG-fS.mjs → robots-DAptQnkx.mjs}

@@ -1,4 +1,4 @@
-import { Mt as resolveDocsSitemapConfig, Q as normalizeDocsPathSegment, 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-BMxMpEa0.mjs";
+import { $ as normalizeDocsPathSegment, Nt 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-DXkXi-pS.mjs";
 
 //#region src/robots.ts
 const DEFAULT_ROBOTS_TXT_ROUTE = "/robots.txt";

package/dist/{search-CtAXkk_J.mjs → search-B8cF77_i.mjs}

@@ -1,10 +1,11 @@
-import "./agent-contract-b0akaPcg.mjs";
-import "./agent-BMxMpEa0.mjs";
-import { n as buildDocsSearchDocuments, r as createAlgoliaSearchAdapter, s as createTypesenseSearchAdapter } from "./search-CJNLkdjX.mjs";
-import "./sitemap-server-DnilMEiZ.mjs";
+import "./agent-DXkXi-pS.mjs";
+import { n as buildDocsSearchDocuments, r as createAlgoliaSearchAdapter, s as createTypesenseSearchAdapter } from "./search-CEg1omHv.mjs";
+import "./sitemap-server-wsNLyVkb.mjs";
+import "./agent-evals-BD17jOqL.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import "./code-blocks-C9awWzEQ.mjs";
 import "./server.mjs";
-import { a as loadProjectEnv, f as readTopLevelStringProperty, m as resolveDocsContentDir, p as resolveDocsConfigPath } from "./config-DhIyFsy9.mjs";
+import { h as resolveDocsContentDir, m as resolveDocsConfigPath, o as loadProjectEnv, p as readTopLevelStringProperty } from "./config-CydaZ5PB.mjs";
 import { readFileSync } from "node:fs";
 import pc from "picocolors";
 

package/dist/{search-CTu6Bvq-.d.mts → search-BnQKgDbk.d.mts}

@@ -1,4 +1,4 @@
-import { A as DocsAskAIMcpConfig, Cn as TypesenseDocsSearchConfig, Ct as DocsSearchDocument, Et as DocsSearchResult, Kt as McpDocsSearchConfig, Ot as DocsSearchSourcePage, Qt as OpenDocsTarget, St as DocsSearchConfig, Yt as OpenDocsProvider, b as DocsAnalyticsEventInput, bt as DocsSearchAdapterFactory, ct as DocsObservabilityEventInput, f as CustomDocsSearchConfig, h as DocsAgentTraceEventInput, kt as DocsSitemapConfig, ot as DocsObservabilityConfig, pn as ResolvedDocsRelatedLink, r as AlgoliaDocsSearchConfig, st as DocsObservabilityEvent, v as DocsAnalyticsConfig, vt as DocsSearchAdapter, xt as DocsSearchChunkingConfig, y as DocsAnalyticsEvent } from "./types-CdKu8KmO.mjs";
+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";
 
 //#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"];

package/dist/{search-CJNLkdjX.mjs → search-CEg1omHv.mjs}

@@ -1,5 +1,4 @@
-import { l as upsertPageAgentContractMarkdown, n as PAGE_AGENT_CONTRACT_START_MARKER, o as renderPageAgentContractMarkdown, t as PAGE_AGENT_CONTRACT_END_MARKER } from "./agent-contract-b0akaPcg.mjs";
-import { U as isDocsAgentDiscoveryRequest, W as isDocsAgentsRequest, X as isDocsSkillRequest, ct as resolveDocsAgentFeedbackRequest, ft as resolveDocsLlmsTxtRequest, gt as resolveDocsMarkdownRequest, st as resolveDocsAgentFeedbackConfig, ut as resolveDocsAgentsFormat, vt as resolveDocsSkillFormat } from "./agent-BMxMpEa0.mjs";
+import { G as isDocsAgentsRequest, Ht as PAGE_AGENT_CONTRACT_START_MARKER, W as isDocsAgentDiscoveryRequest, Xt as upsertPageAgentContractMarkdown, Z as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, ct as resolveDocsAgentFeedbackConfig, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackRequest, pt as resolveDocsLlmsTxtRequest, qt as renderPageAgentContractMarkdown, yt as resolveDocsSkillFormat, zt as PAGE_AGENT_CONTRACT_END_MARKER } from "./agent-DXkXi-pS.mjs";
 
 //#region src/telemetry.ts
 const DOCS_PACKAGE_NAME = "@farming-labs/docs";
@@ -54,15 +53,42 @@ function readRequestOrigin(request) {
 		return;
 	}
 }
-function normalizeTelemetryOrigin(candidate) {
-	if (!candidate) return void 0;
+/** Normalize an HTTP(S) telemetry site value to its origin. */
+function normalizeDocsTelemetryOrigin(candidate) {
+	if (typeof candidate !== "string") return void 0;
+	const trimmed = candidate.trim();
+	if (!trimmed) return void 0;
 	try {
-		const withProtocol = /^https?:\/\//i.test(candidate) ? candidate : `https://${candidate}`;
-		return new URL(withProtocol).origin;
+		const hasScheme = /^[a-z][a-z\d+.-]*:(?!\d)/i.test(trimmed);
+		const url = new URL(hasScheme ? trimmed : `https://${trimmed}`);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+		return url.origin;
 	} catch {
 		return;
 	}
 }
+/** Return whether a telemetry origin points at a local development server. */
+function isLocalDocsTelemetryOrigin(candidate) {
+	const origin = normalizeDocsTelemetryOrigin(candidate);
+	if (!origin) return false;
+	const hostname = new URL(origin).hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.+$/, "");
+	if ([
+		"localhost",
+		"localhost.localdomain",
+		"localhost6",
+		"localhost6.localdomain6",
+		"ip6-localhost",
+		"ip6-loopback"
+	].includes(hostname) || hostname.endsWith(".localhost")) return true;
+	if (hostname === "::" || hostname === "::1") return true;
+	const ipv4 = hostname.split(".").map((part) => Number(part));
+	if (ipv4.length === 4 && ipv4.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) return ipv4[0] === 127 || ipv4.every((part) => part === 0);
+	return /^::ffff:7f[0-9a-f]{2}:/.test(hostname) || hostname === "::ffff:0:0";
+}
+function isBlockedDocsTelemetryOrigin(candidate) {
+	if (candidate === void 0) return false;
+	return !normalizeDocsTelemetryOrigin(candidate) || isLocalDocsTelemetryOrigin(candidate);
+}
 function readDeploymentOrigin() {
 	const candidates = [
 		readRuntimeEnv("DOCS_SITE_URL"),
@@ -76,7 +102,7 @@ function readDeploymentOrigin() {
 		readRuntimeEnv("DEPLOY_PRIME_URL")
 	];
 	for (const candidate of candidates) {
-		const origin = normalizeTelemetryOrigin(candidate);
+		const origin = normalizeDocsTelemetryOrigin(candidate);
 		if (origin) return origin;
 	}
 }
@@ -159,7 +185,15 @@ function getDocsTelemetryFeatures(config) {
 }
 function createDocsTelemetryEvent(config, input, context = {}) {
 	const telemetryConfig = config.telemetry && typeof config.telemetry === "object" ? config.telemetry : void 0;
-	const siteOrigin = context.siteOrigin ?? input.site?.origin ?? normalizeTelemetryOrigin(telemetryConfig?.siteOrigin) ?? readRequestOrigin(context.request) ?? readDeploymentOrigin();
+	const siteOriginCandidates = [
+		context.siteOrigin,
+		input.site?.origin,
+		telemetryConfig?.siteOrigin,
+		readRequestOrigin(context.request),
+		readDeploymentOrigin()
+	];
+	if (siteOriginCandidates.some(isBlockedDocsTelemetryOrigin)) return void 0;
+	const siteOrigin = siteOriginCandidates.map(normalizeDocsTelemetryOrigin).find((origin) => Boolean(origin));
 	const deployment = input.deployment ?? detectDeployment();
 	const properties = context.properties || input.properties ? {
 		...input.properties,
@@ -207,7 +241,13 @@ function pruneSentProjectKeys(sent, now) {
 }
 async function emitDocsTelemetryEvent(telemetry, event) {
 	const resolved = resolveDocsTelemetryConfig(telemetry);
-	if (!resolved.enabled || !resolved.endpoint || typeof fetch !== "function") return;
+	const eventSiteOrigin = event.site?.origin;
+	const normalizedSiteOrigin = normalizeDocsTelemetryOrigin(eventSiteOrigin);
+	if (!resolved.enabled || !resolved.endpoint || typeof fetch !== "function" || eventSiteOrigin !== void 0 && (!normalizedSiteOrigin || isLocalDocsTelemetryOrigin(eventSiteOrigin))) return;
+	const eventToSend = normalizedSiteOrigin ? {
+		...event,
+		site: { origin: normalizedSiteOrigin }
+	} : event;
 	try {
 		const ingestKey = readRuntimeEnv("DOCS_TELEMETRY_INGEST_KEY");
 		const headers = { "content-type": "application/json" };
@@ -215,13 +255,14 @@ async function emitDocsTelemetryEvent(telemetry, event) {
 		await fetch(resolved.endpoint, {
 			method: "POST",
 			headers,
-			body: JSON.stringify({ event }),
+			body: JSON.stringify({ event: eventToSend }),
 			keepalive: true
 		});
 	} catch {}
 }
 function emitDocsTelemetryProjectEvent(config, context = {}) {
 	const event = createDocsTelemetryEvent(config, { type: "project_detected" }, context);
+	if (!event) return;
 	const key = projectEventKey(event);
 	const sent = getSentProjectKeys();
 	const now = Date.now();
@@ -237,6 +278,7 @@ function emitDocsTelemetryAgentSurfaceEvent(config, context) {
 		type: context.surface === "mcp" ? "mcp_request" : "agent_surface_used",
 		properties: { surface: context.surface }
 	}, context);
+	if (!event) return;
 	emitDocsTelemetryEvent(config.telemetry, event);
 }
 function emitDocsTelemetryMcpToolEvent(config, context) {
@@ -248,6 +290,7 @@ function emitDocsTelemetryMcpToolEvent(config, context) {
 			resultCount: context.resultCount
 		}
 	}, context);
+	if (!event) return;
 	emitDocsTelemetryEvent(config.telemetry, event);
 }
 function inferDocsTelemetryAgentSurface(request, options) {
@@ -1585,4 +1628,4 @@ function createCustomSearchAdapter(adapter) {
 }
 
 //#endregion
-export { getDocsTelemetryFeatures as A, resolvePageSidebarFolderIndexBehavior as C, emitDocsTelemetryEvent as D, emitDocsTelemetryAgentSurfaceEvent as E, resolveDocsTelemetryConfig as M, emitDocsTelemetryMcpToolEvent as O, applySidebarFolderIndexBehavior as S, resolveSidebarFolderIndexBehaviorForPath as T, hashGeneratedAgentContent as _, createMcpSearchAdapter as a, serializeGeneratedAgentDocument as b, formatDocsAskAIPackageHints as c, resolveAskAISearchRequestConfig as d, resolveSearchRequestConfig as f, GENERATED_AGENT_PROVENANCE_VERSION as g, GENERATED_AGENT_PROVENANCE_MARKER as h, createCustomSearchAdapter as i, inferDocsTelemetryAgentSurface as j, emitDocsTelemetryProjectEvent as k, inferDocsAskAIPackageHints as l, parseDocsMarkdownSections as m, buildDocsSearchDocuments as n, createSimpleSearchAdapter as o, findDocsMarkdownSection as p, createAlgoliaSearchAdapter as r, createTypesenseSearchAdapter as s, buildDocsAskAIContext as t, performDocsSearch as u, normalizeGeneratedAgentContent as v, resolveSidebarFolderIndexBehavior as w, stripGeneratedAgentProvenance as x, parseGeneratedAgentDocument as y };
+export { getDocsTelemetryFeatures as A, resolvePageSidebarFolderIndexBehavior as C, emitDocsTelemetryEvent as D, emitDocsTelemetryAgentSurfaceEvent as E, isLocalDocsTelemetryOrigin as M, normalizeDocsTelemetryOrigin as N, emitDocsTelemetryMcpToolEvent as O, resolveDocsTelemetryConfig as P, applySidebarFolderIndexBehavior as S, resolveSidebarFolderIndexBehaviorForPath as T, hashGeneratedAgentContent as _, createMcpSearchAdapter as a, serializeGeneratedAgentDocument as b, formatDocsAskAIPackageHints as c, resolveAskAISearchRequestConfig as d, resolveSearchRequestConfig as f, GENERATED_AGENT_PROVENANCE_VERSION as g, GENERATED_AGENT_PROVENANCE_MARKER as h, createCustomSearchAdapter as i, inferDocsTelemetryAgentSurface as j, emitDocsTelemetryProjectEvent as k, inferDocsAskAIPackageHints as l, parseDocsMarkdownSections as m, buildDocsSearchDocuments as n, createSimpleSearchAdapter as o, findDocsMarkdownSection as p, createAlgoliaSearchAdapter as r, createTypesenseSearchAdapter as s, buildDocsAskAIContext as t, performDocsSearch as u, normalizeGeneratedAgentContent as v, resolveSidebarFolderIndexBehavior as w, stripGeneratedAgentProvenance as x, parseGeneratedAgentDocument as y };

package/dist/server.d.mts

@@ -1,8 +1,8 @@
-import { A as DocsAskAIMcpConfig, Ct as DocsSearchDocument, D as DocsAskAIFeedbackData, E as DocsAskAIFeedbackConfig, Et as DocsSearchResult, Kt as McpDocsSearchConfig, O as DocsAskAIFeedbackMessage, Ot as DocsSearchSourcePage, St as DocsSearchConfig, Tt as DocsSearchQuery, W as DocsConfig, _ as DocsAgentTraceStatus, a as ApiReferenceRenderer, b as DocsAnalyticsEventInput, bt as DocsSearchAdapterFactory, ct as DocsObservabilityEventInput, dt as DocsReviewCiMode, ft as DocsReviewConfig, g as DocsAgentTraceEventType, h as DocsAgentTraceEventInput, k as DocsAskAIFeedbackValue, kt as DocsSitemapConfig, ot as DocsObservabilityConfig, pt as DocsReviewRulesConfig, st as DocsObservabilityEvent, v as DocsAnalyticsConfig, vt as DocsSearchAdapter, y as DocsAnalyticsEvent, yt as DocsSearchAdapterContext } from "./types-CdKu8KmO.mjs";
-import { i as isDocsCloudAskAIProvider, n as DocsCloudAskAIResponseOptions, r as createDocsCloudAskAIResponse, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-CMzYVzVX.mjs";
+import { $t as McpDocsSearchConfig, At as DocsSearchDocument, C as DocsAgentTraceEventType, D as DocsAnalyticsEventInput, Dt as DocsSearchAdapterFactory, E as DocsAnalyticsEvent, Et as DocsSearchAdapterContext, F as DocsAskAIFeedbackMessage, Ft as DocsSearchSourcePage, I as DocsAskAIFeedbackValue, It as DocsSitemapConfig, L as DocsAskAIMcpConfig, Mt as DocsSearchQuery, N as DocsAskAIFeedbackConfig, Nt as DocsSearchResult, P as DocsAskAIFeedbackData, S as DocsAgentTraceEventInput, T as DocsAnalyticsConfig, Tt as DocsSearchAdapter, Z as DocsConfig, a as ApiReferenceRenderer, b as DocsAgentGoldenTaskExpectation, bt as DocsReviewRulesConfig, ht as DocsObservabilityEventInput, kt as DocsSearchConfig, mt as DocsObservabilityEvent, pt as DocsObservabilityConfig, v as DocsAgentGoldenExpectedExample, vt as DocsReviewCiMode, w as DocsAgentTraceStatus, x as DocsAgentGoldenTaskFilters, y as DocsAgentGoldenTask, yt as DocsReviewConfig } from "./types-R-DN23yw.mjs";
+import { i as isDocsCloudAskAIProvider, n as DocsCloudAskAIResponseOptions, r as createDocsCloudAskAIResponse, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-CvRVnwdK.mjs";
 import { DocsCloudAskAIOptions, DocsCloudPublicConfig, DocsCloudRouteHandlerOptions, DocsCloudRouteHandlers, DocsCloudRuntimeEnv, DocsCloudRuntimeValue, DocsCloudServer, DocsCloudServerOptions, DocsCloudTrackEventOptions, createDocsCloudRouteHandler, createDocsCloudServer } from "./docs-cloud-server.mjs";
-import { $ as createDocsAgentTraceId, A as resolveDocsSitemapRequest, B as normalizePromptProviderName, C as buildDocsSitemapManifest, D as renderDocsSitemapXml, E as renderDocsSitemapMarkdown, F as DEFAULT_PROMPT_PROVIDER_TEMPLATES, G as serializeDocsIconRegistry, H as resolvePromptProviderChoices, I as PromptAction, J as DOCS_AGENT_TRACE_EVENT_TYPES, K as serializeOpenDocsProvider, L as PromptProviderChoice, M as DEFAULT_OPEN_DOCS_PROMPT, N as DEFAULT_OPEN_DOCS_PROVIDER_IDS, O as resolveDocsSitemapConfig, P as DEFAULT_OPEN_DOCS_TARGET, Q as createDocsAgentTraceContext, R as SerializeOpenDocsProviderOptions, S as DocsSitemapResolvedConfig, T as readDocsSitemapManifestFromContentMap, U as sanitizePromptText, V as parsePromptStringArray, W as serializeDocsIcon, X as ResolvedDocsAnalyticsConfig, Y as DocsAgentTraceContext, Z as ResolvedDocsObservabilityConfig, _ as DEFAULT_SITEMAP_XML_ROUTE, a as createMcpSearchAdapter, at as resolveDocsObservabilityConfig, b as DocsSitemapManifestPage, c as formatDocsAskAIPackageHints, d as resolveAskAISearchRequestConfig, et as emitDocsAgentTraceEvent, f as resolveSearchRequestConfig, g as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, h as DEFAULT_SITEMAP_MD_ROUTE, i as createCustomSearchAdapter, it as resolveDocsAnalyticsConfig, j as toDocsSitemapMarkdownUrl, k as resolveDocsSitemapPageLastmod, l as inferDocsAskAIPackageHints, m as DEFAULT_SITEMAP_MD_DOCS_ROUTE, n as buildDocsSearchDocuments, nt as emitDocsObservabilityEvent, o as createSimpleSearchAdapter, p as DEFAULT_SITEMAP_MANIFEST_PATH, q as serializeOpenDocsProviders, r as createAlgoliaSearchAdapter, rt as getDocsRequestAnalyticsProperties, s as createTypesenseSearchAdapter, t as buildDocsAskAIContext, tt as emitDocsAnalyticsEvent, u as performDocsSearch, v as DocsSitemapFormat, w as createDocsSitemapResponse, x as DocsSitemapPageInput, y as DocsSitemapManifest, z as SerializedOpenDocsProvider } from "./search-CTu6Bvq-.mjs";
-import { CreateDocsMcpServerOptions, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DocsMcpAgentContractSummary, DocsMcpCodeExample, DocsMcpConfigSchema, DocsMcpConfigSchemaOption, DocsMcpContextResult, DocsMcpContextSource, DocsMcpDocsList, DocsMcpDocsPageSummary, DocsMcpDocsSection, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpRequestContext, DocsMcpResolvedConfig, DocsMcpResolvedCorsConfig, DocsMcpResolvedSecurityConfig, DocsMcpSource, DocsMcpTaskSummary, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
+import { $ as createDocsAgentTraceId, A as resolveDocsSitemapRequest, B as normalizePromptProviderName, C as buildDocsSitemapManifest, D as renderDocsSitemapXml, E as renderDocsSitemapMarkdown, F as DEFAULT_PROMPT_PROVIDER_TEMPLATES, G as serializeDocsIconRegistry, H as resolvePromptProviderChoices, I as PromptAction, J as DOCS_AGENT_TRACE_EVENT_TYPES, K as serializeOpenDocsProvider, L as PromptProviderChoice, M as DEFAULT_OPEN_DOCS_PROMPT, N as DEFAULT_OPEN_DOCS_PROVIDER_IDS, O as resolveDocsSitemapConfig, P as DEFAULT_OPEN_DOCS_TARGET, Q as createDocsAgentTraceContext, R as SerializeOpenDocsProviderOptions, S as DocsSitemapResolvedConfig, T as readDocsSitemapManifestFromContentMap, U as sanitizePromptText, V as parsePromptStringArray, W as serializeDocsIcon, X as ResolvedDocsAnalyticsConfig, Y as DocsAgentTraceContext, Z as ResolvedDocsObservabilityConfig, _ as DEFAULT_SITEMAP_XML_ROUTE, a as createMcpSearchAdapter, at as resolveDocsObservabilityConfig, b as DocsSitemapManifestPage, c as formatDocsAskAIPackageHints, d as resolveAskAISearchRequestConfig, et as emitDocsAgentTraceEvent, f as resolveSearchRequestConfig, g as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, h as DEFAULT_SITEMAP_MD_ROUTE, i as createCustomSearchAdapter, it as resolveDocsAnalyticsConfig, j as toDocsSitemapMarkdownUrl, k as resolveDocsSitemapPageLastmod, l as inferDocsAskAIPackageHints, m as DEFAULT_SITEMAP_MD_DOCS_ROUTE, n as buildDocsSearchDocuments, nt as emitDocsObservabilityEvent, o as createSimpleSearchAdapter, p as DEFAULT_SITEMAP_MANIFEST_PATH, q as serializeOpenDocsProviders, r as createAlgoliaSearchAdapter, rt as getDocsRequestAnalyticsProperties, s as createTypesenseSearchAdapter, t as buildDocsAskAIContext, tt as emitDocsAnalyticsEvent, u as performDocsSearch, v as DocsSitemapFormat, w as createDocsSitemapResponse, x as DocsSitemapPageInput, y as DocsSitemapManifest, z as SerializedOpenDocsProvider } from "./search-BnQKgDbk.mjs";
+import { CreateDocsMcpServerOptions, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DOCS_CONFIG_SCHEMA_OPTIONS, DocsMcpAgentContractSummary, DocsMcpCodeExample, DocsMcpConfigSchema, DocsMcpConfigSchemaOption, DocsMcpContextResult, DocsMcpContextSource, DocsMcpDocsList, DocsMcpDocsPageSummary, DocsMcpDocsSection, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpRequestContext, DocsMcpResolvedConfig, DocsMcpResolvedCorsConfig, DocsMcpResolvedSecurityConfig, DocsMcpSource, DocsMcpTaskSummary, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
 
 //#region src/code-group-mdx.d.ts
 interface MarkdownNode {
@@ -130,7 +130,110 @@ declare function buildDocsReviewWorkflowPathFilters(options: {
   configContent?: string;
 }): string[];
 //#endregion
+//#region src/agent-evals.d.ts
+type DocsGoldenEvaluationStatus = "unmeasured" | "passed" | "failed";
+type DocsGoldenTaskFilters = DocsAgentGoldenTaskFilters;
+type DocsGoldenExpectedExample = DocsAgentGoldenExpectedExample;
+type DocsGoldenTaskExpectation = DocsAgentGoldenTaskExpectation;
+type DocsGoldenTask = DocsAgentGoldenTask;
+interface DocsGoldenRetrievedSource {
+  rank: number;
+  url: string;
+  title: string;
+  framework?: string;
+  version?: string;
+  utf8Bytes: number;
+  relevant: boolean;
+  truncated: boolean;
+}
+interface DocsGoldenRetrievalMetrics {
+  expectedRelevant: number;
+  retrievedRelevant: number;
+  recallAtK: number;
+  firstRelevantRank: number | null;
+  reciprocalRank: number;
+  forbiddenSources: string[];
+  passed: boolean;
+}
+interface DocsGoldenCitationMetrics {
+  expected: string[];
+  actual: string[];
+  missing: string[];
+  unexpected: string[];
+  precision: number;
+  recall: number;
+  /** True when every rendered Source line maps one-to-one to a returned source record. */
+  integrity: boolean;
+  passed: boolean;
+}
+interface DocsGoldenSelectionMetrics {
+  requestedFramework?: string;
+  requestedVersion?: string;
+  firstFrameworkMatchRank: number | null;
+  firstVersionMatchRank: number | null;
+  conflictingSources: string[];
+  ambiguousSources: string[];
+  passed: boolean;
+}
+interface DocsGoldenExampleResult {
+  expected: DocsGoldenExpectedExample;
+  matchedId?: string;
+  source?: string;
+  executable: boolean;
+  passed: boolean;
+}
+interface DocsGoldenExampleMetrics {
+  expected: number;
+  matched: number;
+  executable: number;
+  results: DocsGoldenExampleResult[];
+  passed: boolean;
+}
+interface DocsGoldenUsageMetrics {
+  budgetUnit: "utf8-bytes";
+  tokenBudget: number;
+  usedUtf8Bytes: number;
+  remainingUtf8Bytes: number;
+  estimatedTokens: number;
+  /** Exact conservative upper bound: one token per UTF-8 byte. */
+  conservativeTokenUpperBound: number;
+  usefulUtf8Bytes: number;
+  usefulByteRatio: number;
+  truncated: boolean;
+  withinBudget: boolean;
+  passed: boolean;
+}
+interface DocsGoldenTaskReport {
+  id: string;
+  query: string;
+  status: "passed" | "failed";
+  passed: boolean;
+  score: number;
+  context: string;
+  sources: DocsGoldenRetrievedSource[];
+  retrieval: DocsGoldenRetrievalMetrics;
+  citations: DocsGoldenCitationMetrics;
+  selection: DocsGoldenSelectionMetrics;
+  examples: DocsGoldenExampleMetrics;
+  usage: DocsGoldenUsageMetrics;
+  issues: string[];
+}
+interface DocsGoldenTasksReport {
+  status: DocsGoldenEvaluationStatus;
+  passed: boolean | null;
+  score: number | null;
+  taskCount: number;
+  passedTaskCount: number;
+  failedTaskCount: number;
+  tasks: DocsGoldenTaskReport[];
+}
+/**
+ * Run deterministic, offline golden-task evaluations against MCP-ready docs pages.
+ * An empty task list is intentionally unmeasured so CI cannot turn absent coverage into a pass.
+ */
+declare function runDocsGoldenTasks(pages: readonly DocsMcpPage[], tasks: readonly DocsGoldenTask[] | undefined): Promise<DocsGoldenTasksReport>;
+//#endregion
 //#region src/sitemap-server.d.ts
 declare function readDocsSitemapManifest(rootDir: string, sitemap?: boolean | DocsSitemapConfig): DocsSitemapManifest | null;
 //#endregion
-export { type ApiReferenceFramework, type ApiReferenceOpenApiDiscovery, type ApiReferenceRenderer, type ApiReferenceRoute, type CreateDocsMcpServerOptions, DEFAULT_API_REFERENCE_OPENAPI_ROUTE, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH, DEFAULT_OPEN_DOCS_PROMPT, DEFAULT_OPEN_DOCS_PROVIDER_IDS, DEFAULT_OPEN_DOCS_TARGET, DEFAULT_PROMPT_PROVIDER_TEMPLATES, DEFAULT_SITEMAP_MANIFEST_PATH, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, DOCS_AGENT_TRACE_EVENT_TYPES, type DocsAgentTraceContext, type DocsAgentTraceEventInput, type DocsAgentTraceEventType, type DocsAgentTraceStatus, type DocsAnalyticsConfig, type DocsAnalyticsEvent, type DocsAnalyticsEventInput, type DocsAskAIFeedbackConfig, type DocsAskAIFeedbackData, type DocsAskAIFeedbackMessage, type DocsAskAIFeedbackValue, type DocsAskAIMcpConfig, type DocsCloudAskAIConfig, type DocsCloudAskAIOptions, type DocsCloudAskAIResponseOptions, type DocsCloudPublicConfig, type DocsCloudRouteHandlerOptions, type DocsCloudRouteHandlers, type DocsCloudRuntimeEnv, type DocsCloudRuntimeValue, type DocsCloudServer, type DocsCloudServerOptions, type DocsCloudTrackEventOptions, type DocsMcpAgentContractSummary, type DocsMcpCodeExample, type DocsMcpConfigSchema, type DocsMcpConfigSchemaOption, type DocsMcpContextResult, type DocsMcpContextSource, type DocsMcpDocsList, type DocsMcpDocsPageSummary, type DocsMcpDocsSection, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpRequestContext, type DocsMcpResolvedConfig, type DocsMcpResolvedCorsConfig, type DocsMcpResolvedSecurityConfig, type DocsMcpSource, type DocsMcpTaskSummary, type DocsObservabilityConfig, type DocsObservabilityEvent, type DocsObservabilityEventInput, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchQuery, type DocsSearchResult, type DocsSearchSourcePage, type DocsSitemapFormat, type DocsSitemapManifest, type DocsSitemapManifestPage, type DocsSitemapPageInput, type DocsSitemapResolvedConfig, type McpDocsSearchConfig, type PromptAction, type PromptProviderChoice, type ResolvedApiReferenceConfig, type ResolvedDocsAnalyticsConfig, type ResolvedDocsObservabilityConfig, type ResolvedDocsReviewConfig, type SerializeOpenDocsProviderOptions, type SerializedOpenDocsProvider, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsAskAIContext, buildDocsReviewWorkflow, buildDocsReviewWorkflowPathFilters, buildDocsSearchDocuments, buildDocsSitemapManifest, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCloudAskAIResponse, createDocsCloudRouteHandler, createDocsCloudServer, createDocsMcpHttpHandler, createDocsMcpServer, createDocsSitemapResponse, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsObservabilityEvent, ensureDocsReviewWorkflow, formatDocsAskAIPackageHints, getDocsRequestAnalyticsProperties, inferDocsAskAIPackageHints, isApiReferenceOpenApiRequest, isDocsCloudAskAIProvider, normalizeDocsMcpRoute, normalizePromptProviderName, parsePromptStringArray, performDocsSearch, readDocsReviewConfigFromSource, readDocsSitemapManifest, readDocsSitemapManifestFromContentMap, remarkCodeGroup, renderDocsSitemapMarkdown, renderDocsSitemapXml, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveApiReferenceRenderer, resolveAskAISearchRequestConfig, resolveDocsAnalyticsConfig, resolveDocsMcpConfig, resolveDocsObservabilityConfig, resolveDocsReviewConfig, resolveDocsSitemapConfig, resolveDocsSitemapPageLastmod, resolveDocsSitemapRequest, resolvePromptProviderChoices, resolveSearchRequestConfig, runDocsMcpStdio, sanitizePromptText, serializeDocsIcon, serializeDocsIconRegistry, serializeOpenDocsProvider, serializeOpenDocsProviders, toDocsSitemapMarkdownUrl };
+export { type ApiReferenceFramework, type ApiReferenceOpenApiDiscovery, type ApiReferenceRenderer, type ApiReferenceRoute, type CreateDocsMcpServerOptions, DEFAULT_API_REFERENCE_OPENAPI_ROUTE, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH, DEFAULT_OPEN_DOCS_PROMPT, DEFAULT_OPEN_DOCS_PROVIDER_IDS, DEFAULT_OPEN_DOCS_TARGET, DEFAULT_PROMPT_PROVIDER_TEMPLATES, DEFAULT_SITEMAP_MANIFEST_PATH, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, DOCS_AGENT_TRACE_EVENT_TYPES, DOCS_CONFIG_SCHEMA_OPTIONS, type DocsAgentTraceContext, type DocsAgentTraceEventInput, type DocsAgentTraceEventType, type DocsAgentTraceStatus, type DocsAnalyticsConfig, type DocsAnalyticsEvent, type DocsAnalyticsEventInput, type DocsAskAIFeedbackConfig, type DocsAskAIFeedbackData, type DocsAskAIFeedbackMessage, type DocsAskAIFeedbackValue, type DocsAskAIMcpConfig, type DocsCloudAskAIConfig, type DocsCloudAskAIOptions, type DocsCloudAskAIResponseOptions, type DocsCloudPublicConfig, type DocsCloudRouteHandlerOptions, type DocsCloudRouteHandlers, type DocsCloudRuntimeEnv, type DocsCloudRuntimeValue, type DocsCloudServer, type DocsCloudServerOptions, type DocsCloudTrackEventOptions, type DocsGoldenCitationMetrics, type DocsGoldenEvaluationStatus, type DocsGoldenExampleMetrics, type DocsGoldenExampleResult, type DocsGoldenExpectedExample, type DocsGoldenRetrievalMetrics, type DocsGoldenRetrievedSource, type DocsGoldenSelectionMetrics, type DocsGoldenTask, type DocsGoldenTaskExpectation, type DocsGoldenTaskFilters, type DocsGoldenTaskReport, type DocsGoldenTasksReport, type DocsGoldenUsageMetrics, type DocsMcpAgentContractSummary, type DocsMcpCodeExample, type DocsMcpConfigSchema, type DocsMcpConfigSchemaOption, type DocsMcpContextResult, type DocsMcpContextSource, type DocsMcpDocsList, type DocsMcpDocsPageSummary, type DocsMcpDocsSection, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpRequestContext, type DocsMcpResolvedConfig, type DocsMcpResolvedCorsConfig, type DocsMcpResolvedSecurityConfig, type DocsMcpSource, type DocsMcpTaskSummary, type DocsObservabilityConfig, type DocsObservabilityEvent, type DocsObservabilityEventInput, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchQuery, type DocsSearchResult, type DocsSearchSourcePage, type DocsSitemapFormat, type DocsSitemapManifest, type DocsSitemapManifestPage, type DocsSitemapPageInput, type DocsSitemapResolvedConfig, type McpDocsSearchConfig, type PromptAction, type PromptProviderChoice, type ResolvedApiReferenceConfig, type ResolvedDocsAnalyticsConfig, type ResolvedDocsObservabilityConfig, type ResolvedDocsReviewConfig, type SerializeOpenDocsProviderOptions, type SerializedOpenDocsProvider, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsAskAIContext, buildDocsReviewWorkflow, buildDocsReviewWorkflowPathFilters, buildDocsSearchDocuments, buildDocsSitemapManifest, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCloudAskAIResponse, createDocsCloudRouteHandler, createDocsCloudServer, createDocsMcpHttpHandler, createDocsMcpServer, createDocsSitemapResponse, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsObservabilityEvent, ensureDocsReviewWorkflow, formatDocsAskAIPackageHints, getDocsConfigSchema, getDocsRequestAnalyticsProperties, inferDocsAskAIPackageHints, isApiReferenceOpenApiRequest, isDocsCloudAskAIProvider, normalizeDocsMcpRoute, normalizePromptProviderName, parsePromptStringArray, performDocsSearch, readDocsReviewConfigFromSource, readDocsSitemapManifest, readDocsSitemapManifestFromContentMap, remarkCodeGroup, renderDocsSitemapMarkdown, renderDocsSitemapXml, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveApiReferenceRenderer, resolveAskAISearchRequestConfig, resolveDocsAnalyticsConfig, resolveDocsMcpConfig, resolveDocsObservabilityConfig, resolveDocsReviewConfig, resolveDocsSitemapConfig, resolveDocsSitemapPageLastmod, resolveDocsSitemapRequest, resolvePromptProviderChoices, resolveSearchRequestConfig, runDocsGoldenTasks, runDocsMcpStdio, sanitizePromptText, serializeDocsIcon, serializeDocsIconRegistry, serializeOpenDocsProvider, serializeOpenDocsProviders, toDocsSitemapMarkdownUrl };