@farming-labs/docs 0.2.80 → 0.2.82

package/dist/{agent-provenance-C_jgqNTW.mjs → content-change-hydration-DpQ0KdAD.mjs}

@@ -1,4 +1,6 @@
-import { G as isDocsAgentDiscoveryRequest, Jt as resolveDocsContentChangesConfig, K as isDocsAgentsRequest, Q as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, qt as isDocsContentChangesRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-Cj50nyeV.mjs";
+import { $t as buildDocsRetrievalDigestProjection, Fn as createDocsPaginationCursor, G as isDocsAgentDiscoveryRequest, Jt as resolveDocsContentChangesConfig, K as isDocsAgentsRequest, Ln as resolveDocsPaginationOffset, Pn as DocsPaginationCursorError, Q as isDocsSkillRequest, Rn as digestDocsRetrievalContent, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, qt as isDocsContentChangesRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-Dze2Cy5B.mjs";
+import { s as parseDocsMarkdownSections } from "./markdown-sections-7OoA7ylx.mjs";
+import matter from "gray-matter";
 
 //#region src/telemetry.ts
 const DOCS_PACKAGE_NAME = "@farming-labs/docs";
@@ -460,4 +462,218 @@ function serializeGeneratedAgentDocument(content, provenance) {
 }
 
 //#endregion
-export { inferDocsTelemetryAgentSurface as _, parseGeneratedAgentDocument as a, resolveDocsTelemetryConfig as b, applySidebarFolderIndexBehavior as c, resolveSidebarFolderIndexBehaviorForPath as d, emitDocsTelemetryAgentSurfaceEvent as f, getDocsTelemetryFeatures as g, emitDocsTelemetryProjectEvent as h, normalizeGeneratedAgentContent as i, resolvePageSidebarFolderIndexBehavior as l, emitDocsTelemetryMcpToolEvent as m, GENERATED_AGENT_PROVENANCE_VERSION as n, serializeGeneratedAgentDocument as o, emitDocsTelemetryEvent as p, hashGeneratedAgentContent as r, stripGeneratedAgentProvenance as s, GENERATED_AGENT_PROVENANCE_MARKER as t, resolveSidebarFolderIndexBehavior as u, isLocalDocsTelemetryOrigin as v, normalizeDocsTelemetryOrigin as y };
+//#region src/content-change-hydration.ts
+const DOCS_CONTENT_CHANGE_HYDRATION_FORMAT = "docs-content-change-hydration.v1";
+const DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET = 5e3;
+const MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET = 4;
+const MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET = 32e3;
+const DOCS_CONTENT_CHANGE_HYDRATION_PAGE_SIZE = 25;
+const DOCS_CONTENT_CHANGE_HYDRATION_CURSOR_KIND = "mcp.tool/hydrate_content_changes";
+function docsHydrationUtf8Bytes(value) {
+	return new TextEncoder().encode(value).byteLength;
+}
+function appendDocsHydrationLocale(url, locale) {
+	if (!locale) return url;
+	const hashIndex = url.indexOf("#");
+	const withoutHash = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+	const hash = hashIndex >= 0 ? url.slice(hashIndex) : "";
+	const queryIndex = withoutHash.indexOf("?");
+	const rawQuery = queryIndex >= 0 ? withoutHash.slice(queryIndex + 1) : "";
+	if (new URLSearchParams(rawQuery).has("lang")) return url;
+	return `${withoutHash}${queryIndex >= 0 ? "&" : "?"}lang=${encodeURIComponent(locale)}${hash}`;
+}
+function splitDocsHydrationChunk(value, maxUtf8Bytes) {
+	if (docsHydrationUtf8Bytes(value) <= maxUtf8Bytes) return [value, ""];
+	const encoder = new TextEncoder();
+	let usedUtf8Bytes = 0;
+	let endOffset = 0;
+	let paragraphOffset = -1;
+	let lineOffset = -1;
+	for (const character of value) {
+		const characterUtf8Bytes = encoder.encode(character).byteLength;
+		if (usedUtf8Bytes + characterUtf8Bytes > maxUtf8Bytes) break;
+		usedUtf8Bytes += characterUtf8Bytes;
+		endOffset += character.length;
+		if (value.slice(Math.max(0, endOffset - 2), endOffset) === "\n\n") paragraphOffset = endOffset;
+		else if (character === "\n") lineOffset = endOffset;
+	}
+	const minimumUsefulBoundary = Math.floor(endOffset * .5);
+	const boundary = paragraphOffset >= minimumUsefulBoundary ? paragraphOffset : lineOffset >= minimumUsefulBoundary ? lineOffset : endOffset;
+	return [value.slice(0, boundary), value.slice(boundary)];
+}
+function splitDocsHydrationContent(value, maxUtf8Bytes) {
+	if (!value) return [""];
+	const chunks = [];
+	let remaining = value;
+	while (remaining) {
+		const [chunk, next] = splitDocsHydrationChunk(remaining, maxUtf8Bytes);
+		if (!chunk && next === remaining) throw new TypeError("Unable to split changed content within the requested token budget.");
+		chunks.push(chunk);
+		remaining = next;
+	}
+	return chunks;
+}
+function partitionDocsHydrationSections(document, page) {
+	const body = matter(document).content.trim();
+	const parsed = parseDocsMarkdownSections(body);
+	if (parsed.length === 0) return [{
+		id: "document",
+		heading: page.title,
+		level: 1,
+		content: body
+	}];
+	const lines = body.split(/\r?\n/u);
+	return parsed.map((section, index) => {
+		const startLine = index === 0 ? 0 : Math.max(0, section.startLine - 1);
+		const nextStartLine = parsed[index + 1]?.startLine;
+		const endLine = nextStartLine ? Math.max(startLine, nextStartLine - 1) : lines.length;
+		return {
+			id: section.anchor,
+			heading: section.title,
+			level: section.level,
+			content: lines.slice(startLine, endLine).join("\n").trim()
+		};
+	});
+}
+function toHydrationContentUnits(change, kind, page, maxUtf8Bytes) {
+	return partitionDocsHydrationSections(buildDocsRetrievalDigestProjection(page, "agent"), page).flatMap((section) => {
+		const sectionDigest = digestDocsRetrievalContent(section.content);
+		const chunks = splitDocsHydrationContent(section.content, maxUtf8Bytes);
+		return chunks.map((content, index) => ({
+			type: "content",
+			change: kind,
+			url: change.url,
+			canonicalUrl: change.canonicalUrl,
+			digest: change.digest,
+			..."previousDigest" in change ? { previousDigest: change.previousDigest } : {},
+			...change.lastModified ? { lastModified: change.lastModified } : {},
+			..."previousLastModified" in change && change.previousLastModified ? { previousLastModified: change.previousLastModified } : {},
+			section: {
+				id: section.id,
+				heading: section.heading,
+				level: section.level
+			},
+			sectionDigest,
+			chunkDigest: digestDocsRetrievalContent(content),
+			chunk: {
+				index,
+				count: chunks.length
+			},
+			content,
+			utf8Bytes: docsHydrationUtf8Bytes(content)
+		}));
+	});
+}
+function buildDocsHydrationUnits(changes, pages, maxUtf8Bytes) {
+	const pagesByUrl = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		pagesByUrl.set(page.url, page);
+		pagesByUrl.set(appendDocsHydrationLocale(page.url, changes.locale), page);
+	}
+	const currentUnits = [...changes.added.map((change) => [change, "added"]), ...changes.changed.map((change) => [change, "changed"])].flatMap(([change, kind]) => {
+		const page = pagesByUrl.get(change.url);
+		if (!page) throw new TypeError(`Unable to hydrate changed documentation content for ${change.url}.`);
+		return toHydrationContentUnits(change, kind, page, maxUtf8Bytes);
+	});
+	const tombstones = changes.deleted.map((change) => ({
+		type: "tombstone",
+		change: "deleted",
+		url: change.url,
+		canonicalUrl: change.canonicalUrl,
+		digest: change.digest,
+		...change.lastModified ? { lastModified: change.lastModified } : {}
+	}));
+	return [...currentUnits, ...tombstones];
+}
+function resolveDocsHydrationTokenBudget(value) {
+	const tokenBudget = value ?? DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET;
+	if (!Number.isSafeInteger(tokenBudget) || tokenBudget < MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET || tokenBudget > MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET) throw new TypeError(`Content-change hydration tokenBudget must be between ${MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET} and ${MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET}.`);
+	return tokenBudget;
+}
+/**
+* Hydrate only the current bodies named by a content-change delta.
+*
+* The conservative budget treats one UTF-8 byte as at most one token. Cursors are
+* bound to the requested generation, current generation, locale, and budget.
+*/
+function hydrateDocsContentChanges(options) {
+	if (options.changes.audience !== "agent") throw new TypeError("MCP content-change hydration requires the agent audience.");
+	if (options.changes.since !== options.since) throw new TypeError("Content-change hydration must use the resolved delta generation.");
+	const tokenBudget = resolveDocsHydrationTokenBudget(options.tokenBudget);
+	const units = buildDocsHydrationUnits(options.changes, options.pages, tokenBudget);
+	const hydrationSnapshot = digestDocsRetrievalContent(JSON.stringify({
+		format: DOCS_CONTENT_CHANGE_HYDRATION_FORMAT,
+		since: options.since,
+		indexGeneration: options.changes.indexGeneration,
+		mode: options.changes.mode,
+		resetRequired: options.changes.resetRequired,
+		units: units.map((unit) => unit.type === "content" ? {
+			type: unit.type,
+			change: unit.change,
+			canonicalUrl: unit.canonicalUrl,
+			digest: unit.digest,
+			section: unit.section.id,
+			sectionDigest: unit.sectionDigest,
+			chunk: unit.chunk.index,
+			chunkDigest: unit.chunkDigest
+		} : {
+			type: unit.type,
+			canonicalUrl: unit.canonicalUrl,
+			digest: unit.digest
+		})
+	}));
+	const paginationOptions = {
+		kind: DOCS_CONTENT_CHANGE_HYDRATION_CURSOR_KIND,
+		scope: JSON.stringify({
+			server: options.cursorScope,
+			since: options.since,
+			locale: options.changes.locale ?? null,
+			tokenBudget
+		}),
+		snapshot: hydrationSnapshot
+	};
+	const offset = resolveDocsPaginationOffset(options.cursor, paginationOptions);
+	if (options.cursor !== void 0 && offset >= units.length) throw new DocsPaginationCursorError();
+	const selected = [];
+	let usedUtf8Bytes = 0;
+	for (let index = offset; index < units.length && selected.length < DOCS_CONTENT_CHANGE_HYDRATION_PAGE_SIZE; index += 1) {
+		const unit = units[index];
+		const unitUtf8Bytes = unit.type === "content" ? unit.utf8Bytes : 0;
+		if (unitUtf8Bytes > 0 && usedUtf8Bytes + unitUtf8Bytes > tokenBudget) break;
+		selected.push(unit);
+		usedUtf8Bytes += unitUtf8Bytes;
+	}
+	const nextOffset = offset + selected.length;
+	const hasMore = nextOffset < units.length;
+	const nextCursor = hasMore ? createDocsPaginationCursor(nextOffset, paginationOptions) : void 0;
+	const content = selected.filter((unit) => unit.type === "content");
+	const tombstones = selected.filter((unit) => unit.type === "tombstone");
+	return {
+		format: DOCS_CONTENT_CHANGE_HYDRATION_FORMAT,
+		audience: "agent",
+		...options.changes.locale ? { locale: options.changes.locale } : {},
+		since: options.since,
+		indexGeneration: options.changes.indexGeneration,
+		mode: options.changes.mode,
+		resetRequired: options.changes.resetRequired,
+		documentCount: options.changes.documentCount,
+		counts: { ...options.changes.counts },
+		budget: {
+			requestedTokens: tokenBudget,
+			strategy: "utf8-bytes",
+			maxUtf8Bytes: tokenBudget,
+			usedUtf8Bytes,
+			conservativeTokenUpperBound: usedUtf8Bytes,
+			remainingUtf8Bytes: Math.max(0, tokenBudget - usedUtf8Bytes)
+		},
+		resultCount: selected.length,
+		total: units.length,
+		hasMore,
+		...nextCursor ? { nextCursor } : {},
+		content,
+		tombstones
+	};
+}
+
+//#endregion
+export { isLocalDocsTelemetryOrigin as C, inferDocsTelemetryAgentSurface as S, resolveDocsTelemetryConfig as T, emitDocsTelemetryAgentSurfaceEvent as _, hydrateDocsContentChanges as a, emitDocsTelemetryProjectEvent as b, hashGeneratedAgentContent as c, serializeGeneratedAgentDocument as d, stripGeneratedAgentProvenance as f, resolveSidebarFolderIndexBehaviorForPath as g, resolveSidebarFolderIndexBehavior as h, MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET as i, normalizeGeneratedAgentContent as l, resolvePageSidebarFolderIndexBehavior as m, DOCS_CONTENT_CHANGE_HYDRATION_FORMAT as n, GENERATED_AGENT_PROVENANCE_MARKER as o, applySidebarFolderIndexBehavior as p, MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET as r, GENERATED_AGENT_PROVENANCE_VERSION as s, DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET as t, parseGeneratedAgentDocument as u, emitDocsTelemetryEvent as v, normalizeDocsTelemetryOrigin as w, getDocsTelemetryFeatures as x, emitDocsTelemetryMcpToolEvent as y };

package/dist/docs-cloud-server.d.mts

@@ -1,5 +1,5 @@
-import { at as DocsAnalyticsEvent, it as DocsAnalyticsConfig, ot as DocsAnalyticsEventInput } from "./types-o-ULHPK6.mjs";
-import { n as DocsCloudAskAIResponseOptions, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-o41WfOTk.mjs";
+import { ct as DocsAnalyticsEventInput, ot as DocsAnalyticsConfig, st as DocsAnalyticsEvent } from "./types-lGEHcx_6.mjs";
+import { n as DocsCloudAskAIResponseOptions, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-BQAeHkpZ.mjs";
 
 //#region src/docs-cloud-server.d.ts
 type DocsCloudRuntimeValue<T = string> = T | undefined | null | (() => T | undefined | null);

package/dist/docs-cloud-server.mjs

@@ -1,5 +1,5 @@
 import { n as sendDocsCloudAnalyticsEvent } from "./cloud-analytics-CSyFE6SS.mjs";
-import { t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-sbpjOR2K.mjs";
+import { t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-BRBK4RBG.mjs";
 
 //#region src/docs-cloud-server.ts
 const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";

package/dist/{doctor-BxP-UHaE.mjs → doctor-WjuyRWYT.mjs}

@@ -1,26 +1,26 @@
-import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-aWl_O6xn.mjs";
-import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-CMMoF6AY.mjs";
-import { A as buildDocsAgentDiscoverySpec, At as DEFAULT_SITEMAP_XML_ROUTE, F as buildDocsMcpEndpointCandidates, Gn as getDocsMcpProtectedResourceMetadataRoutes, It as resolveDocsSitemapConfig, Jn as isDocsMcpOAuthScopeToken, M as buildDocsConfigMap, Ot as DEFAULT_SITEMAP_MD_ROUTE, Qn as normalizeDocsMcpAuthorizationServerUrls, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, Un as DEFAULT_MCP_WELL_KNOWN_ROUTE, Vn as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, kt as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, pn as resolveAskAISearchRequestConfig, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-Cj50nyeV.mjs";
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-Biyd8A98.mjs";
+import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-embiJdYt.mjs";
+import { A as buildDocsAgentDiscoverySpec, At as DEFAULT_SITEMAP_XML_ROUTE, F as buildDocsMcpEndpointCandidates, Gn as DEFAULT_MCP_WELL_KNOWN_ROUTE, It as resolveDocsSitemapConfig, M as buildDocsConfigMap, Ot as DEFAULT_SITEMAP_MD_ROUTE, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, Un as DEFAULT_MCP_PUBLIC_ROUTE, Xn as isDocsMcpOAuthScopeToken, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, er as normalizeDocsMcpAuthorizationServerUrls, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, kt as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, pn as resolveAskAISearchRequestConfig, qn as getDocsMcpProtectedResourceMetadataRoutes, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-Dze2Cy5B.mjs";
 import { f as PAGE_AGENT_CONTRACT_FIELDS } from "./markdown-sections-7OoA7ylx.mjs";
 import { isDocsAgentSkillName, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
 import { I as resolveDocsDiscoveryApiRoute, _ as DEFAULT_API_CATALOG_FORMAT, d as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, h as DEFAULT_AGENT_SKILL_FORMAT, l as DEFAULT_AGENT_SKILLS_INDEX_FORMAT, n as API_CATALOG_MEDIA_TYPE, r as API_CATALOG_PROFILE_URI, t as AGENT_SKILLS_DISCOVERY_SCHEMA_URI, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, v as DEFAULT_API_CATALOG_ROUTE } from "./standards-discovery-BKlEnK_H.mjs";
-import "./agent-provenance-C_jgqNTW.mjs";
-import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-BukukxNm.mjs";
+import "./content-change-hydration-DpQ0KdAD.mjs";
+import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-D96X6eVX.mjs";
 import { a as resolveDocsMetadataBaseUrl } from "./metadata-N252j5_a.mjs";
-import "./sitemap-server-DzlV1NOB.mjs";
-import { t as runDocsGoldenTasks } from "./agent-evals-DvQQtN62.mjs";
+import "./sitemap-server-BefXEox6.mjs";
+import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-D5qYU19g.mjs";
+import { t as runDocsGoldenTasks } from "./agent-evals-Burrzyam.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-DnNVNK2M.mjs";
-import { t as resolveConfiguredAgentSkills } from "./agent-skills-server-B2EXn2QD.mjs";
+import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
 import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, r as extractTopLevelConfigObject, s as loadDocsConfigModuleResultWithProjectEnv, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
-import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Bk8MBi3Z.mjs";
+import { a as createAgentUsefulnessPagesFromMcp, i as analyzeAgentUsefulness, n as analyzeConfiguredAgentSkillsProgressiveDisclosure, r as analyzeAgentSurfaceDrift, t as resolveGoldenEvaluationInput } from "./golden-evaluations-B2GHnoFa.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
-import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/server";
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/server";
 import pc from "picocolors";
 
 //#region src/cli/doctor.ts
@@ -606,6 +606,7 @@ function navigationScore(navigationCoverage) {
 const AGENT_OPTIMIZATION_BLOCKING_CHECKS = new Set([
 	"surface-drift",
 	"agent-skills-frontmatter",
+	"agent-skills-progressive-disclosure",
 	"agent-context-quality",
 	"agent-task-completeness",
 	"agent-applicability",
@@ -1680,11 +1681,20 @@ async function inspectAgentReadiness(options = {}) {
 	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	let configuredAgentSkillNames;
 	let configuredAgentSkillsError;
+	let configuredAgentSkillsDisclosure;
+	let configuredAgentSkillsDisclosureError;
 	const configuredAgentSkills = config?.agent?.skills;
-	if (configuredAgentSkills) try {
-		configuredAgentSkillNames = (await resolveConfiguredAgentSkills(configuredAgentSkills, { rootDir })).map((skill) => skill.name);
-	} catch (error) {
-		configuredAgentSkillsError = error instanceof Error ? error.message : String(error);
+	if (configuredAgentSkills) {
+		try {
+			configuredAgentSkillNames = (await resolveConfiguredAgentSkills(configuredAgentSkills, { rootDir })).map((skill) => skill.name);
+		} catch (error) {
+			configuredAgentSkillsError = error instanceof Error ? error.message : String(error);
+		}
+		try {
+			configuredAgentSkillsDisclosure = analyzeConfiguredAgentSkillsProgressiveDisclosure(configuredAgentSkills, { rootDir });
+		} catch (error) {
+			configuredAgentSkillsDisclosureError = error instanceof Error ? error.message : String(error);
+		}
 	}
 	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
 	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
@@ -1812,6 +1822,13 @@ async function inspectAgentReadiness(options = {}) {
 	const checks = [];
 	checks.push(makeCheck("config", "Docs config", configLoad.status === "evaluated" ? "pass" : "warn", configLoad.status === "evaluated" ? 10 : 2, configCheckMax, configLoad.status === "evaluated" ? `Resolved ${path.relative(rootDir, configLoad.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback.`, configLoad.status === "evaluated" ? void 0 : "Fix docs.config module evaluation before relying on resolved diagnostic scores."));
 	checks.push(makeCheck("agent-skills-frontmatter", "Configured Agent Skills frontmatter", configLoad.status !== "evaluated" ? "warn" : configuredAgentSkillsError ? "fail" : "pass", configLoad.status === "evaluated" && !configuredAgentSkillsError ? 1 : 0, 1, configLoad.status !== "evaluated" ? "Not verified because docs.config could not be evaluated." : configuredAgentSkillsError ? configuredAgentSkillsError : configuredAgentSkillNames ? `${configuredAgentSkillNames.length} configured Agent Skill${configuredAgentSkillNames.length === 1 ? "" : "s"} passed full frontmatter validation: ${configuredAgentSkillNames.join(", ")}.` : "No configured Agent Skills require validation.", configuredAgentSkillsError ? "Fix every configured SKILL.md field reported here before building or publishing the docs site." : void 0));
+	const skillDisclosureIssues = configuredAgentSkillsDisclosure?.issues ?? [];
+	const skillDisclosureHasErrors = skillDisclosureIssues.some((issue) => issue.severity === "error");
+	const skillDisclosureStatus = configLoad.status !== "evaluated" ? "warn" : configuredAgentSkillsDisclosureError ? "fail" : skillDisclosureHasErrors ? "fail" : skillDisclosureIssues.length > 0 ? "warn" : "pass";
+	const skillDisclosureDetail = configLoad.status !== "evaluated" ? "Not verified because docs.config could not be evaluated." : configuredAgentSkillsDisclosureError ? configuredAgentSkillsDisclosureError : configuredAgentSkillsDisclosure ? skillDisclosureIssues.length === 0 ? `${configuredAgentSkillsDisclosure.skills.length} configured Agent Skill${configuredAgentSkillsDisclosure.skills.length === 1 ? "" : "s"} stay within line/token budgets, use resolvable shallow references, declare required compatibility, and document bundled scripts.` : `${skillDisclosureIssues.length} progressive-disclosure issue${skillDisclosureIssues.length === 1 ? "" : "s"} across ${configuredAgentSkillsDisclosure.skills.length} configured skill${configuredAgentSkillsDisclosure.skills.length === 1 ? "" : "s"}: ${skillDisclosureIssues.slice(0, 4).map((issue) => {
+		return `${path.relative(rootDir, issue.filePath).replace(/\\/g, "/")}${issue.line ? `:${issue.line}` : ""} ${issue.message}`;
+	}).join(" ")}${skillDisclosureIssues.length > 4 ? ` (+${skillDisclosureIssues.length - 4} more)` : ""}` : "No configured Agent Skills require progressive-disclosure analysis.";
+	checks.push(makeCheck("agent-skills-progressive-disclosure", "Agent Skills progressive disclosure", skillDisclosureStatus, skillDisclosureStatus === "pass" ? 5 : skillDisclosureStatus === "warn" ? 2 : 0, 5, skillDisclosureDetail, skillDisclosureStatus === "pass" ? void 0 : "Keep SKILL.md under its configured line and instruction-token budgets, repair local references, keep reference chains shallow, declare compatibility requirements, and document script dependencies and validation."));
 	const canScoreSurfaceDrift = configLoad.status === "evaluated";
 	checks.push(makeCheck("surface-drift", "Discovery/config/schema consistency", !canScoreSurfaceDrift ? "warn" : surfaceDrift.length === 0 ? "pass" : "fail", !canScoreSurfaceDrift ? 0 : surfaceDrift.length === 0 ? 10 : Math.max(0, 10 - surfaceDrift.length * 2), 10, !canScoreSurfaceDrift ? "Not scored because docs.config could not be evaluated; static parsing cannot prove discovery/config/schema consistency." : surfaceDrift.length === 0 ? "Resolved config, discovery metadata, MCP tool flags, config schema, and agent contract fields agree." : surfaceDrift.slice(0, 3).map((issue) => issue.message).join(" "), canScoreSurfaceDrift && surfaceDrift.length === 0 ? void 0 : canScoreSurfaceDrift ? "Align docs config, agent discovery (including API catalog and Agent Skills routes), MCP tools, config schema, and the canonical page agent contract before publishing." : "Fix docs.config module evaluation so doctor can compare resolved config with discovery and schema surfaces."));
 	const dynamicStaticFallback = configLoad.status === "static-fallback" && /(?:\.\.\.|process\.env|import\.meta\.env|\[[^\]]+\]\s*:|:\s*[A-Za-z_$][\w$]*\s*[,}])/u.test(configContent);