@farming-labs/docs 0.2.120 → 0.2.122

package/README.md

@@ -96,6 +96,14 @@ Routing is file-based, so a page such as `app/docs/guides/deployment/page.mdx` b
 `/docs/guides/deployment` in Next.js. The CLI scaffolds the correct directory layout for every
 supported framework.
 
+### MDX compiler integration
+
+Custom MDX integrations can import `remarkCodeGroup`, `applyDocsMarkdownHeadingAnchors`,
+`encodeDocsHeadingTocUrls`, `isolateDocsMarkdownPromptReferences`, and
+`withDocsMarkdownRenderableHeadings` from `@farming-labs/docs/mdx`. This entry point exposes the
+same helpers without loading the unrelated core/server runtime exports. Existing imports from
+the root and server entry points remain supported.
+
 ## Documentation for agents
 
 Farming Labs can expose the same docs in machine-readable forms, including:

package/dist/access.d.mts

@@ -0,0 +1,13 @@
+import { DocsAccessPrincipal, DocsPageAccessPolicy, PageAgentFrontmatter } from "./types.mjs";
+
+//#region src/access.d.ts
+declare function normalizeDocsPageAccessPolicy(value: unknown): DocsPageAccessPolicy | undefined;
+declare function isDocsPageAccessAllowed(policy: DocsPageAccessPolicy | undefined, principal?: DocsAccessPrincipal): boolean;
+declare function isDocsAgentPageAccessible(page: {
+  agent?: PageAgentFrontmatter;
+}, principal?: DocsAccessPrincipal): boolean;
+declare function filterDocsPagesByAccess<T extends {
+  agent?: PageAgentFrontmatter;
+}>(pages: readonly T[], principal?: DocsAccessPrincipal): T[];
+//#endregion
+export { filterDocsPagesByAccess, isDocsAgentPageAccessible, isDocsPageAccessAllowed, normalizeDocsPageAccessPolicy };

package/dist/access.mjs

@@ -0,0 +1,56 @@
+//#region src/access.ts
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeStrings(value) {
+	if (!Array.isArray(value)) return void 0;
+	const strings = Array.from(new Set(value.flatMap((item) => typeof item === "string" && item.trim() ? [item.trim()] : [])));
+	return strings.length > 0 ? strings : void 0;
+}
+function normalizeClaimValue(value) {
+	if (typeof value === "string") return value.trim() || void 0;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "boolean") return value;
+	return normalizeStrings(value);
+}
+function normalizeDocsPageAccessPolicy(value) {
+	if (!isRecord(value)) return void 0;
+	const visibility = value.visibility === "public" || value.visibility === "authenticated" ? value.visibility : void 0;
+	const scopes = normalizeStrings(value.scopes);
+	const rawClaims = isRecord(value.claims) ? value.claims : void 0;
+	const claims = rawClaims ? Object.fromEntries(Object.entries(rawClaims).flatMap(([name, rawValue]) => {
+		const normalizedName = name.trim();
+		const normalizedValue = normalizeClaimValue(rawValue);
+		return normalizedName && normalizedValue !== void 0 ? [[normalizedName, normalizedValue]] : [];
+	})) : void 0;
+	const normalizedClaims = claims && Object.keys(claims).length > 0 ? claims : void 0;
+	if (!visibility && !scopes && !normalizedClaims) return void 0;
+	return {
+		...visibility ? { visibility } : {},
+		...scopes ? { scopes } : {},
+		...normalizedClaims ? { claims: normalizedClaims } : {}
+	};
+}
+function claimMatches(expected, actual) {
+	const expectedValues = Array.isArray(expected) ? expected : [expected];
+	const actualValues = Array.isArray(actual) ? actual : [actual];
+	return expectedValues.some((expectedValue) => actualValues.some((actualValue) => actualValue === expectedValue));
+}
+function isDocsPageAccessAllowed(policy, principal) {
+	if (!policy) return true;
+	if (!(policy.visibility !== "public" || Boolean(policy.scopes?.length) || Boolean(policy.claims && Object.keys(policy.claims).length > 0))) return true;
+	if (!principal) return false;
+	const scopes = new Set(principal.scopes ?? []);
+	if (policy.scopes?.some((scope) => !scopes.has(scope))) return false;
+	for (const [name, expected] of Object.entries(policy.claims ?? {})) if (!claimMatches(expected, principal.claims?.[name])) return false;
+	return true;
+}
+function isDocsAgentPageAccessible(page, principal) {
+	return isDocsPageAccessAllowed(page.agent?.access, principal);
+}
+function filterDocsPagesByAccess(pages, principal) {
+	return pages.filter((page) => isDocsAgentPageAccessible(page, principal));
+}
+
+//#endregion
+export { filterDocsPagesByAccess, isDocsAgentPageAccessible, isDocsPageAccessAllowed, normalizeDocsPageAccessPolicy };

package/dist/agent-conformance.d.mts

@@ -0,0 +1,60 @@
+//#region src/agent-conformance.d.ts
+declare const DOCS_AGENT_CONTRACT_VERSION = "1.3";
+type DocsAgentAdapter = "next" | "tanstack-start" | "farmjs" | "sveltekit" | "astro" | "nuxt";
+type DocsAgentContractSurface = "discovery" | "api-catalog" | "api-catalog-head" | "agent-skills-index" | "agent-skills-index-head" | "agent-skill" | "agent-skill-head" | "config" | "diagnostics" | "feedback-schema" | "markdown" | "markdown-accept" | "markdown-locale" | "markdown-missing" | "llms" | "llms-full" | "agents" | "skill" | "sitemap-xml" | "sitemap-markdown" | "robots" | "mcp";
+interface DocsAgentContractRequest {
+  url: string;
+  init?: RequestInit;
+}
+interface DocsAgentContractExpectation {
+  statuses: readonly number[];
+  contentTypes: readonly string[];
+  bodyIncludes?: readonly string[];
+  bodyEmpty?: boolean;
+  headerIncludes?: Readonly<Record<string, readonly string[]>>;
+  linkRelations?: readonly {
+    href: string;
+    rel: string;
+    type?: string;
+  }[];
+}
+interface DocsAgentContractCase {
+  surface: DocsAgentContractSurface;
+  request: DocsAgentContractRequest;
+  expect: DocsAgentContractExpectation;
+}
+interface DocsAgentConformanceCaseResult {
+  surface: DocsAgentContractSurface;
+  passed: boolean;
+  status?: number;
+  contentType?: string;
+  issues: string[];
+}
+interface DocsAgentConformanceReport {
+  adapter: DocsAgentAdapter;
+  contractVersion: typeof DOCS_AGENT_CONTRACT_VERSION;
+  passed: boolean;
+  cases: DocsAgentConformanceCaseResult[];
+}
+interface RunDocsAgentConformanceOptions {
+  adapter: DocsAgentAdapter;
+  /** Origin used to construct requests. Defaults to http://localhost. */
+  origin?: string;
+  /** Public docs entry. Defaults to docs. */
+  entry?: string;
+  /** Locale fixture expected to render the word "Bonjour". Set false to skip. */
+  locale?: string | false;
+  handle(request: Request, surface: DocsAgentContractSurface): Response | Promise<Response>;
+}
+/**
+ * The framework-neutral public surface every first-party adapter must implement.
+ * Adapter tests consume this list so new routes and invariants are added once.
+ */
+declare function createDocsAgentContractCases(options?: {
+  origin?: string;
+  entry?: string;
+  locale?: string | false;
+}): DocsAgentContractCase[];
+declare function runDocsAgentConformance(options: RunDocsAgentConformanceOptions): Promise<DocsAgentConformanceReport>;
+//#endregion
+export { DOCS_AGENT_CONTRACT_VERSION, DocsAgentAdapter, DocsAgentConformanceCaseResult, DocsAgentConformanceReport, DocsAgentContractCase, DocsAgentContractExpectation, DocsAgentContractRequest, DocsAgentContractSurface, RunDocsAgentConformanceOptions, createDocsAgentContractCases, runDocsAgentConformance };

package/dist/agent-conformance.mjs

@@ -0,0 +1,538 @@
+import { DEFAULT_MCP_WELL_KNOWN_ROUTE } from "./mcp-auth.mjs";
+import { isDocsAgentSkillName, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
+import { AGENT_SKILLS_DISCOVERY_SCHEMA_URI, API_CATALOG_MEDIA_TYPE, API_CATALOG_PROFILE_URI, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION } from "./standards-discovery.mjs";
+import { DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_XML_ROUTE } from "./sitemap.mjs";
+import { DEFAULT_AGENTS_MD_ROUTE, DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_DOCS_CONFIG_ROUTE, DEFAULT_DOCS_DIAGNOSTICS_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_SKILL_MD_ROUTE } from "./agent.mjs";
+import { AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, readAgentSkillDocumentFromTar } from "./agent-skills-archive.mjs";
+import { httpLinkMatchesExpectation, parseHttpLinkHeader, splitHttpList, unquoteHttpValue } from "./http-link.mjs";
+import { DEFAULT_ROBOTS_TXT_ROUTE } from "./robots.mjs";
+
+//#region src/agent-conformance.ts
+const DOCS_AGENT_CONTRACT_VERSION = "1.3";
+function normalizeOrigin(value) {
+	return value.replace(/\/+$/, "");
+}
+function normalizeEntry(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "docs";
+}
+/**
+* The framework-neutral public surface every first-party adapter must implement.
+* Adapter tests consume this list so new routes and invariants are added once.
+*/
+function createDocsAgentContractCases(options = {}) {
+	const origin = normalizeOrigin(options.origin ?? "http://localhost");
+	const entry = normalizeEntry(options.entry ?? "docs");
+	const locale = options.locale === void 0 ? "fr" : options.locale;
+	const url = (route) => `${origin}${route.startsWith("/") ? route : `/${route}`}`;
+	const markdown = ["text/markdown"];
+	const json = ["application/json"];
+	const cases = [
+		{
+			surface: "discovery",
+			request: { url: url(DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				linkRelations: [
+					{
+						href: DEFAULT_API_CATALOG_ROUTE,
+						rel: "api-catalog"
+					},
+					{
+						href: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+						rel: "service-meta"
+					},
+					{
+						href: DOCS_AGENT_MANIFEST_SCHEMA_URI,
+						rel: "describedby",
+						type: DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE
+					}
+				]
+			}
+		},
+		{
+			surface: "api-catalog",
+			request: { url: url(DEFAULT_API_CATALOG_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: [`${API_CATALOG_MEDIA_TYPE}; profile="${API_CATALOG_PROFILE_URI}"`],
+				bodyIncludes: [
+					"linkset",
+					DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
+					DEFAULT_AGENT_SKILLS_INDEX_ROUTE
+				],
+				linkRelations: [{
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "api-catalog-head",
+			request: {
+				url: url(DEFAULT_API_CATALOG_ROUTE),
+				init: { method: "HEAD" }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: [`${API_CATALOG_MEDIA_TYPE}; profile="${API_CATALOG_PROFILE_URI}"`],
+				bodyEmpty: true,
+				linkRelations: [{
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "agent-skills-index",
+			request: { url: url(DEFAULT_AGENT_SKILLS_INDEX_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: [
+					"https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+					`${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/docs/SKILL.md`,
+					"sha256:"
+				],
+				linkRelations: [{
+					href: `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/docs/SKILL.md`,
+					rel: "item"
+				}, {
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "agent-skills-index-head",
+			request: {
+				url: url(DEFAULT_AGENT_SKILLS_INDEX_ROUTE),
+				init: { method: "HEAD" }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyEmpty: true,
+				linkRelations: [{
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "agent-skill",
+			request: { url: url(`${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/docs/SKILL.md`) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["name: docs"],
+				linkRelations: [{
+					href: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					rel: "collection"
+				}, {
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "agent-skill-head",
+			request: {
+				url: url(`${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/docs/SKILL.md`),
+				init: { method: "HEAD" }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyEmpty: true,
+				linkRelations: [{
+					href: DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					rel: "collection"
+				}, {
+					href: DEFAULT_API_CATALOG_ROUTE,
+					rel: "api-catalog"
+				}]
+			}
+		},
+		{
+			surface: "config",
+			request: { url: url(DEFAULT_DOCS_CONFIG_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-config-map.v1"]
+			}
+		},
+		{
+			surface: "diagnostics",
+			request: { url: url(DEFAULT_DOCS_DIAGNOSTICS_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-diagnostics.v1"]
+			}
+		},
+		{
+			surface: "feedback-schema",
+			request: { url: url(`${DEFAULT_AGENT_FEEDBACK_ROUTE}/schema`) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/schema+json"]
+			}
+		},
+		{
+			surface: "markdown",
+			request: { url: url(`/${entry}.md`) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-accept",
+			request: {
+				url: url(`/${entry}`),
+				init: { headers: { Accept: "text/markdown" } }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-missing",
+			request: { url: url(`/${entry}/missing.md`) },
+			expect: {
+				statuses: [200, 404],
+				contentTypes: markdown,
+				bodyIncludes: ["not found"]
+			}
+		},
+		{
+			surface: "llms",
+			request: { url: url(DEFAULT_LLMS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "llms-full",
+			request: { url: url(DEFAULT_LLMS_FULL_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "agents",
+			request: { url: url(DEFAULT_AGENTS_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["AGENTS.md"]
+			}
+		},
+		{
+			surface: "skill",
+			request: { url: url(DEFAULT_SKILL_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["name:"]
+			}
+		},
+		{
+			surface: "sitemap-xml",
+			request: { url: url(DEFAULT_SITEMAP_XML_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/xml", "text/xml"],
+				bodyIncludes: ["<urlset"]
+			}
+		},
+		{
+			surface: "sitemap-markdown",
+			request: { url: url(DEFAULT_SITEMAP_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "robots",
+			request: { url: url(DEFAULT_ROBOTS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["User-agent:"]
+			}
+		},
+		{
+			surface: "mcp",
+			request: {
+				url: url(DEFAULT_MCP_WELL_KNOWN_ROUTE),
+				init: {
+					method: "POST",
+					headers: {
+						Accept: "application/json, text/event-stream",
+						"Content-Type": "application/json",
+						"MCP-Protocol-Version": "2025-11-25"
+					},
+					body: JSON.stringify({
+						jsonrpc: "2.0",
+						id: 1,
+						method: "initialize",
+						params: {
+							protocolVersion: "2025-11-25",
+							capabilities: {},
+							clientInfo: {
+								name: "agent-conformance",
+								version: DOCS_AGENT_CONTRACT_VERSION
+							}
+						}
+					})
+				}
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/json", "text/event-stream"],
+				bodyIncludes: ["serverInfo", "protocolVersion"]
+			}
+		}
+	];
+	if (locale) {
+		const markdownMissingIndex = cases.findIndex((contractCase) => contractCase.surface === "markdown-missing");
+		cases.splice(markdownMissingIndex, 0, {
+			surface: "markdown-locale",
+			request: { url: url(`/${entry}.md?lang=${encodeURIComponent(locale)}`) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Bonjour"]
+			}
+		});
+	}
+	return cases;
+}
+function parseParameterizedValue(value) {
+	const [rawValue, ...rawParameters] = splitHttpList(value, ";");
+	const normalizedValue = rawValue?.trim().toLowerCase();
+	if (!normalizedValue) return null;
+	const parameters = /* @__PURE__ */ new Map();
+	for (const rawParameter of rawParameters) {
+		const separator = rawParameter.indexOf("=");
+		if (separator < 0) continue;
+		const name = rawParameter.slice(0, separator).trim().toLowerCase();
+		if (!name) continue;
+		parameters.set(name, unquoteHttpValue(rawParameter.slice(separator + 1)));
+	}
+	return {
+		value: normalizedValue,
+		parameters
+	};
+}
+function matchesContentType(actual, expected) {
+	const parsedActual = parseParameterizedValue(actual);
+	if (!parsedActual) return false;
+	return expected.some((value) => {
+		const parsedExpected = parseParameterizedValue(value);
+		if (!parsedExpected || parsedExpected.value !== parsedActual.value) return false;
+		return [...parsedExpected.parameters].every(([name, expectedValue]) => parsedActual.parameters.get(name) === expectedValue);
+	});
+}
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function validateAgentManifest(content) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return ["Agent manifest did not contain valid JSON"];
+	}
+	const root = asRecord(parsed);
+	const issues = [];
+	if (root?.$schema !== DOCS_AGENT_MANIFEST_SCHEMA_URI) issues.push(`Agent manifest did not declare top-level $schema ${DOCS_AGENT_MANIFEST_SCHEMA_URI}`);
+	if (root?.format !== DOCS_AGENT_MANIFEST_FORMAT) issues.push(`Agent manifest did not declare top-level format ${DOCS_AGENT_MANIFEST_FORMAT}`);
+	if (root?.version !== DOCS_AGENT_MANIFEST_VERSION) issues.push(`Agent manifest did not declare top-level version ${DOCS_AGENT_MANIFEST_VERSION}`);
+	return issues;
+}
+function httpLinkMatchesContractExpectation(header, expectation, responseUrl) {
+	if (!httpLinkMatchesExpectation(parseHttpLinkHeader(header), expectation, responseUrl)) return false;
+	if (!expectation.type) return true;
+	let expectedUrl;
+	try {
+		expectedUrl = new URL(expectation.href, responseUrl).toString();
+	} catch {
+		return false;
+	}
+	for (const value of splitHttpList(header ?? "", ",")) {
+		const target = value.match(/^\s*<([^>]*)>/);
+		if (!target) continue;
+		let actualUrl;
+		try {
+			actualUrl = new URL(target[1], responseUrl).toString();
+		} catch {
+			continue;
+		}
+		if (actualUrl !== expectedUrl) continue;
+		const relations = [];
+		let type;
+		for (const rawParameter of splitHttpList(value.slice(target[0].length), ";")) {
+			const separator = rawParameter.indexOf("=");
+			if (separator < 0) continue;
+			const name = rawParameter.slice(0, separator).trim().toLowerCase();
+			const parameterValue = unquoteHttpValue(rawParameter.slice(separator + 1));
+			if (name === "rel") relations.push(...parameterValue.toLowerCase().split(/\s+/).filter(Boolean));
+			else if (name === "type") type = parameterValue.toLowerCase();
+		}
+		if (relations.includes(expectation.rel.toLowerCase()) && type === expectation.type.toLowerCase()) return true;
+	}
+	return false;
+}
+async function sha256Content(content) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", content);
+	return [...new Uint8Array(digest)].map((value) => value.toString(16).padStart(2, "0")).join("");
+}
+async function decompressAgentSkillArchive(content) {
+	if (typeof DecompressionStream !== "function") throw new Error("gzip decompression is unavailable in this runtime");
+	const stream = new Blob([content]).stream().pipeThrough(new DecompressionStream("gzip"));
+	const chunks = [];
+	let totalBytes = 0;
+	for await (const chunk of stream) {
+		totalBytes += chunk.byteLength;
+		if (totalBytes > AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES) throw new Error(`archive exceeds ${AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES} uncompressed bytes`);
+		chunks.push(chunk);
+	}
+	const archive = new Uint8Array(new ArrayBuffer(totalBytes));
+	let offset = 0;
+	for (const chunk of chunks) {
+		archive.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return archive;
+}
+async function validateAgentSkillsIndex(content, indexUrl, handle) {
+	const issues = [];
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return ["Agent Skills index did not contain valid JSON"];
+	}
+	const root = asRecord(parsed);
+	if (root?.$schema !== AGENT_SKILLS_DISCOVERY_SCHEMA_URI) issues.push(`Agent Skills index did not declare ${AGENT_SKILLS_DISCOVERY_SCHEMA_URI}`);
+	if (!Array.isArray(root?.skills) || root.skills.length === 0) {
+		issues.push("Agent Skills index did not declare any skills");
+		return issues;
+	}
+	const seenNames = /* @__PURE__ */ new Set();
+	const origin = new URL(indexUrl).origin;
+	for (const rawSkill of root.skills) {
+		const skill = asRecord(rawSkill);
+		const name = skill?.name;
+		const description = skill?.description;
+		const artifactRoute = skill?.url;
+		const digest = skill?.digest;
+		if (!isNonEmptyString(name) || !isDocsAgentSkillName(name) || skill?.type !== "skill-md" && skill?.type !== "archive" || !isNonEmptyString(description) || Array.from(description).length > 1024 || !isNonEmptyString(artifactRoute) || typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(digest)) {
+			issues.push("Agent Skills index contained an invalid skill entry");
+			continue;
+		}
+		if (seenNames.has(name)) {
+			issues.push(`Agent Skills index declared duplicate skill ${JSON.stringify(name)}`);
+			continue;
+		}
+		seenNames.add(name);
+		let artifactUrl;
+		try {
+			artifactUrl = new URL(artifactRoute, indexUrl);
+		} catch {
+			issues.push(`Agent Skills artifact URL for ${JSON.stringify(name)} was invalid`);
+			continue;
+		}
+		const expectedPath = skill.type === "archive" ? `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/${encodeURIComponent(name)}.tar.gz` : `${DEFAULT_AGENT_SKILLS_ROUTE_PREFIX}/${encodeURIComponent(name)}/SKILL.md`;
+		if (artifactUrl.origin !== origin || !artifactUrl.pathname.endsWith(expectedPath)) {
+			issues.push(`Agent Skills artifact URL for ${JSON.stringify(name)} did not resolve to same-origin ${expectedPath}`);
+			continue;
+		}
+		let skillDocument = null;
+		try {
+			const response = await handle(new Request(artifactUrl), "agent-skill");
+			const artifact = new Uint8Array(await response.arrayBuffer());
+			if (response.status !== 200) issues.push(`Agent Skills artifact ${JSON.stringify(artifactRoute)} returned status ${response.status}`);
+			const contentType = response.headers.get("content-type") ?? "";
+			if (!matchesContentType(contentType, [skill.type === "archive" ? "application/gzip" : "text/markdown"])) issues.push(`Agent Skills artifact ${JSON.stringify(artifactRoute)} returned content-type ${contentType || "<missing>"}`);
+			const actualDigest = `sha256:${await sha256Content(artifact)}`;
+			if (actualDigest !== digest) issues.push(`Agent Skills artifact ${JSON.stringify(artifactRoute)} digest ${actualDigest} did not match ${digest}`);
+			if (skill.type === "skill-md") skillDocument = new TextDecoder("utf-8", { fatal: true }).decode(artifact);
+			else skillDocument = readAgentSkillDocumentFromTar(await decompressAgentSkillArchive(artifact));
+		} catch (error) {
+			issues.push(`Agent Skills artifact ${JSON.stringify(artifactRoute)} failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (skillDocument !== null) {
+			const validation = validateDocsAgentSkillFrontmatter(skillDocument, { directoryName: name });
+			if (!validation.valid) issues.push(`Agent Skill ${JSON.stringify(name)} has invalid SKILL.md frontmatter: ${validation.issues.map((issue) => issue.message).join("; ")}`);
+			else if (validation.data.description !== description) issues.push(`Agent Skill ${JSON.stringify(name)} SKILL.md description does not match the discovery index`);
+		}
+	}
+	return issues;
+}
+async function runDocsAgentConformance(options) {
+	const cases = createDocsAgentContractCases(options);
+	const results = [];
+	for (const contractCase of cases) {
+		const issues = [];
+		try {
+			const response = await options.handle(new Request(contractCase.request.url, contractCase.request.init), contractCase.surface);
+			const contentType = response.headers.get("content-type") ?? "";
+			const body = await response.text();
+			if (!contractCase.expect.statuses.includes(response.status)) issues.push(`expected status ${contractCase.expect.statuses.join(" or ")}, received ${response.status}`);
+			if (!matchesContentType(contentType, contractCase.expect.contentTypes)) issues.push(`expected content-type ${contractCase.expect.contentTypes.join(" or ")}, received ${contentType || "<missing>"}`);
+			for (const requiredText of contractCase.expect.bodyIncludes ?? []) if (!body.toLowerCase().includes(requiredText.toLowerCase())) issues.push(`response body did not include ${JSON.stringify(requiredText)}`);
+			if (contractCase.expect.bodyEmpty && body !== "") issues.push(`expected an empty response body, received ${body.length} characters`);
+			if (contractCase.surface === "discovery") issues.push(...validateAgentManifest(body));
+			if (contractCase.surface === "agent-skills-index") issues.push(...await validateAgentSkillsIndex(body, contractCase.request.url, options.handle));
+			for (const [header, requiredValues] of Object.entries(contractCase.expect.headerIncludes ?? {})) {
+				const actual = response.headers.get(header) ?? "";
+				for (const requiredValue of requiredValues) if (!actual.toLowerCase().includes(requiredValue.toLowerCase())) issues.push(`response header ${JSON.stringify(header)} did not include ${JSON.stringify(requiredValue)}`);
+			}
+			const linkHeader = response.headers.get("link");
+			for (const expectation of contractCase.expect.linkRelations ?? []) if (!httpLinkMatchesContractExpectation(linkHeader, expectation, contractCase.request.url)) {
+				const typeRequirement = expectation.type ? ` and type=${JSON.stringify(expectation.type)}` : "";
+				issues.push(`response Link header did not include ${JSON.stringify(expectation.href)} with rel=${JSON.stringify(expectation.rel)}${typeRequirement} in the same link-value`);
+			}
+			results.push({
+				surface: contractCase.surface,
+				passed: issues.length === 0,
+				status: response.status,
+				contentType,
+				issues
+			});
+		} catch (error) {
+			issues.push(error instanceof Error ? error.message : String(error));
+			results.push({
+				surface: contractCase.surface,
+				passed: false,
+				issues
+			});
+		}
+	}
+	return {
+		adapter: options.adapter,
+		contractVersion: DOCS_AGENT_CONTRACT_VERSION,
+		passed: results.every((result) => result.passed),
+		cases: results
+	};
+}
+
+//#endregion
+export { DOCS_AGENT_CONTRACT_VERSION, createDocsAgentContractCases, runDocsAgentConformance };