@farming-labs/docs 0.1.123 → 0.1.124

package/dist/codeblocks-RacO12_K.mjs

@@ -0,0 +1,1494 @@
+import { _ as parseGeneratedAgentDocument, h as hashGeneratedAgentContent, m as GENERATED_AGENT_PROVENANCE_VERSION, v as serializeGeneratedAgentDocument } from "./search-BL7o2rXk.mjs";
+import { E as findDocsMarkdownPage, U as renderDocsMarkdownDocument } from "./agent-BS39vnhS.mjs";
+import "./index.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import "./server.mjs";
+import { a as loadProjectEnv, c as readNavTitle, d as readTopLevelStringProperty, f as resolveDocsConfigPath, i as loadDocsConfigModule, l as readNumberProperty, o as readBooleanProperty, p as resolveDocsContentDir, s as readEnvReferenceProperty, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-B8wA38OC.mjs";
+import matter from "gray-matter";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { execFile, execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+
+//#region src/cli/agent.ts
+const DEFAULT_TTC_BASE_URL = "https://api.thetokencompany.com";
+const DEFAULT_TTC_MODEL = "bear-1.2";
+const DEFAULT_TTC_AGGRESSIVENESS = .3;
+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.TOKEN_COMPANY_BASE_URL ?? process.env.THE_TOKEN_COMPANY_BASE_URL ?? DEFAULT_TTC_BASE_URL;
+	if (/\/v1\/compress\/?$/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 candidateKeys = [
+		explicitApiKeyEnv,
+		"TOKEN_COMPANY_API_KEY",
+		"THE_TOKEN_COMPANY_API_KEY",
+		"TTC_API_KEY"
+	].filter((value) => typeof value === "string" && value.length > 0);
+	const apiKey = explicitApiKey ?? candidateKeys.map((key) => process.env[key]).find(Boolean);
+	if (!apiKey) throw new Error("Missing Token Company API key. Pass --api-key, set agent.compact.apiKey/apiKeyEnv, or set TOKEN_COMPANY_API_KEY.");
+	return apiKey;
+}
+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 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 normalizeTokenBudget(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	return Math.max(1, Math.ceil(value));
+}
+function readPageTokenBudget(pagePath) {
+	const { data } = matter(readFileSync(pagePath, "utf-8"));
+	return normalizeTokenBudget(data.agent?.tokenBudget);
+}
+function buildCompactionSettingsHash(options) {
+	return hashGeneratedAgentContent(JSON.stringify({
+		model: options.model ?? DEFAULT_TTC_MODEL,
+		aggressiveness: options.aggressiveness ?? DEFAULT_TTC_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 renderDocsMarkdownDocument({
+		...page,
+		agentRawContent: void 0
+	});
+}
+function buildAgentSourceDocument(page) {
+	if (typeof page.agentRawContent === "string") return page.agentRawContent;
+	return 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 = `__TTC_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(`__TTC_SAFE_${index}__`, `<ttc_safe>${segments[index]}</ttc_safe>`);
+	return result;
+}
+function sanitizeCompressedOutput(output) {
+	return output.replace(/<\/?ttc_safe>/g, "");
+}
+async function compressDocument(input, options) {
+	const apiKey = resolveCompressionApiKey(options.apiKey, options.apiKeyEnv);
+	const endpoint = resolveCompressionEndpoint(options.baseUrl);
+	const aggressiveness = options.aggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS;
+	if (aggressiveness < 0 || aggressiveness > 1) throw new Error("Aggressiveness must be between 0.0 and 1.0.");
+	const payload = {
+		model: options.model ?? DEFAULT_TTC_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(`Token Company 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("Token Company 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(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>")}          Token Company API key (or set ${pc.dim("TOKEN_COMPANY_API_KEY")})
+  ${pc.cyan("--api-key-env <name>")}     Custom env var name for the Token Company API key
+  ${pc.cyan("--base-url <url>")}         Override the Token Company API base URL (useful for tests)
+  ${pc.cyan("--model <name>")}           Compression model (${pc.dim("bear-1.2")} by default)
+  ${pc.cyan("--aggressiveness <0-1>")}   Compression intensity (${pc.dim("0.3")} by default)
+  ${pc.cyan("--max-output-tokens <n>")}  Pass through to Token Company compression settings
+  ${pc.cyan("--min-output-tokens <n>")}  Pass through to Token Company 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
+//#region src/code-blocks.ts
+const execFileAsync = promisify(execFile);
+const DEFAULT_ENV_FILES = [
+	".env.local",
+	".env.test",
+	".env"
+];
+const DEFAULT_COMMAND_TIMEOUT_MS = 6e4;
+function resolveDocsCodeBlocksValidateConfig(input) {
+	if (input === false || input === void 0) return {
+		enabled: false,
+		planner: { provider: "metadata" },
+		runner: {
+			provider: "local",
+			tokenEnv: "VERCEL_TOKEN",
+			projectIdEnv: "VERCEL_PROJECT_ID",
+			teamIdEnv: "VERCEL_TEAM_ID",
+			projectJson: ".vercel/project.json",
+			runtime: "node24",
+			timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS
+		},
+		envFile: DEFAULT_ENV_FILES,
+		env: {},
+		missingEnv: "skip",
+		unsupportedLanguage: "skip",
+		mode: "report"
+	};
+	const config = input === true ? {} : input;
+	const planner = normalizePlannerConfig(config.planner);
+	const runner = normalizeRunnerConfig(config.runner);
+	const envFile = Array.isArray(config.envFile) ? config.envFile : typeof config.envFile === "string" ? [config.envFile] : DEFAULT_ENV_FILES;
+	return {
+		enabled: config.enabled ?? true,
+		planner,
+		runner,
+		envFile,
+		env: config.env ?? {},
+		missingEnv: config.missingEnv ?? "skip",
+		unsupportedLanguage: config.unsupportedLanguage ?? "skip",
+		mode: config.mode ?? "report"
+	};
+}
+function parseCodeFenceInfo(info) {
+	const trimmed = info.trim();
+	if (!trimmed) return { meta: {} };
+	const firstToken = trimmed.match(/^(\S+)/)?.[1] ?? "";
+	const language = firstToken && !firstToken.includes("=") ? firstToken : void 0;
+	const attributeSource = language ? trimmed.slice(firstToken.length).trim() : trimmed;
+	const meta = {};
+	const attributePattern = /([A-Za-z_:][\w:.-]*)(?:=(?:"([^"]*)"|'([^']*)'|([^\s"']+)))?/g;
+	let match;
+	while (match = attributePattern.exec(attributeSource)) {
+		const key = match[1];
+		meta[key] = match[2] ?? match[3] ?? match[4] ?? true;
+	}
+	return {
+		language,
+		meta
+	};
+}
+function extractCodeBlocksFromMarkdown(input) {
+	const blocks = [];
+	const lines = input.source.split("\n");
+	let openFence;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		const trimmed = line.trim();
+		if (!openFence) {
+			const openMatch = trimmed.match(/^(`{3,}|~{3,})(.*)$/);
+			if (!openMatch) continue;
+			openFence = {
+				marker: openMatch[1],
+				info: openMatch[2]?.trim() ?? "",
+				code: [],
+				lineStart: index + 1
+			};
+			continue;
+		}
+		if (isClosingFence(trimmed, openFence.marker)) {
+			const parsed = parseCodeFenceInfo(openFence.info);
+			const meta = parsed.meta;
+			const blockIndex = blocks.length + 1;
+			const relativePath = input.relativePath ?? input.filePath;
+			blocks.push({
+				id: `${relativePath}#code-${blockIndex}`,
+				filePath: input.filePath,
+				relativePath,
+				lineStart: openFence.lineStart,
+				lineEnd: index + 1,
+				language: parsed.language,
+				title: readStringMeta(meta, "title"),
+				framework: readStringMeta(meta, "framework"),
+				packageManager: readStringMeta(meta, "packageManager"),
+				runnable: readBooleanMeta(meta, "runnable") ?? false,
+				env: readEnvMeta(meta),
+				meta,
+				code: openFence.code.join("\n")
+			});
+			openFence = void 0;
+			continue;
+		}
+		openFence.code.push(line);
+	}
+	return blocks;
+}
+function collectCodeBlockTargets(options) {
+	const root = path.resolve(options.rootDir);
+	const contentRoot = path.resolve(root, options.contentDir);
+	if (!existsSync(contentRoot)) return [];
+	return walkMarkdownFiles(contentRoot).flatMap((filePath) => {
+		return extractCodeBlocksFromMarkdown({
+			source: readFileSync(filePath, "utf-8"),
+			filePath,
+			relativePath: path.relative(root, filePath).replace(/\\/g, "/")
+		});
+	});
+}
+async function planCodeBlockTargets(targets, config) {
+	if (config.planner.provider === "metadata") return targets.map((target) => buildMetadataExecutionPlan(target, config));
+	if (config.planner.provider === "cloud") throw new Error("Hosted cloud code block planning is not available in this package yet.");
+	return planWithOpenAICompatibleProvider(targets, config);
+}
+async function validateCodeBlockPlans(input) {
+	const validationEnv = loadValidationEnv(input.rootDir, input.config);
+	const preflight = input.plans.map((plan) => preflightPlan(plan, input.config, validationEnv));
+	const runnable = preflight.filter((result) => result.status !== "SKIP" && !result.reason);
+	const skippedOrFailed = preflight.filter((result) => result.status === "SKIP" || result.reason);
+	const plansToRun = runnable.map((result) => result.plan);
+	if (plansToRun.length === 0) return skippedOrFailed;
+	const runResults = input.config.runner.provider === "vercel-sandbox" ? await runPlansInVercelSandbox(plansToRun, input.rootDir, input.config, validationEnv.env) : await runPlansLocally(plansToRun, input.config, validationEnv.env);
+	return [...skippedOrFailed, ...runResults].sort((a, b) => a.id.localeCompare(b.id));
+}
+async function validateCodeBlocks(input) {
+	const targets = collectCodeBlockTargets({
+		rootDir: input.rootDir,
+		contentDir: input.contentDir
+	});
+	const plans = await planCodeBlockTargets(targets, input.config);
+	const results = input.planOnly || input.config.mode === "plan" ? plans.map((plan) => ({
+		id: plan.id,
+		target: plan.target,
+		plan,
+		status: plan.action === "skip" ? "SKIP" : "PLAN",
+		reason: plan.reason ?? (plan.action === "skip" ? "planned skip" : "planned")
+	})) : await validateCodeBlockPlans({
+		plans,
+		rootDir: input.rootDir,
+		config: input.config
+	});
+	return {
+		summary: results.reduce((acc, result) => {
+			acc.total += 1;
+			if (result.status === "PLAN") acc.planned += 1;
+			if (result.status === "PASS") acc.pass += 1;
+			if (result.status === "SKIP") acc.skip += 1;
+			if (result.status === "FAIL") acc.fail += 1;
+			return acc;
+		}, {
+			total: 0,
+			planned: 0,
+			pass: 0,
+			skip: 0,
+			fail: 0
+		}),
+		config: input.config,
+		targets,
+		plans,
+		results
+	};
+}
+function normalizePlannerConfig(input) {
+	if (!input) return { provider: "metadata" };
+	if (typeof input === "string") return { provider: input };
+	return {
+		provider: input.provider ?? "metadata",
+		...input
+	};
+}
+function normalizeRunnerConfig(input) {
+	const config = typeof input === "string" ? { provider: input } : input ?? {};
+	return {
+		provider: config.provider ?? "local",
+		tokenEnv: config.tokenEnv ?? "VERCEL_TOKEN",
+		projectIdEnv: config.projectIdEnv ?? "VERCEL_PROJECT_ID",
+		teamIdEnv: config.teamIdEnv ?? "VERCEL_TEAM_ID",
+		projectJson: config.projectJson === void 0 ? ".vercel/project.json" : config.projectJson,
+		runtime: config.runtime ?? "node24",
+		timeoutMs: config.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS
+	};
+}
+function buildMetadataExecutionPlan(target, config) {
+	const language = normalizeLanguage(target.language);
+	const template = target.framework ?? templateFromLanguage(language);
+	const requiredEnv = target.env;
+	if (readBooleanMeta(target.meta, "partial") || looksPartial(target.code)) return skipPlan(target, template, requiredEnv, "partial fragment", config.planner.provider);
+	if (!language) {
+		if (!target.runnable) return skipPlan(target, "unknown", requiredEnv, "code block is not marked runnable", config.planner.provider);
+		if (looksLikeShellCommand(target.code)) return shellPlan(target, "shell", requiredEnv, config.planner.provider);
+		return skipPlan(target, "unknown", requiredEnv, "missing language and not obviously runnable", config.planner.provider);
+	}
+	if (!target.runnable) return skipPlan(target, template, requiredEnv, "code block is not marked runnable", config.planner.provider);
+	if (isShellLanguage(language)) return shellPlan(target, template, requiredEnv, config.planner.provider);
+	if (language === "json") return syntaxPlan(target, "json", "node", requiredEnv, config.planner.provider);
+	if (language === "javascript" || language === "js" || language === "jsx") return executePlan(target, template, "node", "js", {
+		cmd: "node",
+		args: []
+	}, requiredEnv, config.planner.provider);
+	if (language === "typescript" || language === "ts" || language === "tsx") return executePlan(target, template, "tsx", "ts", {
+		cmd: "npx",
+		args: ["--yes", "tsx"]
+	}, requiredEnv, config.planner.provider);
+	if (language === "python" || language === "py") return executePlan(target, template, "python3", "py", {
+		cmd: "python3",
+		args: []
+	}, requiredEnv, config.planner.provider);
+	if (language === "ruby" || language === "rb") return executePlan(target, template, "ruby", "rb", {
+		cmd: "ruby",
+		args: []
+	}, requiredEnv, config.planner.provider);
+	if (language === "elixir" || language === "ex" || language === "exs") return executePlan(target, template, "elixir", "exs", {
+		cmd: "elixir",
+		args: []
+	}, requiredEnv, config.planner.provider);
+	if (language === "yaml" || language === "yml") return skipPlan(target, "yaml", requiredEnv, "YAML syntax validation requires a YAML parser", config.planner.provider);
+	if (!target.runnable) return skipPlan(target, template, requiredEnv, "code block is not marked runnable", config.planner.provider);
+	return skipPlan(target, template, requiredEnv, `unsupported language: ${target.language}`, config.planner.provider);
+}
+function executePlan(target, template, runtime, extension, command, requiredEnv, planner) {
+	const filePath = `snippet-${slugify(target.id)}.${extension}`;
+	return {
+		id: target.id,
+		target,
+		action: "execute",
+		template,
+		runtime,
+		filePath,
+		command: {
+			cmd: command.cmd,
+			args: [...command.args, filePath]
+		},
+		requiredEnv,
+		planner
+	};
+}
+function shellPlan(target, template, requiredEnv, planner) {
+	const filePath = `snippet-${slugify(target.id)}.sh`;
+	return {
+		id: target.id,
+		target,
+		action: "execute",
+		template,
+		runtime: "bash",
+		filePath,
+		command: {
+			cmd: "bash",
+			args: [filePath]
+		},
+		requiredEnv,
+		planner
+	};
+}
+function syntaxPlan(target, template, runtime, requiredEnv, planner) {
+	const filePath = `snippet-${slugify(target.id)}.json`;
+	return {
+		id: target.id,
+		target,
+		action: "validate-syntax",
+		template,
+		runtime,
+		filePath,
+		command: {
+			cmd: "node",
+			args: [
+				"-e",
+				`JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"))`,
+				filePath
+			]
+		},
+		requiredEnv,
+		planner
+	};
+}
+function skipPlan(target, template, requiredEnv, reason, planner) {
+	return {
+		id: target.id,
+		target,
+		action: "skip",
+		template,
+		requiredEnv,
+		reason,
+		planner
+	};
+}
+async function planWithOpenAICompatibleProvider(targets, config) {
+	const baseUrl = config.planner.baseUrl ?? (config.planner.baseUrlEnv ? process.env[config.planner.baseUrlEnv] : void 0) ?? (config.planner.provider === "openai" ? "https://api.openai.com/v1" : void 0);
+	const apiKey = config.planner.apiKey ?? (config.planner.apiKeyEnv ? process.env[config.planner.apiKeyEnv] : void 0);
+	if (!baseUrl) throw new Error("codeBlocks.validate planner requires baseUrl or baseUrlEnv.");
+	if (!apiKey) throw new Error(`codeBlocks.validate planner requires an API key. Set ${config.planner.apiKeyEnv ?? "apiKeyEnv"} in your environment.`);
+	const metadataPlans = targets.map((target) => buildMetadataExecutionPlan(target, config));
+	const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/chat/completions`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			model: config.planner.model ?? "gpt-4.1-mini",
+			temperature: 0,
+			response_format: { type: "json_object" },
+			messages: [{
+				role: "system",
+				content: "You produce JSON execution plans for documentation code blocks. Do not rewrite snippets. If the snippet is partial, missing setup, or unsafe, choose action skip. Return only JSON."
+			}, {
+				role: "user",
+				content: JSON.stringify({
+					contract: { plans: "array of {id, action: execute|validate-syntax|skip, template, runtime?, reason?, requiredEnv?: string[]}" },
+					codeBlocks: targets.map((target) => ({
+						id: target.id,
+						language: target.language,
+						title: target.title,
+						framework: target.framework,
+						packageManager: target.packageManager,
+						runnable: target.runnable,
+						env: target.env,
+						meta: target.meta,
+						code: target.code.slice(0, 8e3)
+					}))
+				})
+			}]
+		})
+	});
+	if (!response.ok) throw new Error(`Planner request failed with ${response.status} ${response.statusText}.`);
+	const content = (await response.json()).choices?.[0]?.message?.content ?? "";
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		throw new Error("Planner returned non-JSON content.");
+	}
+	const byId = new Map(metadataPlans.map((plan) => [plan.id, plan]));
+	for (const plan of parsed.plans ?? []) {
+		if (!plan.id || !byId.has(plan.id)) continue;
+		const fallback = byId.get(plan.id);
+		byId.set(plan.id, {
+			...fallback,
+			action: isPlanAction(plan.action) ? plan.action : fallback.action,
+			template: typeof plan.template === "string" && plan.template ? plan.template : fallback.template,
+			runtime: typeof plan.runtime === "string" && plan.runtime ? plan.runtime : fallback.runtime,
+			requiredEnv: Array.isArray(plan.requiredEnv) ? plan.requiredEnv.filter((value) => typeof value === "string") : fallback.requiredEnv,
+			reason: typeof plan.reason === "string" ? plan.reason : fallback.reason,
+			planner: config.planner.provider
+		});
+	}
+	return metadataPlans.map((plan) => byId.get(plan.id));
+}
+function preflightPlan(plan, config, validationEnv) {
+	if (plan.action === "skip") return {
+		id: plan.id,
+		target: plan.target,
+		plan,
+		status: "SKIP",
+		reason: plan.reason
+	};
+	const missingEnv = plan.requiredEnv.filter((key) => !validationEnv.env[key]);
+	if (missingEnv.length > 0) {
+		const reason = `missing env: ${missingEnv.join(", ")}`;
+		return {
+			id: plan.id,
+			target: plan.target,
+			plan,
+			status: config.missingEnv === "error" ? "FAIL" : "SKIP",
+			reason
+		};
+	}
+	if (!plan.command || !plan.filePath) return {
+		id: plan.id,
+		target: plan.target,
+		plan,
+		status: config.unsupportedLanguage === "error" ? "FAIL" : "SKIP",
+		reason: "no executable command in plan"
+	};
+	return {
+		id: plan.id,
+		target: plan.target,
+		plan,
+		status: "PASS"
+	};
+}
+async function runPlansLocally(plans, config, env) {
+	const tempDir = mkdtempSync(path.join(tmpdir(), "docs-codeblocks-"));
+	try {
+		return await Promise.all(plans.map(async (plan) => {
+			if (!plan.command || !plan.filePath) return skippedResult(plan, "no executable command in plan");
+			writeFileSync(path.join(tempDir, plan.filePath), plan.target.code, "utf-8");
+			try {
+				const result = await execFileAsync(plan.command.cmd, plan.command.args, {
+					cwd: tempDir,
+					env: {
+						...process.env,
+						...env
+					},
+					timeout: config.runner.timeoutMs,
+					maxBuffer: 1024 * 1024
+				});
+				return {
+					id: plan.id,
+					target: plan.target,
+					plan,
+					status: "PASS",
+					stdout: result.stdout,
+					stderr: result.stderr,
+					exitCode: 0
+				};
+			} catch (error) {
+				const err = error;
+				return {
+					id: plan.id,
+					target: plan.target,
+					plan,
+					status: "FAIL",
+					stdout: err.stdout,
+					stderr: err.stderr,
+					exitCode: typeof err.code === "number" ? err.code : null,
+					reason: err.signal ? `terminated by ${err.signal}` : err.message
+				};
+			}
+		}));
+	} finally {
+		rmSync(tempDir, {
+			force: true,
+			recursive: true
+		});
+	}
+}
+async function runPlansInVercelSandbox(plans, rootDir, config, env) {
+	const credentials = await resolveVercelSandboxCredentials(rootDir, config);
+	if (credentials.missing.length > 0) return plans.map((plan) => skippedResult(plan, `missing ${credentials.missing.join(", ")}`));
+	try {
+		const { Sandbox } = await import("@vercel/sandbox");
+		const sandbox = await Sandbox.create({
+			runtime: config.runner.runtime,
+			timeout: Math.max(config.runner.timeoutMs * Math.max(1, plans.length), config.runner.timeoutMs),
+			env,
+			token: credentials.token,
+			projectId: credentials.projectId,
+			teamId: credentials.teamId
+		});
+		try {
+			return await Promise.all(plans.map(async (plan) => {
+				if (!plan.command || !plan.filePath) return skippedResult(plan, "no executable command in plan");
+				await sandbox.writeFiles([{
+					path: plan.filePath,
+					content: Buffer.from(plan.target.code)
+				}]);
+				const command = await sandbox.runCommand({
+					cmd: plan.command.cmd,
+					args: plan.command.args,
+					cwd: "/vercel/sandbox",
+					env
+				});
+				const [stdout, stderr] = await Promise.all([command.stdout(), command.stderr()]);
+				return {
+					id: plan.id,
+					target: plan.target,
+					plan,
+					status: command.exitCode === 0 ? "PASS" : "FAIL",
+					stdout,
+					stderr,
+					exitCode: command.exitCode,
+					reason: command.exitCode === 0 ? void 0 : `exit code ${command.exitCode}`
+				};
+			}));
+		} finally {
+			await sandbox.stop().catch(() => {});
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return plans.map((plan) => skippedResult(plan, `vercel-sandbox unavailable: ${message}`));
+	}
+}
+async function resolveVercelSandboxCredentials(rootDir, config) {
+	const projectJson = readVercelProjectJson(rootDir, config.runner.projectJson);
+	const token = process.env[config.runner.tokenEnv];
+	if (!token && process.env.VERCEL_OIDC_TOKEN) return { missing: [] };
+	if (!token) return { missing: [config.runner.tokenEnv] };
+	const envProjectId = process.env[config.runner.projectIdEnv];
+	const envTeamId = process.env[config.runner.teamIdEnv];
+	const discoveredProject = !(envProjectId && envTeamId) && !(projectJson?.projectId && projectJson?.orgId) ? await discoverVercelSandboxProject(token) : void 0;
+	const projectId = envProjectId ?? projectJson?.projectId ?? discoveredProject?.projectId;
+	const teamId = envTeamId ?? projectJson?.orgId ?? discoveredProject?.teamId;
+	return {
+		token,
+		projectId,
+		teamId,
+		missing: [projectId ? void 0 : "Vercel project id", teamId ? void 0 : "Vercel team id"].filter((value) => Boolean(value))
+	};
+}
+async function discoverVercelSandboxProject(token) {
+	try {
+		const response = await fetch("https://api.vercel.com/v9/projects?limit=1", { headers: { Authorization: `Bearer ${token}` } });
+		if (!response.ok) return void 0;
+		const project = (await response.json()).projects?.[0];
+		if (!project) return void 0;
+		return {
+			projectId: typeof project.id === "string" ? project.id : void 0,
+			teamId: typeof project.accountId === "string" ? project.accountId : void 0
+		};
+	} catch {
+		return;
+	}
+}
+function readVercelProjectJson(rootDir, projectJson) {
+	if (projectJson === false) return void 0;
+	const fullPath = path.resolve(rootDir, projectJson);
+	if (!existsSync(fullPath)) return void 0;
+	try {
+		const parsed = JSON.parse(readFileSync(fullPath, "utf-8"));
+		return {
+			projectId: typeof parsed.projectId === "string" ? parsed.projectId : void 0,
+			orgId: typeof parsed.orgId === "string" ? parsed.orgId : void 0
+		};
+	} catch {
+		return;
+	}
+}
+function loadValidationEnv(rootDir, config) {
+	const fileEnv = {};
+	for (const file of config.envFile) {
+		const fullPath = path.resolve(rootDir, file);
+		if (!existsSync(fullPath)) continue;
+		Object.assign(fileEnv, parseEnvFile(readFileSync(fullPath, "utf-8")));
+	}
+	const resolved = {};
+	const missing = [];
+	for (const [runtimeKey, sourceKey] of Object.entries(config.env)) {
+		const value = process.env[sourceKey] ?? fileEnv[sourceKey];
+		if (value === void 0) {
+			missing.push(runtimeKey);
+			continue;
+		}
+		resolved[runtimeKey] = value;
+	}
+	return {
+		env: resolved,
+		missing
+	};
+}
+function parseEnvFile(source) {
+	const env = {};
+	for (const line of source.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const equals = trimmed.indexOf("=");
+		if (equals <= 0) continue;
+		const key = trimmed.slice(0, equals).trim();
+		env[key] = trimmed.slice(equals + 1).trim().replace(/^['"]|['"]$/g, "");
+	}
+	return env;
+}
+function readStringMeta(meta, key) {
+	const value = meta[key];
+	return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readBooleanMeta(meta, key) {
+	const value = meta[key];
+	if (typeof value === "boolean") return value;
+	if (typeof value !== "string") return void 0;
+	const normalized = value.trim().toLowerCase();
+	if (!normalized || normalized === "true" || normalized === "1" || normalized === "yes") return true;
+	if (normalized === "false" || normalized === "0" || normalized === "no") return false;
+	return true;
+}
+function readEnvMeta(meta) {
+	const direct = meta.env;
+	const values = /* @__PURE__ */ new Set();
+	if (typeof direct === "string") for (const item of direct.split(/[,\s]+/)) {
+		const trimmed = item.trim();
+		if (trimmed) values.add(trimmed);
+	}
+	for (const [key, value] of Object.entries(meta)) {
+		if (!key.startsWith("env:") && !key.startsWith("env.")) continue;
+		const envName = key.slice(4).trim();
+		if (envName && value !== false) values.add(envName);
+	}
+	return [...values];
+}
+function walkMarkdownFiles(root) {
+	const files = [];
+	const ignored = new Set([
+		".git",
+		".next",
+		".nuxt",
+		".svelte-kit",
+		"dist",
+		"node_modules",
+		"out"
+	]);
+	function visit(dir) {
+		for (const entry of readdirSync(dir)) {
+			if (ignored.has(entry)) continue;
+			const fullPath = path.join(dir, entry);
+			if (statSync(fullPath).isDirectory()) visit(fullPath);
+			else if (/\.(?:md|mdx)$/i.test(entry)) files.push(fullPath);
+		}
+	}
+	visit(root);
+	return files.sort();
+}
+function normalizeLanguage(language) {
+	return language?.trim().toLowerCase();
+}
+function isClosingFence(trimmedLine, marker) {
+	return new RegExp(`^${marker[0]}{${marker.length},}[ \\t]*$`).test(trimmedLine);
+}
+function isShellLanguage(language) {
+	return [
+		"bash",
+		"sh",
+		"shell",
+		"zsh",
+		"curl"
+	].includes(language);
+}
+function templateFromLanguage(language) {
+	if (!language) return "unknown";
+	if (isShellLanguage(language)) return "shell";
+	if (language === "js" || language === "javascript" || language === "jsx") return "node";
+	if (language === "ts" || language === "typescript" || language === "tsx") return "typescript";
+	if (language === "py" || language === "python") return "python";
+	return language;
+}
+function looksLikeShellCommand(code) {
+	return /^(?:\s*(?:npm|pnpm|yarn|bun|npx|curl|git|node|python3?|deno|uv|pip)\b)/m.test(code);
+}
+function looksPartial(code) {
+	const trimmed = code.trim();
+	if (!trimmed) return true;
+	return /^\.\.\.$/m.test(trimmed) || /\/\/\s*\.\.\.|#\s*\.\.\./.test(trimmed);
+}
+function slugify(value) {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "snippet";
+}
+function isPlanAction(value) {
+	return value === "execute" || value === "validate-syntax" || value === "skip";
+}
+function skippedResult(plan, reason) {
+	return {
+		id: plan.id,
+		target: plan.target,
+		plan,
+		status: "SKIP",
+		reason
+	};
+}
+
+//#endregion
+//#region src/cli/codeblocks.ts
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseCodeBlocksValidateArgs(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 === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--plan") {
+			parsed.plan = true;
+			continue;
+		}
+		if (arg === "--run") {
+			parsed.run = 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 codeblocks validate flag: ${arg}.`);
+	}
+	return parsed;
+}
+function printCodeBlocksValidateHelp() {
+	console.log(`
+${pc.bold("@farming-labs/docs codeblocks validate")}
+
+${pc.dim("Usage:")}
+  pnpm exec docs codeblocks validate
+  pnpm exec docs codeblocks validate --plan
+  pnpm exec docs codeblocks validate --json
+  pnpm exec docs codeblocks validate --config docs.config.ts
+
+${pc.dim("Options:")}
+  ${pc.cyan("--plan")}             Build the execution plan without running code
+  ${pc.cyan("--run")}              Force execution even when config mode is ${pc.dim("\"plan\"")}
+  ${pc.cyan("--json")}             Print machine-readable output
+  ${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
+`);
+}
+async function runCodeBlocksValidate(options = {}) {
+	const rootDir = process.cwd();
+	const loaded = await loadDocsConfigModule(rootDir, options.configPath, { silent: options.json });
+	const configPath = loaded?.path ?? resolveDocsConfigPath(rootDir, options.configPath);
+	const configContent = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+	const entry = loaded?.config.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = loaded?.config.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
+	const config = resolveDocsCodeBlocksValidateConfig(loaded?.config.codeBlocks?.validate ?? readStaticCodeBlocksValidateConfig(configContent));
+	if (!config.enabled) {
+		const disabledReport = {
+			summary: {
+				total: 0,
+				planned: 0,
+				pass: 0,
+				skip: 0,
+				fail: 0
+			},
+			config,
+			targets: [],
+			plans: [],
+			results: []
+		};
+		if (options.json) console.log(JSON.stringify(redactReport(disabledReport), null, 2));
+		else console.log(pc.yellow("codeBlocks.validate is disabled. Add `codeBlocks: { validate: true }` to docs.config.ts."));
+		return disabledReport;
+	}
+	const effectiveConfig = {
+		...config,
+		mode: options.run ? "report" : config.mode
+	};
+	const planOnly = options.plan === true || effectiveConfig.mode === "plan";
+	const report = await validateCodeBlocks({
+		rootDir,
+		contentDir,
+		config: effectiveConfig,
+		planOnly: options.plan
+	});
+	if (options.json) console.log(JSON.stringify(redactReport(report), null, 2));
+	else printCodeBlocksReport(report, planOnly);
+	if (!options.plan && report.summary.fail > 0) process.exitCode = 1;
+	return report;
+}
+function readStaticCodeBlocksValidateConfig(content) {
+	const block = extractNestedObjectLiteral(content, ["codeBlocks"]);
+	if (!block) return void 0;
+	if (/\bvalidate\s*:\s*true\b/.test(block)) return true;
+	if (/\bvalidate\s*:\s*false\b/.test(block)) return false;
+	const validateBlock = extractNestedObjectLiteral(content, ["codeBlocks", "validate"]);
+	if (validateBlock) {
+		const config = {};
+		const enabled = readBooleanProperty(validateBlock, "enabled");
+		const mode = readStringProperty(validateBlock, "mode");
+		const missingEnv = readStringProperty(validateBlock, "missingEnv");
+		const unsupportedLanguage = readStringProperty(validateBlock, "unsupportedLanguage");
+		const envFile = readStringArrayProperty(validateBlock, "envFile");
+		if (enabled !== void 0) config.enabled = enabled;
+		if (mode === "plan" || mode === "report") config.mode = mode;
+		if (missingEnv === "skip" || missingEnv === "warn" || missingEnv === "error") config.missingEnv = missingEnv;
+		if (unsupportedLanguage === "skip" || unsupportedLanguage === "warn" || unsupportedLanguage === "error") config.unsupportedLanguage = unsupportedLanguage;
+		if (envFile) config.envFile = envFile;
+		const planner = readStaticPlannerConfig(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"planner"
+		]));
+		if (planner) config.planner = planner;
+		const runner = readStaticRunnerConfig(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"runner"
+		]));
+		if (runner) config.runner = runner;
+		const env = readStringRecord(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"env"
+		]));
+		if (env && Object.keys(env).length > 0) config.env = env;
+		return config;
+	}
+	if (/\bvalidate\s*:\s*\{/.test(block)) return true;
+}
+function readStaticPlannerConfig(block) {
+	if (!block) return void 0;
+	const provider = readStringProperty(block, "provider");
+	const model = readStringProperty(block, "model");
+	const baseUrl = readStringProperty(block, "baseUrl");
+	const baseUrlEnv = readStringProperty(block, "baseUrlEnv");
+	const apiKeyEnv = readStringProperty(block, "apiKeyEnv");
+	if (provider !== "metadata" && provider !== "openai" && provider !== "openai-compatible" && provider !== "cloud") return;
+	return {
+		provider,
+		...model ? { model } : {},
+		...baseUrl ? { baseUrl } : {},
+		...baseUrlEnv ? { baseUrlEnv } : {},
+		...apiKeyEnv ? { apiKeyEnv } : {}
+	};
+}
+function readStaticRunnerConfig(block) {
+	if (!block) return void 0;
+	const provider = readStringProperty(block, "provider");
+	const tokenEnv = readStringProperty(block, "tokenEnv");
+	const projectIdEnv = readStringProperty(block, "projectIdEnv");
+	const teamIdEnv = readStringProperty(block, "teamIdEnv");
+	const projectJson = readStringProperty(block, "projectJson");
+	const runtime = readStringProperty(block, "runtime");
+	const timeoutMs = readNumberProperty(block, "timeoutMs");
+	if (provider !== "local" && provider !== "vercel-sandbox" && provider !== "cloud") return;
+	return {
+		provider,
+		...tokenEnv ? { tokenEnv } : {},
+		...projectIdEnv ? { projectIdEnv } : {},
+		...teamIdEnv ? { teamIdEnv } : {},
+		...projectJson ? { projectJson } : {},
+		...runtime === "node24" || runtime === "node22" || runtime === "python3.13" ? { runtime } : {},
+		...timeoutMs !== void 0 ? { timeoutMs } : {}
+	};
+}
+function readStringArrayProperty(content, key) {
+	const single = readStringProperty(content, key);
+	if (single) return [single];
+	const match = content.match(new RegExp(`\\b${key}\\b\\s*:\\s*\\[([\\s\\S]*?)\\]`));
+	if (!match) return void 0;
+	const values = [...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1]);
+	return values.length > 0 ? values : void 0;
+}
+function readStringRecord(block) {
+	if (!block) return void 0;
+	const record = {};
+	for (const pattern of [/(?:^|,)\s*([A-Za-z_$][\w$]*)\s*:\s*["']([^"']+)["']/g, /(?:^|,)\s*["']([^"']+)["']\s*:\s*["']([^"']+)["']/g]) {
+		let match;
+		while (match = pattern.exec(block)) record[match[1]] = match[2];
+	}
+	return record;
+}
+function printCodeBlocksReport(report, planOnly) {
+	const label = planOnly ? "Code block plan" : "Code block validation";
+	console.log(pc.bold(label));
+	console.log([
+		...report.summary.planned > 0 ? [`${pc.cyan(`${report.summary.planned} planned`)}`] : [],
+		`${pc.green(`${report.summary.pass} pass`)}`,
+		`${pc.yellow(`${report.summary.skip} skip`)}`,
+		`${report.summary.fail > 0 ? pc.red(`${report.summary.fail} fail`) : pc.dim("0 fail")}`,
+		`${report.targets.length} code blocks`
+	].join(pc.dim(" • ")));
+	if (report.results.length === 0) return;
+	console.log();
+	for (const result of report.results) {
+		const status = result.status === "PLAN" ? pc.cyan(result.status) : result.status === "PASS" ? pc.green(result.status) : result.status === "FAIL" ? pc.red(result.status) : pc.yellow(result.status);
+		const location = `${result.target.relativePath}:${result.target.lineStart}`;
+		const detail = result.reason ?? result.plan.reason ?? result.plan.template;
+		console.log(`${status} ${pc.cyan(location)} ${pc.dim(detail)}`);
+	}
+}
+function redactReport(report) {
+	return {
+		...report,
+		config: {
+			...report.config,
+			planner: {
+				...report.config.planner,
+				apiKey: report.config.planner.apiKey ? "[REDACTED]" : void 0
+			}
+		},
+		results: report.results.map((result) => ({
+			...result,
+			stdout: trimOutput(result.stdout),
+			stderr: trimOutput(result.stderr)
+		}))
+	};
+}
+function trimOutput(value) {
+	if (!value) return value;
+	return value.length > 4e3 ? `${value.slice(0, 4e3)}...` : value;
+}
+
+//#endregion
+export { readPageTokenBudget as a, printAgentCompactHelp as i, inspectAgentCompactionState as n, scanDocsPageTargets as o, parseCodeBlocksValidateArgs, printCodeBlocksValidateHelp, parseAgentCompactArgs as r, runCodeBlocksValidate, compactAgentDocs as t };