@farming-labs/docs 0.2.59 → 0.2.61

package/dist/mcp.mjs

@@ -1,7 +1,8 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { Ot as resolveDocsAudienceMdxContent, Sn as upsertPageAgentContractMarkdown, _n as hasStructuredPageAgentContract, ln as normalizeDocsRelated, un as renderDocsRelatedMarkdownLines, vn as normalizePageAgentFrontmatter } from "./agent-BFqyqEnC.mjs";
-import { C as resolvePageSidebarFolderIndexBehavior, E as emitDocsTelemetryAgentSurfaceEvent, O as emitDocsTelemetryMcpToolEvent, k as emitDocsTelemetryProjectEvent, m as parseDocsMarkdownSections, p as findDocsMarkdownSection, u as performDocsSearch, x as stripGeneratedAgentProvenance } from "./search-D57JXQLj.mjs";
-import { a as normalizeAgentScopeValues, i as normalizeAgentLocale, n as agentVersionConstraintsOverlap, r as normalizeAgentFramework, t as agentVersionConstraintMatches } from "./agent-scope-CCaIY1aK.mjs";
+import { Bt as renderDocsRelatedMarkdownLines, Jt as normalizePageAgentFrontmatter, Qt as upsertPageAgentContractMarkdown, cn as isDocsMcpProtectedResourceMetadataPath, dn as normalizeDocsMcpAuthorizationServerUrls, fn as normalizeDocsMcpEndpointPath, mn as resolveDocsMcpResourceLocation, pn as resolveDocsMcpProtectedResourceMetadataLocation, qt as hasStructuredPageAgentContract, sn as isDocsMcpOAuthScopeToken, un as isDocsMcpResourcePath, wt as resolveDocsAudienceMdxContent, zt as normalizeDocsRelated } from "./agent-Fl0pjVNF.mjs";
+import "./standards-discovery-C54V_aJH.mjs";
+import { C as resolvePageSidebarFolderIndexBehavior, E as emitDocsTelemetryAgentSurfaceEvent, O as emitDocsTelemetryMcpToolEvent, k as emitDocsTelemetryProjectEvent, m as parseDocsMarkdownSections, p as findDocsMarkdownSection, u as performDocsSearch, x as stripGeneratedAgentProvenance } from "./search-9OnMGMvt.mjs";
+import { a as normalizeAgentScopeValues, i as normalizeAgentLocale, n as agentVersionConstraintsOverlap, r as normalizeAgentFramework, t as agentVersionConstraintMatches } from "./agent-scope-C_U--OZ7.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -12,7 +13,6 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod/v4";
 
 //#region src/mcp.ts
-const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
 const DEFAULT_MCP_VERSION = "0.0.0";
 const DEFAULT_MCP_NAME = "@farming-labs/docs";
 const DEFAULT_MCP_CONTEXT_TOKEN_BUDGET = 4e3;
@@ -222,405 +222,490 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		type: "DocsAgentConfig",
 		description: "Agent compaction defaults and offline-by-default usefulness evaluations.",
 		docs: "/docs/getting-started/agent-ready-docs",
-		children: [{
-			path: "agent.compact",
-			name: "compact",
-			type: "DocsAgentCompactConfig",
-			description: "Defaults for generated agent.md compaction.",
-			children: [
-				{
-					path: "agent.compact.apiKey",
-					name: "apiKey",
-					type: "string",
-					description: "Direct compaction provider API key; prefer apiKeyEnv."
-				},
-				{
-					path: "agent.compact.apiKeyEnv",
-					name: "apiKeyEnv",
-					type: "string",
-					description: "Environment variable containing the compaction provider API key."
-				},
-				{
-					path: "agent.compact.baseUrl",
-					name: "baseUrl",
-					type: "string",
-					description: "Compaction provider base URL."
-				},
-				{
-					path: "agent.compact.model",
-					name: "model",
+		children: [
+			{
+				path: "agent.skills",
+				name: "skills",
+				type: "string | readonly string[] | DocsAgentSkillsConfig",
+				description: "Project skill files or collection directories published through discovery, static export, and MCP.",
+				children: [{
+					path: "agent.skills.paths",
+					name: "paths",
+					type: "string | readonly string[]",
+					description: "Workspace-contained SKILL.md file, skill directory, or collection directory paths."
+				}, {
+					path: "agent.skills.paths[]",
+					name: "path",
 					type: "string",
-					description: "Compaction model identifier."
-				},
-				{
-					path: "agent.compact.aggressiveness",
-					name: "aggressiveness",
-					type: "number",
-					default: .3,
-					description: "Compression aggressiveness from 0 to 1."
-				},
-				{
-					path: "agent.compact.maxOutputTokens",
-					name: "maxOutputTokens",
-					type: "number",
-					description: "Upper output token target."
-				},
-				{
-					path: "agent.compact.minOutputTokens",
-					name: "minOutputTokens",
-					type: "number",
-					description: "Lower output token target."
-				},
-				{
-					path: "agent.compact.protectJson",
-					name: "protectJson",
-					type: "boolean",
-					description: "Preserve JSON objects during compaction when supported."
-				}
-			]
-		}, {
-			path: "agent.evaluations",
-			name: "evaluations",
-			type: "boolean | DocsAgentEvaluationsConfig",
-			description: "Offline-by-default golden tasks for retrieval, citation, version, example, answer, and budget evaluation, with explicit external-provider and execution opt-ins.",
-			children: [
-				{
-					path: "agent.evaluations.enabled",
-					name: "enabled",
-					type: "boolean",
-					default: true,
-					description: "Enable configured golden-task evaluation."
-				},
-				{
-					path: "agent.evaluations.tokenBudget",
-					name: "tokenBudget",
-					type: "number",
-					default: 4e3,
-					description: "Default hard UTF-8 context-byte ceiling for golden tasks."
-				},
-				{
-					path: "agent.evaluations.topK",
-					name: "topK",
-					type: "number",
-					default: 5,
-					description: "Default number of ranked search results evaluated per task."
-				},
-				{
-					path: "agent.evaluations.surface",
-					name: "surface",
-					type: "\"mcp-context\" | \"configured-search\" | \"ask-ai-context\"",
-					default: "mcp-context",
-					description: "Retrieval/context surface measured by the golden task suite."
-				},
-				{
-					path: "agent.evaluations.allowNetwork",
-					name: "allowNetwork",
-					type: "boolean",
-					default: false,
-					description: "Allow external search, HTTP answers, and explicit executable-example verification during evaluation."
-				},
-				{
-					path: "agent.evaluations.searchTimeoutMs",
-					name: "searchTimeoutMs",
-					type: "number",
-					default: 3e4,
-					description: "Per-task configured search and Ask AI retrieval timeout in milliseconds."
-				},
-				{
-					path: "agent.evaluations.answer",
-					name: "answer",
-					type: "DocsAgentEvaluationAnswerProvider",
-					description: "Opt-in callback or HTTP provider used to evaluate actual generated answers and citations.",
-					children: [
-						{
-							path: "agent.evaluations.answer.provider",
-							name: "provider",
-							type: "\"callback\" | \"http\"",
-							description: "Answer evaluation provider kind."
-						},
-						{
-							path: "agent.evaluations.answer.run",
-							name: "run",
-							type: "DocsAgentEvaluationAnswerRunner",
-							description: "Callback invoked with retrieved context and source references."
-						},
-						{
-							path: "agent.evaluations.answer.endpoint",
-							name: "endpoint",
-							type: "string",
-							description: "HTTP endpoint used by the opt-in HTTP answer provider."
-						},
-						{
-							path: "agent.evaluations.answer.headers",
-							name: "headers",
-							type: "Record<string, string>",
-							description: "Optional HTTP request headers; values are never reported.",
-							children: [{
-								path: "agent.evaluations.answer.headers.*",
-								name: "header",
+					description: "One workspace-contained Agent Skill path."
+				}]
+			},
+			{
+				path: "agent.a2a",
+				name: "a2a",
+				type: "DocsAgentA2AConfig",
+				description: "Opt-in Agent Card metadata for a separately implemented real A2A service.",
+				children: [
+					{
+						path: "agent.a2a.interfaceUrl",
+						name: "interfaceUrl",
+						type: "string",
+						description: "HTTP(S) URL of the real A2A interface."
+					},
+					{
+						path: "agent.a2a.name",
+						name: "name",
+						type: "string",
+						description: "Public A2A agent name."
+					},
+					{
+						path: "agent.a2a.description",
+						name: "description",
+						type: "string",
+						description: "Public A2A agent description."
+					},
+					{
+						path: "agent.a2a.documentationUrl",
+						name: "documentationUrl",
+						type: "string",
+						description: "HTTP(S) documentation URL for the A2A service."
+					},
+					{
+						path: "agent.a2a.provider.organization",
+						name: "organization",
+						type: "string",
+						description: "A2A service provider organization."
+					},
+					{
+						path: "agent.a2a.provider.url",
+						name: "url",
+						type: "string",
+						description: "HTTP(S) provider URL."
+					},
+					{
+						path: "agent.a2a.version",
+						name: "version",
+						type: "string",
+						default: "1.0.0",
+						description: "A2A service version advertised by the card."
+					},
+					{
+						path: "agent.a2a.protocolVersion",
+						name: "protocolVersion",
+						type: "string",
+						default: "0.3",
+						description: "A2A protocol version implemented by the configured interface."
+					},
+					{
+						path: "agent.a2a.protocolBinding",
+						name: "protocolBinding",
+						type: "string",
+						default: "HTTP+JSON",
+						description: "A2A transport binding implemented by the configured interface."
+					}
+				]
+			},
+			{
+				path: "agent.compact",
+				name: "compact",
+				type: "DocsAgentCompactConfig",
+				description: "Defaults for generated agent.md compaction.",
+				children: [
+					{
+						path: "agent.compact.apiKey",
+						name: "apiKey",
+						type: "string",
+						description: "Direct compaction provider API key; prefer apiKeyEnv."
+					},
+					{
+						path: "agent.compact.apiKeyEnv",
+						name: "apiKeyEnv",
+						type: "string",
+						description: "Environment variable containing the compaction provider API key."
+					},
+					{
+						path: "agent.compact.baseUrl",
+						name: "baseUrl",
+						type: "string",
+						description: "Compaction provider base URL."
+					},
+					{
+						path: "agent.compact.model",
+						name: "model",
+						type: "string",
+						description: "Compaction model identifier."
+					},
+					{
+						path: "agent.compact.aggressiveness",
+						name: "aggressiveness",
+						type: "number",
+						default: .3,
+						description: "Compression aggressiveness from 0 to 1."
+					},
+					{
+						path: "agent.compact.maxOutputTokens",
+						name: "maxOutputTokens",
+						type: "number",
+						description: "Upper output token target."
+					},
+					{
+						path: "agent.compact.minOutputTokens",
+						name: "minOutputTokens",
+						type: "number",
+						description: "Lower output token target."
+					},
+					{
+						path: "agent.compact.protectJson",
+						name: "protectJson",
+						type: "boolean",
+						description: "Preserve JSON objects during compaction when supported."
+					}
+				]
+			},
+			{
+				path: "agent.evaluations",
+				name: "evaluations",
+				type: "boolean | DocsAgentEvaluationsConfig",
+				description: "Offline-by-default golden tasks for retrieval, citation, version, example, answer, and budget evaluation, with explicit external-provider and execution opt-ins.",
+				children: [
+					{
+						path: "agent.evaluations.enabled",
+						name: "enabled",
+						type: "boolean",
+						default: true,
+						description: "Enable configured golden-task evaluation."
+					},
+					{
+						path: "agent.evaluations.tokenBudget",
+						name: "tokenBudget",
+						type: "number",
+						default: 4e3,
+						description: "Default hard UTF-8 context-byte ceiling for golden tasks."
+					},
+					{
+						path: "agent.evaluations.topK",
+						name: "topK",
+						type: "number",
+						default: 5,
+						description: "Default number of ranked search results evaluated per task."
+					},
+					{
+						path: "agent.evaluations.surface",
+						name: "surface",
+						type: "\"mcp-context\" | \"configured-search\" | \"ask-ai-context\"",
+						default: "mcp-context",
+						description: "Retrieval/context surface measured by the golden task suite."
+					},
+					{
+						path: "agent.evaluations.allowNetwork",
+						name: "allowNetwork",
+						type: "boolean",
+						default: false,
+						description: "Allow external search, HTTP answers, and explicit executable-example verification during evaluation."
+					},
+					{
+						path: "agent.evaluations.searchTimeoutMs",
+						name: "searchTimeoutMs",
+						type: "number",
+						default: 3e4,
+						description: "Per-task configured search and Ask AI retrieval timeout in milliseconds."
+					},
+					{
+						path: "agent.evaluations.answer",
+						name: "answer",
+						type: "DocsAgentEvaluationAnswerProvider",
+						description: "Opt-in callback or HTTP provider used to evaluate actual generated answers and citations.",
+						children: [
+							{
+								path: "agent.evaluations.answer.provider",
+								name: "provider",
+								type: "\"callback\" | \"http\"",
+								description: "Answer evaluation provider kind."
+							},
+							{
+								path: "agent.evaluations.answer.run",
+								name: "run",
+								type: "DocsAgentEvaluationAnswerRunner",
+								description: "Callback invoked with retrieved context and source references."
+							},
+							{
+								path: "agent.evaluations.answer.endpoint",
+								name: "endpoint",
 								type: "string",
-								description: "One custom HTTP header value."
-							}]
-						},
-						{
-							path: "agent.evaluations.answer.timeoutMs",
-							name: "timeoutMs",
-							type: "number",
-							default: 3e4,
-							description: "Callback or HTTP answer provider timeout in milliseconds."
-						}
-					]
-				},
-				{
-					path: "agent.evaluations.tasks",
-					name: "tasks",
-					type: "DocsAgentGoldenTask[]",
-					description: "Golden task fixtures evaluated by docs doctor and docs review; the default MCP context surface runs offline.",
-					children: [
-						{
-							path: "agent.evaluations.tasks[]",
-							name: "task",
-							type: "DocsAgentGoldenTask",
-							description: "One golden task entry."
-						},
-						{
-							path: "agent.evaluations.tasks[].id",
-							name: "id",
-							type: "string",
-							description: "Stable task identifier shown in diagnostics."
-						},
-						{
-							path: "agent.evaluations.tasks[].query",
-							name: "query",
-							type: "string",
-							description: "User-shaped retrieval query."
-						},
-						{
-							path: "agent.evaluations.tasks[].tokenBudget",
-							name: "tokenBudget",
-							type: "number",
-							description: "Per-task UTF-8 context-byte ceiling override."
-						},
-						{
-							path: "agent.evaluations.tasks[].topK",
-							name: "topK",
-							type: "number",
-							description: "Per-task ranked retrieval depth override."
-						},
-						{
-							path: "agent.evaluations.tasks[].surface",
-							name: "surface",
-							type: "\"mcp-context\" | \"configured-search\" | \"ask-ai-context\"",
-							description: "Per-task evaluation surface override."
-						},
-						{
-							path: "agent.evaluations.tasks[].filters",
-							name: "filters",
-							type: "DocsAgentGoldenTaskFilters",
-							description: "Framework, version, and locale retrieval scope.",
-							children: [
-								{
-									path: "agent.evaluations.tasks[].filters.framework",
-									name: "framework",
-									type: "string",
-									description: "Required framework, such as nextjs or astro."
-								},
-								{
-									path: "agent.evaluations.tasks[].filters.version",
-									name: "version",
-									type: "string",
-									description: "Exact version requested by the task."
-								},
-								{
-									path: "agent.evaluations.tasks[].filters.locale",
-									name: "locale",
+								description: "HTTP endpoint used by the opt-in HTTP answer provider."
+							},
+							{
+								path: "agent.evaluations.answer.headers",
+								name: "headers",
+								type: "Record<string, string>",
+								description: "Optional HTTP request headers; values are never reported.",
+								children: [{
+									path: "agent.evaluations.answer.headers.*",
+									name: "header",
 									type: "string",
-									description: "Required locale."
-								}
-							]
-						},
-						{
-							path: "agent.evaluations.tasks[].expect",
-							name: "expect",
-							type: "DocsAgentGoldenTaskExpectation",
-							description: "Evaluator-only source, rank, citation, scope, answer, example, and budget expectations.",
-							children: [
-								{
-									path: "agent.evaluations.tasks[].expect.relevantSources",
-									name: "relevantSources",
-									type: "string[]",
-									description: "Canonical page or section URLs that should answer the task."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.allowedSources",
-									name: "allowedSources",
-									type: "string[]",
-									description: "Additional legitimate citations that do not reduce precision."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.forbiddenSources",
-									name: "forbiddenSources",
-									type: "string[]",
-									description: "Sources that must not be retrieved or cited."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.requiredCitations",
-									name: "requiredCitations",
-									type: "string[]",
-									description: "Citations that must appear; defaults to relevantSources."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.minRecallAtK",
-									name: "minRecallAtK",
-									type: "number",
-									default: 1,
-									description: "Minimum relevant-source recall in the top K results."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.maxFirstRelevantRank",
-									name: "maxFirstRelevantRank",
-									type: "number",
-									description: "Maximum acceptable rank of the first relevant source."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.minUsefulByteRatio",
-									name: "minUsefulByteRatio",
-									type: "number",
-									description: "Minimum share of context bytes supplied by relevant sources."
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.scope",
-									name: "scope",
-									type: "DocsAgentGoldenTaskFilters",
-									description: "Framework, version, and locale assertions checked against returned sources without pre-filtering retrieval.",
-									children: [
-										{
-											path: "agent.evaluations.tasks[].expect.scope.framework",
-											name: "framework",
-											type: "string",
-											description: "Framework the returned sources must select."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.scope.version",
-											name: "version",
-											type: "string",
-											description: "Version the returned sources must select."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.scope.locale",
-											name: "locale",
-											type: "string",
-											description: "Locale the returned sources must select."
-										}
-									]
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.answer",
-									name: "answer",
-									type: "DocsAgentGoldenAnswerExpectation",
-									description: "Required answer text and citation assertions for an explicitly configured answer provider.",
-									children: [
-										{
-											path: "agent.evaluations.tasks[].expect.answer.includes",
-											name: "includes",
-											type: "string[]",
-											description: "Literal fragments required in the actual answer."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.answer.excludes",
-											name: "excludes",
-											type: "string[]",
-											description: "Literal fragments forbidden in the actual answer."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.answer.requiredCitations",
-											name: "requiredCitations",
-											type: "string[]",
-											description: "Citations required in the actual answer."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.answer.allowedCitations",
-											name: "allowedCitations",
-											type: "string[]",
-											description: "Additional valid actual-answer citations."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.answer.forbiddenCitations",
-											name: "forbiddenCitations",
-											type: "string[]",
-											description: "Citations forbidden in the actual answer."
-										}
-									]
-								},
-								{
-									path: "agent.evaluations.tasks[].expect.examples",
-									name: "examples",
-									type: "DocsAgentGoldenExpectedExample[]",
-									description: "Runnable examples that must be present in returned context.",
-									children: [
-										{
-											path: "agent.evaluations.tasks[].expect.examples[]",
-											name: "example",
-											type: "DocsAgentGoldenExpectedExample",
-											description: "One expected code example."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].source",
-											name: "source",
-											type: "string",
-											description: "Canonical source URL containing the example."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].language",
-											name: "language",
-											type: "string",
-											description: "Expected code-fence language."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].framework",
-											name: "framework",
-											type: "string",
-											description: "Expected framework metadata."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].packageManager",
-											name: "packageManager",
-											type: "string",
-											description: "Expected package-manager metadata."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].title",
-											name: "title",
-											type: "string",
-											description: "Expected code-fence title metadata."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].runnable",
-											name: "runnable",
-											type: "boolean",
-											default: true,
-											description: "Whether the example must be marked runnable."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].includes",
-											name: "includes",
-											type: "string[]",
-											description: "Literal code fragments that must appear."
-										},
-										{
-											path: "agent.evaluations.tasks[].expect.examples[].verification",
-											name: "verification",
-											type: "\"present\" | \"syntax\" | \"execute\"",
-											description: "Required verification strength; defaults to present when runnable is false and syntax otherwise. Runtime execution is always explicit."
-										}
-									]
-								}
-							]
-						}
-					]
-				}
-			]
-		}]
+									description: "One custom HTTP header value."
+								}]
+							},
+							{
+								path: "agent.evaluations.answer.timeoutMs",
+								name: "timeoutMs",
+								type: "number",
+								default: 3e4,
+								description: "Callback or HTTP answer provider timeout in milliseconds."
+							}
+						]
+					},
+					{
+						path: "agent.evaluations.tasks",
+						name: "tasks",
+						type: "DocsAgentGoldenTask[]",
+						description: "Golden task fixtures evaluated by docs doctor and docs review; the default MCP context surface runs offline.",
+						children: [
+							{
+								path: "agent.evaluations.tasks[]",
+								name: "task",
+								type: "DocsAgentGoldenTask",
+								description: "One golden task entry."
+							},
+							{
+								path: "agent.evaluations.tasks[].id",
+								name: "id",
+								type: "string",
+								description: "Stable task identifier shown in diagnostics."
+							},
+							{
+								path: "agent.evaluations.tasks[].query",
+								name: "query",
+								type: "string",
+								description: "User-shaped retrieval query."
+							},
+							{
+								path: "agent.evaluations.tasks[].tokenBudget",
+								name: "tokenBudget",
+								type: "number",
+								description: "Per-task UTF-8 context-byte ceiling override."
+							},
+							{
+								path: "agent.evaluations.tasks[].topK",
+								name: "topK",
+								type: "number",
+								description: "Per-task ranked retrieval depth override."
+							},
+							{
+								path: "agent.evaluations.tasks[].surface",
+								name: "surface",
+								type: "\"mcp-context\" | \"configured-search\" | \"ask-ai-context\"",
+								description: "Per-task evaluation surface override."
+							},
+							{
+								path: "agent.evaluations.tasks[].filters",
+								name: "filters",
+								type: "DocsAgentGoldenTaskFilters",
+								description: "Framework, version, and locale retrieval scope.",
+								children: [
+									{
+										path: "agent.evaluations.tasks[].filters.framework",
+										name: "framework",
+										type: "string",
+										description: "Required framework, such as nextjs or astro."
+									},
+									{
+										path: "agent.evaluations.tasks[].filters.version",
+										name: "version",
+										type: "string",
+										description: "Exact version requested by the task."
+									},
+									{
+										path: "agent.evaluations.tasks[].filters.locale",
+										name: "locale",
+										type: "string",
+										description: "Required locale."
+									}
+								]
+							},
+							{
+								path: "agent.evaluations.tasks[].expect",
+								name: "expect",
+								type: "DocsAgentGoldenTaskExpectation",
+								description: "Evaluator-only source, rank, citation, scope, answer, example, and budget expectations.",
+								children: [
+									{
+										path: "agent.evaluations.tasks[].expect.relevantSources",
+										name: "relevantSources",
+										type: "string[]",
+										description: "Canonical page or section URLs that should answer the task."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.allowedSources",
+										name: "allowedSources",
+										type: "string[]",
+										description: "Additional legitimate citations that do not reduce precision."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.forbiddenSources",
+										name: "forbiddenSources",
+										type: "string[]",
+										description: "Sources that must not be retrieved or cited."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.requiredCitations",
+										name: "requiredCitations",
+										type: "string[]",
+										description: "Citations that must appear; defaults to relevantSources."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.minRecallAtK",
+										name: "minRecallAtK",
+										type: "number",
+										default: 1,
+										description: "Minimum relevant-source recall in the top K results."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.maxFirstRelevantRank",
+										name: "maxFirstRelevantRank",
+										type: "number",
+										description: "Maximum acceptable rank of the first relevant source."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.minUsefulByteRatio",
+										name: "minUsefulByteRatio",
+										type: "number",
+										description: "Minimum share of context bytes supplied by relevant sources."
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.scope",
+										name: "scope",
+										type: "DocsAgentGoldenTaskFilters",
+										description: "Framework, version, and locale assertions checked against returned sources without pre-filtering retrieval.",
+										children: [
+											{
+												path: "agent.evaluations.tasks[].expect.scope.framework",
+												name: "framework",
+												type: "string",
+												description: "Framework the returned sources must select."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.scope.version",
+												name: "version",
+												type: "string",
+												description: "Version the returned sources must select."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.scope.locale",
+												name: "locale",
+												type: "string",
+												description: "Locale the returned sources must select."
+											}
+										]
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.answer",
+										name: "answer",
+										type: "DocsAgentGoldenAnswerExpectation",
+										description: "Required answer text and citation assertions for an explicitly configured answer provider.",
+										children: [
+											{
+												path: "agent.evaluations.tasks[].expect.answer.includes",
+												name: "includes",
+												type: "string[]",
+												description: "Literal fragments required in the actual answer."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.answer.excludes",
+												name: "excludes",
+												type: "string[]",
+												description: "Literal fragments forbidden in the actual answer."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.answer.requiredCitations",
+												name: "requiredCitations",
+												type: "string[]",
+												description: "Citations required in the actual answer."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.answer.allowedCitations",
+												name: "allowedCitations",
+												type: "string[]",
+												description: "Additional valid actual-answer citations."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.answer.forbiddenCitations",
+												name: "forbiddenCitations",
+												type: "string[]",
+												description: "Citations forbidden in the actual answer."
+											}
+										]
+									},
+									{
+										path: "agent.evaluations.tasks[].expect.examples",
+										name: "examples",
+										type: "DocsAgentGoldenExpectedExample[]",
+										description: "Runnable examples that must be present in returned context.",
+										children: [
+											{
+												path: "agent.evaluations.tasks[].expect.examples[]",
+												name: "example",
+												type: "DocsAgentGoldenExpectedExample",
+												description: "One expected code example."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].source",
+												name: "source",
+												type: "string",
+												description: "Canonical source URL containing the example."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].language",
+												name: "language",
+												type: "string",
+												description: "Expected code-fence language."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].framework",
+												name: "framework",
+												type: "string",
+												description: "Expected framework metadata."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].packageManager",
+												name: "packageManager",
+												type: "string",
+												description: "Expected package-manager metadata."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].title",
+												name: "title",
+												type: "string",
+												description: "Expected code-fence title metadata."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].runnable",
+												name: "runnable",
+												type: "boolean",
+												default: true,
+												description: "Whether the example must be marked runnable."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].includes",
+												name: "includes",
+												type: "string[]",
+												description: "Literal code fragments that must appear."
+											},
+											{
+												path: "agent.evaluations.tasks[].expect.examples[].verification",
+												name: "verification",
+												type: "\"present\" | \"syntax\" | \"execute\"",
+												description: "Required verification strength; defaults to present when runnable is false and syntax otherwise. Runtime execution is always explicit."
+											}
+										]
+									}
+								]
+							}
+						]
+					}
+				]
+			}
+		]
 	},
 	{
 		path: "review",
@@ -966,6 +1051,45 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 						default: "public (callback omitted)",
 						description: "Opt-in HTTP authentication callback. Return a principal to continue, null for 401, or a Response to control the rejection."
 					},
+					{
+						path: "mcp.security.protectedResource",
+						name: "protectedResource",
+						type: "DocsMcpProtectedResourceConfig",
+						description: "Opt-in RFC 9728 OAuth protected-resource metadata and endpoint-wide scope enforcement. Active only with authenticate.",
+						children: [
+							{
+								path: "mcp.security.protectedResource.authorizationServers",
+								name: "authorizationServers",
+								type: "string[]",
+								description: "One or more HTTPS OAuth issuer URLs without query or fragment; loopback HTTP is accepted for development."
+							},
+							{
+								path: "mcp.security.protectedResource.scopesSupported",
+								name: "scopesSupported",
+								type: "string[]",
+								description: "OAuth scopes advertised through RFC 9728 scopes_supported metadata."
+							},
+							{
+								path: "mcp.security.protectedResource.requiredScopes",
+								name: "requiredScopes",
+								type: "string[]",
+								description: "Scopes required on every principal returned by authenticate; missing scopes receive a challenged 403."
+							},
+							{
+								path: "mcp.security.protectedResource.resourceName",
+								name: "resourceName",
+								type: "string",
+								default: "resolved MCP server name",
+								description: "Human-readable protected-resource name shown during authorization."
+							},
+							{
+								path: "mcp.security.protectedResource.resourceDocumentation",
+								name: "resourceDocumentation",
+								type: "string",
+								description: "Absolute HTTP(S) URL with human-readable authentication guidance."
+							}
+						]
+					},
 					{
 						path: "mcp.security.maxBodyBytes",
 						name: "maxBodyBytes",
@@ -1199,13 +1323,18 @@ export default defineDocs({
 });`
 	},
 	{
-		title: "Opt-in MCP authentication",
+		title: "Opt-in OAuth MCP authentication",
 		code: `export default defineDocs({
   mcp: {
     security: {
+      protectedResource: {
+        authorizationServers: ["https://auth.example.com"],
+        scopesSupported: ["docs:read"],
+        requiredScopes: ["docs:read"],
+      },
       async authenticate({ request }) {
         const user = await authenticateRequest(request);
-        return user ? { id: user.id, scopes: ["docs:read"] } : null;
+        return user ? { id: user.id, scopes: user.scopes } : null;
       },
     },
   },
@@ -1519,9 +1648,7 @@ const contextOutputSchema = z.object({
 	sources: z.array(contextSourceOutputSchema)
 });
 function normalizeDocsMcpRoute(route) {
-	if (!route || route.trim().length === 0) return DEFAULT_MCP_ROUTE;
-	const normalized = `/${route}`.replace(/\/+/g, "/");
-	return normalized !== "/" ? normalized.replace(/\/+$/, "") : DEFAULT_MCP_ROUTE;
+	return normalizeDocsMcpEndpointPath(route);
 }
 function resolveDocsMcpConfig(mcp, defaults = {}) {
 	if (mcp === false) return {
@@ -1570,10 +1697,52 @@ function resolveDocsMcpSecurityConfig(security) {
 	return {
 		allowedOrigins: security?.allowedOrigins ?? "same-origin",
 		authenticate: security?.authenticate,
+		protectedResource: resolveDocsMcpProtectedResourceConfig(security?.protectedResource),
 		maxBodyBytes,
 		cors: resolveDocsMcpCorsConfig(security?.cors)
 	};
 }
+function resolveDocsMcpProtectedResourceConfig(config) {
+	if (!config || typeof config !== "object") return void 0;
+	const configuredAuthorizationServers = config.authorizationServers;
+	if (!Array.isArray(configuredAuthorizationServers) || configuredAuthorizationServers.length === 0 || configuredAuthorizationServers.some((value) => typeof value !== "string" || value.trim().length === 0)) throw new TypeError("mcp.security.protectedResource.authorizationServers must contain at least one authorization server issuer URL.");
+	const authorizationServerCandidates = normalizeMcpStringList(configuredAuthorizationServers);
+	const authorizationServers = normalizeDocsMcpAuthorizationServerUrls(authorizationServerCandidates);
+	if (authorizationServers.length !== authorizationServerCandidates.length) throw new TypeError("mcp.security.protectedResource.authorizationServers must use HTTPS issuer URLs without query strings or fragments; HTTP is allowed only for loopback development.");
+	const resourceName = normalizeMcpOptionalString(config.resourceName);
+	const resourceDocumentation = normalizeMcpOptionalHttpUrl(config.resourceDocumentation);
+	if (config.resourceDocumentation !== void 0 && !resourceDocumentation) throw new TypeError("mcp.security.protectedResource.resourceDocumentation must be an absolute HTTP or HTTPS URL.");
+	return {
+		authorizationServers,
+		scopesSupported: normalizeMcpScopeList(config.scopesSupported, "mcp.security.protectedResource.scopesSupported"),
+		requiredScopes: normalizeMcpScopeList(config.requiredScopes, "mcp.security.protectedResource.requiredScopes"),
+		...resourceName ? { resourceName } : {},
+		...resourceDocumentation ? { resourceDocumentation } : {}
+	};
+}
+function normalizeMcpStringList(values) {
+	if (!Array.isArray(values)) return [];
+	return Array.from(new Set(values.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean)));
+}
+function normalizeMcpScopeList(values, path) {
+	if (values === void 0) return [];
+	if (!Array.isArray(values) || values.some((value) => typeof value !== "string" || !isDocsMcpOAuthScopeToken(value.trim()))) throw new TypeError(`${path} must contain valid OAuth scope tokens.`);
+	return normalizeMcpStringList(values);
+}
+function normalizeMcpOptionalString(value) {
+	if (typeof value !== "string") return void 0;
+	return value.trim() || void 0;
+}
+function normalizeMcpOptionalHttpUrl(value) {
+	const normalized = normalizeMcpOptionalString(value);
+	if (!normalized) return void 0;
+	try {
+		const url = new URL(normalized);
+		return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password ? normalized : void 0;
+	} catch {
+		return;
+	}
+}
 function resolveDocsMcpCorsConfig(cors) {
 	const config = cors && typeof cors === "object" ? cors : {};
 	const configuredMaxAge = config.maxAgeSeconds;
@@ -1661,6 +1830,9 @@ async function createDocsMcpServer(options) {
 	function getSourceNavigation(locale) {
 		return options.source.getNavigation(locale, options.requestContext);
 	}
+	function getSourceSkills() {
+		return options.source.getSkills?.(options.requestContext) ?? [];
+	}
 	function trackMcpTool(tool, values) {
 		emitDocsTelemetryMcpToolEvent(telemetryConfig, {
 			framework: telemetryFramework,
@@ -1672,6 +1844,7 @@ async function createDocsMcpServer(options) {
 	}
 	const defaultPages = dedupePages(await getSourcePages());
 	const defaultTree = await getSourceNavigation();
+	const defaultSkills = await getSourceSkills();
 	server.registerResource("docs-navigation", "docs://navigation", {
 		title: "Docs Navigation",
 		description: "Structured navigation tree for the documentation site.",
@@ -1693,6 +1866,23 @@ async function createDocsMcpServer(options) {
 			text: renderPageDocument(page)
 		}] }));
 	}
+	for (const skill of defaultSkills) for (const file of skill.files) {
+		const encodedPath = file.path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+		const resourceUri = `docs://skills/${encodeURIComponent(skill.name)}/${encodedPath}`;
+		server.registerResource(`skill-${encodeURIComponent(skill.name)}-${Buffer.from(file.path).toString("base64url")}`, resourceUri, {
+			title: `${skill.name}: ${file.path}`,
+			description: `${skill.description} (${file.digest})`,
+			mimeType: file.mediaType
+		}, async () => ({ contents: [typeof file.content === "string" ? {
+			uri: resourceUri,
+			mimeType: file.mediaType,
+			text: file.content
+		} : {
+			uri: resourceUri,
+			mimeType: file.mediaType,
+			blob: Buffer.from(file.content).toString("base64")
+		}] }));
+	}
 	if (resolved.tools.listPages) server.registerTool("list_pages", {
 		title: "List docs pages",
 		description: "List the known documentation pages with titles, slugs, and URLs.",
@@ -2802,12 +2992,26 @@ function createDocsMcpHttpHandler(options) {
 		};
 	}
 	async function handle(request) {
-		const url = new URL(request.url);
+		const originalUrl = new URL(request.url);
 		const method = request.method.toUpperCase();
 		const security = resolved.security ?? resolveDocsMcpSecurityConfig();
+		const metadataLocation = resolveDocsMcpProtectedResourceMetadataLocation(request, resolved.route);
+		if (metadataLocation || isDocsMcpProtectedResourceMetadataPath(originalUrl.pathname)) {
+			if (security.authenticate && security.protectedResource && metadataLocation && !isAllowedMcpProtectedResourceUrl(metadataLocation.resourceUrl)) return createMcpHttpSecurityErrorResponse(400, "Protected MCP requires HTTPS; HTTP is allowed only for loopback development");
+			return createDocsMcpProtectedResourceMetadataResponse({
+				request,
+				location: metadataLocation,
+				config: security.authenticate ? security.protectedResource : void 0,
+				defaultResourceName: resolved.name
+			});
+		}
+		if (security.authenticate && security.protectedResource && !isDocsMcpResourcePath(originalUrl.pathname, resolved.route)) return createJsonErrorResponse(404, "Not Found");
+		const resourceLocation = resolveDocsMcpResourceLocation(request, resolved.route);
+		if (security.authenticate && security.protectedResource && !isAllowedMcpProtectedResourceUrl(resourceLocation.resourceUrl)) return createMcpHttpSecurityErrorResponse(400, "Protected MCP requires HTTPS; HTTP is allowed only for loopback development");
 		const prepared = await prepareDocsMcpHttpRequest(request, security.maxBodyBytes);
 		if (prepared.status === "too-large") return createMcpRequestTooLargeResponse(security.maxBodyBytes);
 		request = prepared.request;
+		const url = new URL(request.url);
 		let originAllowed;
 		try {
 			originAllowed = await isDocsMcpOriginAllowed(request.clone(), security.allowedOrigins);
@@ -2823,14 +3027,16 @@ function createDocsMcpHttpHandler(options) {
 			try {
 				authentication = await security.authenticate({
 					request: request.clone(),
-					pathname: url.pathname
+					pathname: resourceLocation.resourceUrl.pathname,
+					resource: serializeMcpResourceIdentifier(resourceLocation.resourceUrl)
 				});
 			} catch {
 				return withCors(createMcpHttpSecurityErrorResponse(500, "MCP authentication failed"));
 			}
 			if (authentication instanceof Response) return withCors(authentication);
-			if (authentication === null || authentication === void 0) return withCors(createMcpHttpSecurityErrorResponse(401, "Unauthorized"));
+			if (authentication === null || authentication === void 0) return withCors(createMcpUnauthorizedResponse(request, resourceLocation, security.protectedResource));
 			if (!isDocsMcpAuthPrincipal(authentication)) return withCors(createMcpHttpSecurityErrorResponse(500, "MCP authentication returned an invalid principal"));
+			if (findMissingMcpScopes(authentication.scopes, security.protectedResource?.requiredScopes).length > 0) return withCors(createMcpInsufficientScopeResponse(resourceLocation, security.protectedResource));
 			auth = authentication;
 		}
 		const sessionId = request.headers.get("mcp-session-id") ?? request.headers.get("Mcp-Session-Id");
@@ -3054,6 +3260,91 @@ function cloneResponseWithHeaders(response, headers) {
 		headers
 	});
 }
+function createDocsMcpProtectedResourceMetadataResponse({ request, location, config, defaultResourceName }) {
+	const method = request.method.toUpperCase();
+	const headers = new Headers({
+		"Access-Control-Allow-Origin": "*",
+		"Access-Control-Expose-Headers": "Content-Type",
+		Allow: "GET, HEAD, OPTIONS",
+		"Cache-Control": config && location ? "public, max-age=300" : "no-store",
+		"Content-Type": "application/json",
+		"X-Robots-Tag": "noindex"
+	});
+	if (!config || !location) return new Response(method === "HEAD" ? null : JSON.stringify({ error: "Not Found" }), {
+		status: 404,
+		headers
+	});
+	if (method === "OPTIONS") {
+		headers.set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
+		headers.set("Access-Control-Allow-Headers", "MCP-Protocol-Version");
+		headers.set("Access-Control-Max-Age", "600");
+		return new Response(null, {
+			status: 204,
+			headers
+		});
+	}
+	if (method !== "GET" && method !== "HEAD") return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
+		status: 405,
+		headers
+	});
+	const metadata = {
+		resource: serializeMcpResourceIdentifier(location.resourceUrl),
+		authorization_servers: config.authorizationServers,
+		scopes_supported: config.scopesSupported.length > 0 ? config.scopesSupported : void 0,
+		bearer_methods_supported: ["header"],
+		resource_name: config.resourceName ?? defaultResourceName,
+		resource_documentation: config.resourceDocumentation
+	};
+	return new Response(method === "HEAD" ? null : JSON.stringify(metadata), { headers });
+}
+function serializeMcpResourceIdentifier(resourceUrl) {
+	return resourceUrl.pathname === "/" ? resourceUrl.origin : resourceUrl.href;
+}
+function isAllowedMcpProtectedResourceUrl(resourceUrl) {
+	if (resourceUrl.protocol === "https:") return true;
+	return resourceUrl.protocol === "http:" && (resourceUrl.hostname === "localhost" || resourceUrl.hostname === "127.0.0.1" || resourceUrl.hostname === "[::1]");
+}
+function findMissingMcpScopes(grantedScopes, requiredScopes) {
+	if (!requiredScopes || requiredScopes.length === 0) return [];
+	const granted = new Set(grantedScopes ?? []);
+	return requiredScopes.filter((scope) => !granted.has(scope));
+}
+function createMcpUnauthorizedResponse(request, location, config) {
+	if (!config) return createMcpHttpSecurityErrorResponse(401, "Unauthorized");
+	return createMcpOAuthErrorResponse(401, "invalid_token", buildMcpBearerChallenge({
+		error: request.headers.has("authorization") ? "invalid_token" : void 0,
+		resourceMetadata: location.metadataUrl.href,
+		scopes: config.requiredScopes
+	}));
+}
+function createMcpInsufficientScopeResponse(location, config) {
+	if (!config) return createMcpHttpSecurityErrorResponse(403, "Forbidden");
+	return createMcpOAuthErrorResponse(403, "insufficient_scope", buildMcpBearerChallenge({
+		error: "insufficient_scope",
+		resourceMetadata: location.metadataUrl.href,
+		scopes: config.requiredScopes
+	}));
+}
+function buildMcpBearerChallenge({ error, resourceMetadata, scopes }) {
+	return `Bearer ${[
+		...error ? [`error=${quoteHttpAuthParameter(error)}`] : [],
+		`resource_metadata=${quoteHttpAuthParameter(resourceMetadata)}`,
+		...scopes.length > 0 ? [`scope=${quoteHttpAuthParameter(scopes.join(" "))}`] : []
+	].join(", ")}`;
+}
+function quoteHttpAuthParameter(value) {
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+function createMcpOAuthErrorResponse(status, error, challenge) {
+	return new Response(JSON.stringify({ error }), {
+		status,
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "no-store",
+			"WWW-Authenticate": challenge
+		}
+	});
+}
 function createMcpRequestTooLargeResponse(maxBodyBytes) {
 	const response = createJsonRpcErrorResponse({
 		status: 413,