@farming-labs/docs 0.2.62 → 0.2.63

package/dist/agent-CQTH7NFu.mjs

@@ -0,0 +1,624 @@
+import { Jt as normalizePageAgentFrontmatter, L as findDocsMarkdownPage, Zt as stripGeneratedPageAgentContractMarkdown, tt as renderDocsMarkdownDocument } from "./agent-DKKptIgy.mjs";
+import { _ as GENERATED_AGENT_PROVENANCE_VERSION, b as parseGeneratedAgentDocument, v as hashGeneratedAgentContent, x as serializeGeneratedAgentDocument } from "./search-B6V6qtiI.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral, u as readEnvReferenceProperty } from "./config-Wcdj-D0a.mjs";
+import { createRequire } from "node:module";
+import matter from "gray-matter";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import pc from "picocolors";
+
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+//#region src/cli/agent.ts
+var agent_exports = /* @__PURE__ */ __exportAll({
+	compactAgentDocs: () => compactAgentDocs,
+	inspectAgentCompactionState: () => inspectAgentCompactionState,
+	parseAgentCompactArgs: () => parseAgentCompactArgs,
+	printAgentCompactHelp: () => printAgentCompactHelp,
+	readPageTokenBudget: () => readPageTokenBudget,
+	scanDocsPageTargets: () => scanDocsPageTargets
+});
+const DEFAULT_COMPRESSION_BASE_URL = "https://api.farming-labs.dev";
+const DEFAULT_COMPRESSION_MODEL = "docs-cloud-compress-v1";
+const DEFAULT_COMPRESSION_AGGRESSIVENESS = .3;
+const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
+const INDEX_PAGE_BASENAMES = new Set([
+	"index",
+	"page",
+	"+page"
+]);
+function parseBooleanFlag(raw) {
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	throw new Error(`Invalid boolean value: ${raw}. Use true or false.`);
+}
+function parseIntegerFlag(raw, name) {
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed)) throw new Error(`Invalid ${name}: ${raw}.`);
+	return parsed;
+}
+function parseFloatFlag(raw, name) {
+	const parsed = Number.parseFloat(raw);
+	if (!Number.isFinite(parsed)) throw new Error(`Invalid ${name}: ${raw}.`);
+	return parsed;
+}
+function parseAgentCompactArgs(argv) {
+	const parsed = { pages: [] };
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--all") {
+			parsed.all = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			parsed.dryRun = true;
+			continue;
+		}
+		if (arg === "--changed") {
+			parsed.changed = true;
+			continue;
+		}
+		if (arg === "--stale") {
+			parsed.stale = true;
+			continue;
+		}
+		if (arg === "--include-missing") {
+			parsed.includeMissing = true;
+			continue;
+		}
+		if (arg === "--protect-json") {
+			const nextValue = argv[index + 1];
+			if (nextValue && !nextValue.startsWith("--")) {
+				parsed.protectJson = parseBooleanFlag(nextValue);
+				index += 1;
+			} else parsed.protectJson = true;
+			continue;
+		}
+		if (!arg.startsWith("--")) {
+			parsed.pages.push(arg);
+			continue;
+		}
+		const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+		const key = rawKey.trim();
+		const hasInlineValue = inlineValue !== void 0;
+		const nextValue = !hasInlineValue ? argv[index + 1] : void 0;
+		const consumeNextValue = () => {
+			if (!nextValue || nextValue.startsWith("--")) throw new Error(`Missing value for --${key}.`);
+			index += 1;
+			return nextValue;
+		};
+		const value = hasInlineValue ? inlineValue : consumeNextValue();
+		switch (key) {
+			case "page":
+				parsed.pages.push(value);
+				break;
+			case "config":
+				parsed.configPath = value;
+				break;
+			case "api-key":
+				parsed.apiKey = value;
+				break;
+			case "base-url":
+				parsed.baseUrl = value;
+				break;
+			case "api-key-env":
+				parsed.apiKeyEnv = value;
+				break;
+			case "model":
+				parsed.model = value;
+				break;
+			case "aggressiveness":
+				parsed.aggressiveness = parseFloatFlag(value, "aggressiveness");
+				break;
+			case "max-output-tokens":
+				parsed.maxOutputTokens = parseIntegerFlag(value, "max-output-tokens");
+				break;
+			case "min-output-tokens":
+				parsed.minOutputTokens = parseIntegerFlag(value, "min-output-tokens");
+				break;
+			case "protect-json":
+				parsed.protectJson = parseBooleanFlag(value);
+				break;
+			default: throw new Error(`Unknown agent compact flag: --${key}.`);
+		}
+	}
+	return parsed;
+}
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function normalizeUrlPath(value) {
+	const normalized = value.replace(/\/+/g, "/");
+	if (normalized === "/") return normalized;
+	return normalized.replace(/\/+$/, "");
+}
+function normalizeRequestedPage(entry, rawValue) {
+	const trimmed = rawValue.trim();
+	if (!trimmed || trimmed === ".") return `/${normalizePathSegment(entry) || "docs"}`;
+	if (/^https?:\/\//i.test(trimmed)) try {
+		return normalizeUrlPath(new URL(trimmed).pathname.replace(/\.md$/i, ""));
+	} catch {
+		return trimmed;
+	}
+	const withoutMarkdownSuffix = trimmed.replace(/\.md$/i, "");
+	const normalizedEntry = `/${normalizePathSegment(entry) || "docs"}`;
+	const normalized = normalizeUrlPath(withoutMarkdownSuffix.startsWith("/") ? withoutMarkdownSuffix : `/${withoutMarkdownSuffix}`);
+	if (normalized === normalizedEntry || normalized.startsWith(`${normalizedEntry}/`)) return normalized;
+	const slug = normalizePathSegment(withoutMarkdownSuffix);
+	return slug ? normalizeUrlPath(`${normalizedEntry}/${slug}`) : normalizedEntry;
+}
+function scanDocsPageTargets(rootDir, contentDir, entry) {
+	const contentDirAbs = path.resolve(rootDir, contentDir);
+	const targets = [];
+	const visit = (dir, slugParts) => {
+		if (!existsSync(dir)) return;
+		for (const name of readdirSync(dir).sort()) {
+			const fullPath = path.join(dir, name);
+			if (statSync(fullPath).isDirectory()) {
+				visit(fullPath, [...slugParts, name]);
+				continue;
+			}
+			if (name === "agent.md") continue;
+			if (!name.endsWith(".md") && !name.endsWith(".mdx") && !name.endsWith(".svx")) continue;
+			const baseName = name.replace(/\.(md|mdx|svx)$/i, "");
+			if (!INDEX_PAGE_BASENAMES.has(baseName)) continue;
+			const slug = slugParts.join("/");
+			const url = slug ? `/${normalizePathSegment(entry)}/${slug}` : `/${normalizePathSegment(entry)}`;
+			const agentPath = path.join(dir, "agent.md");
+			targets.push({
+				slug,
+				url,
+				pagePath: fullPath,
+				pageDir: dir,
+				agentPath,
+				hasAgentFile: existsSync(agentPath)
+			});
+		}
+	};
+	visit(contentDirAbs, []);
+	return targets;
+}
+function resolveCompressionEndpoint(rawBaseUrl) {
+	const baseUrl = rawBaseUrl ?? process.env.DOCS_CLOUD_COMPRESSION_BASE_URL ?? process.env.DOCS_CLOUD_API_BASE_URL ?? process.env.FARMING_LABS_DOCS_API_BASE_URL ?? DEFAULT_COMPRESSION_BASE_URL;
+	if (/\/v1\/(?:compress|agent\/compact)\/?$/i.test(baseUrl)) return baseUrl.replace(/\/+$/, "");
+	return `${baseUrl.replace(/\/+$/, "")}/v1/compress`;
+}
+function runGitCommand(rootDir, args) {
+	return execFileSync("git", args, {
+		cwd: rootDir,
+		encoding: "utf-8"
+	}).trim();
+}
+function normalizeGitRelativePath(value) {
+	return value.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/^\/+/, "");
+}
+function listGitChangedFiles(rootDir, contentDir) {
+	let gitRoot;
+	try {
+		gitRoot = runGitCommand(rootDir, ["rev-parse", "--show-toplevel"]);
+	} catch {
+		throw new Error("Use --changed inside a git repository.");
+	}
+	const contentDirAbs = path.resolve(rootDir, contentDir);
+	const relativeContentDir = normalizeGitRelativePath(path.relative(gitRoot, contentDirAbs));
+	if (relativeContentDir.startsWith("../")) throw new Error("Configured contentDir must live inside the current git repository for --changed.");
+	const pathspec = relativeContentDir || ".";
+	const changedFiles = /* @__PURE__ */ new Set();
+	const commands = [
+		[
+			"diff",
+			"--name-only",
+			"--",
+			pathspec
+		],
+		[
+			"diff",
+			"--name-only",
+			"--cached",
+			"--",
+			pathspec
+		],
+		[
+			"ls-files",
+			"--others",
+			"--exclude-standard",
+			"--",
+			pathspec
+		]
+	];
+	for (const args of commands) {
+		const output = runGitCommand(gitRoot, args);
+		if (!output) continue;
+		for (const line of output.split("\n")) {
+			const normalized = normalizeGitRelativePath(line.trim());
+			if (!normalized) continue;
+			const absolutePath = path.resolve(gitRoot, normalized);
+			const relativeToRoot = normalizeGitRelativePath(path.relative(rootDir, absolutePath));
+			if (relativeToRoot && !relativeToRoot.startsWith("../")) changedFiles.add(relativeToRoot);
+		}
+	}
+	return changedFiles;
+}
+function resolveCompressionApiKey(explicitApiKey, explicitApiKeyEnv) {
+	const apiKey = explicitApiKey ?? (explicitApiKeyEnv && explicitApiKeyEnv.length > 0 ? process.env[explicitApiKeyEnv] : void 0);
+	if (!apiKey) {
+		if (explicitApiKeyEnv && explicitApiKeyEnv.length > 0) throw new Error(`Missing Docs Cloud API key. The configured API key env "${explicitApiKeyEnv}" was not found in your shell or project .env/.env.local files. Add ${explicitApiKeyEnv}=fl_key_... to .env.local, configure cloud.apiKey.env in your root docs config, or pass --api-key.`);
+		throw new Error("Missing Docs Cloud API key. Configure cloud.apiKey.env in your root docs config and set DOCS_CLOUD_API_KEY=fl_key_... in .env/.env.local, or pass --api-key.");
+	}
+	return apiKey;
+}
+function readCloudApiKeyConfig(content) {
+	if (!extractNestedObjectLiteral(content, ["cloud"])) return {};
+	const apiKeyBlock = extractNestedObjectLiteral(content, ["cloud", "apiKey"]);
+	return { apiKeyEnv: apiKeyBlock ? readStringProperty(apiKeyBlock, "env") ?? DEFAULT_DOCS_CLOUD_API_KEY_ENV : DEFAULT_DOCS_CLOUD_API_KEY_ENV };
+}
+function readAgentCompactConfig(content) {
+	const compactBlock = extractNestedObjectLiteral(content, ["agent", "compact"]);
+	if (!compactBlock) return {};
+	const configuredApiKey = readStringProperty(compactBlock, "apiKey");
+	return {
+		apiKey: configuredApiKey,
+		apiKeyEnv: readStringProperty(compactBlock, "apiKeyEnv") ?? (!configuredApiKey ? readEnvReferenceProperty(compactBlock, "apiKey") : void 0),
+		baseUrl: readStringProperty(compactBlock, "baseUrl"),
+		model: readStringProperty(compactBlock, "model"),
+		aggressiveness: readNumberProperty(compactBlock, "aggressiveness"),
+		maxOutputTokens: readNumberProperty(compactBlock, "maxOutputTokens"),
+		minOutputTokens: readNumberProperty(compactBlock, "minOutputTokens"),
+		protectJson: readBooleanProperty(compactBlock, "protectJson")
+	};
+}
+function readCloudApiKeyConfigFromModule(config) {
+	if (!config.cloud) return {};
+	return { apiKeyEnv: config.cloud.apiKey?.env?.trim() || DEFAULT_DOCS_CLOUD_API_KEY_ENV };
+}
+function readAgentCompactConfigFromModule(config) {
+	const compact = config.agent?.compact;
+	if (!compact) return {};
+	return {
+		apiKey: compact.apiKey,
+		apiKeyEnv: compact.apiKeyEnv,
+		baseUrl: compact.baseUrl,
+		model: compact.model,
+		aggressiveness: compact.aggressiveness,
+		maxOutputTokens: compact.maxOutputTokens,
+		minOutputTokens: compact.minOutputTokens,
+		protectJson: compact.protectJson
+	};
+}
+function mergeAgentCompactOptions(defaults, overrides) {
+	return {
+		...defaults,
+		...Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0))
+	};
+}
+function readPageTokenBudget(pagePath) {
+	const { data } = matter(readFileSync(pagePath, "utf-8"));
+	return normalizePageAgentFrontmatter(data.agent)?.tokenBudget;
+}
+function buildCompactionSettingsHash(options) {
+	return hashGeneratedAgentContent(JSON.stringify({
+		model: options.model ?? DEFAULT_COMPRESSION_MODEL,
+		aggressiveness: options.aggressiveness ?? DEFAULT_COMPRESSION_AGGRESSIVENESS,
+		maxOutputTokens: options.maxOutputTokens ?? null,
+		minOutputTokens: options.minOutputTokens ?? null,
+		protectJson: options.protectJson ?? null
+	}));
+}
+function buildPageOptions(defaults, pagePath) {
+	const tokenBudget = readPageTokenBudget(pagePath);
+	const pageOptions = mergeAgentCompactOptions(defaults, { maxOutputTokens: tokenBudget });
+	if (pageOptions.minOutputTokens !== void 0 && pageOptions.maxOutputTokens !== void 0 && pageOptions.minOutputTokens > pageOptions.maxOutputTokens) pageOptions.minOutputTokens = pageOptions.maxOutputTokens;
+	return {
+		pageOptions,
+		tokenBudget
+	};
+}
+function buildResolvedPageSourceDocument(page) {
+	return stripGeneratedPageAgentContractMarkdown(renderDocsMarkdownDocument({
+		...page,
+		agentContent: void 0,
+		agentRawContent: void 0
+	}));
+}
+function buildAgentSourceDocument(page) {
+	if (typeof page.agentRawContent === "string") return stripGeneratedPageAgentContractMarkdown(page.agentRawContent);
+	return stripGeneratedPageAgentContractMarkdown(renderDocsMarkdownDocument(page));
+}
+function readCurrentAgentDocument(target) {
+	if (!target.hasAgentFile || !existsSync(target.agentPath)) return void 0;
+	return parseGeneratedAgentDocument(readFileSync(target.agentPath, "utf-8"));
+}
+function shouldCompactChangedAgentFile(target) {
+	const currentDocument = readCurrentAgentDocument(target);
+	if (!currentDocument) return false;
+	if (!currentDocument.provenance) return true;
+	if (currentDocument.provenance.sourceKind !== "agent-md") return false;
+	return hashGeneratedAgentContent(currentDocument.content) !== currentDocument.provenance.outputHash;
+}
+function resolveSourceKindForCompaction(target, currentDocument) {
+	if (!target.hasAgentFile) return "resolved-page";
+	if (currentDocument?.provenance?.sourceKind === "resolved-page") return "resolved-page";
+	return "agent-md";
+}
+function buildSourceDocumentForCompaction(page, sourceKind) {
+	return sourceKind === "resolved-page" ? buildResolvedPageSourceDocument(page) : buildAgentSourceDocument(page);
+}
+function buildGeneratedAgentProvenance(sourceKind, sourceDocument, output, pageOptions) {
+	return {
+		version: GENERATED_AGENT_PROVENANCE_VERSION,
+		sourceKind,
+		sourceHash: hashGeneratedAgentContent(sourceDocument),
+		settingsHash: buildCompactionSettingsHash(pageOptions),
+		outputHash: hashGeneratedAgentContent(output),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function inspectAgentCompactionState(page, target, defaults) {
+	const { pageOptions, tokenBudget } = buildPageOptions(defaults, target.pagePath);
+	const currentDocument = readCurrentAgentDocument(target);
+	if (!currentDocument) return {
+		status: "missing",
+		sourceKind: "resolved-page",
+		pageOptions,
+		sourceDocument: buildResolvedPageSourceDocument(page),
+		tokenBudget
+	};
+	const sourceKind = resolveSourceKindForCompaction(target, currentDocument);
+	const sourceDocument = buildSourceDocumentForCompaction(page, sourceKind);
+	if (!currentDocument.provenance) return {
+		status: "unknown",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		tokenBudget
+	};
+	const outputModified = hashGeneratedAgentContent(currentDocument.content) !== currentDocument.provenance.outputHash;
+	if (currentDocument.provenance.sourceKind === "agent-md") return {
+		status: outputModified ? "modified" : "unknown",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		provenance: currentDocument.provenance,
+		tokenBudget
+	};
+	const sourceChanged = hashGeneratedAgentContent(sourceDocument) !== currentDocument.provenance.sourceHash;
+	const settingsChanged = buildCompactionSettingsHash(pageOptions) !== currentDocument.provenance.settingsHash;
+	return {
+		status: outputModified && (sourceChanged || settingsChanged) ? "stale-modified" : outputModified ? "modified" : sourceChanged || settingsChanged ? "stale" : "fresh",
+		sourceKind,
+		pageOptions,
+		sourceDocument,
+		provenance: currentDocument.provenance,
+		tokenBudget
+	};
+}
+function protectForCompression(input) {
+	const segments = [];
+	const stash = (value) => {
+		const token = `__DOCS_SAFE_${segments.length}__`;
+		segments.push(value);
+		return token;
+	};
+	let result = input;
+	result = result.replace(/```[\s\S]*?```/g, stash);
+	result = result.replace(/\[[^\]]+\]\([^)]+\)/g, stash);
+	result = result.replace(/`[^`\n]+`/g, stash);
+	result = result.replace(/^(URL|Description|Related):[^\n]*$/gm, stash);
+	result = result.replace(/https?:\/\/[^\s)]+/g, stash);
+	for (let index = 0; index < segments.length; index += 1) result = result.replace(`__DOCS_SAFE_${index}__`, `<docs_safe>${segments[index]}</docs_safe>`);
+	return result;
+}
+function sanitizeCompressedOutput(output) {
+	return output.replace(/<\/?docs_safe>/g, "");
+}
+async function compressDocument(input, options) {
+	const apiKey = resolveCompressionApiKey(options.apiKey, options.apiKeyEnv);
+	const endpoint = resolveCompressionEndpoint(options.baseUrl);
+	const aggressiveness = options.aggressiveness ?? DEFAULT_COMPRESSION_AGGRESSIVENESS;
+	if (aggressiveness < 0 || aggressiveness > 1) throw new Error("Aggressiveness must be between 0.0 and 1.0.");
+	const payload = {
+		model: options.model ?? DEFAULT_COMPRESSION_MODEL,
+		input: protectForCompression(input),
+		compression_settings: {
+			aggressiveness,
+			...options.maxOutputTokens !== void 0 ? { max_output_tokens: options.maxOutputTokens } : {},
+			...options.minOutputTokens !== void 0 ? { min_output_tokens: options.minOutputTokens } : {},
+			...options.protectJson !== void 0 ? { protect_json: options.protectJson } : {}
+		}
+	};
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(payload)
+	});
+	if (!response.ok) {
+		const body = await response.text();
+		throw new Error(`Docs Cloud compression request failed (${response.status}): ${body || response.statusText}`);
+	}
+	const result = await response.json();
+	const sanitizedOutput = typeof result.output === "string" ? sanitizeCompressedOutput(result.output) : result.output;
+	if (typeof sanitizedOutput !== "string" || sanitizedOutput.trim().length === 0) throw new Error("Docs Cloud compression response did not include a compressed output.");
+	return {
+		...result,
+		output: sanitizedOutput
+	};
+}
+function resolveSelectedPages(pages, targets, entry, requested, includeAll) {
+	const compactableBySlug = new Map(targets.map((target) => [target.slug, target]));
+	if (includeAll) return targets.map((target) => {
+		const page = pages.find((candidate) => candidate.slug === target.slug);
+		return page ? {
+			page,
+			target
+		} : null;
+	}).filter((value) => value !== null);
+	const resolved = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const rawRequest of requested) {
+		const page = findDocsMarkdownPage(entry, pages, normalizeRequestedPage(entry, rawRequest));
+		if (!page) throw new Error(`Could not find a docs page for "${rawRequest}".`);
+		const target = compactableBySlug.get(page.slug);
+		if (!target) throw new Error(`Page "${rawRequest}" does not use a folder-based page file, so it cannot be written to a sibling agent.md automatically.`);
+		if (seen.has(target.slug)) continue;
+		seen.add(target.slug);
+		resolved.push({
+			page,
+			target
+		});
+	}
+	return resolved;
+}
+function filterChangedPages(rootDir, contentDir, selectedPages) {
+	const changedFiles = listGitChangedFiles(rootDir, contentDir);
+	return selectedPages.filter(({ target }) => {
+		const relativePagePath = normalizeGitRelativePath(path.relative(rootDir, target.pagePath));
+		if (changedFiles.has(relativePagePath)) return true;
+		const relativeAgentPath = normalizeGitRelativePath(path.relative(rootDir, target.agentPath));
+		return changedFiles.has(relativeAgentPath) && shouldCompactChangedAgentFile(target);
+	});
+}
+async function compactAgentDocs(options = {}) {
+	const rootDir = process.cwd();
+	const loadedEnv = loadProjectEnv(rootDir);
+	for (const [key, value] of Object.entries(loadedEnv)) if (process.env[key] === void 0) process.env[key] = value;
+	const loadedConfigModule = await loadDocsConfigModule(rootDir, options.configPath);
+	const configContent = readFileSync(loadedConfigModule?.path ?? resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const resolvedOptions = mergeAgentCompactOptions(mergeAgentCompactOptions(mergeAgentCompactOptions(readCloudApiKeyConfig(configContent), loadedConfigModule?.config ? readCloudApiKeyConfigFromModule(loadedConfigModule.config) : {}), mergeAgentCompactOptions(readAgentCompactConfig(configContent), loadedConfigModule?.config ? readAgentCompactConfigFromModule(loadedConfigModule.config) : {})), options);
+	const entry = normalizePathSegment(loadedConfigModule?.config.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs") || "docs";
+	const contentDir = typeof loadedConfigModule?.config.contentDir === "string" ? loadedConfigModule.config.contentDir : resolveDocsContentDir(rootDir, configContent, entry);
+	const siteTitle = typeof loadedConfigModule?.config.nav?.title === "string" ? loadedConfigModule.config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	if (resolvedOptions.all && resolvedOptions.pages && resolvedOptions.pages.length > 0) throw new Error("Use either --all or specific page arguments, not both.");
+	if (resolvedOptions.includeMissing && !resolvedOptions.stale) throw new Error("Use --include-missing together with --stale.");
+	const requestedPages = resolvedOptions.pages?.filter((value) => value.trim().length > 0) ?? [];
+	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale && !resolvedOptions.changed) throw new Error("Pass --all, --changed, --stale, or at least one docs page slug/path to compact.");
+	const pages = await createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle
+	}).getPages();
+	if (pages.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
+	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true || resolvedOptions.stale === true && requestedPages.length === 0 || resolvedOptions.changed === true && requestedPages.length === 0);
+	const filteredPages = resolvedOptions.changed ? filterChangedPages(rootDir, contentDir, selectedPages) : selectedPages;
+	if (filteredPages.length === 0) {
+		if (resolvedOptions.changed) {
+			console.log(pc.green("No changed docs pages needed compaction."));
+			return;
+		}
+		throw new Error("No compactable docs pages matched the request.");
+	}
+	let created = 0;
+	let overwritten = 0;
+	let processed = 0;
+	let skippedFresh = 0;
+	let skippedModified = 0;
+	let skippedUnknown = 0;
+	let skippedMissing = 0;
+	const requestedExplicitPages = requestedPages.length > 0;
+	for (const { page, target } of filteredPages) {
+		const state = inspectAgentCompactionState(page, target, resolvedOptions);
+		if (resolvedOptions.stale) {
+			if (state.status === "fresh") {
+				skippedFresh += 1;
+				continue;
+			}
+			if (state.status === "modified" || state.status === "stale-modified") {
+				skippedModified += 1;
+				continue;
+			}
+			if (state.status === "unknown") {
+				skippedUnknown += 1;
+				continue;
+			}
+			if (state.status === "missing") {
+				if (!(resolvedOptions.includeMissing === true && (requestedExplicitPages || state.tokenBudget !== void 0))) {
+					skippedMissing += 1;
+					continue;
+				}
+			}
+		}
+		const compressed = await compressDocument(state.sourceDocument, state.pageOptions);
+		const nextContent = compressed.output.trimEnd();
+		const generatedDocument = serializeGeneratedAgentDocument(nextContent, buildGeneratedAgentProvenance(state.sourceKind, state.sourceDocument, nextContent, state.pageOptions));
+		console.log(pc.dim(`Compacting ${page.url} (${compressed.original_input_tokens ?? "?"} -> ${compressed.output_tokens ?? "?"} tokens)...`));
+		if (resolvedOptions.dryRun) continue;
+		mkdirSync(target.pageDir, { recursive: true });
+		writeFileSync(target.agentPath, generatedDocument, "utf-8");
+		if (target.hasAgentFile) overwritten += 1;
+		else created += 1;
+		processed += 1;
+	}
+	if (resolvedOptions.dryRun) processed = filteredPages.length - skippedFresh - skippedModified - skippedUnknown - skippedMissing;
+	if (resolvedOptions.stale && processed === 0) {
+		console.log(pc.green("No stale generated agent.md files needed updates."));
+		if (skippedFresh + skippedModified + skippedUnknown + skippedMissing > 0) console.log(pc.dim(`Skipped ${skippedFresh} fresh, ${skippedModified} modified, ${skippedUnknown} unknown, and ${skippedMissing} missing page${skippedFresh + skippedModified + skippedUnknown + skippedMissing === 1 ? "" : "s"}.`));
+		return;
+	}
+	const summaryPrefix = resolvedOptions.dryRun ? "Dry run complete" : "Compaction complete";
+	console.log(pc.green(`${summaryPrefix}: ${processed} page${processed === 1 ? "" : "s"} processed` + (resolvedOptions.dryRun ? "." : ` (${created} created, ${overwritten} overwritten).`)));
+	if (resolvedOptions.stale) console.log(pc.dim(`Skipped ${skippedFresh} fresh, ${skippedModified} modified, ${skippedUnknown} unknown, and ${skippedMissing} missing page${skippedFresh + skippedModified + skippedUnknown + skippedMissing === 1 ? "" : "s"}.`));
+}
+function printAgentCompactHelp() {
+	console.log(`
+${pc.bold("docs agent compact")} — Generate sibling ${pc.cyan("agent.md")} files by compacting resolved docs pages.
+
+${pc.dim("Usage:")}
+  npx @farming-labs/docs@latest ${pc.cyan("agent compact")} ${pc.dim("[page ...]")}
+
+${pc.dim("Examples:")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact installation configuration")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact /docs/installation")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --page installation --page configuration")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --all")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --changed")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale --include-missing")}
+
+${pc.dim("Per-page override:")}
+  Add ${pc.cyan("agent.tokenBudget")} to a page frontmatter block to override the compact output target for that page.
+
+${pc.dim("Options:")}
+  ${pc.cyan("--all")}                    Compact every folder-based docs page under the configured contentDir
+  ${pc.cyan("--page <slug|path>")}       Add a page explicitly (repeatable); positional page args work too
+  ${pc.cyan("--changed")}                Compact only docs pages changed in the current git working tree
+  ${pc.cyan("--stale")}                  Re-compact only stale generated agent.md files
+  ${pc.cyan("--include-missing")}        With ${pc.cyan("--stale")}, also create missing agent.md files for explicit pages or pages that define ${pc.cyan("agent.tokenBudget")}
+  ${pc.cyan("--config <path>")}          Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+  ${pc.cyan("--api-key <key>")}          Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
+  ${pc.cyan("--api-key-env <name>")}     Env var name for the Docs Cloud API key; prefer ${pc.dim("cloud.apiKey.env")}
+  ${pc.cyan("--base-url <url>")}         Override the compression API base URL (useful for tests)
+  ${pc.cyan("--model <name>")}           Compression model (${pc.dim("docs-cloud-compress-v1")} by default)
+  ${pc.cyan("--aggressiveness <0-1>")}   Compression intensity (${pc.dim("0.3")} by default)
+  ${pc.cyan("--max-output-tokens <n>")}  Pass through to compression settings
+  ${pc.cyan("--min-output-tokens <n>")}  Pass through to compression settings
+  ${pc.cyan("--protect-json <bool>")}    Preserve JSON objects during compression
+  ${pc.cyan("--dry-run")}                Resolve pages and call the compressor without writing files
+`);
+}
+
+//#endregion
+export { scanDocsPageTargets as i, compactAgentDocs as n, inspectAgentCompactionState as r, agent_exports as t };