@farming-labs/docs 0.2.84 → 0.2.87

package/dist/skills-CPDwsMq4.mjs

@@ -0,0 +1,467 @@
+import "./agent-CTOUI2BK.mjs";
+import { _ as hasStructuredPageAgentContract, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
+import "./standards-discovery-Ckx0tN7B.mjs";
+import { isDocsAgentSkillName, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
+import "./content-change-hydration-DLBinuFR.mjs";
+import "./sitemap-server-Ds5z4WQB.mjs";
+import "./agent-skills-server-CwmzAzf_.mjs";
+import "./agent-evals-DCptRrdP.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import "./code-blocks-0wjOsqdJ.mjs";
+import "./server.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { n as estimateAgentSkillInstructionTokens, r as resolveDocsAgentSkillsProgressiveDisclosureConfig } from "./agent-skills-progressive-disclosure-BVvj7nM8.mjs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import pc from "picocolors";
+
+//#region src/cli/skills.ts
+const SKILL_SCAFFOLD_MARKER = "<!-- Generated by @farming-labs/docs skills scaffold. -->";
+const DEFAULT_SKILL_NAME = "docs-workflows";
+const SKILL_SCAFFOLD_VALUE_FLAGS = new Set([
+	"name",
+	"output",
+	"config",
+	"include"
+]);
+function inlineFlag(arg) {
+	const flag = arg.slice(2);
+	const separator = flag.indexOf("=");
+	return {
+		key: (separator === -1 ? flag : flag.slice(0, separator)).trim(),
+		value: separator === -1 ? void 0 : flag.slice(separator + 1)
+	};
+}
+function parseSkillScaffoldArgs(argv) {
+	const parsed = { include: [] };
+	let positionalName;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--check") {
+			parsed.check = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			parsed.dryRun = true;
+			continue;
+		}
+		if (arg === "--force") {
+			parsed.force = true;
+			continue;
+		}
+		if (!arg.startsWith("--")) {
+			if (positionalName) throw new Error(`Unexpected skill scaffold argument: ${arg}.`);
+			positionalName = arg;
+			continue;
+		}
+		const { key, value: inlineValue } = inlineFlag(arg);
+		if (!SKILL_SCAFFOLD_VALUE_FLAGS.has(key)) throw new Error(`Unknown skill scaffold flag: --${key}.`);
+		const value = inlineValue ?? (() => {
+			const next = argv[index + 1];
+			if (!next || next.startsWith("--")) throw new Error(`Missing value for --${key}.`);
+			index += 1;
+			return next;
+		})();
+		switch (key) {
+			case "name":
+				parsed.name = value;
+				break;
+			case "output":
+				parsed.output = value;
+				break;
+			case "config":
+				parsed.configPath = value;
+				break;
+			case "include":
+				parsed.include.push(value);
+				break;
+		}
+	}
+	if (positionalName && parsed.name && positionalName !== parsed.name) throw new Error("Use either the positional skill name or --name, not conflicting values.");
+	parsed.name ??= positionalName;
+	if (parsed.check && parsed.dryRun) throw new Error("Use either --check or --dry-run, not both.");
+	return parsed;
+}
+function normalizeSkillName(value) {
+	return value.normalize("NFKD").replace(/[\u0300-\u036f]/gu, "").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/-{2,}/gu, "-").replace(/^-|-$/gu, "").slice(0, 64).replace(/-$/u, "") || DEFAULT_SKILL_NAME;
+}
+function inferSkillName(siteTitle) {
+	const base = normalizeSkillName(siteTitle);
+	if (base === DEFAULT_SKILL_NAME || base.endsWith("-docs") || base === "docs") return base;
+	return `${base.slice(0, 59).replace(/-$/u, "")}-docs`;
+}
+function normalizeRoutePrefix(value) {
+	const trimmed = value.trim();
+	if (!trimmed) throw new Error("--include requires a non-empty route prefix.");
+	const normalized = `/${(/^https?:\/\//iu.test(trimmed) ? new URL(trimmed).pathname : trimmed).replace(/^\/+|\/+$/gu, "")}`;
+	return normalized === "/" ? normalized : normalized.replace(/\/+$/gu, "");
+}
+function pageMatchesIncludes(page, includes) {
+	if (includes.length === 0) return true;
+	return includes.some((prefix) => prefix === "/" || page.url === prefix || page.url.startsWith(`${prefix}/`));
+}
+function relativeInside(rootDir, candidate) {
+	const relative = path.relative(rootDir, candidate);
+	if (relative === "" || path.isAbsolute(relative) || relative.startsWith("..")) return null;
+	return relative;
+}
+function assertSafeOutputDirectory(rootDir, outputDir) {
+	if (!relativeInside(rootDir, outputDir)) throw new Error("Skill output must be a directory inside the current project root.");
+	let cursor = outputDir;
+	const existing = [];
+	while (relativeInside(rootDir, cursor)) {
+		if (existsSync(cursor)) existing.push(cursor);
+		cursor = path.dirname(cursor);
+	}
+	for (const candidate of existing) if (lstatSync(candidate).isSymbolicLink()) throw new Error(`Skill output cannot traverse a symbolic link: ${candidate}`);
+	if (existsSync(outputDir) && !lstatSync(outputDir).isDirectory()) throw new Error(`Skill output must be a directory: ${outputDir}`);
+}
+function lstatIfPresent(filePath) {
+	try {
+		return lstatSync(filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+function assertSafeScaffoldFile(skillDir, filePath) {
+	if (!relativeInside(skillDir, filePath)) throw new Error(`Skill output file must remain inside the selected skill directory: ${filePath}`);
+	let candidate = filePath;
+	while (true) {
+		const stats = lstatIfPresent(candidate);
+		if (stats?.isSymbolicLink()) throw new Error(`Refusing to traverse symbolic-link skill output: ${candidate}`);
+		if (candidate !== filePath && stats && !stats.isDirectory()) throw new Error(`Skill output parent must be a directory: ${candidate}`);
+		if (candidate === skillDir) break;
+		candidate = path.dirname(candidate);
+	}
+}
+function findNestedSkill(directory, root = directory) {
+	if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return void 0;
+	for (const entry of readdirSync(directory, { withFileTypes: true })) {
+		if (entry.isSymbolicLink()) continue;
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isFile() && entry.name === "SKILL.md" && directory !== root) return entryPath;
+		if (entry.isDirectory()) {
+			const nested = findNestedSkill(entryPath, root);
+			if (nested) return nested;
+		}
+	}
+}
+function yamlString(value) {
+	return JSON.stringify(value.replace(/\s+/gu, " ").trim());
+}
+function inlineCode(value) {
+	const longestRun = Math.max(0, ...[...value.matchAll(/`+/gu)].map((match) => match[0].length));
+	const fence = "`".repeat(longestRun + 1);
+	const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+	return `${fence}${padding}${value}${padding}${fence}`;
+}
+function compactText(value) {
+	return value.replace(/\s+/gu, " ").trim();
+}
+function compareText(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function markdownLabel(value) {
+	return compactText(value).replace(/(\[|\]|\\)/gu, "\\$1");
+}
+function normalizeReferenceStem(value) {
+	return normalizeSkillName(value).slice(0, 56).replace(/-$/u, "") || "overview";
+}
+function referenceStem(page, entry) {
+	const pathname = page.url.split(/[?#]/u, 1)[0] ?? page.url;
+	const escapedEntry = entry.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+	return normalizeReferenceStem(pathname.replace(new RegExp(`^/${escapedEntry}(?:/|$)`, "u"), "") || page.slug || page.title);
+}
+function shortDigest(value) {
+	return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+function buildContractReferences(pages, entry) {
+	const references = [];
+	const usedPaths = /* @__PURE__ */ new Set();
+	for (const page of [...pages].sort((left, right) => compareText(left.url, right.url) || compareText(left.title, right.title))) {
+		const contract = normalizePageAgentFrontmatter(page.agent);
+		if (!contract || !hasStructuredPageAgentContract(contract)) continue;
+		const stem = referenceStem(page, entry);
+		let relativePath = `references/${stem}.md`;
+		if (usedPaths.has(relativePath)) {
+			const digest = shortDigest(`${page.url}:${page.sourcePath ?? page.title}`);
+			relativePath = `references/${stem}-${digest}.md`;
+			let collision = 2;
+			while (usedPaths.has(relativePath)) {
+				relativePath = `references/${stem}-${digest}-${collision}.md`;
+				collision += 1;
+			}
+		}
+		usedPaths.add(relativePath);
+		references.push({
+			page,
+			contract,
+			relativePath
+		});
+	}
+	return references;
+}
+function values(value) {
+	if (typeof value === "string") return [value];
+	return value ?? [];
+}
+function renderApplicability(appliesTo) {
+	if (!appliesTo) return "all documented environments";
+	return [
+		values(appliesTo.framework).length ? `framework ${values(appliesTo.framework).map(inlineCode).join(", ")}` : void 0,
+		values(appliesTo.version).length ? `version ${values(appliesTo.version).map(inlineCode).join(", ")}` : void 0,
+		values(appliesTo.package).length ? `package ${values(appliesTo.package).map(inlineCode).join(", ")}` : void 0
+	].filter(Boolean).join("; ") || "all documented environments";
+}
+function canonicalPageUrl(page, baseUrl) {
+	if (!baseUrl) return page.url;
+	try {
+		return new URL(page.url, baseUrl).toString();
+	} catch {
+		return page.url;
+	}
+}
+function pushList(lines, heading, items) {
+	if (!items?.length) return;
+	lines.push("", `## ${heading}`, "");
+	for (const item of items) lines.push(`- ${item}`);
+}
+function renderContractReference(reference, baseUrl) {
+	const { page, contract } = reference;
+	const source = canonicalPageUrl(page, baseUrl);
+	const lines = [
+		SKILL_SCAFFOLD_MARKER,
+		`# ${compactText(page.title)}`,
+		"",
+		`Source: [${markdownLabel(source)}](<${source}>)`
+	];
+	if (contract.task) lines.push("", "## Task", "", contract.task);
+	if (contract.outcome) lines.push("", "## Expected result", "", contract.outcome);
+	if (contract.appliesTo) {
+		lines.push("", "## Applicability", "");
+		for (const [label, field] of [
+			["Framework", "framework"],
+			["Version", "version"],
+			["Package", "package"]
+		]) {
+			const fieldValues = values(contract.appliesTo[field]);
+			if (fieldValues.length) lines.push(`- ${label}: ${fieldValues.map(inlineCode).join(", ")}`);
+		}
+	}
+	pushList(lines, "Prerequisites", contract.prerequisites);
+	pushList(lines, "Files", contract.files?.map(inlineCode));
+	if (contract.commands?.length) {
+		lines.push("", "## Commands", "");
+		for (const command of contract.commands) {
+			if (typeof command === "string") {
+				lines.push(`- ${inlineCode(command)}`);
+				continue;
+			}
+			const context = [command.cwd ? `working directory ${inlineCode(command.cwd)}` : void 0, command.description].filter(Boolean);
+			lines.push(`- ${inlineCode(command.run)}${context.length ? ` — ${context.join("; ")}` : ""}`);
+		}
+	}
+	pushList(lines, "Side effects", contract.sideEffects);
+	if (contract.verification?.length) {
+		lines.push("", "## Verification", "");
+		for (const step of contract.verification) {
+			if (typeof step === "string") {
+				lines.push(`- ${step}`);
+				continue;
+			}
+			const summary = step.description ?? (step.run ? `Run ${inlineCode(step.run)}` : step.expect);
+			if (!summary) continue;
+			lines.push(`- ${summary}`);
+			if (step.run && step.description) lines.push(`  - Run: ${inlineCode(step.run)}`);
+			if (step.expect) lines.push(`  - Expected: ${step.expect}`);
+		}
+	}
+	if (contract.failureModes?.length || contract.rollback?.length) {
+		lines.push("", "## Recovery and rollback", "");
+		for (const mode of contract.failureModes ?? []) if (typeof mode === "string") lines.push(`- ${mode}`);
+		else lines.push(`- ${mode.symptom}${mode.resolution ? ` — Recovery: ${mode.resolution}` : ""}`);
+		for (const rollback of contract.rollback ?? []) lines.push(`- Rollback: ${rollback}`);
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function renderSkillDocument(options) {
+	const rawDescription = compactText(`Use ${options.siteTitle} structured task contracts to implement, configure, migrate, troubleshoot, or verify documented workflows. Use when a request needs authored prerequisites, commands, expected results, recovery, or rollback guidance.`);
+	const description = rawDescription.length <= 1024 ? rawDescription : `${rawDescription.slice(0, 1023)}…`;
+	const lines = [
+		"---",
+		`name: ${yamlString(options.name)}`,
+		`description: ${yamlString(description)}`,
+		`compatibility: ${yamlString("Requires access to the documented project and any tools, runtimes, credentials, or network capabilities named by the selected task reference.")}`,
+		"---",
+		"",
+		SKILL_SCAFFOLD_MARKER,
+		`# ${options.siteTitle} workflows`
+	];
+	if (options.siteDescription) lines.push("", compactText(options.siteDescription));
+	lines.push("", "## Workflow", "", "1. Match the request to the smallest task in the routing list.", "2. Read only the linked reference for that task; read another reference only when the request spans tasks.", "3. Confirm framework, version, package, prerequisites, files, and side effects before changing anything.", "4. Run documented commands from their stated working directories and verify the observable result.", "5. If verification fails, follow the task's recovery guidance; use rollback steps before trying a different approach.", "6. Cite the canonical source from the selected reference when reporting the result.", "", "## Task routing", "");
+	for (const reference of options.references) {
+		const task = compactText(reference.contract.task ?? reference.page.title);
+		lines.push(`- [${markdownLabel(task)}](${reference.relativePath}) — ${renderApplicability(reference.contract.appliesTo)}`);
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function readStaticBaseUrl(configContent) {
+	for (const key of ["sitemap", "llmsTxt"]) {
+		const block = extractNestedObjectLiteral(configContent, [key]);
+		const baseUrl = block ? readStringProperty(block, "baseUrl") : void 0;
+		if (baseUrl) return baseUrl;
+	}
+}
+function configuredSkillPaths(input) {
+	if (!input) return [];
+	if (typeof input === "string") return [input];
+	if (Array.isArray(input)) return [...input];
+	const paths = input.paths;
+	return typeof paths === "string" ? [paths] : [...paths ?? []];
+}
+function isPublishedByConfig(rootDir, skillDir, input) {
+	return configuredSkillPaths(input).some((configuredPath) => {
+		const absolute = path.resolve(rootDir, configuredPath);
+		if (path.basename(absolute) === "SKILL.md" && path.dirname(absolute) === skillDir) return true;
+		const relative = path.relative(absolute, skillDir);
+		return relative === "" || !path.isAbsolute(relative) && !relative.startsWith("..");
+	});
+}
+function isManagedFile(filePath) {
+	return existsSync(filePath) && readFileSync(filePath, "utf8").includes(SKILL_SCAFFOLD_MARKER);
+}
+function listManagedReferenceFiles(referenceDir) {
+	if (!existsSync(referenceDir) || !lstatSync(referenceDir).isDirectory()) return [];
+	return readdirSync(referenceDir, { withFileTypes: true }).filter((entry) => entry.isFile() && !entry.isSymbolicLink()).map((entry) => path.join(referenceDir, entry.name)).filter(isManagedFile).sort();
+}
+function validateRenderedSkill(document, name, configuredSkills) {
+	const frontmatter = validateDocsAgentSkillFrontmatter(document, { directoryName: name });
+	if (!frontmatter.valid) throw new Error(`Generated Agent Skill frontmatter is invalid:\n${frontmatter.issues.map((issue) => `- ${issue.message}`).join("\n")}`);
+	const limits = resolveDocsAgentSkillsProgressiveDisclosureConfig(configuredSkills);
+	const lineCount = document.split(/\r?\n/gu).length;
+	const tokenEstimate = estimateAgentSkillInstructionTokens(document);
+	if (lineCount > limits.maxSkillLines || tokenEstimate > limits.instructionTokenBudget) throw new Error(`Generated SKILL.md needs ${lineCount} lines and approximately ${tokenEstimate} tokens, exceeding the configured ${limits.maxSkillLines}-line or ${limits.instructionTokenBudget}-token budget. Use one or more --include route prefixes to scaffold smaller focused skills.`);
+}
+function compareScaffoldFiles(skillDir, files, force) {
+	const expected = new Set(files.map((file) => path.resolve(skillDir, file.relativePath)));
+	const changedFiles = [];
+	for (const file of files) {
+		const filePath = path.resolve(skillDir, file.relativePath);
+		assertSafeScaffoldFile(skillDir, filePath);
+		const current = existsSync(filePath) ? readFileSync(filePath, "utf8") : void 0;
+		if (current === file.content) continue;
+		if (current !== void 0 && !force && !current.includes(SKILL_SCAFFOLD_MARKER)) throw new Error(`Refusing to replace user-owned skill file ${filePath}. Use --force or choose another --output directory.`);
+		changedFiles.push(filePath);
+	}
+	return {
+		changedFiles,
+		obsoleteFiles: listManagedReferenceFiles(path.join(skillDir, "references")).filter((filePath) => !expected.has(path.resolve(filePath)))
+	};
+}
+function writeScaffoldFiles(skillDir, files, changedFiles, obsoleteFiles) {
+	const changed = new Set(changedFiles.map((filePath) => path.resolve(filePath)));
+	for (const file of files) {
+		const filePath = path.resolve(skillDir, file.relativePath);
+		if (!changed.has(filePath)) continue;
+		assertSafeScaffoldFile(skillDir, filePath);
+		mkdirSync(path.dirname(filePath), { recursive: true });
+		assertSafeScaffoldFile(skillDir, filePath);
+		writeFileSync(filePath, file.content, "utf8");
+	}
+	for (const filePath of obsoleteFiles) rmSync(filePath);
+}
+async function scaffoldSkillFromContracts(options = {}) {
+	const rootDir = process.cwd();
+	const loaded = await loadDocsConfigModule(rootDir, options.configPath);
+	const configContent = readFileSync(loaded?.path ?? resolveDocsConfigPath(rootDir, options.configPath), "utf8");
+	const config = loaded?.config;
+	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
+	const siteTitle = compactText(typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation");
+	const siteDescription = typeof config?.metadata?.description === "string" ? config.metadata.description : void 0;
+	const configuredBaseUrl = (typeof config?.sitemap === "object" ? config.sitemap.baseUrl : void 0) ?? (typeof config?.llmsTxt === "object" ? config.llmsTxt.baseUrl : void 0) ?? readStaticBaseUrl(configContent);
+	const inferredName = inferSkillName(siteTitle);
+	const name = options.name ? options.name.normalize("NFKC") : options.output ? path.basename(path.resolve(rootDir, options.output)).normalize("NFKC") : inferredName;
+	if (!isDocsAgentSkillName(name)) throw new Error(`Invalid Agent Skill name ${JSON.stringify(name)}. Use lowercase letters, numbers, and single hyphens, up to 64 characters.`);
+	const skillDir = path.resolve(rootDir, options.output ?? path.join("skills", name));
+	assertSafeOutputDirectory(rootDir, skillDir);
+	if (path.basename(skillDir).normalize("NFKC") !== name) throw new Error(`Agent Skill name ${JSON.stringify(name)} must match the --output directory name ${JSON.stringify(path.basename(skillDir))}.`);
+	if (!existsSync(path.join(skillDir, "SKILL.md"))) {
+		const nestedSkill = findNestedSkill(skillDir);
+		if (nestedSkill) throw new Error(`Refusing to turn an Agent Skill collection into one skill because it already contains ${nestedSkill}. Choose a different --output directory.`);
+	}
+	const includes = (options.include ?? []).map(normalizeRoutePrefix);
+	const references = buildContractReferences((await createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle
+	}).getPages()).filter((page) => pageMatchesIncludes(page, includes)), entry);
+	if (references.length === 0) {
+		const detail = includes.length ? ` matching ${includes.join(", ")}` : "";
+		throw new Error(`No structured page agent contracts were found${detail}.`);
+	}
+	const skillDocument = renderSkillDocument({
+		name,
+		siteTitle,
+		siteDescription,
+		references
+	});
+	validateRenderedSkill(skillDocument, name, config?.agent?.skills);
+	const files = [{
+		relativePath: "SKILL.md",
+		content: skillDocument
+	}, ...references.map((reference) => ({
+		relativePath: reference.relativePath,
+		content: renderContractReference(reference, configuredBaseUrl)
+	}))];
+	const { changedFiles, obsoleteFiles } = compareScaffoldFiles(skillDir, files, options.force === true);
+	if (options.check && (changedFiles.length > 0 || obsoleteFiles.length > 0)) throw new Error(`Generated Agent Skill is stale (${changedFiles.length + obsoleteFiles.length} file(s)). Rerun the same \`docs skills scaffold\` command without --check to update it.`);
+	if (!options.check && !options.dryRun) writeScaffoldFiles(skillDir, files, changedFiles, obsoleteFiles);
+	const relativeSkillDir = path.relative(rootDir, skillDir).replaceAll("\\", "/");
+	const status = options.dryRun ? "dry-run" : changedFiles.length > 0 || obsoleteFiles.length > 0 ? "generated" : "current";
+	console.log(status === "dry-run" ? pc.cyan(`Would scaffold ${references.length} task contract(s) into ${relativeSkillDir}/.`) : status === "generated" ? pc.green(`Scaffolded ${references.length} task contract(s) into ${relativeSkillDir}/.`) : pc.green(`Generated Agent Skill is current at ${relativeSkillDir}/.`));
+	if (!options.check && status !== "current") {
+		for (const filePath of changedFiles) console.log(pc.dim(path.relative(rootDir, filePath).replaceAll("\\", "/")));
+		for (const filePath of obsoleteFiles) console.log(pc.dim(`removed ${path.relative(rootDir, filePath).replaceAll("\\", "/")}`));
+	}
+	if (!isPublishedByConfig(rootDir, skillDir, config?.agent?.skills)) console.log(pc.yellow(`Add ${JSON.stringify(relativeSkillDir)} to agent.skills.paths to publish this skill through discovery, exports, and MCP.`));
+	return {
+		skillDir,
+		name,
+		contractCount: references.length,
+		changedFiles,
+		removedFiles: obsoleteFiles,
+		status
+	};
+}
+function printSkillScaffoldHelp() {
+	console.log(`
+${pc.bold("docs skills scaffold")} — Compile structured page contracts into a compact Agent Skill.
+
+${pc.dim("Usage:")}
+  pnpm exec docs ${pc.cyan("skills scaffold")} ${pc.dim("[name]")}
+
+${pc.dim("Options:")}
+  ${pc.cyan("--name <name>")}        Agent Skill name; defaults to a slug of the docs site title
+  ${pc.cyan("--output <directory>")} Full skill directory; defaults to ${pc.dim("skills/<name>")}
+  ${pc.cyan("--include <route>")}    Include one route prefix; repeat to combine focused sections
+  ${pc.cyan("--check")}              Fail when generated skill files are missing or stale
+  ${pc.cyan("--dry-run")}            Preview file changes without writing them
+  ${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.cyan("-h, --help")}           Show this help message
+
+The command is offline and deterministic. It writes one compact ${pc.dim("SKILL.md")} router and
+one direct ${pc.dim("references/*.md")} file for every selected page with structured agent frontmatter.
+`);
+}
+
+//#endregion
+export { parseSkillScaffoldArgs, printSkillScaffoldHelp, scaffoldSkillFromContracts };

package/dist/{standards-discovery-UdXpOfmN.d.mts → standards-discovery-CG_cZRSx.d.mts}

@@ -1,4 +1,4 @@
-import { A as DocsAgentA2ASecurityScheme, M as DocsAgentA2ASkill, O as DocsAgentA2AProtocolBinding, h as DocsAgentA2AConfig, k as DocsAgentA2ASecurityRequirement, m as DocsAgentA2ACapabilities } from "./types-DQl2dvDl.mjs";
+import { A as DocsAgentA2ASecurityScheme, M as DocsAgentA2ASkill, O as DocsAgentA2AProtocolBinding, h as DocsAgentA2AConfig, k as DocsAgentA2ASecurityRequirement, m as DocsAgentA2ACapabilities } from "./types-CigzkdLB.mjs";
 
 //#region src/standards-discovery.d.ts
 declare const DEFAULT_API_CATALOG_ROUTE = "/.well-known/api-catalog";
@@ -200,6 +200,8 @@ interface CreateDocsStandardsResponseOptions {
   publishedSkills?: readonly DocsPublishedAgentSkill[];
   /** Identity used to publish the optional A2A Agent Card. */
   agentCard?: DocsA2AAgentCardOptions;
+  /** Stable representation generation or source modification time. */
+  lastModified?: string | Date | null;
 }
 /** Resolve the same-origin Docs API pathname used by query-form discovery routes. */
 declare function resolveDocsDiscoveryApiRoute(apiRoute?: string): string;
@@ -242,7 +244,8 @@ declare function createDocsStandardsResponse({
   preferredSkillDocument,
   fallbackSkillDocument,
   publishedSkills,
-  agentCard
+  agentCard,
+  lastModified
 }: CreateDocsStandardsResponseOptions): Promise<Response | null>;
 //#endregion
 export { resolveDocsDiscoveryApiRoute as $, DocsAgentSkillIndexEntry as A, DocsPublishedAgentSkillFile as B, DOCS_AGENT_MANIFEST_FORMAT as C, DocsA2AAgentCard as D, DOCS_AGENT_MANIFEST_VERSION as E, DocsApiCatalogLinkTarget as F, buildDocsA2AAgentCard as G, DocsStandardsDiscoveryRequest as H, DocsApiCatalogOpenApiDefinition as I, buildDocsLegacySkillsIndex as J, buildDocsAgentSkillsIndex as K, DocsApiCatalogOptions as L, DocsApiCatalog as M, DocsApiCatalogApiTarget as N, DocsA2AAgentCardOptions as O, DocsApiCatalogLinkContext as P, isDocsStandardsDiscoveryRequest as Q, DocsDiscoveryApiRouteOptions as R, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX as S, DOCS_AGENT_MANIFEST_SCHEMA_URI as T, DocsStandardsDiscoveryRouteOptions as U, DocsPublishedAgentSkillOptions as V, appendDocsDiscoveryLinkHeader as W, getDocsAgentManifestLinkHeader as X, createDocsStandardsResponse as Y, getDocsDiscoveryLinkHeader as Z, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT as _, DEFAULT_A2A_AGENT_CARD_FORMAT as a, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT as b, DEFAULT_A2A_PROTOCOL_VERSION as c, DEFAULT_AGENT_SKILLS_INDEX_ROUTE as d, resolveDocsPublishedAgentSkill as et, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN as f, DEFAULT_AGENT_SKILL_FORMAT as g, DEFAULT_AGENT_SKILL_FILE_FORMAT as h, CreateDocsStandardsResponseOptions as i, DocsAgentSkillsIndex as j, DocsA2AAgentInterface as k, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN as l, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT as m, API_CATALOG_MEDIA_TYPE as n, sha256DocsDiscoveryContent as nt, DEFAULT_A2A_AGENT_CARD_ROUTE as o, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX as p, buildDocsApiCatalog as q, API_CATALOG_PROFILE_URI as r, DEFAULT_A2A_PROTOCOL_BINDING as s, AGENT_SKILLS_DISCOVERY_SCHEMA_URI as t, resolveDocsStandardsDiscoveryRequest as tt, DEFAULT_AGENT_SKILLS_INDEX_FORMAT as u, DEFAULT_API_CATALOG_FORMAT as v, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE as w, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE as x, DEFAULT_API_CATALOG_ROUTE as y, DocsPublishedAgentSkill as z };