@farming-labs/docs 0.2.84 → 0.2.87

package/dist/agent-skills-progressive-disclosure-BVvj7nM8.mjs

@@ -0,0 +1,308 @@
+import { validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
+import { n as resolveConfiguredAgentSkillPathsSync } from "./agent-skills-server-CwmzAzf_.mjs";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+//#region src/agent-skills-progressive-disclosure.ts
+const DEFAULT_AGENT_SKILL_MAX_LINES = 500;
+const DEFAULT_AGENT_SKILL_INSTRUCTION_TOKEN_BUDGET = 5e3;
+const DEFAULT_AGENT_SKILL_MAX_REFERENCE_DEPTH = 1;
+const MARKDOWN_LINK_PATTERN = /!?\[[^\]]*\]\(([^)\n]+)\)/gu;
+const SKILL_PATH_PATTERN = /(?:^|[\s"'`(])((?:\.\/)?(?:references|scripts|assets)\/[\p{L}\p{N}@._+\-/]+)/gmu;
+const REQUIREMENT_PATTERN = /\b(?:requires?|prerequisites?|node(?:\.js)?|python|npm|pnpm|yarn|bun|deno|docker|git|network access|internet access|api key|environment variables?|macos|linux|windows)\b/iu;
+const DEPENDENCY_DOCUMENTATION_PATTERN = /\b(?:dependenc(?:y|ies)|requires?|prerequisites?|self-contained|standard library|no external dependencies)\b/iu;
+const VALIDATION_DOCUMENTATION_PATTERN = /\b(?:validate|validation|verify|verification|tests?|expected (?:result|output)|--check|--dry-run)\b/iu;
+const PUBLISHED_SKILL_ROOTS = new Set([
+	"references",
+	"scripts",
+	"assets"
+]);
+const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]);
+function positiveInteger(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}
+function nonNegativeInteger(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+}
+function readProgressiveDisclosureConfig(input) {
+	if (!input || typeof input === "string" || Array.isArray(input)) return void 0;
+	return input.progressiveDisclosure;
+}
+function resolveDocsAgentSkillsProgressiveDisclosureConfig(input) {
+	const config = readProgressiveDisclosureConfig(input);
+	return {
+		maxSkillLines: positiveInteger(config?.maxSkillLines, DEFAULT_AGENT_SKILL_MAX_LINES),
+		instructionTokenBudget: positiveInteger(config?.instructionTokenBudget, DEFAULT_AGENT_SKILL_INSTRUCTION_TOKEN_BUDGET),
+		maxReferenceDepth: nonNegativeInteger(config?.maxReferenceDepth, DEFAULT_AGENT_SKILL_MAX_REFERENCE_DEPTH),
+		compatibility: config?.compatibility === "always" || config?.compatibility === "off" || config?.compatibility === "when-needed" ? config.compatibility : "when-needed",
+		checkScripts: config?.checkScripts !== false
+	};
+}
+function stripFrontmatter(document) {
+	if (!/^---[ \t]*(?:\r?\n)/u.test(document)) return document;
+	const closing = /^---[ \t]*(?:\r?\n|$)/gmu;
+	closing.lastIndex = document.indexOf("\n") + 1;
+	const match = closing.exec(document);
+	return match ? document.slice(match.index + match[0].length) : document;
+}
+/**
+* Dependency-free estimate for diagnostics, deliberately using three UTF-8 bytes per token
+* so code-heavy instructions are less likely to be under-counted.
+*/
+function estimateAgentSkillInstructionTokens(document) {
+	return Math.ceil(Buffer.byteLength(stripFrontmatter(document), "utf8") / 3);
+}
+function lineForIndex(source, index) {
+	return source.slice(0, index).split(/\r?\n/u).length;
+}
+function cleanReferenceTarget(rawTarget) {
+	let target = rawTarget.trim();
+	if (target.startsWith("<") && target.includes(">")) target = target.slice(1, target.indexOf(">"));
+	else target = target.split(/\s+(?=["'])/u, 1)[0] ?? "";
+	if (!target || target.startsWith("#") || target.startsWith("/") || /^[a-z][a-z\d+.-]*:/iu.test(target) || target.includes("{") || target.includes("}")) return null;
+	const withoutFragment = target.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+	if (!withoutFragment) return null;
+	try {
+		return decodeURIComponent(withoutFragment).replace(/^\.\//u, "").replace(/[.,;:!?]+$/u, "");
+	} catch {
+		return withoutFragment.replace(/^\.\//u, "").replace(/[.,;:!?]+$/u, "");
+	}
+}
+function extractLocalReferences(source) {
+	const references = [];
+	const seen = /* @__PURE__ */ new Set();
+	let match;
+	MARKDOWN_LINK_PATTERN.lastIndex = 0;
+	while (match = MARKDOWN_LINK_PATTERN.exec(source)) {
+		if (match[0]?.startsWith("!")) continue;
+		const target = cleanReferenceTarget(match[1] ?? "");
+		if (!target) continue;
+		const index = match.index + (match[0]?.indexOf(match[1] ?? "") ?? 0);
+		const key = `${target}:${index}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		references.push({
+			target,
+			index,
+			line: lineForIndex(source, index)
+		});
+	}
+	SKILL_PATH_PATTERN.lastIndex = 0;
+	while (match = SKILL_PATH_PATTERN.exec(source)) {
+		const target = cleanReferenceTarget(match[1] ?? "");
+		if (!target) continue;
+		const index = match.index + (match[0]?.lastIndexOf(match[1] ?? "") ?? 0);
+		const key = `${target}:${index}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		references.push({
+			target,
+			index,
+			line: lineForIndex(source, index)
+		});
+	}
+	return references.sort((left, right) => left.index - right.index);
+}
+function isInside(parent, candidate) {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function toSkillRelativePath(skillDir, filePath) {
+	return path.relative(skillDir, filePath).replaceAll("\\", "/");
+}
+function isPublishedSkillPath(relativePath) {
+	if (relativePath === "SKILL.md") return true;
+	const [root] = relativePath.split("/");
+	return Boolean(root && PUBLISHED_SKILL_ROOTS.has(root));
+}
+function resolveReferencePath(skillDir, currentFilePath, target) {
+	const [root] = target.replaceAll("\\", "/").replace(/^\.\//u, "").split("/");
+	return path.resolve(root && PUBLISHED_SKILL_ROOTS.has(root) ? skillDir : path.dirname(currentFilePath), target);
+}
+function listRegularFiles(directory) {
+	if (!existsSync(directory)) return [];
+	const files = [];
+	for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) files.push(...listRegularFiles(entryPath));
+		else if (entry.isFile()) files.push(entryPath);
+	}
+	return files;
+}
+function issue(issues, input) {
+	issues.push(input);
+}
+function analyzeOneSkill(skillPath, config) {
+	const skillDir = path.dirname(skillPath);
+	const document = readFileSync(skillPath, "utf8");
+	const frontmatter = validateDocsAgentSkillFrontmatter(document, { directoryName: path.basename(skillDir) });
+	const name = frontmatter.valid ? frontmatter.data.name : path.basename(skillDir);
+	const issues = [];
+	const lineCount = document.split(/\r?\n/u).length;
+	const estimatedInstructionTokens = estimateAgentSkillInstructionTokens(document);
+	if (lineCount > config.maxSkillLines) issue(issues, {
+		code: "skill-lines-exceeded",
+		severity: "warning",
+		skill: name,
+		skillPath,
+		filePath: skillPath,
+		line: 1,
+		message: `SKILL.md has ${lineCount} lines, exceeding the configured ${config.maxSkillLines}-line limit; move detailed material into focused references/.`
+	});
+	if (estimatedInstructionTokens > config.instructionTokenBudget) issue(issues, {
+		code: "skill-token-budget-exceeded",
+		severity: "warning",
+		skill: name,
+		skillPath,
+		filePath: skillPath,
+		line: 1,
+		message: `SKILL.md instructions are approximately ${estimatedInstructionTokens} tokens, exceeding the configured ${config.instructionTokenBudget}-token budget.`
+	});
+	const referenceQueue = [{
+		filePath: skillPath,
+		depth: 0
+	}];
+	const visitedDepth = new Map([[skillPath, 0]]);
+	const markdownDocuments = new Map([[skillPath, document]]);
+	const validReferencePaths = /* @__PURE__ */ new Set();
+	const referencedTargets = /* @__PURE__ */ new Set();
+	for (let cursor = 0; cursor < referenceQueue.length; cursor += 1) {
+		const current = referenceQueue[cursor];
+		const source = markdownDocuments.get(current.filePath) ?? readFileSync(current.filePath, "utf8");
+		markdownDocuments.set(current.filePath, source);
+		for (const reference of extractLocalReferences(source)) {
+			referencedTargets.add(reference.target);
+			const resolved = resolveReferencePath(skillDir, current.filePath, reference.target);
+			if (!isInside(skillDir, resolved)) {
+				issue(issues, {
+					code: "skill-reference-outside-root",
+					severity: "error",
+					skill: name,
+					skillPath,
+					filePath: current.filePath,
+					line: reference.line,
+					message: `Local reference escapes the skill directory: ${reference.target}`
+				});
+				continue;
+			}
+			const relativeTarget = toSkillRelativePath(skillDir, resolved);
+			if (!isPublishedSkillPath(relativeTarget)) {
+				issue(issues, {
+					code: "skill-reference-unpublished",
+					severity: "error",
+					skill: name,
+					skillPath,
+					filePath: current.filePath,
+					line: reference.line,
+					message: `Local reference is outside SKILL.md, references/, scripts/, or assets/ and will not be published: ${reference.target}`
+				});
+				continue;
+			}
+			if (!existsSync(resolved) || !lstatSync(resolved).isFile()) {
+				issue(issues, {
+					code: "skill-reference-broken",
+					severity: "error",
+					skill: name,
+					skillPath,
+					filePath: current.filePath,
+					line: reference.line,
+					message: `Local skill reference does not resolve to a regular file: ${reference.target}`
+				});
+				continue;
+			}
+			validReferencePaths.add(relativeTarget);
+			if (!MARKDOWN_EXTENSIONS.has(path.extname(resolved).toLowerCase())) continue;
+			const nextDepth = current.depth + 1;
+			const previousDepth = visitedDepth.get(resolved);
+			if (resolved !== skillPath && previousDepth === void 0 && nextDepth > config.maxReferenceDepth) issue(issues, {
+				code: "skill-reference-depth-exceeded",
+				severity: "warning",
+				skill: name,
+				skillPath,
+				filePath: current.filePath,
+				line: reference.line,
+				message: `Reference chain reaches depth ${nextDepth}, exceeding the configured maximum of ${config.maxReferenceDepth}: ${reference.target}`
+			});
+			if (previousDepth !== void 0 && previousDepth <= nextDepth) continue;
+			visitedDepth.set(resolved, nextDepth);
+			referenceQueue.push({
+				filePath: resolved,
+				depth: nextDepth
+			});
+		}
+	}
+	const scriptPaths = listRegularFiles(path.join(skillDir, "scripts"));
+	const documentation = [...markdownDocuments.values()].join("\n\n");
+	if ((config.compatibility === "always" || config.compatibility === "when-needed" && (scriptPaths.length > 0 || REQUIREMENT_PATTERN.test(documentation))) && frontmatter.valid && !frontmatter.data.compatibility?.trim()) issue(issues, {
+		code: "skill-compatibility-missing",
+		severity: "warning",
+		skill: name,
+		skillPath,
+		filePath: skillPath,
+		line: 1,
+		message: "Skill instructions require tools, environment capabilities, or scripts but frontmatter does not declare compatibility requirements."
+	});
+	if (config.checkScripts && scriptPaths.length > 0) {
+		const dependencyDocumented = Boolean(frontmatter.valid && frontmatter.data.compatibility?.trim()) || DEPENDENCY_DOCUMENTATION_PATTERN.test(documentation);
+		const validationDocumented = VALIDATION_DOCUMENTATION_PATTERN.test(documentation);
+		for (const scriptPath of scriptPaths) {
+			const relativeScript = toSkillRelativePath(skillDir, scriptPath);
+			if (!validReferencePaths.has(relativeScript)) issue(issues, {
+				code: "skill-script-undocumented",
+				severity: "warning",
+				skill: name,
+				skillPath,
+				filePath: scriptPath,
+				line: 1,
+				message: `Script is bundled but never referenced by SKILL.md or a reachable reference: ${relativeScript}`
+			});
+			if (!dependencyDocumented) issue(issues, {
+				code: "skill-script-dependencies-undocumented",
+				severity: "warning",
+				skill: name,
+				skillPath,
+				filePath: scriptPath,
+				line: 1,
+				message: `Document required runtimes/packages or explicitly state that ${relativeScript} is self-contained.`
+			});
+			if (!validationDocumented) issue(issues, {
+				code: "skill-script-validation-undocumented",
+				severity: "warning",
+				skill: name,
+				skillPath,
+				filePath: scriptPath,
+				line: 1,
+				message: `Document how to validate ${relativeScript}, including an expected result, test, --check, or --dry-run command.`
+			});
+		}
+	}
+	return {
+		summary: {
+			name,
+			skillPath,
+			lineCount,
+			estimatedInstructionTokens,
+			referenceCount: referencedTargets.size,
+			scriptCount: scriptPaths.length
+		},
+		issues
+	};
+}
+function analyzeConfiguredAgentSkillsProgressiveDisclosure(input, options = {}) {
+	const config = resolveDocsAgentSkillsProgressiveDisclosureConfig(input);
+	const analyses = resolveConfiguredAgentSkillPathsSync(input, options).map((skillPath) => analyzeOneSkill(skillPath, config));
+	return {
+		config,
+		skills: analyses.map((analysis) => analysis.summary),
+		issues: analyses.flatMap((analysis) => analysis.issues).sort((left, right) => {
+			const fileOrder = left.filePath.localeCompare(right.filePath);
+			if (fileOrder !== 0) return fileOrder;
+			const lineOrder = (left.line ?? 0) - (right.line ?? 0);
+			return lineOrder !== 0 ? lineOrder : left.code.localeCompare(right.code);
+		})
+	};
+}
+
+//#endregion
+export { estimateAgentSkillInstructionTokens as n, resolveDocsAgentSkillsProgressiveDisclosureConfig as r, analyzeConfiguredAgentSkillsProgressiveDisclosure as t };

package/dist/{agent-skills-server-D5qYU19g.mjs → agent-skills-server-CwmzAzf_.mjs}

@@ -1,4 +1,4 @@
-import { f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, j as buildDocsPublishedAgentSkill } from "./standards-discovery-BKlEnK_H.mjs";
+import { f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, j as buildDocsPublishedAgentSkill } from "./standards-discovery-Ckx0tN7B.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";

package/dist/{agent-skills-server-aKgt9CR9.d.mts → agent-skills-server-DEqyYAhL.d.mts}

@@ -1,5 +1,5 @@
-import { tt as DocsAgentSkillsInput } from "./types-DQl2dvDl.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
+import { tt as DocsAgentSkillsInput } from "./types-CigzkdLB.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-CG_cZRSx.mjs";
 
 //#region src/agent-skills-server.d.ts
 interface ResolveConfiguredAgentSkillsOptions {

package/dist/agent-skills-vite.d.mts

@@ -1,6 +1,6 @@
-import { tt as DocsAgentSkillsInput } from "./types-DQl2dvDl.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
-import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-aKgt9CR9.mjs";
+import { tt as DocsAgentSkillsInput } from "./types-CigzkdLB.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-CG_cZRSx.mjs";
+import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-DEqyYAhL.mjs";
 
 //#region src/agent-skills-vite.d.ts
 declare const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/agent-skills-vite.mjs

@@ -1,5 +1,5 @@
-import "./standards-discovery-BKlEnK_H.mjs";
-import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-D5qYU19g.mjs";
+import "./standards-discovery-Ckx0tN7B.mjs";
+import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-CwmzAzf_.mjs";
 
 //#region src/agent-skills-vite.ts
 const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/{agents-D1j3fKjv.mjs → agents-DjUz5voa.mjs}

@@ -1,10 +1,10 @@
-import { a as DEFAULT_AGENT_MD_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, t as DEFAULT_AGENTS_MD_ROUTE } from "./agent-D68WI6-N.mjs";
+import { a as DEFAULT_AGENT_MD_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, t as DEFAULT_AGENTS_MD_ROUTE } from "./agent-CTOUI2BK.mjs";
 import "./markdown-sections-7OoA7ylx.mjs";
-import "./standards-discovery-BKlEnK_H.mjs";
-import "./content-change-hydration-CiMxs3LF.mjs";
-import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-_AeFxJQB.mjs";
-import "./agent-skills-server-D5qYU19g.mjs";
-import "./agent-evals-CEvUQb_Z.mjs";
+import "./standards-discovery-Ckx0tN7B.mjs";
+import "./content-change-hydration-DLBinuFR.mjs";
+import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-Ds5z4WQB.mjs";
+import "./agent-skills-server-CwmzAzf_.mjs";
+import "./agent-evals-DCptRrdP.mjs";
 import { resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";

package/dist/cli/index.mjs

@@ -108,7 +108,7 @@ async function main() {
 		]
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-DAkI0Lkf.mjs");
+		const { init } = await import("../init-D0GcUKJ0.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "dev") {
 		const { dev } = await import("../dev-kjaxOOla.mjs");
@@ -141,10 +141,10 @@ async function main() {
 		printCloudHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "mcp") {
-		const { runMcp } = await import("../mcp-CwTbgrZm.mjs");
+		const { runMcp } = await import("../mcp-7bvRe9Da.mjs");
 		await runMcp(mcpOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "compact") {
-		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-DuwSq3C7.mjs").then((n) => n.t);
+		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-FyPQ2AZ4.mjs").then((n) => n.t);
 		const agentCompactOptions = parseAgentCompactArgs(args.slice(2));
 		if (agentCompactOptions.help) {
 			printAgentCompactHelp();
@@ -152,7 +152,7 @@ async function main() {
 		}
 		await compactAgentDocs(agentCompactOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "export") {
-		const { exportAgentBundle, parseAgentExportArgs, printAgentExportHelp } = await import("../agent-export-BMljO4ll.mjs");
+		const { exportAgentBundle, parseAgentExportArgs, printAgentExportHelp } = await import("../agent-export-Di1Ofstb.mjs");
 		const agentExportOptions = parseAgentExportArgs(args.slice(2));
 		if (agentExportOptions.help) {
 			printAgentExportHelp();
@@ -162,13 +162,13 @@ async function main() {
 	} else if (parsedCommand.command === "agent") {
 		console.error(pc.red(`Unknown agent subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentCompactHelp } = await import("../agent-DuwSq3C7.mjs").then((n) => n.t);
-		const { printAgentExportHelp } = await import("../agent-export-BMljO4ll.mjs");
+		const { printAgentCompactHelp } = await import("../agent-FyPQ2AZ4.mjs").then((n) => n.t);
+		const { printAgentExportHelp } = await import("../agent-export-Di1Ofstb.mjs");
 		printAgentCompactHelp();
 		printAgentExportHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "agents" && subcommand === "generate") {
-		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-D1j3fKjv.mjs");
+		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-DjUz5voa.mjs");
 		const agentsOptions = parseAgentsGenerateArgs(args.slice(2));
 		if (agentsOptions.help) {
 			printAgentsGenerateHelp();
@@ -178,11 +178,28 @@ async function main() {
 	} else if (parsedCommand.command === "agents") {
 		console.error(pc.red(`Unknown agents subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentsGenerateHelp } = await import("../agents-D1j3fKjv.mjs");
+		const { printAgentsGenerateHelp } = await import("../agents-DjUz5voa.mjs");
 		printAgentsGenerateHelp();
 		process.exit(1);
+	} else if (parsedCommand.command === "skills" && subcommand === "scaffold") {
+		const { parseSkillScaffoldArgs, printSkillScaffoldHelp, scaffoldSkillFromContracts } = await import("../skills-CPDwsMq4.mjs");
+		const skillOptions = parseSkillScaffoldArgs(args.slice(2));
+		if (skillOptions.help) {
+			printSkillScaffoldHelp();
+			return;
+		}
+		await scaffoldSkillFromContracts(skillOptions);
+	} else if (parsedCommand.command === "skills" && (subcommand === "--help" || subcommand === "-h")) {
+		const { printSkillScaffoldHelp } = await import("../skills-CPDwsMq4.mjs");
+		printSkillScaffoldHelp();
+	} else if (parsedCommand.command === "skills") {
+		console.error(pc.red(`Unknown skills subcommand: ${subcommand ?? "(missing)"}`));
+		console.error();
+		const { printSkillScaffoldHelp } = await import("../skills-CPDwsMq4.mjs");
+		printSkillScaffoldHelp();
+		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DaZp33gE.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DUnOjP9T.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -190,7 +207,7 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "review") {
-		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-BMO-4X_5.mjs");
+		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-DEnzotkg.mjs");
 		const reviewOptions = parseReviewArgs(args.slice(1));
 		if (reviewOptions.help) {
 			printReviewHelp();
@@ -212,7 +229,7 @@ async function main() {
 		printCodeBlocksValidateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "search" && subcommand === "sync") {
-		const { syncSearch } = await import("../search-ZY4rf1fy.mjs");
+		const { syncSearch } = await import("../search-DznddPqw.mjs");
 		await syncSearch(searchSyncOptions);
 	} else if (parsedCommand.command === "search") {
 		console.error(pc.red(`Unknown search subcommand: ${subcommand ?? "(missing)"}`));
@@ -220,7 +237,7 @@ async function main() {
 		printHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "sitemap" && subcommand === "generate") {
-		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-CAzZFDic.mjs");
+		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-DCsrVSPf.mjs");
 		const sitemapOptions = parseSitemapGenerateArgs(args.slice(2));
 		if (sitemapOptions.help) {
 			printSitemapGenerateHelp();
@@ -230,11 +247,11 @@ async function main() {
 	} else if (parsedCommand.command === "sitemap") {
 		console.error(pc.red(`Unknown sitemap subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printSitemapGenerateHelp } = await import("../sitemap-CAzZFDic.mjs");
+		const { printSitemapGenerateHelp } = await import("../sitemap-DCsrVSPf.mjs");
 		printSitemapGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "robots" && subcommand === "generate") {
-		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-CLtbWSEJ.mjs");
+		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-DXy1xW3D.mjs");
 		const robotsOptions = parseRobotsGenerateArgs(args.slice(2));
 		if (robotsOptions.help) {
 			printRobotsGenerateHelp();
@@ -244,11 +261,11 @@ async function main() {
 	} else if (parsedCommand.command === "robots") {
 		console.error(pc.red(`Unknown robots subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printRobotsGenerateHelp } = await import("../robots-CLtbWSEJ.mjs");
+		const { printRobotsGenerateHelp } = await import("../robots-DXy1xW3D.mjs");
 		printRobotsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "downgrade") {
-		const { downgrade } = await import("../downgrade-w7e6Se0L.mjs");
+		const { downgrade } = await import("../downgrade-Wcgqbfv_.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		await downgrade({
@@ -257,7 +274,7 @@ async function main() {
 			dryRun: flags["dry-run"] === true
 		});
 	} else if (parsedCommand.command === "upgrade") {
-		const { upgrade } = await import("../upgrade-oz-GChgt.mjs");
+		const { upgrade } = await import("../upgrade-BSCjUH0V.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		const version = typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0;
@@ -291,6 +308,7 @@ ${pc.dim("Commands:")}
   ${pc.cyan("cloud")}    Docs Cloud utilities (${pc.dim("init")}, ${pc.dim("check")}, ${pc.dim("deploy")}, ${pc.dim("preview")}, ${pc.dim("sync")})
   ${pc.cyan("agent")}    Agent utilities (${pc.dim("compact")} page context, ${pc.dim("export")} static bundles)
   ${pc.cyan("agents")}   AGENTS.md utilities (${pc.dim("generate")} for static agent instructions)
+  ${pc.cyan("skills")}   Agent Skills utilities (${pc.dim("scaffold")} from structured page contracts)
   ${pc.cyan("doctor")}   Inspect and score agent or reader-facing docs quality
   ${pc.cyan("review")}   Review changed docs files and wire Docs Review CI
   ${pc.cyan("codeblocks")} Validate fenced MDX code blocks (${pc.dim("validate")})
@@ -365,6 +383,15 @@ ${pc.dim("Options for agent export:")}
   ${pc.cyan("agent export --check")}                Fail when the static Agent Bundle is stale
   ${pc.cyan("--config <path>")}                     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
 
+${pc.dim("Options for skills scaffold:")}
+  ${pc.cyan("skills scaffold [name]")}              Compile page agent contracts into a compact ${pc.dim("SKILL.md")} router and focused references
+  ${pc.cyan("--output <directory>")}                Write to a full skill directory; defaults to ${pc.dim("skills/<name>")}
+  ${pc.cyan("--include <route>")}                   Include a route prefix; repeat for multiple focused sections
+  ${pc.cyan("--check")}                             Fail when generated skill files are missing or stale
+  ${pc.cyan("--dry-run")}                           Preview generated skill changes without writing files
+  ${pc.cyan("--force")}                             Replace colliding user-owned files in the selected directory
+  ${pc.cyan("--config <path>")}                     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+
 ${pc.dim("Options for doctor:")}
   ${pc.cyan("doctor")}                              Score the current docs app for agent-readiness
   ${pc.cyan("doctor --agent")}                      Same as ${pc.cyan("doctor")}; explicit agent scoring mode

package/dist/client/react.d.mts

@@ -1,4 +1,4 @@
-import { ot as DocsAnalyticsConfig } from "../types-DQl2dvDl.mjs";
+import { ot as DocsAnalyticsConfig } from "../types-CigzkdLB.mjs";
 import { ReactNode } from "react";
 
 //#region src/docs-cloud-client.d.ts

package/dist/{cloud-ask-ai-Bx-qtqHL.d.mts → cloud-ask-ai-uzDpy0um.d.mts}

@@ -1,4 +1,4 @@
-import { bt as DocsCloudConfig, ot as DocsAnalyticsConfig, t as AIConfig } from "./types-DQl2dvDl.mjs";
+import { bt as DocsCloudConfig, ot as DocsAnalyticsConfig, t as AIConfig } from "./types-CigzkdLB.mjs";
 
 //#region src/cloud-ask-ai.d.ts
 interface DocsCloudAskAIConfig {

package/dist/{content-change-hydration-CiMxs3LF.mjs → content-change-hydration-DLBinuFR.mjs}

@@ -1,5 +1,6 @@
-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-D68WI6-N.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, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, qt as isDocsContentChangesRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-CTOUI2BK.mjs";
 import { s as parseDocsMarkdownSections } from "./markdown-sections-7OoA7ylx.mjs";
+import { K as digestDocsRetrievalContent } from "./standards-discovery-Ckx0tN7B.mjs";
 import matter from "gray-matter";
 
 //#region src/telemetry.ts

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

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

package/dist/{doctor-DaZp33gE.mjs → doctor-DUnOjP9T.mjs}

@@ -1,21 +1,22 @@
-import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-DuwSq3C7.mjs";
-import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-ClTizbsa.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-D68WI6-N.mjs";
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-FyPQ2AZ4.mjs";
+import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-B6gxePm8.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-CTOUI2BK.mjs";
 import { f as PAGE_AGENT_CONTRACT_FIELDS } from "./markdown-sections-7OoA7ylx.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-Ckx0tN7B.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 "./content-change-hydration-CiMxs3LF.mjs";
-import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-HWKsiZQS.mjs";
+import "./content-change-hydration-DLBinuFR.mjs";
+import { a as analyzeDocsRobotsTxt, n as DEFAULT_ROBOTS_TXT_ROUTE, u as resolveDocsRobotsConfig } from "./robots-DaU38DZw.mjs";
 import { a as resolveDocsMetadataBaseUrl } from "./metadata-N252j5_a.mjs";
-import "./sitemap-server-_AeFxJQB.mjs";
-import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-D5qYU19g.mjs";
-import { t as runDocsGoldenTasks } from "./agent-evals-CEvUQb_Z.mjs";
+import "./sitemap-server-Ds5z4WQB.mjs";
+import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-CwmzAzf_.mjs";
+import { t as runDocsGoldenTasks } from "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.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 { a as createAgentUsefulnessPagesFromMcp, i as analyzeAgentUsefulness, n as analyzeConfiguredAgentSkillsProgressiveDisclosure, r as analyzeAgentSurfaceDrift, t as resolveGoldenEvaluationInput } from "./golden-evaluations-BKxcJ1qw.mjs";
+import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-CNDwoUOe.mjs";
+import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-BVvj7nM8.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";

package/dist/{downgrade-w7e6Se0L.mjs → downgrade-Wcgqbfv_.mjs}

@@ -1,5 +1,5 @@
 import { c as fileExists, o as exec, s as execOutput } from "./utils-DpiIioYb.mjs";
-import { a as getPackagesForFramework, c as resolveDocsPackageManager, l as validateUpgradeVersion, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework } from "./package-version-n5AFur8a.mjs";
+import { a as getPackagesForFramework, c as resolveDocsPackageManager, l as validateUpgradeVersion, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework } from "./package-version-B3PJ6IDr.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";