@farming-labs/docs 0.2.60 → 0.2.62

package/dist/golden-evaluations-BN9u2wxw.mjs

@@ -1,1483 +0,0 @@
-import { Ot as resolveDocsAudienceMdxContent, Tt as findDocsAudienceMdxTags, _n as hasStructuredPageAgentContract, vn as normalizePageAgentFrontmatter } from "./agent-BFqyqEnC.mjs";
-import { n as agentVersionConstraintsOverlap, o as normalizeAgentVersion, r as normalizeAgentFramework } from "./agent-scope-CCaIY1aK.mjs";
-import { t as extractCodeBlocksFromMarkdown } from "./code-blocks-qe0T8-xe.mjs";
-import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
-import path from "node:path";
-
-//#region src/agent-usefulness.ts
-/** Build analyzer inputs from the same filesystem MCP pages used by doctor and review. */
-function createAgentUsefulnessPagesFromMcp(rootDir, pages) {
-	return pages.map((page) => {
-		const sourcePath = page.sourcePath ?? page.url;
-		const absoluteSourcePath = page.sourcePath ? path.isAbsolute(page.sourcePath) ? page.sourcePath : path.join(rootDir, page.sourcePath) : void 0;
-		const source = absoluteSourcePath && existsSync(absoluteSourcePath) ? readFileSync(absoluteSourcePath, "utf-8") : page.rawContent ?? page.agentFallbackRawContent ?? page.content;
-		const absoluteAgentPath = Boolean(absoluteSourcePath && /(?:^|\/)(?:page|index|\+page)\.(?:md|mdx|svx)$/i.test(absoluteSourcePath)) && absoluteSourcePath ? path.join(path.dirname(absoluteSourcePath), "agent.md") : void 0;
-		const hasAgentSource = Boolean(absoluteAgentPath && existsSync(absoluteAgentPath));
-		return {
-			route: page.url,
-			sourcePath,
-			source,
-			agentSourcePath: hasAgentSource && absoluteAgentPath ? path.relative(rootDir, absoluteAgentPath).replace(/\\/g, "/") : void 0,
-			agentSource: hasAgentSource && absoluteAgentPath ? readFileSync(absoluteAgentPath, "utf-8") : void 0,
-			title: page.title,
-			description: page.description,
-			related: page.related,
-			framework: page.framework,
-			version: page.version,
-			agent: page.agent
-		};
-	});
-}
-const DEFAULT_DOCS_COMMANDS = [
-	"init",
-	"dev",
-	"deploy",
-	"preview",
-	"cloud init",
-	"cloud sync",
-	"cloud check",
-	"cloud deploy",
-	"cloud preview",
-	"mcp",
-	"agent compact",
-	"agent export",
-	"agents generate",
-	"doctor",
-	"review",
-	"codeblocks validate",
-	"code-blocks validate",
-	"search sync",
-	"sitemap generate",
-	"robots generate",
-	"upgrade",
-	"downgrade"
-];
-const ACTIONABLE_PATTERN = /\b(?:add|authenticate|build|configure|create|debug|deploy|disable|enable|fetch|fix|implement|install|integrate|migrate|open|remove|run|set|set\s*up|test|troubleshoot|update|upgrade)\b/i;
-const PREREQUISITE_PATTERN = /(?:^|\n)\s{0,3}#{1,6}\s+(?:before you begin|prerequisites?|requirements?|setup)\b|\b(?:before (?:starting|you begin)|requires? (?:an?|the|you))\b/i;
-const EXPECTED_RESULT_PATTERN = /(?:^|\n)\s{0,3}#{1,6}\s+(?:expected (?:result|output)|outcome|result|success|verification)\b|\b(?:you should see|expected to (?:see|return|produce)|succeeds? when|tests? pass(?:es)?)\b/i;
-const RECOVERY_PATTERN = /(?:^|\n)\s{0,3}#{1,6}\s+(?:failure modes?|recovery|rollback|troubleshooting)\b|\b(?:if .{0,80} fails?|recover(?:y)?|restore|retry|revert|roll back|undo)\b/i;
-const STRONG_SPECIFIC_CONTEXT_PATTERN = /(?:@[a-z0-9_-]+\/[a-z0-9_.-]+|(?:^|\s)--[a-z][\w-]*|(?:^|\s)(?:\.\.?\/|\/)[\w./-]+|\b[\w-]+\.(?:[cm]?[jt]sx?|json|mdx?|vue|svelte|astro)\b|\bv?\d+(?:\.\d+)+\b)/im;
-const GENERIC_SENTENCE_PATTERN = /\b(?:follow|keep answers|refer to|read|use) (?:the |this )?(?:documentation|docs|instructions|page)\b|\bkeep answers grounded\b|\bpoint to (?:the )?(?:closest )?related docs\b|\bif the request moves beyond this page\b|\bdo not (?:guess|invent)\b/i;
-const FRAMEWORK_PATTERNS = [
-	["nextjs", /\bNext\.js\b|@farming-labs\/next\b|\bnext\.config\b|\bApp Router\b/i],
-	["tanstackstart", /\bTanStack Start\b|@farming-labs\/(?:tanstack|tanstack-start)\b|\bcreateFileRoute\b/i],
-	["sveltekit", /\bSvelteKit\b|@farming-labs\/svelte(?:kit)?\b|\bhooks\.server\b|\+server\.[cm]?[jt]s\b/i],
-	["astro", /\bAstro\b|@farming-labs\/astro\b|\bastro\.config\b/i],
-	["nuxt", /\bNuxt\b|@farming-labs\/nuxt\b|\bnuxt\.config\b/i]
-];
-const PACKAGE_MANAGER_BUILT_INS = {
-	npm: new Set([
-		"access",
-		"adduser",
-		"audit",
-		"cache",
-		"ci",
-		"config",
-		"dedupe",
-		"exec",
-		"help",
-		"init",
-		"install",
-		"link",
-		"login",
-		"logout",
-		"org",
-		"outdated",
-		"owner",
-		"pack",
-		"ping",
-		"prefix",
-		"profile",
-		"prune",
-		"publish",
-		"query",
-		"rebuild",
-		"repo",
-		"restart",
-		"root",
-		"run",
-		"run-script",
-		"search",
-		"shrinkwrap",
-		"star",
-		"stars",
-		"start",
-		"stop",
-		"team",
-		"test",
-		"token",
-		"uninstall",
-		"unpublish",
-		"unstar",
-		"update",
-		"version",
-		"view",
-		"whoami"
-	]),
-	pnpm: new Set([
-		"add",
-		"approve-builds",
-		"audit",
-		"bin",
-		"config",
-		"create",
-		"dedupe",
-		"deploy",
-		"dlx",
-		"env",
-		"exec",
-		"fetch",
-		"help",
-		"import",
-		"init",
-		"install",
-		"link",
-		"list",
-		"outdated",
-		"pack",
-		"patch",
-		"patch-commit",
-		"prune",
-		"publish",
-		"rebuild",
-		"remove",
-		"root",
-		"run",
-		"server",
-		"setup",
-		"store",
-		"test",
-		"unlink",
-		"update",
-		"view",
-		"why"
-	]),
-	yarn: new Set([
-		"add",
-		"bin",
-		"cache",
-		"config",
-		"create",
-		"dedupe",
-		"dlx",
-		"exec",
-		"help",
-		"info",
-		"init",
-		"install",
-		"link",
-		"npm",
-		"pack",
-		"plugin",
-		"rebuild",
-		"remove",
-		"run",
-		"set",
-		"stage",
-		"unlink",
-		"up",
-		"why",
-		"workspace",
-		"workspaces"
-	]),
-	bun: new Set([
-		"add",
-		"build",
-		"create",
-		"dev",
-		"help",
-		"install",
-		"link",
-		"pm",
-		"publish",
-		"remove",
-		"repl",
-		"run",
-		"test",
-		"unlink",
-		"update",
-		"upgrade",
-		"x"
-	])
-};
-const PACKAGE_MANAGER_OPTIONS_WITH_VALUES = new Set([
-	"--cwd",
-	"--dir",
-	"--filter",
-	"--prefix",
-	"--workspace",
-	"-C",
-	"-F",
-	"-w"
-]);
-function isAgentContextVisible(scopes) {
-	return scopes.every((scope) => scope.only === void 0 || scope.only === "agent");
-}
-/**
-* Extract actual agent-only context while ignoring examples in fenced and inline code.
-*
-* `<Agent>` is agent-only shorthand. `<Audience>` counts only when `only` is the
-* static value `"agent"`; human-only and dynamic/invalid audience declarations do
-* not contribute to agent-context usefulness metrics.
-*/
-function extractAgentBlocks(source, options = {}) {
-	const sourcePath = options.sourcePath ?? "unknown";
-	const tags = findDocsAudienceMdxTags(source);
-	const blocks = [];
-	const scopes = [];
-	let nextScopeId = 1;
-	let cursor = 0;
-	let active;
-	const appendVisibleContent = (content) => {
-		if (active && isAgentContextVisible(scopes)) active.content.push(content);
-	};
-	const finishActiveBlock = () => {
-		if (!active) return;
-		blocks.push({
-			sourcePath,
-			route: options.route,
-			line: active.line,
-			content: active.content.join("").trim()
-		});
-		active = void 0;
-	};
-	for (const tag of tags) {
-		const activeScope = scopes.at(-1);
-		if (tag.closing && activeScope?.name !== tag.name) continue;
-		appendVisibleContent(source.slice(cursor, tag.index));
-		cursor = tag.end;
-		if (tag.closing) {
-			const closedScope = scopes.pop();
-			if (active && closedScope?.id === active.scopeId) finishActiveBlock();
-			continue;
-		}
-		if (tag.selfClosing) continue;
-		const scope = {
-			id: nextScopeId,
-			name: tag.name,
-			only: tag.only
-		};
-		nextScopeId += 1;
-		scopes.push(scope);
-		const isAgentOnly = tag.name === "Agent" || tag.name === "Audience" && tag.only === "agent";
-		if (!active && isAgentOnly && isAgentContextVisible(scopes)) active = {
-			line: source.slice(0, tag.index).split(/\r?\n/).length,
-			scopeId: scope.id,
-			content: []
-		};
-	}
-	appendVisibleContent(source.slice(cursor));
-	return blocks;
-}
-/** Analyze page-level context quality without executing documented commands. */
-function analyzeAgentUsefulness(options) {
-	const rootDir = path.resolve(options.rootDir);
-	const packageManager = options.packageManager ?? detectPackageManager(rootDir);
-	const knownDocsCommands = new Set([...DEFAULT_DOCS_COMMANDS, ...options.knownDocsCommands ?? []]);
-	const packageManifests = readProjectPackageManifests(rootDir);
-	const pages = options.pages.map((page) => analyzePage(page));
-	const findings = [];
-	const unhealthyCommandKeys = /* @__PURE__ */ new Set();
-	const unverifiedCommandKeys = /* @__PURE__ */ new Set();
-	const blockQuality = analyzeBlockQuality(pages, options.boilerplate);
-	findings.push(...blockQuality.findings);
-	let completeTaskPages = 0;
-	let missingPrerequisites = 0;
-	let missingExpectedResults = 0;
-	let missingRecovery = 0;
-	let conflictingPages = 0;
-	let ambiguousPages = 0;
-	let mismatchedPages = 0;
-	let commandCount = 0;
-	let coveredActionablePages = 0;
-	let missingRelatedPages = 0;
-	let brokenRelatedLinks = 0;
-	const knownRoutes = new Set(options.pages.map((page) => normalizeRoute(page.route)));
-	for (const analysis of pages) {
-		const { page, agent, actionable, projectedSource } = analysis;
-		if (actionable) {
-			const guidance = [
-				stripFencedContent(projectedSource),
-				page.agentSource ? stripFencedContent(page.agentSource) : void 0,
-				...analysis.blocks.map((block) => stripFencedContent(block.content))
-			].filter((value) => Boolean(value)).join("\n\n");
-			const taskIssuesBefore = findings.length;
-			if (!agent?.prerequisites?.length && !PREREQUISITE_PATTERN.test(guidance)) {
-				missingPrerequisites += 1;
-				findings.push(makeFinding(page, {
-					code: "task-missing-prerequisites",
-					severity: "warning",
-					category: "task",
-					message: "Actionable agent guidance is missing prerequisites or an explicit before-you-begin condition."
-				}));
-			}
-			if (!hasExpectedResult(agent) && !EXPECTED_RESULT_PATTERN.test(guidance)) {
-				missingExpectedResults += 1;
-				findings.push(makeFinding(page, {
-					code: "task-missing-expected-result",
-					severity: "warning",
-					category: "task",
-					message: "Actionable agent guidance is missing an observable outcome or expected verification result."
-				}));
-			}
-			if (!hasRecovery(agent) && !RECOVERY_PATTERN.test(guidance)) {
-				missingRecovery += 1;
-				findings.push(makeFinding(page, {
-					code: "task-missing-recovery",
-					severity: "warning",
-					category: "task",
-					message: "Actionable agent guidance is missing rollback, recovery, or resolved failure-mode steps."
-				}));
-			}
-			if (findings.length === taskIssuesBefore) completeTaskPages += 1;
-		}
-		const applicability = analyzeApplicability(page, agent, actionable, options.projectFramework);
-		findings.push(...applicability.findings);
-		if (applicability.conflicting) conflictingPages += 1;
-		if (applicability.ambiguous) ambiguousPages += 1;
-		if (applicability.mismatched) mismatchedPages += 1;
-		for (const [commandIndex, command] of analysis.shellCommands.entries()) {
-			commandCount += 1;
-			const commandKey = `${page.sourcePath}:${command.line ?? 1}:${commandIndex}`;
-			const commandAnalysis = analyzeCommand({
-				page,
-				command,
-				rootDir,
-				packageManager,
-				knownDocsCommands,
-				packageManifests
-			});
-			if (commandAnalysis.status === "unhealthy") unhealthyCommandKeys.add(commandKey);
-			if (commandAnalysis.status === "unverified") unverifiedCommandKeys.add(commandKey);
-			findings.push(...commandAnalysis.findings);
-		}
-		if (actionable) {
-			const related = normalizeRelated(page.related);
-			const validRelated = related.filter((href) => {
-				const route = internalRelatedRoute(href);
-				return route !== void 0 && knownRoutes.has(route);
-			});
-			for (const href of related) {
-				const route = internalRelatedRoute(href);
-				if (!route || knownRoutes.has(route)) continue;
-				brokenRelatedLinks += 1;
-				findings.push(makeFinding(page, {
-					code: "related-broken",
-					severity: "warning",
-					category: "related",
-					message: `Related page does not resolve to a known docs route: ${href}`
-				}));
-			}
-			if (validRelated.length > 0) coveredActionablePages += 1;
-			else {
-				missingRelatedPages += 1;
-				findings.push(makeFinding(page, {
-					code: "related-missing",
-					severity: "suggestion",
-					category: "related",
-					message: "Actionable agent guidance has no valid related-page route."
-				}));
-			}
-		}
-	}
-	const actionablePages = pages.filter((page) => page.actionable).length;
-	const usefulBlocks = Math.max(0, blockQuality.totalBlocks - blockQuality.lowQualityBlockKeys.size);
-	return {
-		findings: findings.sort(compareFindings),
-		metrics: {
-			totalPages: pages.length,
-			actionablePages,
-			agentBlocks: {
-				total: blockQuality.totalBlocks,
-				pages: pages.filter((page) => page.blocks.length > 0).length,
-				duplicate: blockQuality.duplicateBlockKeys.size,
-				boilerplate: blockQuality.boilerplateBlockKeys.size,
-				generic: blockQuality.genericBlockKeys.size,
-				useful: usefulBlocks
-			},
-			taskCompleteness: {
-				completePages: completeTaskPages,
-				missingPrerequisites,
-				missingExpectedResults,
-				missingRecovery,
-				coverage: percentage(completeTaskPages, actionablePages)
-			},
-			applicability: {
-				conflictingPages,
-				ambiguousPages,
-				mismatchedPages
-			},
-			commands: {
-				total: commandCount,
-				healthy: Math.max(0, commandCount - unhealthyCommandKeys.size - unverifiedCommandKeys.size),
-				unhealthy: unhealthyCommandKeys.size,
-				unverified: unverifiedCommandKeys.size
-			},
-			related: {
-				coveredActionablePages,
-				missingActionablePages: missingRelatedPages,
-				brokenLinks: brokenRelatedLinks,
-				coverage: percentage(coveredActionablePages, actionablePages)
-			}
-		}
-	};
-}
-function analyzePage(page) {
-	const agent = normalizePageAgentFrontmatter(page.agent);
-	const projectedSource = resolveDocsAudienceMdxContent(page.source, "agent");
-	const blocks = extractAgentBlocks(page.source, {
-		sourcePath: page.sourcePath,
-		route: page.route
-	});
-	const shellCommands = collectPageCommands(page, agent, projectedSource);
-	return {
-		page,
-		agent,
-		blocks,
-		projectedSource,
-		shellCommands,
-		actionable: page.actionable ?? (hasStructuredPageAgentContract(agent) || shellCommands.length > 0 || blocks.some((block) => ACTIONABLE_PATTERN.test(block.content)) || ACTIONABLE_PATTERN.test(page.agentSource ?? ""))
-	};
-}
-function analyzeBlockQuality(pages, config) {
-	const findings = [];
-	const allBlocks = pages.flatMap((analysis) => analysis.blocks.map((block, index) => ({
-		analysis,
-		block,
-		index
-	})));
-	const signatureGroups = /* @__PURE__ */ new Map();
-	const sentenceOccurrences = /* @__PURE__ */ new Map();
-	const blockSentences = /* @__PURE__ */ new Map();
-	for (const item of allBlocks) {
-		const key = blockKey(item.block, item.index);
-		const sentences = splitNormalizedSentences(item.block.content);
-		blockSentences.set(key, sentences);
-		const signature = normalizeBlockSignature(item.block.content);
-		if (signature) {
-			const group = signatureGroups.get(signature) ?? [];
-			group.push(item);
-			signatureGroups.set(signature, group);
-		}
-		for (const sentence of new Set(sentences)) {
-			const occurrences = sentenceOccurrences.get(sentence) ?? /* @__PURE__ */ new Set();
-			occurrences.add(key);
-			sentenceOccurrences.set(sentence, occurrences);
-		}
-	}
-	const minOccurrences = Math.max(2, Math.round(config?.minOccurrences ?? 3));
-	const corpusRatio = clampRatio(config?.corpusRatio ?? .2);
-	const repeatedThreshold = Math.min(minOccurrences, Math.max(2, Math.ceil(allBlocks.length * corpusRatio)));
-	const blockRatio = clampRatio(config?.blockRatio ?? .5);
-	const repeatedSentences = new Set([...sentenceOccurrences].filter(([, occurrences]) => occurrences.size >= repeatedThreshold).map(([sentence]) => sentence));
-	const duplicateBlockKeys = /* @__PURE__ */ new Set();
-	const boilerplateBlockKeys = /* @__PURE__ */ new Set();
-	const genericBlockKeys = /* @__PURE__ */ new Set();
-	const lowQualityBlockKeys = /* @__PURE__ */ new Set();
-	for (const group of signatureGroups.values()) {
-		if (group.length < 2) continue;
-		const relatedFiles = Array.from(new Set(group.map((item) => item.block.sourcePath))).sort();
-		for (const item of group) {
-			const key = blockKey(item.block, item.index);
-			duplicateBlockKeys.add(key);
-			lowQualityBlockKeys.add(key);
-			findings.push(makeFinding(item.analysis.page, {
-				code: "agent-block-duplicate",
-				severity: "warning",
-				category: "context",
-				line: item.block.line,
-				relatedFiles: relatedFiles.filter((file) => file !== item.block.sourcePath),
-				message: `Agent-only block duplicates context used on ${group.length - 1} other page${group.length === 2 ? "" : "s"}.`
-			}));
-		}
-	}
-	for (const item of allBlocks) {
-		const key = blockKey(item.block, item.index);
-		const sentences = blockSentences.get(key) ?? [];
-		const totalChars = sentences.reduce((total, sentence) => total + sentence.length, 0);
-		const repeatedChars = sentences.filter((sentence) => repeatedSentences.has(sentence)).reduce((total, sentence) => total + sentence.length, 0);
-		const ratio = totalChars > 0 ? repeatedChars / totalChars : 0;
-		if (ratio >= blockRatio) {
-			boilerplateBlockKeys.add(key);
-			lowQualityBlockKeys.add(key);
-			if (!duplicateBlockKeys.has(key)) findings.push(makeFinding(item.analysis.page, {
-				code: "agent-block-boilerplate",
-				severity: "warning",
-				category: "context",
-				line: item.block.line,
-				message: `${Math.round(ratio * 100)}% of this agent-only block repeats sentences used across the docs corpus.`
-			}));
-		}
-		if (isGenericAgentBlock(item.block.content, sentences)) {
-			genericBlockKeys.add(key);
-			lowQualityBlockKeys.add(key);
-			findings.push(makeFinding(item.analysis.page, {
-				code: "agent-block-generic",
-				severity: "suggestion",
-				category: "context",
-				line: item.block.line,
-				message: "Agent-only block is generic and lacks a concrete command, path, identifier, version, or task-specific constraint."
-			}));
-		}
-	}
-	return {
-		findings,
-		totalBlocks: allBlocks.length,
-		duplicateBlockKeys,
-		boilerplateBlockKeys,
-		genericBlockKeys,
-		lowQualityBlockKeys
-	};
-}
-function analyzeApplicability(page, agent, actionable, projectFramework) {
-	const findings = [];
-	const topFrameworks = normalizeFrameworks(page.framework);
-	const contractFrameworks = normalizeFrameworks(agent?.appliesTo?.framework);
-	const topVersions = normalizeValues(page.version);
-	const contractVersions = normalizeValues(agent?.appliesTo?.version);
-	let conflicting = false;
-	let ambiguous = false;
-	let mismatched = false;
-	if (topFrameworks.length > 0 && contractFrameworks.length > 0 && !setsOverlap(topFrameworks, contractFrameworks)) {
-		conflicting = true;
-		findings.push(makeFinding(page, {
-			code: "applicability-framework-conflict",
-			severity: "warning",
-			category: "applicability",
-			message: `Top-level framework (${topFrameworks.join(", ")}) conflicts with agent.appliesTo.framework (${contractFrameworks.join(", ")}).`
-		}));
-	}
-	if (topVersions.length > 0 && contractVersions.length > 0 && !versionSetsCompatible(topVersions, contractVersions)) {
-		conflicting = true;
-		findings.push(makeFinding(page, {
-			code: "applicability-version-conflict",
-			severity: "warning",
-			category: "applicability",
-			message: `Top-level version (${topVersions.join(", ")}) conflicts with agent.appliesTo.version (${contractVersions.join(", ")}).`
-		}));
-	}
-	const declaredFrameworks = Array.from(new Set([...topFrameworks, ...contractFrameworks]));
-	const inferredFrameworks = inferFrameworks(`${page.source}\n${page.agentSource ?? ""}`);
-	if (actionable && declaredFrameworks.length === 0 && inferredFrameworks.length > 1) {
-		ambiguous = true;
-		findings.push(makeFinding(page, {
-			code: "applicability-framework-ambiguous",
-			severity: "warning",
-			category: "applicability",
-			message: `Actionable page references multiple frameworks (${inferredFrameworks.join(", ")}) without framework applicability metadata.`
-		}));
-	}
-	const normalizedProjectFramework = projectFramework ? normalizeAgentFramework(projectFramework) : void 0;
-	const effectiveFrameworks = declaredFrameworks.length > 0 ? declaredFrameworks : inferredFrameworks;
-	if (actionable && normalizedProjectFramework && effectiveFrameworks.length > 0 && !effectiveFrameworks.includes(normalizedProjectFramework)) {
-		mismatched = true;
-		findings.push(makeFinding(page, {
-			code: "applicability-framework-mismatch",
-			severity: "warning",
-			category: "applicability",
-			message: `Page applicability (${effectiveFrameworks.join(", ")}) does not include the detected project framework (${normalizedProjectFramework}).`
-		}));
-	}
-	if (actionable && topVersions.length === 0 && contractVersions.length === 0 && hasAmbiguousVersionSignals(`${page.source}\n${page.agentSource ?? ""}`)) {
-		ambiguous = true;
-		findings.push(makeFinding(page, {
-			code: "applicability-version-ambiguous",
-			severity: "warning",
-			category: "applicability",
-			message: "Actionable page discusses multiple current, legacy, or migrated versions without version applicability metadata."
-		}));
-	}
-	return {
-		findings,
-		conflicting,
-		ambiguous,
-		mismatched
-	};
-}
-function analyzeCommand(options) {
-	const findings = [];
-	let verificationEstablished = false;
-	const commandText = normalizeShellCommand(options.command.run);
-	if (!commandText) return commandAnalysis(findings);
-	let commandCwd = options.command.cwd ?? ".";
-	const inlineCwd = /^(?:cd)\s+([^;&|]+?)\s*&&\s*(.+)$/s.exec(commandText);
-	const executableCommand = inlineCwd?.[2]?.trim() ?? commandText;
-	if (inlineCwd?.[1]) commandCwd = stripShellQuotes(inlineCwd[1].trim());
-	const resolvedCwd = path.resolve(options.rootDir, commandCwd);
-	if (!isPathInside(options.rootDir, resolvedCwd)) {
-		findings.push(commandFinding(options, {
-			code: "command-cwd-outside-root",
-			severity: "error",
-			message: `Command working directory resolves outside the project root: ${commandCwd}`
-		}));
-		return commandAnalysis(findings);
-	}
-	if (!existsSync(resolvedCwd)) {
-		findings.push(commandFinding(options, {
-			code: "command-cwd-missing",
-			severity: "error",
-			message: `Command working directory does not exist: ${commandCwd}`
-		}));
-		return commandAnalysis(findings);
-	}
-	const tokens = tokenizeShellCommand(executableCommand);
-	const commandPackageManager = readCommandPackageManager(tokens);
-	const expectedPackageManager = options.command.packageManagerHint ?? (options.command.source === "contract" ? options.packageManager : void 0);
-	if (commandPackageManager && expectedPackageManager && commandPackageManager !== expectedPackageManager) findings.push(commandFinding(options, {
-		code: "command-package-manager-mismatch",
-		severity: "warning",
-		message: `Command uses ${commandPackageManager}, but ${expectedPackageManager} is expected for this project or code block.`
-	}));
-	const workspaceSelection = readWorkspaceSelection(tokens, commandPackageManager);
-	const workspaceResolution = resolveWorkspaceSelection(workspaceSelection, options.packageManifests, options.rootDir);
-	if (workspaceResolution.status === "unresolved") {
-		const selectors = workspaceSelection.selectors.length ? workspaceSelection.selectors.join(", ") : "all workspaces";
-		findings.push(commandFinding(options, {
-			code: "command-unverified",
-			severity: "suggestion",
-			message: `Workspace selector could not be resolved statically (${selectors}); this command is unverified.`
-		}));
-	}
-	const script = readPackageScript(tokens);
-	if (script) {
-		const packageJsons = workspaceResolution.status === "resolved" ? workspaceResolution.manifests : workspaceResolution.status === "none" ? [readNearestPackageJson(resolvedCwd, options.rootDir)].filter((manifest) => Boolean(manifest)) : [];
-		if (workspaceResolution.status === "none" && packageJsons.length === 0) findings.push(commandFinding(options, {
-			code: "command-unverified",
-			severity: "suggestion",
-			message: `No package.json could be found for package script "${script}"; this command is unverified.`
-		}));
-		for (const packageJson of packageJsons) if (packageJson.scripts.has(script)) verificationEstablished = true;
-		else findings.push(commandFinding(options, {
-			code: "command-script-missing",
-			severity: "error",
-			message: `Command references package script "${script}", but that script is not defined in ${packageJson.relativePath}.`
-		}));
-	}
-	const docsCommand = readDocsCommand(tokens);
-	if (docsCommand) if (matchesKnownDocsCommand(docsCommand, options.knownDocsCommands)) verificationEstablished = true;
-	else findings.push(commandFinding(options, {
-		code: "command-cli-unknown",
-		severity: "error",
-		message: `Command references an unknown docs CLI command: docs ${docsCommand}`
-	}));
-	if (isStaticallyKnownPackageManagerCommand(tokens) || isVersionProbe(tokens)) verificationEstablished = true;
-	if (!verificationEstablished && findings.length === 0) findings.push(commandFinding(options, {
-		code: "command-unverified",
-		severity: "suggestion",
-		message: "Command form could not be verified statically; this command is unverified."
-	}));
-	return commandAnalysis(findings);
-}
-function commandAnalysis(findings) {
-	if (findings.some((finding) => finding.code !== "command-unverified")) return {
-		findings,
-		status: "unhealthy"
-	};
-	if (findings.length > 0) return {
-		findings,
-		status: "unverified"
-	};
-	return {
-		findings,
-		status: "healthy"
-	};
-}
-function collectPageCommands(page, agent, projectedSource) {
-	const commands = [];
-	for (const command of agent?.commands ?? []) commands.push(normalizeAgentCommand(command, page.sourcePath));
-	for (const verification of agent?.verification ?? []) if (typeof verification !== "string" && verification.run) commands.push({
-		run: verification.run,
-		sourcePath: page.sourcePath,
-		source: "contract"
-	});
-	collectMarkdownCommands(commands, projectedSource, page.sourcePath);
-	if (page.agentSource) collectMarkdownCommands(commands, page.agentSource, page.agentSourcePath ?? page.sourcePath);
-	return dedupeCommands(commands);
-}
-function collectMarkdownCommands(commands, source, sourcePath) {
-	const blocks = extractCodeBlocksFromMarkdown({
-		source,
-		filePath: sourcePath,
-		relativePath: sourcePath
-	});
-	for (const block of blocks) {
-		if (!/^(?:bash|console|sh|shell|zsh)$/i.test(block.language ?? "")) continue;
-		for (const command of shellLines(block.code, block.language)) commands.push({
-			run: command,
-			line: block.lineStart,
-			sourcePath,
-			packageManagerHint: block.packageManager,
-			source: "fence"
-		});
-	}
-}
-function normalizeAgentCommand(command, sourcePath) {
-	return typeof command === "string" ? {
-		run: command,
-		sourcePath,
-		source: "contract"
-	} : {
-		run: command.run,
-		cwd: command.cwd,
-		sourcePath,
-		source: "contract"
-	};
-}
-function shellLines(code, language) {
-	const lines = code.replace(/\\\s*\r?\n\s*/g, " ").split(/\r?\n/);
-	const promptedConsole = language?.toLowerCase() === "console" && lines.some((line) => /^(?:\$|>)\s+/.test(line.trim()));
-	return lines.map((line) => line.trim()).filter((line) => !promptedConsole || /^(?:\$|>)\s+/.test(line)).map((line) => line.replace(/^(?:\$|>)\s+/, "")).filter((line) => Boolean(line) && !line.startsWith("#") && !/^\w+=\S+$/.test(line));
-}
-function dedupeCommands(commands) {
-	const seen = /* @__PURE__ */ new Set();
-	return commands.filter((command) => {
-		const key = `${command.sourcePath ?? ""}\0${command.cwd ?? ""}\0${command.run}\0${command.packageManagerHint ?? ""}`;
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
-	});
-}
-function hasExpectedResult(agent) {
-	if (agent?.outcome) return true;
-	return Boolean(agent?.verification?.some((step) => {
-		if (typeof step === "string") return EXPECTED_RESULT_PATTERN.test(step);
-		return Boolean(step.expect?.trim() || EXPECTED_RESULT_PATTERN.test(step.description ?? ""));
-	}));
-}
-function hasRecovery(agent) {
-	if (agent?.rollback?.length) return true;
-	return Boolean(agent?.failureModes?.some((mode) => {
-		if (typeof mode === "string") return RECOVERY_PATTERN.test(mode);
-		return Boolean(mode.resolution?.trim());
-	}));
-}
-function splitNormalizedSentences(content) {
-	const withoutFences = stripFencedContent(content);
-	const sentences = [];
-	for (const line of withoutFences.split(/\r?\n/)) {
-		const cleanedLine = line.replace(/^\s*(?:[-*+] |\d+[.)] )/, "").replace(/^\s{0,3}#{1,6}\s+/, "").trim();
-		if (!cleanedLine) continue;
-		const parts = cleanedLine.match(/[^.!?]+[.!?]?/g) ?? [cleanedLine];
-		for (const part of parts) {
-			const normalized = normalizeSentence(part);
-			if (normalized) sentences.push(normalized);
-		}
-	}
-	return sentences;
-}
-function normalizeSentence(value) {
-	return value.replace(/!?(?:\[([^\]]*)\])\([^)]+\)/g, "$1").replace(/[`*_~]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
-}
-function normalizeBlockSignature(content) {
-	const signature = [];
-	let fence;
-	for (const line of content.replace(/\r\n?/g, "\n").split("\n")) {
-		const trimmed = line.trim();
-		const nextFence = advanceFence(trimmed, fence);
-		if (fence) {
-			if (nextFence) signature.push(`code:${line}`);
-			else signature.push("fence:end");
-			fence = nextFence;
-			continue;
-		}
-		if (nextFence) {
-			signature.push(`fence:start:${trimmed}`);
-			fence = nextFence;
-			continue;
-		}
-		const prose = normalizeSentence(line);
-		if (prose) signature.push(`prose:${prose}`);
-	}
-	return signature.join("\n");
-}
-function stripFencedContent(source) {
-	const output = [];
-	let fence;
-	for (const line of source.split(/\r?\n/)) {
-		const nextFence = advanceFence(line.trim(), fence);
-		if (!fence && !nextFence) output.push(line);
-		fence = nextFence;
-	}
-	return output.join("\n");
-}
-function advanceFence(line, fence) {
-	if (fence) {
-		const closing = /^(`+|~+)\s*$/.exec(line)?.[1];
-		if (closing?.[0] === fence.character && closing.length >= fence.length) return void 0;
-		return fence;
-	}
-	const opening = /^(`{3,}|~{3,})(.*)$/.exec(line)?.[1];
-	if (!opening) return void 0;
-	return {
-		character: opening[0],
-		length: opening.length
-	};
-}
-function isGenericAgentBlock(content, sentences) {
-	const words = normalizeSentence(content).match(/[a-z0-9][a-z0-9_-]*/g) ?? [];
-	const hasSpecificContext = hasMeaningfulSpecificContext(content);
-	const genericSentences = sentences.filter((sentence) => GENERIC_SENTENCE_PATTERN.test(sentence));
-	const totalSentenceChars = sentences.reduce((total, sentence) => total + sentence.length, 0);
-	const genericSentenceChars = genericSentences.reduce((total, sentence) => total + sentence.length, 0);
-	const genericRatio = totalSentenceChars > 0 ? genericSentenceChars / totalSentenceChars : 0;
-	return !hasSpecificContext && words.length < 12 || !hasSpecificContext && sentences.length > 0 && genericRatio >= .67;
-}
-function hasMeaningfulSpecificContext(content) {
-	if (STRONG_SPECIFIC_CONTEXT_PATTERN.test(content)) return true;
-	if (!ACTIONABLE_PATTERN.test(content)) return false;
-	if (/https?:\/\/[^\s)]+/i.test(content)) return true;
-	const trivialInlineValues = new Set([
-		"config",
-		"documentation",
-		"docs",
-		"page",
-		"settings"
-	]);
-	return [...content.matchAll(/`([^`\n]+)`/g)].some((match) => {
-		const value = (match[1] ?? "").trim().toLowerCase();
-		return value.length >= 3 && !trivialInlineValues.has(value);
-	});
-}
-function normalizeFrameworks(value) {
-	return normalizeValues(value).map(normalizeAgentFramework);
-}
-function normalizeValues(value) {
-	const values = Array.isArray(value) ? value : value ? [value] : [];
-	return Array.from(new Set(values.map((item) => item.trim().toLowerCase()).filter((item) => item.length > 0)));
-}
-function inferFrameworks(source) {
-	return FRAMEWORK_PATTERNS.filter(([, pattern]) => pattern.test(source)).map(([name]) => name);
-}
-function hasAmbiguousVersionSignals(source) {
-	if (!/\b(?:current|deprecated|latest|legacy|migrat(?:e|ion)|version)\b/i.test(source)) return false;
-	return new Set([...source.matchAll(/\b(?:v|version\s*)(\d+(?:\.\d+){0,2})\b/gi)].map((match) => match[1])).size > 1;
-}
-function versionSetsCompatible(left, right) {
-	return left.some((leftVersion) => right.some((rightVersion) => versionsCompatible(leftVersion, rightVersion)));
-}
-function versionsCompatible(left, right) {
-	const normalizedLeft = normalizeAgentVersion(left);
-	const normalizedRight = normalizeAgentVersion(right);
-	if (normalizedLeft === normalizedRight) return true;
-	if (isVersionConstraint(normalizedLeft) && isVersionConstraint(normalizedRight)) return agentVersionConstraintsOverlap(normalizedLeft, normalizedRight);
-	return true;
-}
-function isExactVersion(value) {
-	return /^\d+(?:\.\d+){0,2}(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i.test(value);
-}
-function isVersionConstraint(value) {
-	return isExactVersion(value) || /(?:[<>=~^*x]|\|\||\s+-\s+)/i.test(value);
-}
-function setsOverlap(left, right) {
-	return left.some((value) => right.includes(value));
-}
-function normalizeRelated(related) {
-	if (!related) return [];
-	return Array.from(new Set(related.map((item) => typeof item === "string" ? item : item.href).map((item) => item.trim()).filter(Boolean)));
-}
-function internalRelatedRoute(href) {
-	if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#")) return void 0;
-	const pathname = href.split(/[?#]/, 1)[0];
-	if (!pathname) return void 0;
-	return normalizeRoute(pathname);
-}
-function normalizeRoute(route) {
-	const normalized = `/${route}`.replace(/\/+/g, "/").replace(/\.md$/i, "");
-	return normalized.length > 1 ? normalized.replace(/\/+$/, "") : normalized;
-}
-function detectPackageManager(rootDir) {
-	if (existsSync(path.join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(path.join(rootDir, "yarn.lock"))) return "yarn";
-	if (existsSync(path.join(rootDir, "bun.lock")) || existsSync(path.join(rootDir, "bun.lockb"))) return "bun";
-	if (existsSync(path.join(rootDir, "package-lock.json"))) return "npm";
-	const packageJson = readJsonFile(path.join(rootDir, "package.json"));
-	const declared = typeof packageJson?.packageManager === "string" ? packageJson.packageManager : "";
-	return /^(npm|pnpm|yarn|bun)@/.exec(declared)?.[1];
-}
-function normalizeShellCommand(command) {
-	return command.trim().replace(/^\$\s*/, "");
-}
-function tokenizeShellCommand(command) {
-	return command.match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map(stripShellQuotes) ?? [];
-}
-function stripShellQuotes(value) {
-	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
-	return value;
-}
-function readCommandPackageManager(tokens) {
-	const command = tokens[0];
-	if (command === "npx") return "npm";
-	if (command === "pnpx") return "pnpm";
-	if (command === "bunx") return "bun";
-	return command && command in PACKAGE_MANAGER_BUILT_INS ? command : void 0;
-}
-function readPackageScript(tokens) {
-	const manager = readCommandPackageManager(tokens);
-	if (!manager) return void 0;
-	if ([
-		"npx",
-		"pnpx",
-		"bunx"
-	].includes(tokens[0] ?? "")) return void 0;
-	if (manager === "yarn") {
-		const workspaceIndex = findPackageManagerCommandIndex(tokens);
-		if (workspaceIndex >= 0 && tokens[workspaceIndex] === "workspace") return readScriptFromArguments(manager, tokens.slice(workspaceIndex + 2));
-	}
-	return readScriptFromArguments(manager, readPackageManagerArguments(tokens));
-}
-function readScriptFromArguments(manager, commandArguments) {
-	if ([
-		"dlx",
-		"exec",
-		"x"
-	].includes(commandArguments[0] ?? "")) return void 0;
-	if (["run", "run-script"].includes(commandArguments[0] ?? "")) return cleanShellToken(commandArguments[1]);
-	const candidate = cleanShellToken(commandArguments[0]);
-	if (!candidate) return void 0;
-	if ([
-		"start",
-		"stop",
-		"restart",
-		"test"
-	].includes(candidate)) return candidate;
-	return PACKAGE_MANAGER_BUILT_INS[manager]?.has(candidate) ? void 0 : candidate;
-}
-function readWorkspaceSelection(tokens, manager) {
-	if (!manager) return {
-		requested: false,
-		selectors: []
-	};
-	if (manager === "pnpm" || manager === "bun") {
-		const selectors = readOptionValues(tokens, ["--filter"], manager === "pnpm" ? ["-F"] : []);
-		const recursive = manager === "pnpm" && hasOptionBeforeCommand(tokens, ["-r", "--recursive"]);
-		return {
-			requested: selectors.length > 0 || recursive,
-			selectors
-		};
-	}
-	if (manager === "npm") {
-		const selectors = readOptionValues(tokens, ["--workspace"], ["-w"]);
-		const allWorkspaces = hasOptionBeforeCommand(tokens, ["--workspaces"]);
-		return {
-			requested: selectors.length > 0 || allWorkspaces,
-			selectors
-		};
-	}
-	if (manager === "yarn") {
-		const workspaceIndex = findPackageManagerCommandIndex(tokens);
-		if (workspaceIndex >= 0 && tokens[workspaceIndex] === "workspace") {
-			const selector = cleanShellToken(tokens[workspaceIndex + 1]);
-			return {
-				requested: true,
-				selectors: selector ? [selector] : []
-			};
-		}
-		if (workspaceIndex >= 0 && tokens[workspaceIndex] === "workspaces") return {
-			requested: true,
-			selectors: []
-		};
-	}
-	return {
-		requested: false,
-		selectors: []
-	};
-}
-function readOptionValues(tokens, longOptions, shortOptions) {
-	const values = [];
-	for (let index = 1; index < tokens.length; index += 1) {
-		const token = tokens[index] ?? "";
-		if (token === "--" || !token.startsWith("-")) break;
-		if ([...longOptions, ...shortOptions].includes(token)) {
-			const value = cleanShellToken(tokens[index + 1]);
-			if (value) values.push(value);
-			index += 1;
-			continue;
-		}
-		const longOption = longOptions.find((option) => token.startsWith(`${option}=`));
-		if (longOption) {
-			const value = cleanShellToken(token.slice(longOption.length + 1));
-			if (value) values.push(value);
-			continue;
-		}
-		if (PACKAGE_MANAGER_OPTIONS_WITH_VALUES.has(token)) {
-			index += 1;
-			continue;
-		}
-		const shortOption = shortOptions.find((option) => token.startsWith(option) && token.length > option.length);
-		if (shortOption) {
-			const value = cleanShellToken(token.slice(shortOption.length).replace(/^=/, ""));
-			if (value) values.push(value);
-		}
-	}
-	return values;
-}
-function readPackageManagerArguments(tokens) {
-	const commandArguments = [];
-	for (let index = 1; index < tokens.length; index += 1) {
-		const token = tokens[index] ?? "";
-		if (token === "--") break;
-		if (PACKAGE_MANAGER_OPTIONS_WITH_VALUES.has(token)) {
-			index += 1;
-			continue;
-		}
-		if (token.startsWith("-")) continue;
-		commandArguments.push(token);
-	}
-	return commandArguments;
-}
-function findPackageManagerCommandIndex(tokens) {
-	for (let index = 1; index < tokens.length; index += 1) {
-		const token = tokens[index] ?? "";
-		if (token === "--") return -1;
-		if (PACKAGE_MANAGER_OPTIONS_WITH_VALUES.has(token)) {
-			index += 1;
-			continue;
-		}
-		if (!token.startsWith("-")) return index;
-	}
-	return -1;
-}
-function hasOptionBeforeCommand(tokens, options) {
-	for (let index = 1; index < tokens.length; index += 1) {
-		const token = tokens[index] ?? "";
-		if (token === "--" || !token.startsWith("-")) return false;
-		if (options.includes(token)) return true;
-		if (PACKAGE_MANAGER_OPTIONS_WITH_VALUES.has(token)) index += 1;
-	}
-	return false;
-}
-function isStaticallyKnownPackageManagerCommand(tokens) {
-	const manager = readCommandPackageManager(tokens);
-	if (!manager || [
-		"npx",
-		"pnpx",
-		"bunx"
-	].includes(tokens[0] ?? "")) return false;
-	const command = readPackageManagerArguments(tokens)[0];
-	if (!command || [
-		"dlx",
-		"exec",
-		"x"
-	].includes(command)) return false;
-	return Boolean(PACKAGE_MANAGER_BUILT_INS[manager]?.has(command));
-}
-function isVersionProbe(tokens) {
-	return tokens.length === 2 && [
-		"node",
-		"deno",
-		"bun",
-		"npm",
-		"pnpm",
-		"yarn"
-	].includes(tokens[0] ?? "") && ["--version", "-v"].includes(tokens[1] ?? "");
-}
-function resolveWorkspaceSelection(selection, manifests, rootDir) {
-	if (!selection.requested) return {
-		status: "none",
-		manifests: []
-	};
-	if (selection.selectors.length === 0) return {
-		status: "unresolved",
-		manifests: []
-	};
-	const resolved = [];
-	for (const rawSelector of selection.selectors) {
-		const selector = rawSelector.trim();
-		if (!selector || selector.startsWith("!") || /(?:\.\.\.|[?*[\]{}<>])/.test(selector)) return {
-			status: "unresolved",
-			manifests: []
-		};
-		const namedManifest = manifests.get(selector);
-		if (namedManifest) {
-			resolved.push(namedManifest);
-			continue;
-		}
-		const selectorPath = path.resolve(rootDir, selector);
-		const pathManifest = [...manifests.values()].find((manifest) => path.resolve(manifest.directory) === selectorPath);
-		if (!pathManifest) return {
-			status: "unresolved",
-			manifests: []
-		};
-		resolved.push(pathManifest);
-	}
-	return {
-		status: "resolved",
-		manifests: Array.from(new Set(resolved))
-	};
-}
-function cleanShellToken(value) {
-	return value?.replace(/[;&|]+$/, "").trim() || void 0;
-}
-function readDocsCommand(tokens) {
-	const first = tokens[0] ?? "";
-	const isDocsBinary = (token) => token === "docs" || !token.startsWith("@") && /(?:^|\/)\.?(?:bin\/)?docs$/.test(token);
-	let commandStart = -1;
-	if (isDocsBinary(first)) commandStart = 1;
-	else if ([
-		"npx",
-		"pnpx",
-		"bunx"
-	].includes(first) && tokens[1] === "@farming-labs/docs") commandStart = 2;
-	else if ([
-		"npm",
-		"pnpm",
-		"yarn",
-		"bun"
-	].includes(first)) {
-		const launcherIndex = tokens.findIndex((token, index) => index > 0 && [
-			"dlx",
-			"exec",
-			"x"
-		].includes(token));
-		if (launcherIndex >= 0) {
-			const binaryIndex = tokens.findIndex((token, index) => index > launcherIndex && (token === "@farming-labs/docs" || isDocsBinary(token)));
-			if (binaryIndex >= 0) commandStart = binaryIndex + 1;
-		}
-	}
-	if (commandStart < 0) return void 0;
-	return tokens.slice(commandStart).filter((token) => !token.startsWith("-")).slice(0, 2).map((token) => cleanShellToken(token)).filter((token) => Boolean(token)).join(" ");
-}
-function matchesKnownDocsCommand(command, known) {
-	if (!command) return true;
-	if (known.has(command)) return true;
-	const first = command.split(" ")[0];
-	return known.has(first);
-}
-function readNearestPackageJson(startDir, rootDir) {
-	let current = startDir;
-	while (isPathInside(rootDir, current)) {
-		const packagePath = path.join(current, "package.json");
-		const contents = readJsonFile(packagePath);
-		if (contents) {
-			const scripts = contents.scripts && typeof contents.scripts === "object" && !Array.isArray(contents.scripts) ? new Set(Object.keys(contents.scripts)) : /* @__PURE__ */ new Set();
-			return {
-				directory: current,
-				scripts,
-				relativePath: path.relative(rootDir, packagePath).replace(/\\/g, "/") || "package.json"
-			};
-		}
-		if (current === rootDir) break;
-		current = path.dirname(current);
-	}
-}
-function readProjectPackageManifests(rootDir) {
-	const manifests = /* @__PURE__ */ new Map();
-	const ignored = new Set([
-		".git",
-		".next",
-		".nuxt",
-		".output",
-		".svelte-kit",
-		"build",
-		"coverage",
-		"dist",
-		"node_modules",
-		"out"
-	]);
-	const visit = (directory) => {
-		const packagePath = path.join(directory, "package.json");
-		const contents = readJsonFile(packagePath);
-		if (contents) {
-			const name = typeof contents.name === "string" ? contents.name.trim() : "";
-			const scripts = contents.scripts && typeof contents.scripts === "object" && !Array.isArray(contents.scripts) ? new Set(Object.keys(contents.scripts)) : /* @__PURE__ */ new Set();
-			if (name) manifests.set(name, {
-				directory,
-				scripts,
-				relativePath: path.relative(rootDir, packagePath).replace(/\\/g, "/") || "package.json"
-			});
-		}
-		let names;
-		try {
-			names = readdirSync(directory);
-		} catch {
-			return;
-		}
-		for (const name of names) {
-			if (ignored.has(name)) continue;
-			const child = path.join(directory, name);
-			try {
-				if (lstatSync(child).isDirectory()) visit(child);
-			} catch {}
-		}
-	};
-	visit(rootDir);
-	return manifests;
-}
-function readJsonFile(filePath) {
-	if (!existsSync(filePath)) return void 0;
-	try {
-		const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
-	} catch {
-		return;
-	}
-}
-function isPathInside(rootDir, candidate) {
-	const relative = path.relative(rootDir, candidate);
-	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
-}
-function commandFinding(options, finding) {
-	return {
-		...makeFinding(options.page, {
-			...finding,
-			category: "command",
-			line: options.command.line,
-			command: options.command.run
-		}),
-		file: options.command.sourcePath ?? options.page.sourcePath
-	};
-}
-function makeFinding(page, finding) {
-	return {
-		...finding,
-		file: page.sourcePath,
-		route: page.route
-	};
-}
-function blockKey(block, index) {
-	return `${block.sourcePath}:${block.line}:${index}`;
-}
-function compareFindings(left, right) {
-	return left.file.localeCompare(right.file) || (left.line ?? 0) - (right.line ?? 0) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message);
-}
-function percentage(numerator, denominator) {
-	if (denominator === 0) return 0;
-	return Math.round(numerator / denominator * 100);
-}
-function clampRatio(value) {
-	if (!Number.isFinite(value)) return 0;
-	return Math.min(1, Math.max(0, value));
-}
-
-//#endregion
-//#region src/agent-surface-drift.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizeDotPath(value) {
-	const segments = value.trim().replace(/\[\d+\]/gu, "[]").replace(/^\/+|\/+$/g, "").replaceAll("/", ".").split(".").map((segment) => segment.trim()).filter(Boolean);
-	const normalized = [];
-	for (const segment of segments) {
-		if (/^\d+$/u.test(segment) && normalized.length > 0) {
-			normalized[normalized.length - 1] = `${normalized.at(-1)}[]`;
-			continue;
-		}
-		normalized.push(segment);
-	}
-	return normalized.join(".");
-}
-function collectSchemaPaths(options) {
-	const paths = /* @__PURE__ */ new Set();
-	const visited = /* @__PURE__ */ new Set();
-	const visit = (option) => {
-		if (visited.has(option)) return;
-		visited.add(option);
-		const optionPath = normalizeDotPath(option.path);
-		if (optionPath) paths.add(optionPath);
-		for (const child of option.children ?? []) visit(child);
-	};
-	for (const option of options) visit(option);
-	return paths;
-}
-function schemaCoversConfigPath(schemaPaths, configPath) {
-	if (schemaPaths.has(configPath)) return true;
-	if (configPath.endsWith("[]") && schemaPaths.has(configPath.slice(0, -2))) return true;
-	for (const schemaPath of schemaPaths) {
-		if (!schemaPath.endsWith(".*")) continue;
-		const prefix = schemaPath.slice(0, -1);
-		if (configPath.startsWith(prefix) && configPath.length > prefix.length) return true;
-	}
-	return false;
-}
-function readPath(root, dotPath) {
-	const normalized = normalizeDotPath(dotPath);
-	if (!normalized) return {
-		present: true,
-		value: root
-	};
-	let current = root;
-	for (const segment of normalized.split(".")) {
-		if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, segment)) return {
-			present: false,
-			value: void 0
-		};
-		current = current[segment];
-	}
-	return {
-		present: true,
-		value: current
-	};
-}
-function stableJsonValue(value) {
-	if (Array.isArray(value)) return value.map(stableJsonValue);
-	if (!isRecord(value)) return value;
-	return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableJsonValue(value[key])]));
-}
-function displayValue(value, present = true) {
-	if (!present || value === void 0) return "<missing>";
-	if (typeof value === "string") return JSON.stringify(value);
-	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
-	try {
-		return JSON.stringify(stableJsonValue(value));
-	} catch {
-		return "<unserializable>";
-	}
-}
-function valuesMatch(actual, expected) {
-	return actual.present && Object.is(actual.value, expected);
-}
-function mismatchIssue(code, path, expected, actual, label) {
-	const expectedDisplay = displayValue(expected);
-	const actualDisplay = displayValue(actual.value, actual.present);
-	return {
-		code,
-		path,
-		expected: expectedDisplay,
-		actual: actualDisplay,
-		message: `${label} is ${actualDisplay}; expected ${expectedDisplay}.`
-	};
-}
-function compareExpectedValue(issues, discovery, code, path, expected, label) {
-	const actual = readPath(discovery, path);
-	if (!valuesMatch(actual, expected)) issues.push(mismatchIssue(code, path, expected, actual, label));
-}
-/**
-* Compare independently resolved docs values with the public agent discovery and
-* config-schema surfaces. The helper is intentionally pure so doctor, review,
-* and golden evaluations can use the same deterministic drift rules.
-*/
-function analyzeAgentSurfaceDrift(options) {
-	const issues = [];
-	const schemaPaths = collectSchemaPaths(options.schemaOptions);
-	const configPaths = Array.from(new Set(options.configOptionPaths.map(normalizeDotPath).filter(Boolean))).sort();
-	for (const configPath of configPaths) {
-		if (schemaCoversConfigPath(schemaPaths, configPath)) continue;
-		issues.push({
-			code: "config-schema-omission",
-			path: configPath,
-			expected: "documented schema option",
-			actual: "<missing>",
-			message: `Config option ${JSON.stringify(configPath)} is present but missing from the published config schema.`
-		});
-	}
-	const canonicalFields = Array.from(new Set(options.agentContractFields.map((field) => field.trim()).filter(Boolean))).sort();
-	const discoveredFieldsValue = readPath(options.discovery, "agentContract.fields");
-	const discoveredFields = isRecord(discoveredFieldsValue.value) ? Object.keys(discoveredFieldsValue.value).sort() : [];
-	const canonicalFieldSet = new Set(canonicalFields);
-	const discoveredFieldSet = new Set(discoveredFields);
-	for (const field of canonicalFields) {
-		if (discoveredFieldSet.has(field)) continue;
-		const issuePath = `agentContract.fields.${field}`;
-		issues.push({
-			code: "agent-contract-field-missing",
-			path: issuePath,
-			expected: "canonical field",
-			actual: "<missing>",
-			message: `Discovery agent contract is missing canonical field ${JSON.stringify(field)}.`
-		});
-	}
-	for (const field of discoveredFields) {
-		if (canonicalFieldSet.has(field)) continue;
-		const issuePath = `agentContract.fields.${field}`;
-		issues.push({
-			code: "agent-contract-field-unexpected",
-			path: issuePath,
-			expected: "<absent>",
-			actual: "declared field",
-			message: `Discovery agent contract advertises non-canonical field ${JSON.stringify(field)}.`
-		});
-	}
-	compareExpectedValue(issues, options.discovery, "entry-mismatch", "site.entry", options.expected.entry, "Discovery site.entry");
-	compareExpectedValue(issues, options.discovery, "search-enabled-mismatch", "search.enabled", options.expected.search.enabled, "Discovery search.enabled");
-	compareExpectedValue(issues, options.discovery, "search-capability-mismatch", "capabilities.search", options.expected.search.enabled, "Discovery capabilities.search");
-	compareExpectedValue(issues, options.discovery, "search-route-mismatch", "search.endpoint", options.expected.search.endpoint, "Discovery search.endpoint");
-	compareExpectedValue(issues, options.discovery, "mcp-enabled-mismatch", "mcp.enabled", options.expected.mcp.enabled, "Discovery mcp.enabled");
-	compareExpectedValue(issues, options.discovery, "mcp-capability-mismatch", "capabilities.mcp", options.expected.mcp.enabled, "Discovery capabilities.mcp");
-	compareExpectedValue(issues, options.discovery, "mcp-route-mismatch", "mcp.endpoint", options.expected.mcp.endpoint, "Discovery mcp.endpoint");
-	const expectedToolNames = Object.keys(options.expected.mcp.tools).sort();
-	const expectedToolSet = new Set(expectedToolNames);
-	const discoveredToolsValue = readPath(options.discovery, "mcp.tools");
-	const discoveredTools = isRecord(discoveredToolsValue.value) ? discoveredToolsValue.value : {};
-	for (const toolName of expectedToolNames) {
-		const expected = options.expected.mcp.tools[toolName];
-		const path = `mcp.tools.${toolName}`;
-		const actual = Object.prototype.hasOwnProperty.call(discoveredTools, toolName) ? {
-			present: true,
-			value: discoveredTools[toolName]
-		} : {
-			present: false,
-			value: void 0
-		};
-		if (!valuesMatch(actual, expected)) issues.push(mismatchIssue("mcp-tool-mismatch", path, expected, actual, `Discovery ${path}`));
-	}
-	for (const toolName of Object.keys(discoveredTools).sort()) {
-		if (expectedToolSet.has(toolName)) continue;
-		const path = `mcp.tools.${toolName}`;
-		issues.push({
-			code: "mcp-tool-unexpected",
-			path,
-			expected: "<absent>",
-			actual: displayValue(discoveredTools[toolName]),
-			message: `Discovery MCP tools advertise unexpected tool flag ${JSON.stringify(toolName)}.`
-		});
-	}
-	for (const routePath of Object.keys(options.expected.routes).sort()) {
-		const expected = options.expected.routes[routePath];
-		compareExpectedValue(issues, options.discovery, "route-mismatch", routePath, expected, `Discovery ${routePath}`);
-	}
-	return issues.sort((left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
-}
-
-//#endregion
-//#region src/cli/golden-evaluations.ts
-function isPlainRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Normalize the runtime docs.config evaluation shape shared by doctor and review. */
-function resolveGoldenEvaluationInput(evaluationInput) {
-	if (evaluationInput === void 0 || typeof evaluationInput === "boolean") return {
-		tasks: void 0,
-		options: {}
-	};
-	if (!isPlainRecord(evaluationInput)) return {
-		tasks: { evaluationConfig: evaluationInput },
-		options: {}
-	};
-	const options = {
-		surface: evaluationInput.surface,
-		allowNetwork: evaluationInput.allowNetwork,
-		searchTimeoutMs: evaluationInput.searchTimeoutMs,
-		answer: evaluationInput.answer
-	};
-	if (evaluationInput.enabled === false) return {
-		tasks: void 0,
-		options
-	};
-	if ("enabled" in evaluationInput && typeof evaluationInput.enabled !== "boolean") return {
-		tasks: evaluationInput,
-		options
-	};
-	if (!("tasks" in evaluationInput)) return {
-		tasks: void 0,
-		options
-	};
-	const runtimeTasks = evaluationInput.tasks;
-	if (!Array.isArray(runtimeTasks)) return {
-		tasks: runtimeTasks,
-		options
-	};
-	return {
-		tasks: runtimeTasks.map((task) => {
-			if (!isPlainRecord(task)) return task;
-			return {
-				...task,
-				tokenBudget: task.tokenBudget ?? evaluationInput.tokenBudget,
-				topK: task.topK ?? evaluationInput.topK
-			};
-		}),
-		options
-	};
-}
-
-//#endregion
-export { extractAgentBlocks as a, createAgentUsefulnessPagesFromMcp as i, analyzeAgentSurfaceDrift as n, analyzeAgentUsefulness as r, resolveGoldenEvaluationInput as t };