@farming-labs/docs 0.2.52 → 0.2.54

package/dist/agent-export-n-a0GbeU.mjs

@@ -0,0 +1,854 @@
+import { M as buildDocsAgentDiscoverySpec, Mt as renderDocsSitemapXml, Nt as resolveDocsSitemapConfig, Ot as buildDocsSitemapManifest, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, ct as resolveDocsAgentFeedbackConfig, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, it as renderDocsMarkdownDocument, jt as renderDocsSitemapMarkdown, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, nt as renderDocsAgentsDocument, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, ot as renderDocsSkillDocument, rt as renderDocsLlmsTxt, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, xt as toDocsMarkdownUrl, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-DXkXi-pS.mjs";
+import "./search-CJIC1Cqo.mjs";
+import { t as resolveDocsI18n } from "./i18n-CAlj1ADU.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-DAptQnkx.mjs";
+import "./sitemap-server-wsNLyVkb.mjs";
+import "./agent-evals-BD17jOqL.mjs";
+import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-C9awWzEQ.mjs";
+import "./server.mjs";
+import { d as readStringProperty, f as readTopLevelBooleanProperty, h as resolveDocsContentDir, i as loadDocsConfigModule, l as readNavTitle, m as resolveDocsConfigPath, p as readTopLevelStringProperty, r as extractTopLevelConfigObject, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-CydaZ5PB.mjs";
+import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import pc from "picocolors";
+import { createHash, randomUUID } from "node:crypto";
+
+//#region src/cli/agent-export.ts
+const AGENT_EXPORT_AGENTS_MARKER = "<!-- Generated by @farming-labs/docs agent export. -->";
+const AGENTS_GENERATE_MARKER = "<!-- Generated by @farming-labs/docs agents generate. -->";
+const AGENT_BUNDLE_MANIFEST_ROUTE = "/.well-known/agent-bundle.json";
+const AGENT_BUNDLE_INTERNAL_MANIFEST = ".farming-labs/agent-bundle-manifest.json";
+const SKILL_CANONICAL_ROUTE = "/skills/docs/SKILL.md";
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseAgentExportArgs(argv) {
+	const parsed = {};
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--public") {
+			parsed.public = true;
+			continue;
+		}
+		if (arg === "--check") {
+			parsed.check = true;
+			continue;
+		}
+		if (arg.startsWith("--config=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			continue;
+		}
+		if (arg === "--config") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown agent export flag: ${arg}.`);
+	}
+	return parsed;
+}
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function normalizeContent(content) {
+	return `${content.trimEnd()}\n`;
+}
+function publicFilePath(publicDir, route) {
+	const resolved = resolveContainedPath(publicDir, route.replace(/^\/+/, ""));
+	if (!resolved) throw new Error(`Agent Bundle route must stay inside the public directory: ${route}`);
+	return resolved;
+}
+function publicRelativePath(publicDir, filePath) {
+	return path.relative(publicDir, filePath).replace(/\\/g, "/");
+}
+function resolveContainedPath(baseDir, relativePath) {
+	const base = path.resolve(baseDir);
+	const resolved = path.resolve(base, relativePath);
+	if (!isPathWithin(base, resolved)) return void 0;
+	const realBase = resolveThroughNearestExistingAncestor(base);
+	const realResolved = resolveThroughNearestExistingAncestor(resolved);
+	if (!realBase || !realResolved || !isPathWithin(realBase, realResolved)) return void 0;
+	return resolved;
+}
+function isPathWithin(baseDir, candidatePath) {
+	const relative = path.relative(baseDir, candidatePath);
+	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/**
+* Resolve the existing portion of a path so a symlinked ancestor cannot move a future write or
+* delete outside its declared root. Missing suffixes are appended to the nearest real ancestor.
+*/
+function resolveThroughNearestExistingAncestor(absolutePath) {
+	let cursor = path.resolve(absolutePath);
+	const missingSegments = [];
+	while (true) {
+		let exists = false;
+		try {
+			lstatSync(cursor);
+			exists = true;
+		} catch (error) {
+			const code = error.code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") return void 0;
+		}
+		if (exists) try {
+			return path.resolve(realpathSync(cursor), ...missingSegments.reverse());
+		} catch {
+			return;
+		}
+		const parent = path.dirname(cursor);
+		if (parent === cursor) return void 0;
+		missingSegments.push(path.basename(cursor));
+		cursor = parent;
+	}
+}
+function sha256(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+function byteLength(content) {
+	return Buffer.byteLength(content, "utf-8");
+}
+function readExisting(filePath) {
+	return existsSync(filePath) ? readFileSync(filePath, "utf-8") : void 0;
+}
+function atomicWriteFile(filePath, content) {
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporaryPath, content, "utf-8");
+		renameSync(temporaryPath, filePath);
+	} finally {
+		if (existsSync(temporaryPath)) rmSync(temporaryPath, { force: true });
+	}
+}
+function readStaticLlmsConfig(content) {
+	const enabled = readTopLevelBooleanProperty(content, "llmsTxt");
+	if (enabled !== void 0) return enabled;
+	const block = extractNestedObjectLiteral(content, ["llmsTxt"]);
+	if (!block) return void 0;
+	const maxCharsBlock = extractNestedObjectLiteral(content, ["llmsTxt", "maxChars"]);
+	return {
+		enabled: readBooleanProperty(block, "enabled") ?? true,
+		baseUrl: readStringProperty(block, "baseUrl"),
+		siteTitle: readStringProperty(block, "siteTitle"),
+		siteDescription: readStringProperty(block, "siteDescription"),
+		maxChars: maxCharsBlock ? {
+			mode: readStringProperty(maxCharsBlock, "mode"),
+			chars: readNumericProperty(maxCharsBlock, "chars")
+		} : void 0,
+		sections: readStaticLlmsSections(block)
+	};
+}
+function readNumericProperty(content, key) {
+	const match = content.match(new RegExp(`\\b${key}\\b\\s*:\\s*(-?\\d[\\d_]*(?:\\.\\d+)?)`));
+	if (!match) return void 0;
+	const value = Number(match[1].replace(/_/g, ""));
+	return Number.isFinite(value) ? value : void 0;
+}
+function findBalancedDelimiterEnd(content, start, open, close) {
+	let depth = 0;
+	let quote = null;
+	let escaped = false;
+	for (let index = start; index < content.length; index += 1) {
+		const char = content[index];
+		if (quote) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === quote) quote = null;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			quote = char;
+			continue;
+		}
+		if (char === open) depth += 1;
+		if (char !== close) continue;
+		depth -= 1;
+		if (depth === 0) return index;
+	}
+	return -1;
+}
+function extractArrayProperty(content, key) {
+	const keyIndex = content.search(new RegExp(`\\b${key}\\b\\s*:\\s*\\[`));
+	if (keyIndex === -1) return void 0;
+	const start = content.indexOf("[", keyIndex);
+	if (start === -1) return void 0;
+	const end = findBalancedDelimiterEnd(content, start, "[", "]");
+	return end === -1 ? void 0 : content.slice(start + 1, end);
+}
+function readStaticLlmsSections(content) {
+	const sections = extractArrayProperty(content, "sections");
+	if (!sections) return void 0;
+	const result = [];
+	for (let index = 0; index < sections.length; index += 1) {
+		if (sections[index] !== "{") continue;
+		const end = findBalancedDelimiterEnd(sections, index, "{", "}");
+		if (end === -1) break;
+		const block = sections.slice(index + 1, end);
+		const title = readStringProperty(block, "title");
+		const match = readStringProperty(block, "match") ?? readStringArrayProperty(block, "match");
+		if (title && (typeof match === "string" || match.length > 0)) {
+			const maxCharsBlock = extractNestedObjectLiteral(block, ["maxChars"]);
+			result.push({
+				title,
+				description: readStringProperty(block, "description"),
+				match,
+				maxChars: maxCharsBlock ? {
+					mode: readStringProperty(maxCharsBlock, "mode"),
+					chars: readNumericProperty(maxCharsBlock, "chars")
+				} : void 0
+			});
+		}
+		index = end;
+	}
+	return result.length > 0 ? result : void 0;
+}
+function readStaticSitemapConfig(content) {
+	const enabled = readTopLevelBooleanProperty(content, "sitemap");
+	if (enabled !== void 0) return enabled;
+	const block = extractNestedObjectLiteral(content, ["sitemap"]);
+	if (!block) return void 0;
+	const xmlBoolean = readTopLevelBooleanProperty(block, "xml");
+	const xmlBlock = extractNestedObjectLiteral(content, ["sitemap", "xml"]);
+	const markdownBoolean = readTopLevelBooleanProperty(block, "markdown");
+	const markdownBlock = extractNestedObjectLiteral(content, ["sitemap", "markdown"]);
+	return {
+		enabled: readBooleanProperty(block, "enabled") ?? true,
+		routePrefix: readStringProperty(block, "routePrefix"),
+		baseUrl: readStringProperty(block, "baseUrl"),
+		manifestPath: readStringProperty(block, "manifestPath"),
+		xml: xmlBoolean ?? (xmlBlock ? {
+			enabled: readBooleanProperty(xmlBlock, "enabled"),
+			includeLastmod: readBooleanProperty(xmlBlock, "includeLastmod")
+		} : void 0),
+		markdown: markdownBoolean ?? (markdownBlock ? {
+			enabled: readBooleanProperty(markdownBlock, "enabled"),
+			includeDescriptions: readBooleanProperty(markdownBlock, "includeDescriptions"),
+			includeLastmod: readBooleanProperty(markdownBlock, "includeLastmod"),
+			linkTarget: readStringProperty(markdownBlock, "linkTarget")
+		} : void 0)
+	};
+}
+function readStaticRobotsConfig(content) {
+	const enabled = readTopLevelBooleanProperty(content, "robots");
+	if (enabled !== void 0) return enabled;
+	const block = extractNestedObjectLiteral(content, ["robots"]);
+	if (!block) return void 0;
+	const ai = readStringProperty(block, "ai");
+	return {
+		enabled: readBooleanProperty(block, "enabled") ?? true,
+		baseUrl: readStringProperty(block, "baseUrl"),
+		ai: ai === "allow" || ai === "disallow" ? ai : readBooleanProperty(block, "ai")
+	};
+}
+function readStringArrayProperty(content, key) {
+	const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const match = content.match(new RegExp(`\\b${escaped}\\b\\s*:\\s*\\[([\\s\\S]*?)\\]`));
+	if (!match) return [];
+	return [...match[1].matchAll(/["']([^"']+)["']/g)].map((value) => value[1]);
+}
+function readStaticI18nConfig(content) {
+	const block = extractNestedObjectLiteral(content, ["i18n"]);
+	if (!block) return void 0;
+	const locales = readStringArrayProperty(block, "locales");
+	if (locales.length === 0) return void 0;
+	return {
+		locales,
+		defaultLocale: readStringProperty(block, "defaultLocale")
+	};
+}
+function readStaticMetadataDescription(content) {
+	const block = extractNestedObjectLiteral(content, ["metadata"]);
+	return block ? readStringProperty(block, "description") : void 0;
+}
+function readStaticDocsPath(content) {
+	const configured = readTopLevelStringProperty(content, "docsPath");
+	if (configured !== void 0) return configured;
+	const root = extractTopLevelConfigObject(content) ?? content;
+	return /\bdocsPath\b\s*:\s*(["'])\1/.test(root) ? "" : void 0;
+}
+function buildPageUrl(routeEntry, slug, locale) {
+	const parts = [
+		routeEntry,
+		locale,
+		slug
+	].flatMap((value) => value ? [normalizePathSegment(value)] : []);
+	return parts.length > 0 ? `/${parts.join("/")}` : "/";
+}
+function staticMarkdownRoute(page, sourceEntry, routeEntry) {
+	if (!routeEntry && !page.slug) return `/${sourceEntry || "docs"}.md`;
+	return toDocsMarkdownUrl(page.url);
+}
+async function loadPages(options) {
+	const localeInputs = options.i18n ? options.i18n.locales.map((locale) => ({
+		locale,
+		directory: path.join(options.contentDir, locale)
+	})) : [{
+		locale: void 0,
+		directory: options.contentDir
+	}];
+	const pages = [];
+	for (const input of localeInputs) {
+		const source = createFilesystemDocsMcpSource({
+			rootDir: options.rootDir,
+			entry: options.routeEntry || "docs",
+			contentDir: input.directory,
+			siteTitle: options.siteTitle,
+			ordering: options.ordering
+		});
+		const scanned = await Promise.resolve(source.getPages());
+		const localeRoute = input.locale && input.locale !== options.i18n?.defaultLocale ? input.locale : void 0;
+		for (const page of scanned) pages.push({
+			locale: input.locale,
+			page: {
+				...page,
+				url: buildPageUrl(options.routeEntry, page.slug, localeRoute)
+			}
+		});
+	}
+	return pages;
+}
+function formatDateOnly(value) {
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) return void 0;
+	return parsed.toISOString().slice(0, 10);
+}
+function pageGitLastmod(rootDir, page) {
+	if (page.sourcePath) try {
+		const lastmod = formatDateOnly(execFileSync("git", [
+			"log",
+			"-1",
+			"--format=%cI",
+			"--",
+			page.sourcePath
+		], {
+			cwd: rootDir,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim());
+		if (lastmod) return lastmod;
+	} catch {}
+}
+function deterministicSitemapManifest(options) {
+	const manifest = buildDocsSitemapManifest({
+		pages: options.pages,
+		entry: options.entry,
+		siteTitle: options.siteTitle,
+		baseUrl: options.baseUrl,
+		generatedAt: "1970-01-01T00:00:00.000Z",
+		resolveLastmod(page) {
+			const lastmod = formatDateOnly(page.lastModified ?? "");
+			return lastmod ? {
+				lastmod,
+				lastmodSource: "git"
+			} : void 0;
+		}
+	});
+	manifest.generatedAt = `${manifest.pages.reduce((current, page) => {
+		if (!page.lastmod) return current;
+		return !current || page.lastmod > current ? page.lastmod : current;
+	}, void 0) ?? "1970-01-01"}T00:00:00.000Z`;
+	return manifest;
+}
+function isManagedAgentsContent(content) {
+	return content.includes(AGENT_EXPORT_AGENTS_MARKER) || content.includes(AGENTS_GENERATE_MARKER);
+}
+function findPublicAgentsSource(publicDir) {
+	for (const route of [
+		DEFAULT_AGENTS_MD_ROUTE,
+		DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+		DEFAULT_AGENT_MD_ROUTE,
+		DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE
+	]) {
+		const content = readExisting(publicFilePath(publicDir, route));
+		if (content !== void 0 && !isManagedAgentsContent(content)) return normalizeContent(content);
+	}
+}
+function addOutput(outputs, publicDir, route, kind, mediaType, content, managed = true) {
+	const absolutePath = publicFilePath(publicDir, route);
+	if (absolutePath === publicFilePath(publicDir, AGENT_BUNDLE_MANIFEST_ROUTE)) throw new Error(`Agent Bundle output collision at ${route} (reserved bundle manifest). Change the conflicting docs slug or configured route.`);
+	const collision = outputs.find((output) => output.absolutePath === absolutePath);
+	if (collision) throw new Error(`Agent Bundle output collision at ${route} (${collision.kind} and ${kind}). Change the conflicting docs slug or configured route.`);
+	outputs.push({
+		absolutePath,
+		publicPath: publicRelativePath(publicDir, absolutePath),
+		route,
+		kind,
+		mediaType,
+		content: normalizeContent(content),
+		managed
+	});
+}
+function assertOutputPathsDoNotCollide(options) {
+	const claimed = new Map([[options.publicManifestPath, "public Agent Bundle manifest"], [options.internalManifestPath, "internal Agent Bundle manifest"]]);
+	for (const output of options.outputs) {
+		const owner = claimed.get(output.absolutePath);
+		if (owner) throw new Error(`Agent Bundle output collision at ${output.route} (${owner} and ${output.kind}). Change the conflicting docs slug or configured route.`);
+		claimed.set(output.absolutePath, `${output.kind} output`);
+	}
+	for (const output of options.internalOutputs) {
+		const owner = claimed.get(output.absolutePath);
+		if (owner) throw new Error(`Agent Bundle output collision at ${output.path} (${owner} and internal ${output.kind}). Change the conflicting manifest path.`);
+		claimed.set(output.absolutePath, `internal ${output.kind} output`);
+	}
+}
+function resolveUserOwnedAgentsOutputs(outputs) {
+	return outputs.map((output) => {
+		if (output.kind !== "agents") return output;
+		const current = readExisting(output.absolutePath);
+		if (current === void 0 || isManagedAgentsContent(current)) return output;
+		return {
+			...output,
+			content: normalizeContent(current),
+			managed: false
+		};
+	});
+}
+function resolveUserOwnedOverrides(outputs, previous) {
+	const preserveKinds = new Set([
+		"page",
+		"llms",
+		"discovery",
+		"skill"
+	]);
+	const previousByPath = new Map(previous?.files.map((file) => [file.path, file]) ?? []);
+	return outputs.map((output) => {
+		if (!preserveKinds.has(output.kind)) return output;
+		const current = readExisting(output.absolutePath);
+		if (current === void 0 || current === output.content) return output;
+		const previousFile = previousByPath.get(output.publicPath);
+		if (previousFile?.managed && sha256(current) === previousFile.sha256) return output;
+		return {
+			...output,
+			content: normalizeContent(current),
+			managed: false
+		};
+	});
+}
+function resolveRobotsOutput(publicDir, entry, sitemap, robots) {
+	const route = "/robots.txt";
+	const absolutePath = publicFilePath(publicDir, route);
+	const existing = readExisting(absolutePath);
+	const generatedBlock = renderDocsRobotsGeneratedBlock({
+		entry,
+		sitemap,
+		baseUrl: robots.baseUrl,
+		robots
+	});
+	const hasManagedBlock = existing?.includes(DOCS_ROBOTS_GENERATED_BLOCK_START) === true && existing.includes(DOCS_ROBOTS_GENERATED_BLOCK_END);
+	if (existing !== void 0 && !hasManagedBlock) return {
+		absolutePath,
+		publicPath: publicRelativePath(publicDir, absolutePath),
+		route,
+		kind: "robots",
+		mediaType: "text/plain",
+		content: normalizeContent(existing),
+		managed: false
+	};
+	return {
+		absolutePath,
+		publicPath: publicRelativePath(publicDir, absolutePath),
+		route,
+		kind: "robots",
+		mediaType: "text/plain",
+		content: normalizeContent(existing && hasManagedBlock ? upsertDocsRobotsGeneratedBlock(existing, generatedBlock) : generatedBlock),
+		managed: true
+	};
+}
+function toManifestFile(output) {
+	return {
+		path: output.publicPath,
+		route: output.route,
+		kind: output.kind,
+		mediaType: output.mediaType,
+		bytes: byteLength(output.content),
+		sha256: sha256(output.content),
+		managed: output.managed
+	};
+}
+function buildAgentBundleManifest(options) {
+	const files = [...options.outputs.map(toManifestFile), ...options.orphanedFiles].sort((left, right) => left.path.localeCompare(right.path));
+	const internalFiles = [...options.internalOutputs.map((output) => ({
+		path: output.path,
+		kind: output.kind,
+		bytes: byteLength(output.content),
+		sha256: sha256(output.content)
+	})), ...options.orphanedInternalFiles].sort((left, right) => left.path.localeCompare(right.path));
+	const contentHash = sha256([...files.map((file) => `public:${file.path}\0${file.sha256}`), ...internalFiles.map((file) => `internal:${file.path}\0${file.sha256}`)].join("\n"));
+	return {
+		format: "farming-labs-agent-bundle.v1",
+		generator: "@farming-labs/docs",
+		entry: options.entry,
+		publicDirectory: options.publicDirectory,
+		baseUrl: options.baseUrl,
+		contentHash,
+		files,
+		internalFiles,
+		pages: options.pages.map(({ page, locale }) => ({
+			route: page.url,
+			markdownRoute: staticMarkdownRoute(page, options.sourceEntry, options.entry),
+			sourcePath: page.sourcePath,
+			locale
+		})).sort((left, right) => left.markdownRoute.localeCompare(right.markdownRoute))
+	};
+}
+function readPreviousManifest(manifestPath) {
+	if (!existsSync(manifestPath)) return void 0;
+	try {
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+		if (manifest.format !== "farming-labs-agent-bundle.v1" || !Array.isArray(manifest.files) || !Array.isArray(manifest.pages)) return;
+		return {
+			...manifest,
+			files: manifest.files.filter((file) => file && typeof file.path === "string" && typeof file.sha256 === "string" && typeof file.managed === "boolean"),
+			internalFiles: Array.isArray(manifest.internalFiles) ? manifest.internalFiles.filter((file) => file && typeof file.path === "string" && typeof file.sha256 === "string") : []
+		};
+	} catch {
+		return;
+	}
+}
+function staleManagedPaths(publicDir, previous, outputs) {
+	if (!previous) return [];
+	const expected = new Set(outputs.map((output) => output.publicPath));
+	return previous.files.filter((file) => (file.managed || file.orphaned === true) && !expected.has(file.path)).map((file) => resolvePreviousOutputPath(publicDir, file.path, "public")).filter((filePath) => existsSync(filePath));
+}
+function staleInternalPaths(rootDir, previous, outputs) {
+	if (!previous?.internalFiles) return [];
+	const expected = new Set(outputs.map((output) => output.path));
+	return previous.internalFiles.filter((file) => !expected.has(file.path)).map((file) => resolvePreviousOutputPath(rootDir, file.path, "internal")).filter((filePath) => existsSync(filePath));
+}
+function resolvePreviousOutputPath(baseDir, relativePath, kind) {
+	const resolved = resolveContainedPath(baseDir, relativePath);
+	if (!resolved) throw new Error(`Previous Agent Bundle manifest contains an unsafe ${kind} output path: ${relativePath}`);
+	return resolved;
+}
+function preservedStaleManifestFiles(publicDir, previous, outputs) {
+	if (!previous) return [];
+	const expected = new Set(outputs.map((output) => output.publicPath));
+	return previous.files.flatMap((file) => {
+		if (!file.managed && file.orphaned !== true || expected.has(file.path)) return [];
+		const current = readExisting(resolvePreviousOutputPath(publicDir, file.path, "public"));
+		if (current === void 0) return [];
+		if (file.orphaned !== true && sha256(current) === file.sha256) return [];
+		return [{
+			...file,
+			bytes: byteLength(current),
+			sha256: sha256(current),
+			managed: false,
+			orphaned: true
+		}];
+	});
+}
+function preservedStaleInternalManifestFiles(rootDir, previous, outputs) {
+	if (!previous?.internalFiles) return [];
+	const expected = new Set(outputs.map((output) => output.path));
+	return previous.internalFiles.flatMap((file) => {
+		if (expected.has(file.path)) return [];
+		const current = readExisting(resolvePreviousOutputPath(rootDir, file.path, "internal"));
+		if (current === void 0) return [];
+		if (file.orphaned !== true && sha256(current) === file.sha256) return [];
+		return [{
+			...file,
+			bytes: byteLength(current),
+			sha256: sha256(current),
+			orphaned: true
+		}];
+	});
+}
+function removeStaleManagedFiles(publicDir, previous, stalePaths) {
+	if (!previous) return [];
+	const removed = [];
+	const previousByPath = new Map(previous.files.map((file) => [resolvePreviousOutputPath(publicDir, file.path, "public"), file]));
+	for (const filePath of stalePaths) {
+		const previousFile = previousByPath.get(filePath);
+		const current = readExisting(filePath);
+		if (!previousFile?.managed || previousFile.orphaned === true || current === void 0 || sha256(current) !== previousFile.sha256) continue;
+		rmSync(filePath);
+		removed.push(filePath);
+	}
+	return removed;
+}
+function removeStaleInternalFiles(rootDir, previous, stalePaths) {
+	if (!previous?.internalFiles) return [];
+	const previousByPath = new Map(previous.internalFiles.map((file) => [resolvePreviousOutputPath(rootDir, file.path, "internal"), file]));
+	const removed = [];
+	for (const filePath of stalePaths) {
+		const previousFile = previousByPath.get(filePath);
+		const current = readExisting(filePath);
+		if (!previousFile || previousFile.orphaned === true || current === void 0 || sha256(current) !== previousFile.sha256) continue;
+		rmSync(filePath);
+		removed.push(filePath);
+	}
+	return removed;
+}
+function changedOutputs(outputs) {
+	return outputs.filter((output) => readExisting(output.absolutePath) !== output.content);
+}
+async function exportAgentBundle(options = {}) {
+	if (!options.public && !options.check) throw new Error("Pass --public to write the static Agent Bundle into the framework public directory.");
+	const rootDir = process.cwd();
+	const loadedConfigModule = await loadDocsConfigModule(rootDir, options.configPath);
+	const configContent = readFileSync(loadedConfigModule?.path ?? resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const config = loadedConfigModule?.config;
+	const sourceEntry = normalizePathSegment(config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs");
+	const routeEntry = normalizePathSegment(config?.docsPath ?? readStaticDocsPath(configContent) ?? sourceEntry);
+	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, sourceEntry || "docs");
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const metadataDescription = config?.metadata?.description ?? readStaticMetadataDescription(configContent);
+	const llmsInput = config?.llmsTxt ?? readStaticLlmsConfig(configContent) ?? true;
+	const llmsConfig = typeof llmsInput === "object" ? llmsInput : void 0;
+	const llmsEnabled = llmsInput !== false && !(typeof llmsInput === "object" && llmsInput.enabled === false);
+	const siteDescription = llmsConfig?.siteDescription ?? metadataDescription;
+	const resolvedSiteTitle = llmsConfig?.siteTitle ?? siteTitle;
+	const sitemapInput = config?.sitemap ?? readStaticSitemapConfig(configContent) ?? true;
+	const baseUrl = llmsConfig?.baseUrl ?? (typeof sitemapInput === "object" ? sitemapInput.baseUrl : void 0);
+	const robotsInput = config?.robots ?? readStaticRobotsConfig(configContent) ?? true;
+	const i18n = resolveDocsI18n(config?.i18n ?? readStaticI18nConfig(configContent));
+	const publicDirectory = detectFramework(rootDir) === "sveltekit" ? "static" : "public";
+	const publicDir = resolveContainedPath(rootDir, publicDirectory);
+	if (!publicDir) throw new Error(`Agent Bundle public directory must resolve inside the project root: ${publicDirectory}`);
+	const internalManifestPath = resolveContainedPath(rootDir, AGENT_BUNDLE_INTERNAL_MANIFEST);
+	if (!internalManifestPath) throw new Error(`Agent Bundle internal manifest must resolve inside the project root: ${AGENT_BUNDLE_INTERNAL_MANIFEST}`);
+	const publicManifestPath = publicFilePath(publicDir, AGENT_BUNDLE_MANIFEST_ROUTE);
+	const previous = readPreviousManifest(internalManifestPath);
+	const localizedPages = (await loadPages({
+		rootDir,
+		contentDir,
+		routeEntry,
+		siteTitle: resolvedSiteTitle,
+		ordering: config?.ordering,
+		i18n
+	})).map(({ page, locale }) => {
+		const gitLastmod = pageGitLastmod(rootDir, page);
+		return {
+			locale,
+			page: {
+				...page,
+				lastModified: gitLastmod
+			}
+		};
+	});
+	if (localizedPages.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
+	const pages = localizedPages.map(({ page }) => page);
+	const sitemap = resolveDocsSitemapConfig(sitemapInput, { baseUrl });
+	const robots = resolveDocsRobotsConfig(robotsInput, { baseUrl: typeof robotsInput === "object" ? robotsInput.baseUrl ?? sitemap.baseUrl : sitemap.baseUrl });
+	const mcp = resolveDocsMcpConfig(false, { defaultName: resolvedSiteTitle });
+	const feedbackConfig = resolveDocsAgentFeedbackConfig(false);
+	const feedback = {
+		enabled: feedbackConfig.enabled,
+		route: feedbackConfig.route,
+		schemaRoute: feedbackConfig.schemaRoute
+	};
+	const openapi = { enabled: false };
+	const llms = {
+		enabled: llmsEnabled,
+		baseUrl,
+		siteTitle: resolvedSiteTitle,
+		siteDescription,
+		maxChars: llmsConfig?.maxChars,
+		sections: llmsConfig?.sections,
+		openapi
+	};
+	const documentOptions = {
+		origin: baseUrl ?? "/",
+		entry: routeEntry || "docs",
+		search: false,
+		mcp,
+		feedback,
+		llms,
+		sitemap: sitemapInput,
+		robots: robotsInput,
+		openapi,
+		markdown: { acceptHeader: false }
+	};
+	let outputs = [];
+	const internalOutputs = [];
+	for (const { page } of localizedPages) addOutput(outputs, publicDir, staticMarkdownRoute(page, sourceEntry, routeEntry), "page", "text/markdown", renderDocsMarkdownDocument({
+		...page,
+		markdownUrl: staticMarkdownRoute(page, sourceEntry, routeEntry)
+	}, {
+		llms,
+		origin: baseUrl,
+		sitemap: sitemapInput
+	}));
+	if (llmsEnabled) {
+		const llmsContent = renderDocsLlmsTxt(pages.map((page) => ({
+			url: page.url,
+			markdownUrl: staticMarkdownRoute(page, sourceEntry, routeEntry),
+			title: page.title,
+			description: page.description,
+			content: page.agentRawContent ?? page.agentFallbackRawContent ?? page.rawContent ?? page.content
+		})), llms);
+		for (const route of [DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE]) addOutput(outputs, publicDir, route, "llms", "text/plain", llmsContent.llmsTxt);
+		for (const route of [DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE]) addOutput(outputs, publicDir, route, "llms", "text/plain", llmsContent.llmsFullTxt);
+		const sectionRoutes = new Set(llmsContent.sections.flatMap((section) => [section.route, section.fullRoute]));
+		const llmsBaseRoutes = new Set([sourceEntry, routeEntry].filter(Boolean));
+		for (const llmsBaseRoute of llmsBaseRoutes) {
+			const entryLlmsRoute = `/${llmsBaseRoute}/llms.txt`;
+			const entryLlmsFullRoute = `/${llmsBaseRoute}/llms-full.txt`;
+			if (!sectionRoutes.has(entryLlmsRoute)) addOutput(outputs, publicDir, entryLlmsRoute, "llms", "text/plain", llmsContent.llmsTxt);
+			if (!sectionRoutes.has(entryLlmsFullRoute)) addOutput(outputs, publicDir, entryLlmsFullRoute, "llms", "text/plain", llmsContent.llmsFullTxt);
+		}
+		for (const section of llmsContent.sections) {
+			addOutput(outputs, publicDir, section.route, "llms", "text/plain", section.llmsTxt);
+			addOutput(outputs, publicDir, section.fullRoute, "llms", "text/plain", section.llmsFullTxt);
+		}
+	}
+	const discoveryWithBundle = {
+		...buildDocsAgentDiscoverySpec({
+			...documentOptions,
+			i18n
+		}),
+		staticBundle: {
+			format: "farming-labs-agent-bundle.v1",
+			manifest: AGENT_BUNDLE_MANIFEST_ROUTE,
+			check: "docs agent export --check",
+			locales: i18n ? {
+				default: i18n.defaultLocale,
+				pathPattern: `${routeEntry ? `/${routeEntry}` : ""}/{locale}/{slug}.md`
+			} : void 0
+		}
+	};
+	const discoveryJson = JSON.stringify(discoveryWithBundle, null, 2);
+	for (const route of [DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE]) addOutput(outputs, publicDir, route, "discovery", "application/json", discoveryJson);
+	const generatedSkill = renderDocsSkillDocument(documentOptions);
+	const rootSkillPath = path.join(rootDir, "skill.md");
+	const publicSkill = existsSync(rootSkillPath) ? readFileSync(rootSkillPath, "utf-8") : generatedSkill;
+	for (const route of [DEFAULT_SKILL_MD_ROUTE, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE]) addOutput(outputs, publicDir, route, "skill", "text/markdown", publicSkill);
+	addOutput(outputs, publicDir, SKILL_CANONICAL_ROUTE, "skill", "text/markdown", generatedSkill);
+	const generatedAgents = `${AGENT_EXPORT_AGENTS_MARKER}\n${renderDocsAgentsDocument(documentOptions)}`;
+	const publicAgentsSource = findPublicAgentsSource(publicDir) ?? generatedAgents;
+	for (const route of [
+		DEFAULT_AGENTS_MD_ROUTE,
+		DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+		DEFAULT_AGENT_MD_ROUTE,
+		DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE
+	]) addOutput(outputs, publicDir, route, "agents", "text/markdown", publicAgentsSource);
+	outputs = resolveUserOwnedAgentsOutputs(outputs);
+	if (sitemap.enabled) {
+		const sitemapManifest = deterministicSitemapManifest({
+			pages: pages.map((page) => ({
+				...page,
+				markdownUrl: staticMarkdownRoute(page, sourceEntry, routeEntry)
+			})),
+			entry: routeEntry || "docs",
+			siteTitle: resolvedSiteTitle,
+			baseUrl: sitemap.baseUrl
+		});
+		const sitemapManifestPath = resolveContainedPath(rootDir, sitemap.manifestPath);
+		if (!sitemapManifestPath) throw new Error("sitemap.manifestPath must stay inside the project root for agent export.");
+		if (sitemapManifestPath === internalManifestPath) throw new Error(`sitemap.manifestPath conflicts with ${AGENT_BUNDLE_INTERNAL_MANIFEST}. Choose a different sitemap manifest path.`);
+		internalOutputs.push({
+			absolutePath: sitemapManifestPath,
+			path: path.relative(rootDir, sitemapManifestPath).replace(/\\/g, "/"),
+			kind: "sitemap",
+			content: `${JSON.stringify(sitemapManifest, null, 2)}\n`
+		});
+		if (sitemap.xml.enabled) addOutput(outputs, publicDir, sitemap.xml.route, "sitemap", "application/xml", renderDocsSitemapXml(sitemapManifest, {
+			baseUrl: sitemap.baseUrl,
+			includeLastmod: sitemap.xml.includeLastmod
+		}));
+		if (sitemap.markdown.enabled) {
+			const sitemapMarkdown = renderDocsSitemapMarkdown(sitemapManifest, {
+				baseUrl: sitemap.baseUrl,
+				includeDescriptions: sitemap.markdown.includeDescriptions,
+				includeLastmod: sitemap.markdown.includeLastmod,
+				linkTarget: sitemap.markdown.linkTarget
+			});
+			for (const route of [
+				sitemap.markdown.route,
+				sitemap.markdown.docsRoute,
+				sitemap.markdown.wellKnownRoute
+			]) if (route) addOutput(outputs, publicDir, route, "sitemap", "text/markdown", sitemapMarkdown);
+		}
+	}
+	if (robots.enabled) outputs.push(resolveRobotsOutput(publicDir, routeEntry || "docs", sitemapInput, robots));
+	assertOutputPathsDoNotCollide({
+		outputs,
+		internalOutputs,
+		publicManifestPath,
+		internalManifestPath
+	});
+	outputs = resolveUserOwnedOverrides(outputs, previous);
+	outputs.sort((left, right) => left.publicPath.localeCompare(right.publicPath));
+	const stalePaths = staleManagedPaths(publicDir, previous, outputs);
+	const staleInternal = staleInternalPaths(rootDir, previous, internalOutputs);
+	const orphanedFiles = preservedStaleManifestFiles(publicDir, previous, outputs);
+	const orphanedInternalFiles = preservedStaleInternalManifestFiles(rootDir, previous, internalOutputs);
+	const manifest = buildAgentBundleManifest({
+		sourceEntry,
+		entry: routeEntry,
+		publicDirectory,
+		baseUrl,
+		outputs,
+		internalOutputs,
+		orphanedFiles,
+		orphanedInternalFiles,
+		pages: localizedPages
+	});
+	const manifestJson = `${JSON.stringify(manifest, null, 2)}\n`;
+	const changed = changedOutputs(outputs);
+	const changedInternalOutputs = internalOutputs.filter((output) => readExisting(output.absolutePath) !== output.content);
+	if (readExisting(publicManifestPath) !== manifestJson) changed.push({
+		absolutePath: publicManifestPath,
+		publicPath: publicRelativePath(publicDir, publicManifestPath),
+		route: AGENT_BUNDLE_MANIFEST_ROUTE,
+		kind: "discovery",
+		mediaType: "application/json",
+		content: manifestJson,
+		managed: true
+	});
+	const internalChanged = readExisting(internalManifestPath) !== manifestJson;
+	if (options.check && (changed.length > 0 || changedInternalOutputs.length > 0 || internalChanged || stalePaths.length > 0 || staleInternal.length > 0)) throw new Error(`Static Agent Bundle is stale (${changed.length + changedInternalOutputs.length + (internalChanged ? 1 : 0) + stalePaths.length + staleInternal.length} output(s)). Run \`docs agent export --public\` to update it.`);
+	if (!options.check) {
+		for (const output of outputs) if (readExisting(output.absolutePath) !== output.content) atomicWriteFile(output.absolutePath, output.content);
+		for (const output of internalOutputs) if (readExisting(output.absolutePath) !== output.content) atomicWriteFile(output.absolutePath, output.content);
+		atomicWriteFile(publicManifestPath, manifestJson);
+		atomicWriteFile(internalManifestPath, manifestJson);
+		const removed = removeStaleManagedFiles(publicDir, previous, stalePaths);
+		removed.push(...removeStaleInternalFiles(rootDir, previous, staleInternal));
+		for (const filePath of removed) console.log(pc.dim(`Removed ${path.relative(rootDir, filePath).replace(/\\/g, "/")}`));
+	}
+	const managedCount = manifest.files.filter((file) => file.managed).length;
+	const customCount = manifest.files.length - managedCount;
+	const orphanedCount = manifest.files.filter((file) => file.orphaned === true).length + manifest.internalFiles.filter((file) => file.orphaned === true).length;
+	console.log(pc.green(options.check ? `Static Agent Bundle is current (${manifest.files.length} files, ${manifest.pages.length} pages).` : `Exported Static Agent Bundle (${manifest.files.length} files, ${manifest.pages.length} pages).`));
+	console.log(pc.dim(`${publicDirectory}/.well-known/agent-bundle.json`));
+	console.log(pc.dim(AGENT_BUNDLE_INTERNAL_MANIFEST));
+	if (customCount > 0) console.log(pc.yellow(`Preserved ${customCount} user-owned public file(s).`));
+	if (orphanedCount > 0) console.log(pc.yellow(`Preserved ${orphanedCount} modified obsolete output(s); remove them manually, then rerun the export.`));
+}
+function printAgentExportHelp() {
+	console.log(`
+${pc.bold("docs agent export")} — Export a complete static Agent Bundle.
+
+${pc.dim("Usage:")}
+  pnpm exec docs ${pc.cyan("agent export --public")}
+  pnpm exec docs ${pc.cyan("agent export --check")}
+
+${pc.dim("Options:")}
+  ${pc.cyan("--public")}            Write static agent files to ${pc.dim("public/")} or SvelteKit ${pc.dim("static/")}
+  ${pc.cyan("--check")}             Fail when exported files or their SHA-256 manifest are stale
+  ${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
+`);
+}
+
+//#endregion
+export { exportAgentBundle, parseAgentExportArgs, printAgentExportHelp };