pagegraph 0.6.0 → 0.7.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import * as NFS from "node:fs";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as NodeChildProcess from "node:child_process";
 import { spawn } from "node:child_process";
 import { PassThrough } from "node:stream";
@@ -20616,7 +20616,7 @@ const Boolean$5 = class extends ASTNodeImpl {
 * @category constructors
 * @since 4.0.0
 */
-const boolean = /*#__PURE__*/ new Boolean$5();
+const boolean$1 = /*#__PURE__*/ new Boolean$5();
 /**
 * Constructs a {@link BigInt}.
 *
@@ -25834,7 +25834,7 @@ const Number$2 = /*#__PURE__*/ make$14(number);
 * @category schemas
 * @since 4.0.0
 */
-const Boolean$4 = /*#__PURE__*/ make$14(boolean);
+const Boolean$4 = /*#__PURE__*/ make$14(boolean$1);
 /**
 * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
 *
@@ -26424,6 +26424,28 @@ const makeFilter = makeFilter$1;
 */
 const Finite$3 = /*#__PURE__*/ make$14(finite);
 /**
+* Creates a greater-than-or-equal-to (`>=`) check for any ordered type from an
+* `Order.Order` instance.
+*
+* @category validation
+* @since 4.0.0
+*/
+function makeIsGreaterThanOrEqualTo(options) {
+	const gte = isGreaterThanOrEqualTo$1(options.order);
+	const formatter = options.formatter ?? format$2;
+	return (minimum, annotations) => {
+		return makeFilter((input) => gte(input, minimum), {
+			expected: `a value greater than or equal to ${formatter(minimum)}`,
+			arbitraryConstraint: {
+				order: options.order,
+				minimum
+			},
+			...options.annotate?.(minimum),
+			...annotations
+		});
+	};
+}
+/**
 * Creates an inclusive or exclusive range check for any ordered type from an
 * `Order.Order` instance.
 *
@@ -26458,6 +26480,35 @@ function encodeNumberPayload(number) {
 	return number;
 }
 /**
+* Validates that a number is greater than or equal to the specified value
+* (inclusive).
+*
+* **Details**
+*
+* JSON Schema:
+*
+* This check corresponds to the `minimum` constraint in JSON Schema.
+*
+* Arbitrary:
+*
+* During arbitrary generation, this applies a `minimum` constraint
+* to ensure generated numbers are greater than or equal to the specified value.
+*
+* @category validation
+* @since 4.0.0
+*/
+const isGreaterThanOrEqualTo = /*#__PURE__*/ makeIsGreaterThanOrEqualTo({
+	order: Number$6,
+	annotate: (minimum) => ({
+		representation: {
+			id: "effect/schema/isGreaterThanOrEqualTo",
+			payload: { minimum: encodeNumberPayload(minimum) }
+		},
+		toJsonSchema: () => ({ minimum }),
+		toCode: () => ({ runtime: `Schema.isGreaterThanOrEqualTo(${format$2(minimum)})` })
+	})
+});
+/**
 * Validates that a number is within a specified range. The range boundaries can
 * be inclusive or exclusive based on the provided options.
 *
@@ -26538,6 +26589,19 @@ function isInt(annotations) {
 * @since 3.10.0
 */
 const Int$4 = /*#__PURE__*/ Number$2.check(/*#__PURE__*/ isInt());
+/**
+* Schema for non-negative safe integers, including zero.
+*
+* **When to use**
+*
+* Use when you need a count, index, or size that cannot be negative.
+*
+* @see {@link Int} for safe integers that may be negative
+*
+* @category schemas
+* @since 4.0.0
+*/
+const Natural = /*#__PURE__*/ Int$4.check(/*#__PURE__*/ isGreaterThanOrEqualTo(0));
 const getErrorOptionsKey = (options) => (options?.includeStack === true ? 1 : 0) | (options?.excludeCause === true ? 2 : 0);
 const getErrorOptions = (key) => {
 	switch (key) {
@@ -34612,7 +34676,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.6.0";
+var version = "0.7.0";
 //#endregion
 //#region src/core/projections.ts
 const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
@@ -34928,19 +34992,17 @@ const globToRegExp = (glob) => {
 	return new RegExp(`^${source}$`);
 };
 /**
-* Enforce contextual-link coverage rules: a named set of sitemap-eligible
-* "money" pages each needs `minInbound` incoming `related` edges. Only
-* `related` edges count — breadcrumb ancestry is navigation, not context.
+* Enforce contextual-link coverage rules over an explicit surface.
 *
 * A rule that matches no sitemap-eligible page is itself a violation: a typo or
 * a rule aimed at a noindex page would otherwise pass silently forever.
 */
-function checkCoverage(graph, rules) {
+const checkCoverageRules = (surface, rules) => {
 	const violations = [];
 	for (const rule of rules) {
 		const matcher = globToRegExp(rule.path);
-		const matched = [...graph.nodes.values()].filter((node) => matcher.test(node.path));
-		const eligible = matched.filter(isSitemapEligible);
+		const matched = surface.paths.filter((path) => matcher.test(path));
+		const eligible = surface.eligiblePaths.filter((path) => matcher.test(path));
 		if (eligible.length === 0) {
 			violations.push({
 				severity: "structural",
@@ -34950,19 +35012,55 @@ function checkCoverage(graph, rules) {
 			});
 			continue;
 		}
-		for (const node of eligible) {
-			const inbound = graph.edges.filter((edge) => edge.type === "related" && edge.to === node.path).length;
+		for (const path of eligible) {
+			const inbound = surface.inbound(path);
 			if (inbound >= rule.minInbound) continue;
 			violations.push({
 				severity: "structural",
 				rule: "inbound-link-coverage",
-				path: node.path,
-				message: `"${node.path}" has ${inbound} incoming contextual link(s); the coverage rule requires ${rule.minInbound}.`,
-				fix: `Add ${rule.minInbound - inbound} contextual (related) edge(s) pointing at "${node.path}".`
+				path,
+				message: `"${path}" has ${inbound} incoming contextual link(s); the coverage rule requires ${rule.minInbound}.`,
+				fix: `Add ${rule.minInbound - inbound} contextual link(s) pointing at "${path}".`
 			});
 		}
 	}
 	return violations;
+};
+/** The sitemap-eligible path set of a declared graph, in graph insertion order. */
+const eligiblePathsOf = (graph) => [...graph.nodes.values()].filter(isSitemapEligible).map((node) => node.path);
+/**
+* Enforce contextual-link coverage against the *declared* graph: only `related`
+* edges count — breadcrumb ancestry is navigation, not context.
+*/
+function checkCoverage(graph, rules) {
+	return checkCoverageRules({
+		paths: [...graph.nodes.keys()],
+		eligiblePaths: eligiblePathsOf(graph),
+		inbound: (path) => graph.edges.filter((edge) => edge.type === "related" && edge.to === path).length
+	}, rules);
+}
+/**
+* Enforce contextual-link coverage against the *rendered* graph: only same-origin
+* body-region anchors count. Nav, header, and footer anchors are site chrome, so
+* a page linked solely from them has no contextual inbound link — the same
+* distinction the declared pass draws by counting `related` edges alone.
+*
+* The target universe is the declared graph's sitemap-eligible pages: the globs
+* in `seo.config.ts` are written against declared paths, and the crawl is what
+* supplies the served edges. Pass the crawl's `internalEdges` (each edge carries
+* its `region`).
+*/
+function checkRenderedCoverage(graph, renderedEdges, rules) {
+	const inbound = /* @__PURE__ */ new Map();
+	for (const edge of renderedEdges) {
+		if (edge.region !== "body") continue;
+		inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1);
+	}
+	return checkCoverageRules({
+		paths: [...graph.nodes.keys()],
+		eligiblePaths: eligiblePathsOf(graph),
+		inbound: (path) => inbound.get(path) ?? 0
+	}, rules);
 }
 /** Structural violations fail `pagegraph check`; editorial-only stays green. */
 const hasStructuralViolations = (violations) => violations.some((violation) => violation.severity === "structural");
@@ -35017,7 +35115,7 @@ const CONFIG_FILENAMES = [
 	"seo.config.js",
 	"seo.config.mjs"
 ];
-const messageOf$1 = (cause) => cause instanceof Error ? cause.message : String(cause);
+const messageOf$2 = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** First `seo.config.*` at or above `from`, or undefined at the filesystem root. */
 const findConfigFile = (from) => {
 	let directory = resolve(from);
@@ -35045,7 +35143,7 @@ const loadConfigFile = (configPath) => gen(function* () {
 	yield* logDebug(`Loading SEO config from ${configPath}`);
 	const module = yield* tryPromise({
 		try: () => import(pathToFileURL(configPath).href),
-		catch: (cause) => new SeoCliError({ message: `Could not load ${configPath}: ${messageOf$1(cause)}` })
+		catch: (cause) => new SeoCliError({ message: `Could not load ${configPath}: ${messageOf$2(cause)}` })
 	});
 	if (!isSeoCliConfig(module.default)) return yield* new SeoCliError({ message: `${configPath} must default-export defineSeoConfig({ origin, disallow, loadGraph }).` });
 	return module.default;
@@ -35080,8 +35178,8 @@ const acquireGraph = (config) => gen(function* () {
 	yield* logDebug("Loading the SEO graph…");
 	const loaded = yield* acquireRelease(tryPromise({
 		try: () => config.loadGraph(),
-		catch: (cause) => new SeoCliError({ message: messageOf$1(cause) })
-	}), (acquired) => promise(() => acquired.dispose()).pipe(catchDefect((defect) => logWarning(`Could not dispose the SEO graph loader: ${messageOf$1(defect)}`))));
+		catch: (cause) => new SeoCliError({ message: messageOf$2(cause) })
+	}), (acquired) => promise(() => acquired.dispose()).pipe(catchDefect((defect) => logWarning(`Could not dispose the SEO graph loader: ${messageOf$2(defect)}`))));
 	yield* logDebug(`Loaded SEO graph: ${loaded.graph.nodes.size} nodes, ${loaded.graph.edges.length} edges.`);
 	return loaded.graph;
 });
@@ -35289,6 +35387,17 @@ const renderLinksReport = (report) => {
 		lines.push(`  rendered not declared  ${report.declared.renderedNotDeclared.length}`);
 		for (const edge of report.declared.renderedNotDeclared) lines.push(edgeLine(edge));
 	}
+	if (report.coverage !== void 0) {
+		const { coverage } = report;
+		lines.push("", `Rendered coverage (${coverage.rules} rule(s)):`);
+		if (coverage.ok) lines.push("  ✓ every coverage rule is satisfied by the served anchors.");
+		else for (const violation of coverage.violations) {
+			const where = violation.path ? `  ${violation.path}` : "";
+			lines.push(`  ✗ [${violation.rule}]${where}`);
+			lines.push(`      ${violation.message}`);
+			if (violation.fix) lines.push(`      fix: ${violation.fix}`);
+		}
+	}
 	if (crawl.failures.length > 0) {
 		lines.push("", `${crawl.failures.length} page(s) could not be fetched:`);
 		for (const failure of crawl.failures) lines.push(`  ${failure.url}  ${failure.error}`);
@@ -35306,8 +35415,8 @@ const VERDICT_LABELS = {
 	review: "Review"
 };
 const decisionLine = (record) => [
-	`  ${record.sourceUrl} → ${record.destinationUrl}`,
-	`    realReason ${record.realReason.toFixed(2)} · anchorPresent ${record.anchorPresent.toFixed(2)}`,
+	`  ${record.from} ${record.direction === "both" ? "↔" : "→"} ${record.to}`,
+	`    realReason ${record.realReason.toFixed(2)} · anchorPresent ${record.anchorPresent.toFixed(2)} · direction ${record.direction} · relevance ${record.relevance.label}`,
 	`    "${record.sourceText}"`
 ];
 const verdictBlock = (verdict, records) => {
@@ -35323,8 +35432,9 @@ const verdictBlock = (verdict, records) => {
 */
 const renderLinksDecideReport = (report) => {
 	const { counts } = report;
+	const budget = report.budget === null ? "none" : `${report.budget}/source`;
 	const lines = [
-		`${counts.candidates} candidate(s) · model ${report.model} · threshold ${report.threshold.toFixed(2)}`,
+		`${counts.candidates} candidate(s) · model ${report.model} · threshold ${report.threshold.toFixed(2)} · budget ${budget} · dropped ${report.dropped}`,
 		"",
 		`  recommend  ${counts.recommend}`,
 		`  present    ${counts.present}`,
@@ -36214,6 +36324,30 @@ const breadthFirstDepth = (edges, root) => {
 	return depth;
 };
 /**
+* Assemble a {@link RenderedGraph} from page/edge sets. Edges are already
+* same-origin and path-keyed by the callers, so this is the shared, pure tail of
+* {@link buildRenderedGraph} and {@link renderedGraphFromEdges}.
+*/
+const graphFromEdges = (nodes, edges, root) => {
+	const rootKey = root.replace(/\/+$/, "") || "/";
+	const internalEdges = edges;
+	const contextualEdges = edges.filter((edge) => edge.region === "body");
+	const incoming = new Set(internalEdges.map((edge) => edge.to));
+	const orphans = [...nodes].filter((path) => path !== rootKey && !incoming.has(path)).sort();
+	const depthByPath = breadthFirstDepth(internalEdges, rootKey);
+	let maxDepth = null;
+	for (const value of depthByPath.values()) if (maxDepth === null || value > maxDepth) maxDepth = value;
+	return {
+		nodes: [...nodes],
+		edges,
+		internalEdges,
+		contextualEdges,
+		orphans,
+		depthByPath,
+		maxDepth
+	};
+};
+/**
 * Build the rendered graph from crawled pages. `origin` fixes the graph's
 * same-origin boundary — pages and anchors on another origin are dropped, not
 * silently folded in — and `root` is the normalized path the depth BFS starts
@@ -36222,7 +36356,6 @@ const breadthFirstDepth = (edges, root) => {
 */
 const buildRenderedGraph = (origin, pages, root = "/") => {
 	const graphOrigin = new URL(origin).origin;
-	const rootKey = root.replace(/\/+$/, "") || "/";
 	const edges = [];
 	const nodes = /* @__PURE__ */ new Set();
 	for (const page of pages) {
@@ -36252,21 +36385,39 @@ const buildRenderedGraph = (origin, pages, root = "/") => {
 			});
 		}
 	}
-	const internalEdges = edges;
-	const contextualEdges = edges.filter((edge) => edge.region === "body");
-	const incoming = new Set(internalEdges.map((edge) => edge.to));
-	const orphans = [...nodes].filter((path) => path !== rootKey && !incoming.has(path)).sort();
-	const depthByPath = breadthFirstDepth(internalEdges, rootKey);
-	let maxDepth = null;
-	for (const value of depthByPath.values()) if (maxDepth === null || value > maxDepth) maxDepth = value;
-	return {
-		edges,
-		internalEdges,
-		contextualEdges,
-		orphans,
-		depthByPath,
-		maxDepth
-	};
+	return graphFromEdges(nodes, edges, root);
+};
+/** A URL or an already-normalized graph path key both collapse to the path key. */
+const pathKeyOf = (value) => {
+	try {
+		return normalizePath(new URL(value));
+	} catch {
+		return (value.split(/[?#]/, 1)[0] ?? "").replace(/\/+$/, "") || "/";
+	}
+};
+/**
+* Rebuild a {@link RenderedGraph} from a rendered-edge set alone — the artifact
+* `pagegraph links verify --emit-rendered` writes. Path keys are normalized the
+* same way as a crawl, and `nodes` carries the rendered page paths the artifact
+* recorded, so an edge-less page (a redirect target with no internal links) stays
+* a node and its orphan/depth report survives replay. Without `nodes` the node set
+* falls back to the edge endpoints.
+*/
+const renderedGraphFromEdges = (edges, root = "/", nodes = []) => {
+	const nodeSet = new Set(nodes.map(pathKeyOf));
+	const kept = [];
+	for (const edge of edges) {
+		const from = pathKeyOf(edge.from);
+		const to = pathKeyOf(edge.to);
+		nodeSet.add(from);
+		nodeSet.add(to);
+		kept.push({
+			from,
+			to,
+			region: edge.region
+		});
+	}
+	return graphFromEdges(nodeSet, kept, root);
 };
 const edgeKey = (edge) => `${edge.from}\u0000${edge.to}`;
 const normalizeEdge = (edge) => ({
@@ -36289,6 +36440,97 @@ const diffLinkGraph = (declared, rendered) => {
 		renderedContextualCount: rendered.contextualEdges.length
 	};
 };
+const ARTIFACT_KIND = "links-rendered";
+const REGIONS = /* @__PURE__ */ new Set([
+	"nav",
+	"footer",
+	"header",
+	"body"
+]);
+const decodeArtifactEdges = (input) => {
+	if (!Array.isArray(input)) throw new Error("`edges` must be an array of { from, to, region } edges");
+	return input.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each artifact edge must be an object with string `from` and `to`");
+		const { from, to, region } = item;
+		if (typeof from !== "string" || typeof to !== "string") throw new Error("each artifact edge must have string `from` and `to`");
+		if (region !== void 0 && !REGIONS.has(region)) throw new Error(`artifact edge region must be one of nav, footer, header, body (received ${JSON.stringify(region)})`);
+		return {
+			from,
+			to,
+			region: region ?? "body"
+		};
+	});
+};
+const decodeArtifactNodes = (input) => {
+	if (input === void 0) return [];
+	if (!Array.isArray(input) || !input.every((path) => typeof path === "string")) throw new Error("rendered-edge artifact `nodes` must be an array of paths");
+	return input;
+};
+const decodeArtifactFailures = (input) => {
+	if (input === void 0) return [];
+	if (!Array.isArray(input)) throw new Error("rendered-edge artifact `crawl.failures` must be an array");
+	return input.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each artifact failure must be an object with string `url` and `error`");
+		const { url, error } = item;
+		if (typeof url !== "string" || typeof error !== "string") throw new Error("each artifact failure must have string `url` and `error`");
+		return {
+			url,
+			error
+		};
+	});
+};
+const requiredAbsoluteUrl = (value, field) => {
+	if (typeof value !== "string" || value === "") throw new Error(`rendered-edge artifact must carry a non-empty string \`${field}\``);
+	try {
+		new URL(value);
+	} catch {
+		throw new Error(`rendered-edge artifact \`${field}\` must be an absolute URL (received ${JSON.stringify(value)})`);
+	}
+	return value;
+};
+const requiredInteger = (value, field, minimum) => {
+	if (!Number.isSafeInteger(value) || value < minimum) throw new Error(`rendered-edge artifact \`${field}\` must be an integer >= ${minimum} (received ${JSON.stringify(value)})`);
+	return value;
+};
+/**
+* Decode a rendered-edge artifact from user input. Throws on any other shape —
+* this is user input, not a provider payload. `root`, `bodyTruncated`,
+* `truncatedPages`, `failures`, and `nodes` are optional so a hand-written edge
+* dump that only carries provenance can still be replayed.
+*/
+const decodeRenderedEdgeArtifact = (input) => {
+	if (input === null || typeof input !== "object") throw new Error("rendered-edge artifact must be an object");
+	const value = input;
+	if (value["kind"] !== ARTIFACT_KIND) throw new Error(`rendered-edge artifact \`kind\` must be "${ARTIFACT_KIND}" (received ${JSON.stringify(value["kind"])})`);
+	if (value["schemaVersion"] !== 1) throw new Error(`unsupported rendered-edge artifact schemaVersion: ${JSON.stringify(value["schemaVersion"])}`);
+	const origin = requiredAbsoluteUrl(value["origin"], "origin");
+	const seed = requiredAbsoluteUrl(value["seed"], "seed");
+	const crawl = value["crawl"];
+	if (crawl === null || typeof crawl !== "object") throw new Error("rendered-edge artifact must carry a `crawl` object");
+	const provenance = crawl;
+	const truncatedPages = provenance["truncatedPages"];
+	if (truncatedPages !== void 0 && (!Array.isArray(truncatedPages) || !truncatedPages.every((url) => typeof url === "string"))) throw new Error("rendered-edge artifact `truncatedPages` must be an array of URLs");
+	const bodyTruncated = provenance["bodyTruncated"];
+	if (bodyTruncated !== void 0 && typeof bodyTruncated !== "boolean") throw new Error("rendered-edge artifact `bodyTruncated` must be a boolean");
+	if (typeof provenance["truncated"] !== "boolean") throw new Error("rendered-edge artifact `crawl.truncated` must be a boolean");
+	return {
+		kind: ARTIFACT_KIND,
+		schemaVersion: 1,
+		origin,
+		seed,
+		crawl: {
+			pages: requiredInteger(provenance["pages"], "crawl.pages", 0),
+			root: typeof provenance["root"] === "string" ? provenance["root"] : pathKeyOf(seed),
+			limit: requiredInteger(provenance["limit"], "crawl.limit", 1),
+			truncated: provenance["truncated"],
+			bodyTruncated: bodyTruncated === true,
+			truncatedPages: truncatedPages ?? [],
+			failures: decodeArtifactFailures(provenance["failures"])
+		},
+		nodes: decodeArtifactNodes(value["nodes"]),
+		edges: decodeArtifactEdges(value["edges"])
+	};
+};
 //#endregion
 //#region src/audit/network.ts
 const blockedIpv4Addresses = new BlockList();
@@ -37571,7 +37813,7 @@ const requestTimeoutMs$1 = Int("request-timeout-ms").pipe(withDescription$2("HTT
 const scannerTimeoutMs = Int("scanner-timeout-ms").pipe(withDescription$2("Lighthouse and hosted scanner timeout in milliseconds"), withDefault(18e4));
 const maxBodyBytes$1 = Int("max-body-bytes").pipe(withDescription$2("Maximum captured response bytes"), withDefault(2e6));
 const outputDir = String$2("output-dir").pipe(withDescription$2("Atomically write timestamped JSON and Markdown artifacts"), optional$1);
-const positive$1 = (name, value) => Number.isSafeInteger(value) && value > 0 ? succeed$2(value) : fail$3(new SeoCliError({ message: `--${name} must be a positive integer` }));
+const positive$2 = (name, value) => Number.isSafeInteger(value) && value > 0 ? succeed$2(value) : fail$3(new SeoCliError({ message: `--${name} must be a positive integer` }));
 const auditCommand = make$9("audit", {
 	urls,
 	json: jsonFlag,
@@ -37599,11 +37841,11 @@ const auditCommand = make$9("audit", {
 		description: "Audit a local app"
 	}
 ]), withHandler(fn("SeoCli.audit")(function* (options) {
-	const checkedRuns = yield* positive$1("runs", options.runs);
-	const checkedConcurrency = yield* positive$1("concurrency", options.concurrency);
-	const checkedRequestTimeout = yield* positive$1("request-timeout-ms", options.requestTimeoutMs);
-	const checkedScannerTimeout = yield* positive$1("scanner-timeout-ms", options.scannerTimeoutMs);
-	const checkedMaxBody = yield* positive$1("max-body-bytes", options.maxBodyBytes);
+	const checkedRuns = yield* positive$2("runs", options.runs);
+	const checkedConcurrency = yield* positive$2("concurrency", options.concurrency);
+	const checkedRequestTimeout = yield* positive$2("request-timeout-ms", options.requestTimeoutMs);
+	const checkedScannerTimeout = yield* positive$2("scanner-timeout-ms", options.scannerTimeoutMs);
+	const checkedMaxBody = yield* positive$2("max-body-bytes", options.maxBodyBytes);
 	const scanners = [
 		makeHttpScanner({
 			allowPrivate: options.allowPrivate,
@@ -37653,300 +37895,6 @@ const auditCommand = make$9("audit", {
 	if (structural.length > 0 || http.every((result) => result.status === "error")) return yield* new SeoCliError({ message: `${structural.length} structural finding(s); see the report above.` });
 })));
 //#endregion
-//#region src/cli/commands/diff.ts
-const before = String$1("before.json").pipe(withDescription("Earlier pagegraph audit JSON artifact"));
-const after = String$1("after.json").pipe(withDescription("Later pagegraph audit JSON artifact"));
-const readAuditReport = fn("SeoCli.readAuditReport")(function* (label, path) {
-	const contents = yield* (yield* FileSystem).readFileString(path).pipe(mapError((error) => new SeoCliError({ message: `Could not read ${label} report ${path}: ${error.message}` })));
-	return yield* decodeUnknownEffect(fromJsonString(AuditReport))(contents).pipe(mapError((error) => new SeoCliError({ message: `Invalid ${label} report ${path}: ${error.message}` })));
-});
-const diffCommand = make$9("diff", {
-	before,
-	after,
-	json: jsonFlag
-}).pipe(withDescription$1("Compare two versioned pagegraph audit JSON artifacts for semantic regressions"), withExamples([{
-	command: "pagegraph diff before.json after.json",
-	description: "Render a human-readable semantic comparison"
-}, {
-	command: "pagegraph diff before.json after.json --json",
-	description: "Emit one versioned JSON diff on stdout"
-}]), withHandler(fn("SeoCli.diff")(function* (options) {
-	const beforeReport = yield* readAuditReport("before", options.before);
-	const afterReport = yield* readAuditReport("after", options.after);
-	const comparison = compareAuditReports(beforeReport, afterReport);
-	if (AuditComparisonResult.$is("InvalidReport")(comparison)) return yield* new SeoCliError({ message: `Invalid audit report invariants:\n${comparison.issues.map((issue) => `- ${issue}`).join("\n")}` });
-	if (options.json) yield* printJson(comparison.diff);
-	else yield* printText(renderAuditDiff(comparison.diff));
-	if (comparison.diff.outcome === "regressed") {
-		const summary = comparison.diff.summary;
-		return yield* new SeoCliError({ message: `${summary.structuralRegressions} structural, ${summary.scannerRegressions} scanner, and ${summary.coverageRegressions} coverage regression(s); see the diff above.` });
-	}
-})));
-//#endregion
-//#region src/cli/serialize.ts
-const serializeCrumb = (crumb) => {
-	if (crumb === void 0) return void 0;
-	return typeof crumb === "function" ? "(dynamic)" : crumb;
-};
-/** JSON-safe projection of one node (route policy `crumb` functions → sentinel). */
-const serializeNode = (node) => ({
-	path: node.path,
-	kind: node.kind,
-	source: node.source,
-	policy: {
-		kind: node.policy.kind,
-		crumb: serializeCrumb(node.policy.crumb),
-		sitemap: node.policy.sitemap,
-		robots: node.policy.robots,
-		related: node.policy.related,
-		link: node.policy.link,
-		redirectTo: node.policy.redirectTo
-	},
-	instance: node.instance
-});
-/** Flatten the graph to a sorted, JSON-safe shape. Nodes are ordered by path. */
-const serializeGraph = (graph) => ({
-	nodes: [...graph.nodes.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(serializeNode),
-	edges: graph.edges
-});
-const graphCommand = make$9("graph", {
-	format: Literals("format", [
-		"tree",
-		"mermaid",
-		"json"
-	]).pipe(withDescription$2("Output format: tree (default), mermaid diagram, or json"), withDefault("tree")),
-	orphans: Boolean$1("orphans").pipe(withDescription$2("Show only orphan nodes (nothing links to them)"), withDefault(false))
-}).pipe(withDescription$1("Render the SEO graph as a tree, a Mermaid diagram, or JSON"), withExamples([
-	{
-		command: "pagegraph graph",
-		description: "The graph as an indented path tree"
-	},
-	{
-		command: "pagegraph graph --format mermaid",
-		description: "A Mermaid diagram of nodes and edges"
-	},
-	{
-		command: "pagegraph graph --orphans",
-		description: "Only nodes with no incoming edge"
-	},
-	{
-		command: "pagegraph graph --format json",
-		description: "The serialized graph on stdout"
-	}
-]), withHandler(fnUntraced(function* ({ format, orphans }) {
-	const config = yield* loadSeoConfig;
-	const graph = yield* scoped(acquireGraph(config));
-	if (format === "json") {
-		const serialized = serializeGraph(graph);
-		if (!orphans) return yield* printJson(serialized);
-		const orphanSet = orphanPaths(graph);
-		return yield* printJson({
-			nodes: serialized.nodes.filter((node) => orphanSet.has(node.path)),
-			edges: serialized.edges.filter((edge) => orphanSet.has(edge.from) && orphanSet.has(edge.to))
-		});
-	}
-	if (format === "mermaid") return yield* printText(renderMermaid(graph, orphans));
-	return yield* printText(orphans ? renderOrphans(graph) : renderTree(graph));
-})));
-//#endregion
-//#region src/core/inspect-html.ts
-const ENTITIES = {
-	"&amp;": "&",
-	"&lt;": "<",
-	"&gt;": ">",
-	"&quot;": "\"",
-	"&#39;": "'",
-	"&apos;": "'"
-};
-const decodeEntities = (value) => value.replace(/&(?:amp|lt|gt|quot|#39|apos);/g, (match) => ENTITIES[match] ?? match);
-/** Pull double/single-quoted attributes off a single tag string. */
-const parseAttrs = (tag) => {
-	const attrs = {};
-	const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
-	let match;
-	while ((match = re.exec(tag)) !== null) attrs[match[1].toLowerCase()] = decodeEntities(match[2] ?? match[3] ?? "");
-	return attrs;
-};
-/** Normalize a JSON-LD `@type` (string or array) to a single readable label. */
-const typeName = (value) => {
-	if (typeof value === "string") return value;
-	if (Array.isArray(value)) return value.filter((v) => typeof v === "string").join(", ") || "unknown";
-	return "unknown";
-};
-const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** Flatten a parsed JSON-LD payload (single object, array, or `@graph`) to items. */
-const collectItems = (parsed) => {
-	if (Array.isArray(parsed)) return parsed.filter(isObject);
-	if (isObject(parsed)) {
-		if (Array.isArray(parsed["@graph"])) return parsed["@graph"].filter(isObject);
-		return [parsed];
-	}
-	return [];
-};
-const countQuestions = (mainEntity) => {
-	if (!Array.isArray(mainEntity)) return 0;
-	return mainEntity.filter((entry) => isObject(entry) && typeName(entry["@type"]) === "Question").length;
-};
-const validateItemListElements = (value) => {
-	if (!Array.isArray(value) || value.length < 1) return ["ItemList needs at least one `itemListElement` entry."];
-	const errors = [];
-	value.forEach((entry, index) => {
-		if (!isObject(entry) || typeName(entry["@type"]) !== "ListItem") {
-			errors.push(`ItemList entry ${index + 1} is not a ListItem.`);
-			return;
-		}
-		if (entry["position"] !== index + 1) errors.push(`ItemList entry ${index + 1} has an invalid position.`);
-		if (!entry["name"] || !entry["url"]) errors.push(`ItemList entry ${index + 1} needs a name and URL.`);
-	});
-	return errors;
-};
-/** Minimal per-type validation — enough to catch an empty or malformed block. */
-const validateItem = (item) => {
-	const type = typeName(item["@type"]);
-	const errors = [];
-	if (type === "Article" || type === "NewsArticle" || type === "BlogPosting") {
-		if (!item["headline"]) errors.push("Article is missing `headline`.");
-		if (!item["datePublished"]) errors.push("Article is missing `datePublished`.");
-	} else if (type === "FAQPage") {
-		if (countQuestions(item["mainEntity"]) < 1) errors.push("FAQPage needs at least one Question in `mainEntity`.");
-	} else if (type === "BreadcrumbList") {
-		const items = item["itemListElement"];
-		if (!Array.isArray(items) || items.length < 2) errors.push("BreadcrumbList needs at least two `itemListElement` entries.");
-	} else if (type === "ItemList") {
-		errors.push(...validateItemListElements(item["itemListElement"]));
-		const items = item["itemListElement"];
-		if (Array.isArray(items) && item["numberOfItems"] !== items.length) errors.push("ItemList `numberOfItems` does not match its entries.");
-	}
-	return {
-		type,
-		valid: errors.length === 0,
-		errors
-	};
-};
-const validateLdJson = (raw) => {
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (cause) {
-		return [{
-			type: "unparseable",
-			valid: false,
-			errors: [`JSON parse error: ${cause instanceof Error ? cause.message : String(cause)}`]
-		}];
-	}
-	const items = collectItems(parsed);
-	if (items.length === 0) return [{
-		type: "unknown",
-		valid: false,
-		errors: ["No JSON-LD object found in block."]
-	}];
-	return items.map(validateItem);
-};
-/** Parse a rendered HTML document's `<head>` into a report. Pure. */
-const inspectHtml = (url, status, html) => {
-	const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
-	const head = headMatch ? headMatch[1] : html;
-	const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
-	const title = titleMatch ? decodeEntities(titleMatch[1].trim()) : void 0;
-	const og = {};
-	const twitter = {};
-	let description;
-	let robots;
-	for (const tag of head.match(/<meta\b[^>]*>/gi) ?? []) {
-		const attrs = parseAttrs(tag);
-		const content = attrs["content"];
-		if (content === void 0) continue;
-		const property = attrs["property"];
-		const name = attrs["name"];
-		if (property?.startsWith("og:")) og[property] = content;
-		else if (name?.startsWith("twitter:")) twitter[name] = content;
-		else if (name === "description") description = content;
-		else if (name === "robots") robots = content;
-	}
-	let canonical;
-	for (const tag of head.match(/<link\b[^>]*>/gi) ?? []) {
-		const attrs = parseAttrs(tag);
-		if (attrs["rel"] === "canonical") canonical = attrs["href"];
-	}
-	const jsonLd = [];
-	const scriptRe = /<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
-	let scriptMatch;
-	while ((scriptMatch = scriptRe.exec(head)) !== null) jsonLd.push(...validateLdJson(scriptMatch[1].trim()));
-	const issues = [];
-	if (status >= 400) issues.push(`Fetch returned HTTP ${status}.`);
-	if (!title) issues.push("Missing <title>.");
-	if (!description) issues.push("Missing meta description.");
-	if (!canonical) issues.push("Missing canonical link.");
-	for (const block of jsonLd) if (!block.valid) issues.push(...block.errors.map((error) => `JSON-LD (${block.type}): ${error}`));
-	return {
-		url,
-		status,
-		title,
-		description,
-		canonical,
-		robots,
-		og,
-		twitter,
-		jsonLd,
-		issues
-	};
-};
-/** A non-empty `issues` list fails `pagegraph inspect --live` (exit 1). */
-const hasBlockingIssues = (report) => report.issues.length > 0;
-//#endregion
-//#region src/cli/live-inspect.ts
-/**
-* `pagegraph inspect <url> --live`: fetch a URL and hand its body to the pure head
-* validator in `../inspect-html`. The fetch is all that lives here — the
-* validation is a library capability, not a CLI one, so it stays out of the
-* Effect-bearing half of the package.
-*/
-/** Fetch a URL and inspect its `<head>`. Network failures surface as SeoCliError. */
-const fetchAndInspect = (url) => tryPromise({
-	try: async () => {
-		const response = await fetch(url, { headers: { "user-agent": "pagegraph-cli" } });
-		const html = await response.text();
-		return inspectHtml(url, response.status, html);
-	},
-	catch: (cause) => new SeoCliError({ message: `Could not fetch ${url}: ${cause instanceof Error ? cause.message : String(cause)}` })
-});
-const inspectCommand = make$9("inspect", {
-	target: String$1("target").pipe(withDescription("A route path (e.g. /pricing), or a full URL with --live")),
-	live: Boolean$1("live").pipe(withDescription$2("Fetch the URL and inspect its rendered <head> and JSON-LD"), withDefault(false)),
-	json: jsonFlag
-}).pipe(withDescription$1("Inspect one page: its graph declaration, or its live <head> with --live"), withExamples([
-	{
-		command: "pagegraph inspect /pricing",
-		description: "The graph node, policy, and edges for a path"
-	},
-	{
-		command: "pagegraph inspect https://example.com/pricing --live",
-		description: "Fetch the page and validate its head tags + JSON-LD"
-	},
-	{
-		command: "pagegraph inspect /blog/some-post --json",
-		description: "The node report as JSON"
-	}
-]), withHandler(fnUntraced(function* ({ target, live, json }) {
-	if (live) {
-		const report = yield* fetchAndInspect(target);
-		if (json) yield* printJson(report);
-		else yield* printText(renderLiveReport(report));
-		if (hasBlockingIssues(report)) return yield* new SeoCliError({ message: `${report.issues.length} issue(s) found at ${target}.` });
-		return;
-	}
-	const config = yield* loadSeoConfig;
-	const report = inspectNode(yield* scoped(acquireGraph(config)), target);
-	if (report === void 0) return yield* new SeoCliError({ message: `No node at "${target}". Run \`pagegraph graph\` to list paths, or pass a URL with --live.` });
-	if (json) return yield* printJson({
-		node: serializeNode(report.node),
-		inSitemap: report.inSitemap,
-		incoming: report.incoming,
-		outgoing: report.outgoing
-	});
-	return yield* printText(renderNodeReport(report));
-})));
-//#endregion
 //#region node_modules/effect/dist/unstable/http/HttpBody.js
 const TypeId$9 = "~effect/http/HttpBody";
 const HttpBodyErrorTypeId = "~effect/http/HttpBody/HttpBodyError";
@@ -40734,7 +40682,7 @@ const invalidOutput = (description) => make$5({
 	reason: new InvalidOutputError({ description })
 });
 const isFiniteNumber = (value) => isNumber(value) && Number.isFinite(value);
-const isUnitInterval = (value) => isFiniteNumber(value) && value >= 0 && value <= 1;
+const isUnitInterval$1 = (value) => isFiniteNumber(value) && value >= 0 && value <= 1;
 const validateDistribution = (key, labels, answer) => {
 	const raw = answer.probabilities;
 	if (!isObject$1(raw)) return invalidOutput(`Provider returned no probabilities for decision "${key}"`);
@@ -40742,7 +40690,7 @@ const validateDistribution = (key, labels, answer) => {
 	let total = 0;
 	for (const label of labels) {
 		const value = raw[label];
-		if (!isUnitInterval(value)) return invalidOutput(`Provider returned no probability for label "${label}" of decision "${key}"`);
+		if (!isUnitInterval$1(value)) return invalidOutput(`Provider returned no probability for label "${label}" of decision "${key}"`);
 		probabilities[label] = value;
 		total += value;
 	}
@@ -40751,7 +40699,7 @@ const validateDistribution = (key, labels, answer) => {
 };
 const validateConfidence = (key, answer) => {
 	if (answer.confidence === void 0) return;
-	return isUnitInterval(answer.confidence) ? answer.confidence : invalidOutput(`Provider returned confidence outside [0, 1] for decision "${key}"`);
+	return isUnitInterval$1(answer.confidence) ? answer.confidence : invalidOutput(`Provider returned confidence outside [0, 1] for decision "${key}"`);
 };
 const validateAnswer = (key, decision, answer) => {
 	if (!isObject$1(answer)) return invalidOutput(`Provider returned no answer for decision "${key}"`);
@@ -40787,7 +40735,7 @@ const validateAnswer = (key, decision, answer) => {
 			};
 		}
 		case "Probability":
-			if (!isUnitInterval(answer.probability)) return invalidOutput(`Provider returned a probability outside [0, 1] for decision "${key}"`);
+			if (!isUnitInterval$1(answer.probability)) return invalidOutput(`Provider returned a probability outside [0, 1] for decision "${key}"`);
 			return { probability: answer.probability };
 	}
 };
@@ -41052,6 +41000,1501 @@ const make$1 = /*#__PURE__*/ fnUntraced(function* (options) {
 */
 const layer = (options) => effect(DecisionModel, make$1(options));
 //#endregion
+//#region node_modules/effect/dist/unstable/ai/Decision.js
+/**
+* Brand for decision definitions.
+*
+* @category type IDs
+* @since 4.0.0
+*/
+const TypeId = "~effect/ai/Decision";
+/**
+* Creates a classification decision from labelled criteria.
+* Throws if fewer than two labels are supplied.
+*
+* **Example** (Choosing a department)
+*
+* ```ts
+* import { Decision } from "effect/unstable/ai"
+*
+* const department = Decision.classify({
+*   instructions: "Which team should handle this",
+*   criteria: {
+*     billing: "payments",
+*     technical: "bugs",
+*     sales: "pricing"
+*   }
+* })
+* ```
+*
+* @see {@link rate} for an ordered scale
+* @see {@link probability} for a single yes or no likelihood
+*
+* @category constructors
+* @since 4.0.0
+*/
+const classify = (options) => {
+	if (Object.keys(options.criteria).length < 2) throw new Error("Decision.classify: criteria must contain at least two labels");
+	return {
+		_tag: "Classify",
+		instructions: options.instructions,
+		criteria: options.criteria
+	};
+};
+/**
+* Creates a rating decision from an ordered list of criteria.
+* Throws if fewer than two levels or duplicate levels are supplied.
+*
+* **Example** (Rating frustration)
+*
+* ```ts
+* import { Decision } from "effect/unstable/ai"
+*
+* const frustration = Decision.rate({
+*   instructions: "How frustrated",
+*   criteria: ["calm", "frustrated", "angry"]
+* })
+* ```
+*
+* @see {@link classify} for unordered labels
+*
+* @category constructors
+* @since 4.0.0
+*/
+const rate = (options) => {
+	if (options.criteria.length < 2) throw new Error("Decision.rate: criteria must contain at least two levels");
+	if (new Set(options.criteria).size !== options.criteria.length) throw new Error("Decision.rate: criteria must contain distinct levels");
+	return {
+		_tag: "Rate",
+		instructions: options.instructions,
+		criteria: options.criteria
+	};
+};
+/**
+* Creates a probability decision from descriptions of both outcomes.
+*
+* **Example** (Estimating urgency)
+*
+* ```ts
+* import { Decision } from "effect/unstable/ai"
+*
+* const urgent = Decision.probability({
+*   instructions: "The message is time-sensitive",
+*   criteria: {
+*     false: "No time pressure",
+*     true: "Needs action now"
+*   }
+* })
+* ```
+*
+* @see {@link classify} for more than two outcomes
+*
+* @category constructors
+* @since 4.0.0
+*/
+const probability = (options) => ({
+	_tag: "Probability",
+	instructions: options.instructions,
+	criteria: options.criteria
+});
+/**
+* Creates a decision definition from an input schema and named decisions.
+* `DecisionModel.decide` encodes the input with `Schema.toCodecJson` before
+* calling the provider. Answer keys and types are inferred from the decisions.
+* Throws if `decisions` is empty.
+*
+* **Example** (Defining ticket triage)
+*
+* ```ts
+* import { Schema } from "effect"
+* import { Decision } from "effect/unstable/ai"
+*
+* const Ticket = Schema.Struct({
+*   subject: Schema.String,
+*   body: Schema.String
+* })
+*
+* const TicketTriage = Decision.make({
+*   input: Ticket,
+*   decisions: {
+*     department: Decision.classify({
+*       instructions: "Which team should handle this",
+*       criteria: { billing: "payments", technical: "bugs" }
+*     }),
+*     urgent: Decision.probability({
+*       instructions: "The message is time-sensitive",
+*       criteria: { false: "No time pressure", true: "Needs action now" }
+*     })
+*   }
+* })
+* ```
+*
+* @see {@link Definition} for the returned shape
+*
+* @category constructors
+* @since 4.0.0
+*/
+const make = (options) => {
+	if (Object.keys(options.decisions).length === 0) throw new Error("Decision.make: decisions must not be empty");
+	return {
+		[TypeId]: TypeId,
+		input: options.input,
+		decisions: options.decisions
+	};
+};
+//#endregion
+//#region src/decide/cache.ts
+/**
+* Answer cache keyed by input hash. One JSON file per key under `--cache <dir>`.
+*
+* Only model answers are cached — verdicts are recomputed from answers and the
+* current threshold, so raising or lowering `--threshold` never serves a stale
+* verdict. Cache files are plain data: a missing or unreadable file is a miss,
+* never an error that fails the run.
+*/
+/** Read cached answers for `key`, or `undefined` on any miss (absent or unreadable). */
+const cacheGet = (cacheDir, key) => {
+	const file = join(cacheDir, `${key}.json`);
+	if (!existsSync(file)) return void 0;
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+};
+/** Persist answers for `key`; creates `cacheDir` on first write. */
+const cachePut = (cacheDir, key, answers) => {
+	mkdirSync(cacheDir, { recursive: true });
+	writeFileSync(join(cacheDir, `${key}.json`), `${JSON.stringify(answers, null, 2)}\n`, "utf8");
+};
+//#endregion
+//#region src/decide/run.ts
+/**
+* The decision runner. A family supplies its input schema, a definition built
+* from the input (families with dynamic labels build one per input), a way to
+* reference the input in a report, and a pure `evaluate` that maps the model's
+* answers to a verdict. The runner hashes, caches, dispatches with bounded
+* concurrency, and buckets confident answers apart from `review`.
+*
+* This module reaches Effect and the provider, so it is CLI-internal: the
+* library entries stay Effect-free and only the bundled `pagegraph` bin ships it.
+*/
+const isUnitInterval = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A probability distribution over exactly `labels`: unit-range, summing to 1. */
+const isDistribution = (labels, value) => {
+	if (!isPlainObject(value) || Object.keys(value).length !== labels.length) return false;
+	let total = 0;
+	for (const label of labels) {
+		const probability = value[label];
+		if (!isUnitInterval(probability)) return false;
+		total += probability;
+	}
+	return Math.abs(total - 1) <= 1e-6;
+};
+/**
+* Whether cached answers have the shape `DecisionModel` would have validated —
+* the same labels, ranges, and distributions. A cache file is only trusted when
+* it round-trips through this check, so a partially malformed entry cannot
+* produce a confident verdict.
+*/
+const validCachedAnswers = (decisions, answers) => {
+	if (!isPlainObject(answers)) return false;
+	for (const key of Object.keys(decisions)) {
+		const answer = answers[key];
+		if (!isPlainObject(answer)) return false;
+		const decision = decisions[key];
+		switch (decision._tag) {
+			case "Probability":
+				if (!isUnitInterval(answer.probability)) return false;
+				break;
+			case "Classify":
+				if (typeof answer.label !== "string" || !Object.hasOwn(decision.criteria, answer.label) || !isDistribution(Object.keys(decision.criteria), answer.probabilities)) return false;
+				break;
+			case "Rate": if (typeof answer.rating !== "number" || !Number.isFinite(answer.rating) || answer.rating < 0 || answer.rating > decision.criteria.length - 1 || typeof answer.label !== "string" || !decision.criteria.includes(answer.label) || !isDistribution(decision.criteria, answer.probabilities)) return false;
+		}
+	}
+	return true;
+};
+/** A probability is confident when it is at or beyond `threshold` on either side. */
+const isConfident$1 = (probability, threshold) => probability >= threshold || probability <= 1 - threshold;
+/** True when a probability sits inside the review band `(1 - threshold, threshold)`. */
+const inReviewBand = (probability, threshold) => !isConfident$1(probability, threshold);
+/** True when any probability sits inside the review band. */
+const anyInReviewBand = (probabilities, threshold) => probabilities.some((probability) => inReviewBand(probability, threshold));
+/** sha256 of the canonical input JSON — deterministic for a schema-decoded input. */
+const inputHash = (input) => createHash("sha256").update(JSON.stringify(input)).digest("hex");
+/**
+* Cache identity. Answers depend on the family and the model as well as the
+* input, so keying by the input hash alone would let a different family or model
+* reuse incompatible answers. The answer-schema version guards shape changes.
+*/
+const cacheKey = (family, model, answerHash) => createHash("sha256").update(`${family}\u0000${model}\u0000v1\u0000${answerHash}`).digest("hex");
+/** Group records into resolved/review buckets and count each verdict. */
+const buildDecisionReport = (options) => {
+	const verdicts = {};
+	const resolved = [];
+	const review = [];
+	for (const record of options.records) {
+		verdicts[record.verdict] = (verdicts[record.verdict] ?? 0) + 1;
+		if (record.review) review.push(record);
+		else resolved.push(record);
+	}
+	return {
+		kind: "decide",
+		schemaVersion: 1,
+		family: options.family,
+		model: options.model,
+		threshold: options.threshold,
+		counts: {
+			inputs: options.records.length,
+			resolved: resolved.length,
+			review: review.length
+		},
+		verdicts,
+		resolved,
+		review
+	};
+};
+/**
+* Answer every input through the ambient `DecisionModel` and bucket the results.
+* One provider call answers every decision for an input; calls run with bounded
+* concurrency, and a warm cache skips the provider entirely.
+*/
+const runDecisions = (options) => gen(function* () {
+	const records = yield* forEach$1(options.inputs, (input, index) => gen(function* () {
+		const hash = inputHash(input);
+		const key = cacheKey(options.family.name, options.model, hash);
+		const cached = options.cacheDir === void 0 ? void 0 : cacheGet(options.cacheDir, key);
+		let answers;
+		let usage;
+		let verdict;
+		if (cached !== void 0) {
+			const decisions = options.family.definitionFor(input).decisions;
+			if (validCachedAnswers(decisions, cached)) {
+				answers = cached;
+				verdict = options.family.evaluate(input, cached, options.threshold);
+			}
+		}
+		if (verdict === void 0) {
+			const response = yield* decide(options.family.definitionFor(input), { input });
+			answers = response.answers;
+			usage = {
+				inputTokens: response.usage.inputTokens,
+				outputTokens: response.usage.outputTokens
+			};
+			if (options.cacheDir !== void 0) cachePut(options.cacheDir, key, answers);
+			verdict = options.family.evaluate(input, answers, options.threshold);
+		}
+		return {
+			decisionId: `${options.family.name}:${index}`,
+			schemaVersion: 1,
+			family: options.family.name,
+			model: options.model,
+			threshold: options.threshold,
+			inputHash: hash,
+			inputRef: options.family.inputRef(input),
+			verdict,
+			review: verdict === "review",
+			answers,
+			...usage === void 0 ? {} : { usage }
+		};
+	}), { concurrency: options.concurrency ?? 4 });
+	return buildDecisionReport({
+		family: options.family.name,
+		model: options.model,
+		threshold: options.threshold,
+		records
+	});
+});
+/** Decode raw batch inputs against a family's schema. Throws on the first invalid input. */
+/** `decodeUnknownSync` with an unconstrained schema type; the family types the result. */
+const decodeUnknown = decodeUnknownSync;
+const decodeFamilyInputs = (family, raw) => raw.map((value) => decodeUnknown(family.input)(value));
+//#endregion
+//#region src/decide/families/authority.ts
+/**
+* The authority family: is this a real link opportunity, a spam trap, or not
+* worth outreach?
+*
+* Three probabilities judge the domain and one classification places its fit.
+* A confident spam verdict is `spam`, a confident legitimate-and-worth-while fit
+* is `accept`, and everything uncertain is `review` — link outreach is never
+* auto-applied.
+*/
+const AUTHORITY_FIT_CRITERIA = {
+	directory: "A directory or listing page that accepts submissions.",
+	partner: "A partner or integration page that links relevant products.",
+	editorial: "Editorial coverage: an article or guide that could cite this page.",
+	community: "A community space: forum, Q&A, or discussion group.",
+	none: "No genuine fit; outreach here would be noise."
+};
+/** One link target plus the evidence the model reads. */
+const AuthorityInput = Struct({
+	domain: String$6,
+	url: String$6,
+	anchor: String$6,
+	/** The surrounding copy on our page that would carry the link. */
+	context: String$6,
+	targetPath: String$6,
+	/** Referring domains, when known. */
+	rd: optional$3(Number$2),
+	/** Extra observed signals, e.g. `["no-outbound", "paid-links"]`. */
+	signals: optional$3(ArraySchema(String$6))
+});
+/** One provider call answers the three probabilities and the fit classification. */
+const AuthorityDecision = make({
+	input: AuthorityInput,
+	decisions: {
+		legitimate: probability({
+			instructions: "The target is a legitimate site a reader would trust: real editorial or community content, not a link farm, PBN, or paid-link network.",
+			criteria: {
+				false: "The target looks like spam, a link farm, or a paid-link network.",
+				true: "The target is a legitimate site."
+			}
+		}),
+		spam: probability({
+			instructions: "The target shows spam signals: thin auto-generated content, exact-match anchor farms, or a link-selling footprint.",
+			criteria: {
+				false: "No meaningful spam signals.",
+				true: "Clear spam or link-selling signals."
+			}
+		}),
+		outreachWorth: probability({
+			instructions: "Outreach to this target is worth the effort: a human could plausibly place a reader-useful link.",
+			criteria: {
+				false: "Outreach is not worth the effort.",
+				true: "Outreach could place a useful link."
+			}
+		}),
+		fit: classify({
+			instructions: "Classify the relationship this target could support.",
+			criteria: AUTHORITY_FIT_CRITERIA
+		})
+	}
+});
+/**
+* `spam` when spam is confident; `accept` only when legitimate, outreach-worthy,
+* and a non-`none` fit are all confident; otherwise `review`.
+*/
+const classifyAuthorityVerdict = (answers, threshold) => {
+	if (anyInReviewBand([
+		answers.legitimate.probability,
+		answers.spam.probability,
+		answers.outreachWorth.probability
+	], threshold)) return "review";
+	if (answers.spam.probability >= threshold) return "spam";
+	const fitProbability = answers.fit.probabilities[answers.fit.label] ?? 0;
+	if (answers.fit.label === "none" || fitProbability < threshold || answers.legitimate.probability < threshold || answers.outreachWorth.probability < threshold) return "review";
+	return "accept";
+};
+const authorityFamily = {
+	name: "authority",
+	input: AuthorityInput,
+	definitionFor: () => AuthorityDecision,
+	inputRef: (input) => input.domain,
+	evaluate: (_input, answers, threshold) => classifyAuthorityVerdict(answers, threshold)
+};
+//#endregion
+//#region src/decide/families/content.ts
+/**
+* The content family: does this page carry enough original substance?
+*
+* Seven probabilities score the page's editorial quality and one rating places
+* its overall value on `thin | adequate | strong`. A confident page with a
+* `thin` value or any failed probability is `flag`; an uncertain answer is
+* `review`. Nothing is rewritten here — the verdict is the plan.
+*/
+/** Ordered value scale from least to most substance. */
+const CONTENT_VALUES = [
+	"thin",
+	"adequate",
+	"strong"
+];
+/** One page plus the evidence the rubric reads. */
+const ContentInput = Struct({
+	url: String$6,
+	/** The query the page targets; intent rubrics cannot be judged without it. */
+	query: String$6,
+	title: String$6,
+	h1: String$6,
+	first150Words: String$6,
+	headings: ArraySchema(String$6),
+	wordCount: Natural,
+	/** schema.org types present on the page, e.g. `["Article", "FAQPage"]`. */
+	structuredData: ArraySchema(String$6),
+	/** The topic the page must stay inside; drifting outside it is a failure. */
+	categoryLock: String$6,
+	/** Sibling pages' intents, needed to judge `distinctIntent`. */
+	siblingIntents: optional$3(ArraySchema(String$6)),
+	competitorExcerpts: optional$3(ArraySchema(String$6))
+});
+const boolean = (instructions, falseText, trueText) => probability({
+	instructions,
+	criteria: {
+		false: falseText,
+		true: trueText
+	}
+});
+/** One provider call answers the seven rubric probabilities and the value rating. */
+const ContentDecision = make({
+	input: ContentInput,
+	decisions: {
+		answersFirst: boolean("The first 150 words answer the reader's question directly, before background or preamble.", "The opening delays the answer.", "The opening answers the question up front."),
+		originalValue: boolean("The page adds original value — first-hand experience, data, or a distinct point of view — beyond restating common knowledge.", "The page restates what every other result already says.", "The page adds information a reader cannot get elsewhere."),
+		competitiveSubstance: boolean("The page has enough depth and specificity to compete with the current results for this topic.", "The page is shallower or less specific than the competition.", "The page matches or exceeds the competition's substance."),
+		descriptiveTitle: boolean("The title is descriptive and specific to the page's content rather than vague or clickbait.", "The title is vague or misleading.", "The title describes the page's actual content."),
+		structuredDataMatches: boolean("The page's structured data matches its content type and the supplied query's intent.", "Structured data is missing, wrong, or mismatched.", "Structured data correctly describes the page."),
+		categoryConsistency: boolean("The page stays inside its locked category; its headings and body do not drift into an adjacent topic.", "The page drifts outside the locked category.", "The page stays inside the locked category."),
+		distinctIntent: boolean("The page serves a distinct intent rather than duplicating a sibling page's intent. Judge only the sibling intents supplied; if none are supplied, treat this as unresolved.", "The page duplicates a sibling page's intent.", "The page serves an intent no supplied sibling covers."),
+		value: rate({
+			instructions: "Overall reader value of this page: thin restates what exists, adequate is competitive, strong is the best available answer.",
+			criteria: CONTENT_VALUES
+		})
+	}
+});
+/** The seven rubric probabilities that decide pass/flag once confidence is settled. */
+const RUBRIC_KEYS = [
+	"answersFirst",
+	"originalValue",
+	"competitiveSubstance",
+	"descriptiveTitle",
+	"structuredDataMatches",
+	"categoryConsistency",
+	"distinctIntent"
+];
+/** Evidence present by default; a caller with no evidence can still test the band logic. */
+const ALL_EVIDENCE = {
+	distinctIntent: true,
+	competitiveSubstance: true
+};
+/**
+* `flag` when the value rating is `thin` or any rubric probability is
+* confidently false; `review` when any probability (rubric or value
+* distribution) is inside the band, or an evidence-dependent rubric is
+* confidently positive without its evidence; `pass` otherwise. A confident
+* negative on an unevidenced rubric stays `flag` — it is the conservative side.
+*/
+const classifyContentVerdict = (answers, threshold, evidence = ALL_EVIDENCE) => {
+	const rubric = RUBRIC_KEYS.map((key) => answers[key].probability);
+	const distribution = Object.values(answers.value.probabilities);
+	if (anyInReviewBand([...rubric, ...distribution], threshold)) return "review";
+	if (!evidence.distinctIntent && answers.distinctIntent.probability >= threshold) return "review";
+	if (!evidence.competitiveSubstance && answers.competitiveSubstance.probability >= threshold) return "review";
+	if (answers.value.label === "thin") return "flag";
+	if (rubric.some((probability) => probability <= 1 - threshold)) return "flag";
+	return "pass";
+};
+const contentFamily = {
+	name: "content",
+	input: ContentInput,
+	definitionFor: () => ContentDecision,
+	inputRef: (input) => input.url,
+	evaluate: (input, answers, threshold) => classifyContentVerdict(answers, threshold, {
+		distinctIntent: input.siblingIntents !== void 0 && input.siblingIntents.length > 0,
+		competitiveSubstance: input.competitorExcerpts !== void 0 && input.competitorExcerpts.length > 0
+	})
+};
+/** One query plus the candidate pages already on the site. */
+const FitInput = Struct({
+	query: String$6,
+	candidates: ArraySchema(Struct({
+		id: String$6,
+		title: String$6,
+		excerpt: String$6
+	}))
+});
+const candidateCriteria$1 = (candidates) => Object.fromEntries(candidates.map((candidate) => [candidate.id, `${candidate.title} — ${candidate.excerpt}`.slice(0, 255)]));
+/** One provider call answers `bestPage`, `competition`, and `needsNewPage`. */
+const makeFitDecision = (input) => make({
+	input: FitInput,
+	decisions: {
+		bestPage: classify({
+			instructions: "Choose the candidate page that best targets this query, or the closest starting point to update. Use the page's title and excerpt.",
+			criteria: candidateCriteria$1(input.candidates)
+		}),
+		competition: probability({
+			instructions: "Two or more of the supplied pages already target this query, so they risk cannibalizing each other.",
+			criteria: {
+				false: "At most one page targets the query.",
+				true: "Multiple pages target the query."
+			}
+		}),
+		needsNewPage: probability({
+			instructions: "None of the supplied pages can serve this query well; a new page is the right answer.",
+			criteria: {
+				false: "An existing page can serve this query.",
+				true: "No existing page can serve this query; a new page is needed."
+			}
+		})
+	}
+});
+/** Reject inputs whose candidate ids cannot become provider labels. */
+const validateFitInput = (input) => {
+	if (input.candidates.length < 2) return "decide fit needs at least two candidates: bestPage compares them.";
+	const long = input.candidates.find((candidate) => candidate.id.length > 255);
+	if (long !== void 0) return `decide fit candidate id exceeds 255 characters: ${long.id.slice(0, 32)}…`;
+	if (new Set(input.candidates.map((candidate) => candidate.id)).size !== input.candidates.length) return "decide fit candidate ids must be unique: they become provider labels.";
+};
+/**
+* `gap` wins over `cannibalized` when both are confident: a new page is the more
+* decisive answer. `map` needs a confident `bestPage`; otherwise it is `review`.
+*/
+const classifyFitVerdict = (answers, threshold) => {
+	if (anyInReviewBand([answers.competition.probability, answers.needsNewPage.probability], threshold)) return "review";
+	if (answers.needsNewPage.probability >= threshold) return "gap";
+	if (answers.competition.probability >= threshold) return "cannibalized";
+	return (answers.bestPage.probabilities[answers.bestPage.label] ?? 0) >= threshold ? "map" : "review";
+};
+const fitFamily = {
+	name: "fit",
+	input: FitInput,
+	definitionFor: makeFitDecision,
+	inputRef: (input) => `query:${input.query}`,
+	evaluate: (_input, answers, threshold) => classifyFitVerdict(answers, threshold),
+	validate: validateFitInput
+};
+/** One page plus the metadata candidates to rank. */
+const MetaInput = Struct({
+	url: String$6,
+	intent: String$6,
+	categoryLock: String$6,
+	candidates: ArraySchema(Struct({
+		id: String$6,
+		title: String$6,
+		description: String$6
+	}))
+});
+const candidateCriteria = (candidates) => Object.fromEntries(candidates.map((candidate) => [candidate.id, `${candidate.title} — ${candidate.description}`.slice(0, 255)]));
+/** One provider call answers `best` and the four concern probabilities. */
+const makeMetaDecision = (input) => make({
+	input: MetaInput,
+	decisions: {
+		best: classify({
+			instructions: "Choose the candidate title/description that best serves the page's intent and stays inside its category. Judge the supplied candidates only.",
+			criteria: candidateCriteria(input.candidates)
+		}),
+		intentFit: probability({
+			instructions: "The chosen candidate's promise matches the page's intent.",
+			criteria: {
+				false: "The candidate promises something the page does not deliver.",
+				true: "The candidate matches the page's intent."
+			}
+		}),
+		lengthOk: probability({
+			instructions: "The chosen candidate fits search-result limits: a title near 60 characters, a description near 160.",
+			criteria: {
+				false: "The candidate is too short or truncated.",
+				true: "The candidate fits the result limits."
+			}
+		}),
+		categoryDrift: probability({
+			instructions: "The chosen candidate drifts outside the page's locked category.",
+			criteria: {
+				false: "The candidate stays inside the category.",
+				true: "The candidate drifts outside the category."
+			}
+		}),
+		clickbait: probability({
+			instructions: "The chosen candidate uses clickbait or overpromises relative to the page's content.",
+			criteria: {
+				false: "The candidate is accurate and measured.",
+				true: "The candidate overpromises or uses clickbait."
+			}
+		})
+	}
+});
+/** Reject inputs whose candidate ids cannot become provider labels. */
+const validateMetaInput = (input) => {
+	if (input.candidates.length < 2) return "decide meta needs at least two candidates: best ranks them.";
+	const long = input.candidates.find((candidate) => candidate.id.length > 255);
+	if (long !== void 0) return `decide meta candidate id exceeds 255 characters: ${long.id.slice(0, 32)}…`;
+	if (new Set(input.candidates.map((candidate) => candidate.id)).size !== input.candidates.length) return "decide meta candidate ids must be unique: they become provider labels.";
+};
+/**
+* A clean candidate is `choose:<id>`. Any review-band probability, a low-probability
+* pick, confident drift, clickbait, or a mismatch on intent/length is `review`.
+*/
+const classifyMetaVerdict = (answers, threshold) => {
+	if (anyInReviewBand([
+		answers.intentFit.probability,
+		answers.lengthOk.probability,
+		answers.categoryDrift.probability,
+		answers.clickbait.probability
+	], threshold)) return "review";
+	if ((answers.best.probabilities[answers.best.label] ?? 0) < threshold) return "review";
+	if (answers.intentFit.probability < threshold || answers.lengthOk.probability < threshold || answers.categoryDrift.probability >= threshold || answers.clickbait.probability >= threshold) return "review";
+	return `choose:${answers.best.label}`;
+};
+const metaFamily = {
+	name: "meta",
+	input: MetaInput,
+	definitionFor: makeMetaDecision,
+	inputRef: (input) => input.url,
+	evaluate: (_input, answers, threshold) => classifyMetaVerdict(answers, threshold),
+	validate: validateMetaInput
+};
+//#endregion
+//#region src/decide/families/serp.ts
+/**
+* The serp family: is our page the shape this results page rewards?
+*
+* The model classifies the dominant SERP format and answers three probabilities
+* about our page. A confident match is `aligned`, a confident miss is `mismatch`,
+* and any answer inside the confidence band is `review` — the format question is
+* the one a human is most often needed to settle.
+*/
+const SERP_FORMAT_CRITERIA = {
+	definition: "A definition or explainer page: what X is and how it works.",
+	tool: "An interactive tool, calculator, or generator.",
+	comparison: "A comparison of options: X vs Y, or the best X.",
+	listicle: "A ranked or numbered list of items.",
+	docs: "Product, API, or reference documentation.",
+	vendorLanding: "A vendor's marketing or landing page for its own product.",
+	forum: "A community discussion: forum, Reddit, or Stack Overflow.",
+	other: "None of the above."
+};
+/** One ranked result in the saved SERP snapshot. */
+const SerpItem = Struct({
+	type: String$6,
+	rank: Number$2,
+	domain: String$6,
+	title: optional$3(String$6),
+	snippet: optional$3(String$6)
+});
+/** Our candidate page, plus the SERP snapshot for the query. */
+const SerpInput = Struct({
+	query: String$6,
+	ourPage: Struct({
+		url: String$6,
+		title: String$6,
+		kind: String$6,
+		firstWords: String$6
+	}),
+	serpItems: ArraySchema(SerpItem)
+});
+/** One provider call answers the SERP format and the three fit probabilities. */
+const SerpDecision = make({
+	input: SerpInput,
+	decisions: {
+		serpFormat: classify({
+			instructions: "Classify the dominant format of this results page from the ranking results. Weigh the top results most heavily.",
+			criteria: SERP_FORMAT_CRITERIA
+		}),
+		ourFormatFit: probability({
+			instructions: "Our page's format matches how this results page is won: the same shape a top result uses, not merely a related topic.",
+			criteria: {
+				false: "Our format is the wrong shape for this SERP.",
+				true: "Our format is the shape this SERP rewards."
+			}
+		}),
+		intentMatch: probability({
+			instructions: "Our page satisfies the query's dominant intent: the reader's task after landing, not the literal keywords.",
+			criteria: {
+				false: "The query wants something our page does not provide.",
+				true: "Our page provides what the query asks for."
+			}
+		}),
+		titlePatternMatch: probability({
+			instructions: "Our title follows the pattern the ranking titles use, including the qualifiers and framing a searcher expects.",
+			criteria: {
+				false: "Our title does not follow the ranking pattern.",
+				true: "Our title follows the ranking pattern."
+			}
+		})
+	}
+});
+/**
+* `aligned` needs both intent and format confident-positive; anything else that
+* is confident is `mismatch`. `titlePatternMatch` only widens the review band.
+*/
+const classifySerpVerdict = (answers, threshold) => {
+	const probabilities = [
+		answers.ourFormatFit.probability,
+		answers.intentMatch.probability,
+		answers.titlePatternMatch.probability
+	];
+	if (anyInReviewBand(probabilities, threshold)) return "review";
+	return answers.intentMatch.probability >= threshold && answers.ourFormatFit.probability >= threshold ? "aligned" : "mismatch";
+};
+const serpFamily = {
+	name: "serp",
+	input: SerpInput,
+	definitionFor: () => SerpDecision,
+	inputRef: (input) => `${input.ourPage.url} · query:${input.query}`,
+	evaluate: (_input, answers, threshold) => classifySerpVerdict(answers, threshold)
+};
+//#endregion
+//#region src/decide/inputs.ts
+/**
+* Batch input reading for `pagegraph decide <family>`. A batch is either a JSON
+* array, a `{ "inputs": [...] }` envelope, or newline-delimited JSON (one input
+* per non-empty line) — from a file argument or stdin. A TTY with no file is an
+* error: the command must never appear to hang waiting for input that will not
+* come from a pipe.
+*/
+/** Parse a batch of raw inputs from text. Throws a plain `Error` on malformed input. */
+const decodeInputsText = (text) => {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) throw new Error("no input provided");
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch (error) {
+		const lines = trimmed.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+		if (lines.length > 1) try {
+			return lines.map((line) => JSON.parse(line));
+		} catch {
+			throw error;
+		}
+		throw error;
+	}
+	if (Array.isArray(parsed)) return parsed;
+	if (parsed !== null && typeof parsed === "object") {
+		const inputs = parsed.inputs;
+		if (Array.isArray(inputs)) return inputs;
+		return [parsed];
+	}
+	throw new Error("expected a JSON array, a { \"inputs\": [...] } envelope, or JSONL");
+};
+//#endregion
+//#region src/decide/render.ts
+/** One review-queue entry: what was asked, how it landed, and the raw answers. */
+const reviewLine = (record) => [`  ${record.inputRef}  ·  ${record.verdict}`, `      ${JSON.stringify(record.answers)}`].join("\n");
+/**
+* Human `decide` report: the batch header, a verdict breakdown, and the review
+* queue — the only part a human has to act on.
+*/
+const renderDecideReport = (report) => {
+	const lines = [
+		`${report.counts.inputs} input(s) · family ${report.family} · model ${report.model} · threshold ${report.threshold.toFixed(2)}`,
+		"",
+		`  resolved  ${report.counts.resolved}`,
+		`  review    ${report.counts.review}`,
+		""
+	];
+	const verdicts = Object.entries(report.verdicts).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	if (verdicts.length > 0) {
+		lines.push("Verdicts:", "");
+		for (const [verdict, count] of verdicts) lines.push(`  ${verdict.padEnd(20)} ${count}`);
+		lines.push("");
+	}
+	if (report.review.length === 0) lines.push("No inputs need review.");
+	else {
+		lines.push(`Review queue (${report.review.length}):`, "");
+		for (const record of report.review) lines.push(reviewLine(record), "");
+		lines.pop();
+	}
+	return lines.join("\n").trimEnd();
+};
+//#endregion
+//#region src/links/decide.ts
+/**
+* Link decisions over the rendered graph, answered by an Effect `DecisionModel`.
+*
+* A candidate is a `(source → destination)` pair with the source copy. The model
+* answers two probabilities — does the source have a genuine reader-facing
+* reason to link to the destination, and is descriptive anchor text already in
+* the copy — and this module maps them to a verdict. Anything the model is not
+* confident about lands in the `review` bucket; nothing is applied automatically.
+*
+* This module reaches Effect and the TypeSafe provider, so it is CLI-internal:
+* the library entries stay Effect-free and only the bundled `pagegraph` bin
+* ships it.
+*/
+/** Default probability boundary between a confident and an uncertain answer. */
+const DEFAULT_LINK_THRESHOLD = .7;
+/** Ordered relevance scale for budget selection. */
+const LINK_RELEVANCE = [
+	"irrelevant",
+	"useful",
+	"essential"
+];
+/** One proposed contextual link, plus the source copy the model reads. */
+const LinkCandidate = Struct({
+	sourceUrl: String$6,
+	destinationUrl: String$6,
+	sourceText: String$6,
+	/** Descriptive anchor text already present for the destination, when known. */
+	existingAnchor: optional$3(String$6)
+});
+/**
+* The four decisions every candidate answers in one provider call: two
+* probabilities, a direction classification, and a relevance rating. The
+* probabilities decide the verdict; direction and relevance inform the plan and
+* the per-source budget.
+*/
+const LinkDecision = make({
+	input: LinkCandidate,
+	decisions: {
+		realReason: probability({
+			instructions: "The source page has a genuine reader-facing reason to link to the destination page: the destination answers a question the source raises or deepens a topic the source introduces. Navigation, boilerplate, and mere keyword overlap are not reasons.",
+			criteria: {
+				false: "No genuine reason; the link would be noise or only keyword overlap.",
+				true: "A reader of the source would plausibly want the destination next."
+			}
+		}),
+		anchorPresent: probability({
+			instructions: "Descriptive anchor text pointing at the destination already appears in the source copy. A bare mention without a link counts as absent.",
+			criteria: {
+				false: "No existing anchor to the destination in the copy.",
+				true: "Descriptive anchor text to the destination is already in the copy."
+			}
+		}),
+		direction: classify({
+			instructions: "Which direction between the candidate pair deserves a link: source → destination, destination → source, or both.",
+			criteria: {
+				a_to_b: "The source page should link to the destination page.",
+				b_to_a: "The destination page should link to the source page.",
+				both: "Both directions are reader-useful."
+			}
+		}),
+		relevance: rate({
+			instructions: "How relevant this link is to the reader: irrelevant is noise, useful is a sensible next step, essential is a link the page is incomplete without.",
+			criteria: LINK_RELEVANCE
+		})
+	}
+});
+/** A decision confidence band around `threshold`: `[0, 1 - threshold] ∪ [threshold, 1]`. */
+const isConfident = (probability, threshold) => probability >= threshold || probability <= 1 - threshold;
+/**
+* Map the two probabilities to a verdict. A probability inside the review band
+* makes the whole candidate uncertain, so the confident half of the pair can
+* never auto-resolve it. Requires `threshold > 0.5`, so the review band
+* `(1 - threshold, threshold)` is non-empty.
+*
+* - `present` — descriptive anchor already in the copy; nothing to add.
+* - `recommend` — a real reason and no existing anchor; add a contextual link.
+* - `skip` — no real reason; leave the copy alone.
+* - `review` — at least one answer is inside the band; a human decides.
+*/
+const classifyVerdict = (realReason, anchorPresent, threshold) => {
+	if (!isConfident(realReason, threshold) || !isConfident(anchorPresent, threshold)) return "review";
+	if (anchorPresent >= threshold) return "present";
+	if (realReason >= threshold) return "recommend";
+	return "skip";
+};
+/**
+* Keep the top `budget` candidates per outbound page by relevance rating,
+* preserving the original order. The outbound page is `record.from`, which
+* honors `direction` — grouping by the candidate's `sourceUrl` would misspend the
+* quota when the model recommends the reverse direction. Ties keep their
+* original order (stable sort). Pages with fewer candidates pass through.
+*/
+const applyBudget = (records, budget) => {
+	const bySource = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const bucket = bySource.get(record.from);
+		if (bucket === void 0) bySource.set(record.from, [record]);
+		else bucket.push(record);
+	}
+	const kept = /* @__PURE__ */ new Set();
+	for (const bucket of bySource.values()) {
+		const top = [...bucket].sort((a, b) => b.relevance.rating - a.relevance.rating).slice(0, budget);
+		for (const record of top) kept.add(record);
+	}
+	return records.filter((record) => kept.has(record));
+};
+/** Group records into resolved/review buckets and count each verdict. */
+const buildLinksDecideReport = (options) => {
+	const counts = {
+		recommend: 0,
+		present: 0,
+		skip: 0,
+		review: 0
+	};
+	const resolved = [];
+	const review = [];
+	for (const record of options.records) {
+		counts[record.verdict] += 1;
+		if (record.verdict === "review") review.push(record);
+		else resolved.push(record);
+	}
+	return {
+		kind: "links-decide",
+		schemaVersion: 1,
+		model: options.model,
+		threshold: options.threshold,
+		budget: options.budget ?? null,
+		dropped: options.dropped ?? 0,
+		counts: {
+			candidates: options.records.length,
+			...counts
+		},
+		resolved,
+		review
+	};
+};
+/**
+* The endpoints a `recommend` verdict actually directs. `b_to_a` reverses the
+* candidate pair, so the report names the direction the model chose rather than
+* always printing source → destination.
+*/
+const endpoints = (candidate, direction) => direction === "b_to_a" ? {
+	from: candidate.destinationUrl,
+	to: candidate.sourceUrl
+} : {
+	from: candidate.sourceUrl,
+	to: candidate.destinationUrl
+};
+const toRecord = (candidate, answers, threshold) => {
+	const realReason = answers.realReason.probability;
+	const anchorPresent = answers.anchorPresent.probability;
+	const direction = answers.direction.label;
+	return {
+		sourceUrl: candidate.sourceUrl,
+		destinationUrl: candidate.destinationUrl,
+		sourceText: candidate.sourceText,
+		existingAnchor: candidate.existingAnchor ?? null,
+		realReason,
+		anchorPresent,
+		direction,
+		relevance: {
+			rating: answers.relevance.rating,
+			label: answers.relevance.label,
+			probabilities: answers.relevance.probabilities
+		},
+		...endpoints(candidate, direction),
+		verdict: classifyVerdict(realReason, anchorPresent, threshold)
+	};
+};
+/**
+* Answer every candidate through the ambient `DecisionModel` and bucket the
+* results. The model answers both decisions in one call per candidate; candidates
+* are dispatched with bounded concurrency. A warm cache skips the provider.
+*/
+const decideLinks = (candidates, options) => gen(function* () {
+	const records = yield* forEach$1(candidates, (candidate) => gen(function* () {
+		const hash = inputHash(candidate);
+		const key = cacheKey("links", options.model, hash);
+		const cached = options.cacheDir === void 0 ? void 0 : cacheGet(options.cacheDir, key);
+		if (cached !== void 0 && validCachedAnswers(LinkDecision.decisions, cached)) return toRecord(candidate, cached, options.threshold);
+		const { answers } = yield* decide(LinkDecision, { input: candidate });
+		if (options.cacheDir !== void 0) cachePut(options.cacheDir, key, answers);
+		return toRecord(candidate, answers, options.threshold);
+	}), { concurrency: options.concurrency ?? 4 });
+	const selected = options.budget === void 0 ? records : applyBudget(records, options.budget);
+	return buildLinksDecideReport({
+		model: options.model,
+		threshold: options.threshold,
+		records: selected,
+		budget: options.budget,
+		dropped: records.length - selected.length
+	});
+});
+/** Decode the candidate array the CLI reads from a file or stdin. Throws on invalid input. */
+const decodeLinkCandidates = (input) => decodeUnknownSync(ArraySchema(LinkCandidate))(input);
+//#endregion
+//#region src/cli/commands/decide.ts
+/**
+* `pagegraph decide <family>` — the decision runner over a batch. Each family
+* subcommand reads a batch of inputs, answers every decision for an input in one
+* provider call, and separates confident verdicts from `review`.
+*
+* `decide links` is the links family alias of the legacy `pagegraph links decide`.
+* Effect and the TypeSafe provider live only in this CLI-internal command; the
+* library entries stay Effect-free.
+*/
+/** Default probability boundary between a confident and an uncertain answer. */
+const DEFAULT_DECIDE_THRESHOLD = .7;
+const messageOf$1 = (cause) => cause instanceof Error ? cause.message : String(cause);
+const positive$1 = (name, value) => Number.isSafeInteger(value) && value > 0 ? succeed$2(value) : fail$3(new SeoCliError({ message: `--${name} must be a positive integer` }));
+const checkThreshold$1 = (value) => Number.isFinite(value) && value > .5 && value < 1 ? succeed$2(value) : fail$3(new SeoCliError({ message: "--threshold must be greater than 0.5 and less than 1 (a review band needs 1 - t < t)" }));
+const decideFile$1 = String$1("file").pipe(withDescription("JSON batch: an array, { inputs: [...] }, or JSONL (default: stdin)"), optional);
+const decideThresholdFlag = Finite("threshold").pipe(withDescription$2("Probability above which an answer is confident; below is review (0.5 < t < 1)"), withDefault(DEFAULT_DECIDE_THRESHOLD));
+const modelFlag$1 = String$2("model").pipe(withDescription$2("TypeSafe System One model identifier"), withDefault("jev-latest"));
+const concurrencyFlag$1 = Int("concurrency").pipe(withDescription$2("Maximum concurrent decision calls"), withDefault(4));
+const cacheFlag = String$2("cache").pipe(withDescription$2("Reuse model answers by input hash; directory for cache files"), optional$1);
+const reviewOutFlag = String$2("review-out").pipe(withDescription$2("Write only below-threshold records to this JSON file"), optional$1);
+const budgetFlag$1 = Int("budget").pipe(withDescription$2("Keep only the top-K candidates per source by relevance"), withDefault(4));
+/** Read the batch text from a file argument or stdin; a TTY with no file is an error. */
+const readInputsText = (file) => try_({
+	try: () => {
+		if (file !== void 0) return readFileSync(file, "utf8");
+		if (process.stdin.isTTY) throw new Error("no input file given and stdin is a TTY");
+		return readFileSync(0, "utf8");
+	},
+	catch: (cause) => new SeoCliError({ message: `Could not read inputs: ${messageOf$1(cause)}` })
+});
+/** Parse the batch text, then schema-decode every input against the family. */
+const parseInputs = (family, text) => try_({
+	try: () => decodeFamilyInputs(family, decodeInputsText(text)),
+	catch: (cause) => new SeoCliError({ message: `Invalid inputs: ${messageOf$1(cause)}` })
+});
+/** Apply a family's optional input guard to every decoded input. */
+const validateInputs = (family, inputs) => gen(function* () {
+	if (family.validate === void 0) return;
+	for (const input of inputs) {
+		const problem = family.validate(input);
+		if (problem !== void 0) return yield* new SeoCliError({ message: problem });
+	}
+});
+const requireKey = (family) => process.env.TYPESAFE_API_KEY === void 0 || process.env.TYPESAFE_API_KEY === "" ? fail$3(new SeoCliError({ message: `TYPESAFE_API_KEY is not set; \`pagegraph decide ${family}\` answers through TypeSafe System One.` })) : void_;
+/** TypeSafe System One decision model over the shared fetch HTTP client. */
+const typeSafeDecisionModel$1 = (model$2) => model(model$2).pipe(provide$2(layerConfig()), provide$2(layer$1));
+const decisionErrorMessage$1 = (error) => error._tag === "AiError" ? new SeoCliError({ message: `Decision request failed (${error.reason._tag}): ${error.message}` }) : new SeoCliError({ message: `TypeSafe configuration failed: ${error.message}` });
+/** Write the below-threshold records to `file`, creating its parent directory. */
+const writeReviewRecords = (file, payload) => file === void 0 ? void_ : try_({
+	try: () => {
+		mkdirSync(dirname(resolve(file)), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	},
+	catch: (cause) => new SeoCliError({ message: `Could not write review records to ${file}: ${messageOf$1(cause)}` })
+});
+/** Run one family over a decoded batch and print its report. */
+const runFamily = (family, options) => gen(function* () {
+	const threshold = yield* checkThreshold$1(options.threshold);
+	const concurrency = yield* positive$1("concurrency", options.concurrency);
+	const text = yield* readInputsText(getOrUndefined$1(options.file));
+	const inputs = yield* parseInputs(family, text);
+	yield* validateInputs(family, inputs);
+	yield* requireKey(family.name);
+	const report = yield* runDecisions({
+		family,
+		inputs,
+		model: options.model,
+		threshold,
+		concurrency,
+		cacheDir: getOrUndefined$1(options.cache)
+	}).pipe(provide(typeSafeDecisionModel$1(options.model)), mapError(decisionErrorMessage$1));
+	yield* writeReviewRecords(getOrUndefined$1(options.reviewOut), {
+		family: report.family,
+		model: report.model,
+		threshold: report.threshold,
+		review: report.review
+	});
+	if (options.json) yield* printJson(report);
+	else yield* printText(renderDecideReport(report));
+});
+/** Parse the legacy link-candidate batch (array or `{ inputs }`). */
+const parseLinks = (text) => try_({
+	try: () => decodeLinkCandidates(decodeInputsText(text)),
+	catch: (cause) => new SeoCliError({ message: `Invalid candidates: ${messageOf$1(cause)}` })
+});
+/** `decide links` — the links family alias over the legacy `links decide` report. */
+const runLinks = (options) => gen(function* () {
+	const threshold = yield* checkThreshold$1(options.threshold);
+	const concurrency = yield* positive$1("concurrency", options.concurrency);
+	const budget = yield* positive$1("budget", options.budget);
+	const text = yield* readInputsText(getOrUndefined$1(options.file));
+	const candidates = yield* parseLinks(text);
+	yield* requireKey("links");
+	const report = yield* decideLinks(candidates, {
+		model: options.model,
+		threshold,
+		concurrency,
+		cacheDir: getOrUndefined$1(options.cache),
+		budget
+	}).pipe(provide(typeSafeDecisionModel$1(options.model)), mapError(decisionErrorMessage$1));
+	yield* writeReviewRecords(getOrUndefined$1(options.reviewOut), {
+		family: "links",
+		model: report.model,
+		threshold: report.threshold,
+		review: report.review
+	});
+	if (options.json) yield* printJson(report);
+	else yield* printText(renderLinksDecideReport(report));
+});
+const decideCommand = (config) => make$9(config.name, {
+	file: decideFile$1,
+	json: jsonFlag,
+	threshold: decideThresholdFlag,
+	model: modelFlag$1,
+	concurrency: concurrencyFlag$1,
+	cache: cacheFlag,
+	reviewOut: reviewOutFlag
+}).pipe(withDescription$1(config.description), withExamples(config.examples), withHandler((options) => config.run(options)));
+/** Build a family subcommand from its family and help text. */
+const familySubcommand = (family, config) => decideCommand({
+	name: family.name,
+	description: config.description,
+	examples: config.examples,
+	run: (options) => runFamily(family, options)
+});
+const serpCommand = familySubcommand(serpFamily, {
+	description: "Classify the SERP format and score our page's fit, intent, and title (aligned | mismatch | review)",
+	examples: [{
+		command: "pagegraph decide serp serp.json",
+		description: "Decide a saved SERP snapshot and print the reviewable plan"
+	}, {
+		command: "cat serp.json | pagegraph decide serp --json | jq",
+		description: "Read the SERP batch from stdin and emit versioned JSON"
+	}]
+});
+const contentCommand = familySubcommand(contentFamily, {
+	description: "Score a page's content rubric and place its value on thin | adequate | strong (pass | flag | review)",
+	examples: [{
+		command: "pagegraph decide content page.json",
+		description: "Decide a page's content quality and print the reviewable plan"
+	}, {
+		command: "cat page.json | pagegraph decide content --json | jq",
+		description: "Read the content batch from stdin and emit versioned JSON"
+	}]
+});
+const fitCommand = familySubcommand(fitFamily, {
+	description: "Choose the best existing page for a query, or flag cannibalization or a gap (map | cannibalized | gap | review)",
+	examples: [{
+		command: "pagegraph decide fit candidates.json",
+		description: "Rank existing pages for a query and print the reviewable plan"
+	}, {
+		command: "cat candidates.json | pagegraph decide fit --json | jq",
+		description: "Read the fit batch from stdin and emit versioned JSON"
+	}]
+});
+const metaCommand = familySubcommand(metaFamily, {
+	description: "Rank supplied title/description candidates for a page (choose:<id> | review)",
+	examples: [{
+		command: "pagegraph decide meta meta.json",
+		description: "Rank metadata candidates and print the chosen one or a review"
+	}, {
+		command: "cat meta.json | pagegraph decide meta --json | jq",
+		description: "Read the meta batch from stdin and emit versioned JSON"
+	}]
+});
+const authorityCommand = familySubcommand(authorityFamily, {
+	description: "Judge a link target's legitimacy, spam, and outreach worth, plus its fit (accept | spam | review)",
+	examples: [{
+		command: "pagegraph decide authority targets.json",
+		description: "Judge a batch of link targets and print the reviewable plan"
+	}, {
+		command: "cat targets.json | pagegraph decide authority --json | jq",
+		description: "Read the authority batch from stdin and emit versioned JSON"
+	}]
+});
+const linksDecideCommand$1 = make$9("links", {
+	file: decideFile$1,
+	json: jsonFlag,
+	threshold: decideThresholdFlag,
+	model: modelFlag$1,
+	concurrency: concurrencyFlag$1,
+	cache: cacheFlag,
+	reviewOut: reviewOutFlag,
+	budget: budgetFlag$1
+}).pipe(withDescription$1("Answer the links family: real reason, anchor present, direction, and relevance per candidate"), withExamples([
+	{
+		command: "pagegraph decide links candidates.json",
+		description: "Answer a candidate batch and print the reviewable plan"
+	},
+	{
+		command: "pagegraph decide links candidates.json --budget 2",
+		description: "Keep the top two candidates per source by relevance"
+	},
+	{
+		command: "cat candidates.json | pagegraph decide links --json | jq",
+		description: "Read candidates from stdin and emit versioned JSON"
+	}
+]), withHandler((options) => runLinks(options)));
+/**
+* `pagegraph decide` groups the decision families. Each family answers one batch
+* of inputs through TypeSafe System One; confident verdicts resolve, answers in
+* the confidence band go to review, and nothing is applied automatically.
+*/
+const decideCommandGroup = make$9("decide").pipe(withDescription$1("Answer calibrated SEO decisions over a batch with Jev"), withExamples([{
+	command: "pagegraph decide links candidates.json --json | jq",
+	description: "Decide a link-candidate batch and emit versioned JSON"
+}]), withSubcommands([
+	serpCommand,
+	contentCommand,
+	fitCommand,
+	metaCommand,
+	authorityCommand,
+	linksDecideCommand$1
+]));
+//#endregion
+//#region src/cli/commands/diff.ts
+const before = String$1("before.json").pipe(withDescription("Earlier pagegraph audit JSON artifact"));
+const after = String$1("after.json").pipe(withDescription("Later pagegraph audit JSON artifact"));
+const readAuditReport = fn("SeoCli.readAuditReport")(function* (label, path) {
+	const contents = yield* (yield* FileSystem).readFileString(path).pipe(mapError((error) => new SeoCliError({ message: `Could not read ${label} report ${path}: ${error.message}` })));
+	return yield* decodeUnknownEffect(fromJsonString(AuditReport))(contents).pipe(mapError((error) => new SeoCliError({ message: `Invalid ${label} report ${path}: ${error.message}` })));
+});
+const diffCommand = make$9("diff", {
+	before,
+	after,
+	json: jsonFlag
+}).pipe(withDescription$1("Compare two versioned pagegraph audit JSON artifacts for semantic regressions"), withExamples([{
+	command: "pagegraph diff before.json after.json",
+	description: "Render a human-readable semantic comparison"
+}, {
+	command: "pagegraph diff before.json after.json --json",
+	description: "Emit one versioned JSON diff on stdout"
+}]), withHandler(fn("SeoCli.diff")(function* (options) {
+	const beforeReport = yield* readAuditReport("before", options.before);
+	const afterReport = yield* readAuditReport("after", options.after);
+	const comparison = compareAuditReports(beforeReport, afterReport);
+	if (AuditComparisonResult.$is("InvalidReport")(comparison)) return yield* new SeoCliError({ message: `Invalid audit report invariants:\n${comparison.issues.map((issue) => `- ${issue}`).join("\n")}` });
+	if (options.json) yield* printJson(comparison.diff);
+	else yield* printText(renderAuditDiff(comparison.diff));
+	if (comparison.diff.outcome === "regressed") {
+		const summary = comparison.diff.summary;
+		return yield* new SeoCliError({ message: `${summary.structuralRegressions} structural, ${summary.scannerRegressions} scanner, and ${summary.coverageRegressions} coverage regression(s); see the diff above.` });
+	}
+})));
+//#endregion
+//#region src/cli/serialize.ts
+const serializeCrumb = (crumb) => {
+	if (crumb === void 0) return void 0;
+	return typeof crumb === "function" ? "(dynamic)" : crumb;
+};
+/** JSON-safe projection of one node (route policy `crumb` functions → sentinel). */
+const serializeNode = (node) => ({
+	path: node.path,
+	kind: node.kind,
+	source: node.source,
+	policy: {
+		kind: node.policy.kind,
+		crumb: serializeCrumb(node.policy.crumb),
+		sitemap: node.policy.sitemap,
+		robots: node.policy.robots,
+		related: node.policy.related,
+		link: node.policy.link,
+		redirectTo: node.policy.redirectTo
+	},
+	instance: node.instance
+});
+/** Flatten the graph to a sorted, JSON-safe shape. Nodes are ordered by path. */
+const serializeGraph = (graph) => ({
+	nodes: [...graph.nodes.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(serializeNode),
+	edges: graph.edges
+});
+const graphCommand = make$9("graph", {
+	format: Literals("format", [
+		"tree",
+		"mermaid",
+		"json"
+	]).pipe(withDescription$2("Output format: tree (default), mermaid diagram, or json"), withDefault("tree")),
+	orphans: Boolean$1("orphans").pipe(withDescription$2("Show only orphan nodes (nothing links to them)"), withDefault(false))
+}).pipe(withDescription$1("Render the SEO graph as a tree, a Mermaid diagram, or JSON"), withExamples([
+	{
+		command: "pagegraph graph",
+		description: "The graph as an indented path tree"
+	},
+	{
+		command: "pagegraph graph --format mermaid",
+		description: "A Mermaid diagram of nodes and edges"
+	},
+	{
+		command: "pagegraph graph --orphans",
+		description: "Only nodes with no incoming edge"
+	},
+	{
+		command: "pagegraph graph --format json",
+		description: "The serialized graph on stdout"
+	}
+]), withHandler(fnUntraced(function* ({ format, orphans }) {
+	const config = yield* loadSeoConfig;
+	const graph = yield* scoped(acquireGraph(config));
+	if (format === "json") {
+		const serialized = serializeGraph(graph);
+		if (!orphans) return yield* printJson(serialized);
+		const orphanSet = orphanPaths(graph);
+		return yield* printJson({
+			nodes: serialized.nodes.filter((node) => orphanSet.has(node.path)),
+			edges: serialized.edges.filter((edge) => orphanSet.has(edge.from) && orphanSet.has(edge.to))
+		});
+	}
+	if (format === "mermaid") return yield* printText(renderMermaid(graph, orphans));
+	return yield* printText(orphans ? renderOrphans(graph) : renderTree(graph));
+})));
+//#endregion
+//#region src/core/inspect-html.ts
+const ENTITIES = {
+	"&amp;": "&",
+	"&lt;": "<",
+	"&gt;": ">",
+	"&quot;": "\"",
+	"&#39;": "'",
+	"&apos;": "'"
+};
+const decodeEntities = (value) => value.replace(/&(?:amp|lt|gt|quot|#39|apos);/g, (match) => ENTITIES[match] ?? match);
+/** Pull double/single-quoted attributes off a single tag string. */
+const parseAttrs = (tag) => {
+	const attrs = {};
+	const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+	let match;
+	while ((match = re.exec(tag)) !== null) attrs[match[1].toLowerCase()] = decodeEntities(match[2] ?? match[3] ?? "");
+	return attrs;
+};
+/** Normalize a JSON-LD `@type` (string or array) to a single readable label. */
+const typeName = (value) => {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) return value.filter((v) => typeof v === "string").join(", ") || "unknown";
+	return "unknown";
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Flatten a parsed JSON-LD payload (single object, array, or `@graph`) to items. */
+const collectItems = (parsed) => {
+	if (Array.isArray(parsed)) return parsed.filter(isObject);
+	if (isObject(parsed)) {
+		if (Array.isArray(parsed["@graph"])) return parsed["@graph"].filter(isObject);
+		return [parsed];
+	}
+	return [];
+};
+const countQuestions = (mainEntity) => {
+	if (!Array.isArray(mainEntity)) return 0;
+	return mainEntity.filter((entry) => isObject(entry) && typeName(entry["@type"]) === "Question").length;
+};
+const validateItemListElements = (value) => {
+	if (!Array.isArray(value) || value.length < 1) return ["ItemList needs at least one `itemListElement` entry."];
+	const errors = [];
+	value.forEach((entry, index) => {
+		if (!isObject(entry) || typeName(entry["@type"]) !== "ListItem") {
+			errors.push(`ItemList entry ${index + 1} is not a ListItem.`);
+			return;
+		}
+		if (entry["position"] !== index + 1) errors.push(`ItemList entry ${index + 1} has an invalid position.`);
+		if (!entry["name"] || !entry["url"]) errors.push(`ItemList entry ${index + 1} needs a name and URL.`);
+	});
+	return errors;
+};
+/** Minimal per-type validation — enough to catch an empty or malformed block. */
+const validateItem = (item) => {
+	const type = typeName(item["@type"]);
+	const errors = [];
+	if (type === "Article" || type === "NewsArticle" || type === "BlogPosting") {
+		if (!item["headline"]) errors.push("Article is missing `headline`.");
+		if (!item["datePublished"]) errors.push("Article is missing `datePublished`.");
+	} else if (type === "FAQPage") {
+		if (countQuestions(item["mainEntity"]) < 1) errors.push("FAQPage needs at least one Question in `mainEntity`.");
+	} else if (type === "BreadcrumbList") {
+		const items = item["itemListElement"];
+		if (!Array.isArray(items) || items.length < 2) errors.push("BreadcrumbList needs at least two `itemListElement` entries.");
+	} else if (type === "ItemList") {
+		errors.push(...validateItemListElements(item["itemListElement"]));
+		const items = item["itemListElement"];
+		if (Array.isArray(items) && item["numberOfItems"] !== items.length) errors.push("ItemList `numberOfItems` does not match its entries.");
+	}
+	return {
+		type,
+		valid: errors.length === 0,
+		errors
+	};
+};
+const validateLdJson = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		return [{
+			type: "unparseable",
+			valid: false,
+			errors: [`JSON parse error: ${cause instanceof Error ? cause.message : String(cause)}`]
+		}];
+	}
+	const items = collectItems(parsed);
+	if (items.length === 0) return [{
+		type: "unknown",
+		valid: false,
+		errors: ["No JSON-LD object found in block."]
+	}];
+	return items.map(validateItem);
+};
+/** Parse a rendered HTML document's `<head>` into a report. Pure. */
+const inspectHtml = (url, status, html) => {
+	const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+	const head = headMatch ? headMatch[1] : html;
+	const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+	const title = titleMatch ? decodeEntities(titleMatch[1].trim()) : void 0;
+	const og = {};
+	const twitter = {};
+	let description;
+	let robots;
+	for (const tag of head.match(/<meta\b[^>]*>/gi) ?? []) {
+		const attrs = parseAttrs(tag);
+		const content = attrs["content"];
+		if (content === void 0) continue;
+		const property = attrs["property"];
+		const name = attrs["name"];
+		if (property?.startsWith("og:")) og[property] = content;
+		else if (name?.startsWith("twitter:")) twitter[name] = content;
+		else if (name === "description") description = content;
+		else if (name === "robots") robots = content;
+	}
+	let canonical;
+	for (const tag of head.match(/<link\b[^>]*>/gi) ?? []) {
+		const attrs = parseAttrs(tag);
+		if (attrs["rel"] === "canonical") canonical = attrs["href"];
+	}
+	const jsonLd = [];
+	const scriptRe = /<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+	let scriptMatch;
+	while ((scriptMatch = scriptRe.exec(head)) !== null) jsonLd.push(...validateLdJson(scriptMatch[1].trim()));
+	const issues = [];
+	if (status >= 400) issues.push(`Fetch returned HTTP ${status}.`);
+	if (!title) issues.push("Missing <title>.");
+	if (!description) issues.push("Missing meta description.");
+	if (!canonical) issues.push("Missing canonical link.");
+	for (const block of jsonLd) if (!block.valid) issues.push(...block.errors.map((error) => `JSON-LD (${block.type}): ${error}`));
+	return {
+		url,
+		status,
+		title,
+		description,
+		canonical,
+		robots,
+		og,
+		twitter,
+		jsonLd,
+		issues
+	};
+};
+/** A non-empty `issues` list fails `pagegraph inspect --live` (exit 1). */
+const hasBlockingIssues = (report) => report.issues.length > 0;
+//#endregion
+//#region src/cli/live-inspect.ts
+/**
+* `pagegraph inspect <url> --live`: fetch a URL and hand its body to the pure head
+* validator in `../inspect-html`. The fetch is all that lives here — the
+* validation is a library capability, not a CLI one, so it stays out of the
+* Effect-bearing half of the package.
+*/
+/** Fetch a URL and inspect its `<head>`. Network failures surface as SeoCliError. */
+const fetchAndInspect = (url) => tryPromise({
+	try: async () => {
+		const response = await fetch(url, { headers: { "user-agent": "pagegraph-cli" } });
+		const html = await response.text();
+		return inspectHtml(url, response.status, html);
+	},
+	catch: (cause) => new SeoCliError({ message: `Could not fetch ${url}: ${cause instanceof Error ? cause.message : String(cause)}` })
+});
+const inspectCommand = make$9("inspect", {
+	target: String$1("target").pipe(withDescription("A route path (e.g. /pricing), or a full URL with --live")),
+	live: Boolean$1("live").pipe(withDescription$2("Fetch the URL and inspect its rendered <head> and JSON-LD"), withDefault(false)),
+	json: jsonFlag
+}).pipe(withDescription$1("Inspect one page: its graph declaration, or its live <head> with --live"), withExamples([
+	{
+		command: "pagegraph inspect /pricing",
+		description: "The graph node, policy, and edges for a path"
+	},
+	{
+		command: "pagegraph inspect https://example.com/pricing --live",
+		description: "Fetch the page and validate its head tags + JSON-LD"
+	},
+	{
+		command: "pagegraph inspect /blog/some-post --json",
+		description: "The node report as JSON"
+	}
+]), withHandler(fnUntraced(function* ({ target, live, json }) {
+	if (live) {
+		const report = yield* fetchAndInspect(target);
+		if (json) yield* printJson(report);
+		else yield* printText(renderLiveReport(report));
+		if (hasBlockingIssues(report)) return yield* new SeoCliError({ message: `${report.issues.length} issue(s) found at ${target}.` });
+		return;
+	}
+	const config = yield* loadSeoConfig;
+	const report = inspectNode(yield* scoped(acquireGraph(config)), target);
+	if (report === void 0) return yield* new SeoCliError({ message: `No node at "${target}". Run \`pagegraph graph\` to list paths, or pass a URL with --live.` });
+	if (json) return yield* printJson({
+		node: serializeNode(report.node),
+		inSitemap: report.inSitemap,
+		incoming: report.incoming,
+		outgoing: report.outgoing
+	});
+	return yield* printText(renderNodeReport(report));
+})));
+//#endregion
 //#region src/audit/crawl.ts
 /** Anchors that are never HTML documents; skipped so they do not consume the budget. */
 const NON_PAGE = /\.(?:avif|css|csv|gif|ico|jpe?g|js|json|map|mp4|pdf|png|rss|svg|txt|webm|webp|woff2?|xml|zip)$/i;
@@ -41325,316 +42768,237 @@ const decodeRenderedEdges = (input) => {
 	});
 };
 //#endregion
-//#region node_modules/effect/dist/unstable/ai/Decision.js
-/**
-* Brand for decision definitions.
-*
-* @category type IDs
-* @since 4.0.0
-*/
-const TypeId = "~effect/ai/Decision";
-/**
-* Creates a probability decision from descriptions of both outcomes.
-*
-* **Example** (Estimating urgency)
-*
-* ```ts
-* import { Decision } from "effect/unstable/ai"
-*
-* const urgent = Decision.probability({
-*   instructions: "The message is time-sensitive",
-*   criteria: {
-*     false: "No time pressure",
-*     true: "Needs action now"
-*   }
-* })
-* ```
-*
-* @see {@link classify} for more than two outcomes
-*
-* @category constructors
-* @since 4.0.0
-*/
-const probability = (options) => ({
-	_tag: "Probability",
-	instructions: options.instructions,
-	criteria: options.criteria
-});
-/**
-* Creates a decision definition from an input schema and named decisions.
-* `DecisionModel.decide` encodes the input with `Schema.toCodecJson` before
-* calling the provider. Answer keys and types are inferred from the decisions.
-* Throws if `decisions` is empty.
-*
-* **Example** (Defining ticket triage)
-*
-* ```ts
-* import { Schema } from "effect"
-* import { Decision } from "effect/unstable/ai"
-*
-* const Ticket = Schema.Struct({
-*   subject: Schema.String,
-*   body: Schema.String
-* })
-*
-* const TicketTriage = Decision.make({
-*   input: Ticket,
-*   decisions: {
-*     department: Decision.classify({
-*       instructions: "Which team should handle this",
-*       criteria: { billing: "payments", technical: "bugs" }
-*     }),
-*     urgent: Decision.probability({
-*       instructions: "The message is time-sensitive",
-*       criteria: { false: "No time pressure", true: "Needs action now" }
-*     })
-*   }
-* })
-* ```
-*
-* @see {@link Definition} for the returned shape
-*
-* @category constructors
-* @since 4.0.0
-*/
-const make = (options) => {
-	if (Object.keys(options.decisions).length === 0) throw new Error("Decision.make: decisions must not be empty");
-	return {
-		[TypeId]: TypeId,
-		input: options.input,
-		decisions: options.decisions
-	};
-};
-//#endregion
-//#region src/links/decide.ts
-/**
-* Link decisions over the rendered graph, answered by an Effect `DecisionModel`.
-*
-* A candidate is a `(source → destination)` pair with the source copy. The model
-* answers two probabilities — does the source have a genuine reader-facing
-* reason to link to the destination, and is descriptive anchor text already in
-* the copy — and this module maps them to a verdict. Anything the model is not
-* confident about lands in the `review` bucket; nothing is applied automatically.
-*
-* This module reaches Effect and the TypeSafe provider, so it is CLI-internal:
-* the library entries stay Effect-free and only the bundled `pagegraph` bin
-* ships it.
-*/
-/** Default probability boundary between a confident and an uncertain answer. */
-const DEFAULT_LINK_THRESHOLD = .7;
-/** One proposed contextual link, plus the source copy the model reads. */
-const LinkCandidate = Struct({
-	sourceUrl: String$6,
-	destinationUrl: String$6,
-	sourceText: String$6,
-	/** Descriptive anchor text already present for the destination, when known. */
-	existingAnchor: optional$3(String$6)
-});
-/**
-* The two decisions every candidate answers. Both are probabilities, so the
-* model returns a calibrated number rather than generated prose.
-*/
-const LinkDecision = make({
-	input: LinkCandidate,
-	decisions: {
-		realReason: probability({
-			instructions: "The source page has a genuine reader-facing reason to link to the destination page: the destination answers a question the source raises or deepens a topic the source introduces. Navigation, boilerplate, and mere keyword overlap are not reasons.",
-			criteria: {
-				false: "No genuine reason; the link would be noise or only keyword overlap.",
-				true: "A reader of the source would plausibly want the destination next."
-			}
-		}),
-		anchorPresent: probability({
-			instructions: "Descriptive anchor text pointing at the destination already appears in the source copy. A bare mention without a link counts as absent.",
-			criteria: {
-				false: "No existing anchor to the destination in the copy.",
-				true: "Descriptive anchor text to the destination is already in the copy."
-			}
-		})
-	}
-});
-/** A decision confidence band around `threshold`: `[0, 1 - threshold] ∪ [threshold, 1]`. */
-const isConfident = (probability, threshold) => probability >= threshold || probability <= 1 - threshold;
-/**
-* Map the two probabilities to a verdict. A probability inside the review band
-* makes the whole candidate uncertain, so the confident half of the pair can
-* never auto-resolve it. Requires `threshold > 0.5`, so the review band
-* `(1 - threshold, threshold)` is non-empty.
-*
-* - `present` — descriptive anchor already in the copy; nothing to add.
-* - `recommend` — a real reason and no existing anchor; add a contextual link.
-* - `skip` — no real reason; leave the copy alone.
-* - `review` — at least one answer is inside the band; a human decides.
-*/
-const classifyVerdict = (realReason, anchorPresent, threshold) => {
-	if (!isConfident(realReason, threshold) || !isConfident(anchorPresent, threshold)) return "review";
-	if (anchorPresent >= threshold) return "present";
-	if (realReason >= threshold) return "recommend";
-	return "skip";
-};
-/** Group records into resolved/review buckets and count each verdict. */
-const buildLinksDecideReport = (options) => {
-	const counts = {
-		recommend: 0,
-		present: 0,
-		skip: 0,
-		review: 0
-	};
-	const resolved = [];
-	const review = [];
-	for (const record of options.records) {
-		counts[record.verdict] += 1;
-		if (record.verdict === "review") review.push(record);
-		else resolved.push(record);
-	}
-	return {
-		kind: "links-decide",
-		schemaVersion: 1,
-		model: options.model,
-		threshold: options.threshold,
-		counts: {
-			candidates: options.records.length,
-			...counts
-		},
-		resolved,
-		review
-	};
-};
-/**
-* Answer every candidate through the ambient `DecisionModel` and bucket the
-* results. The model answers both decisions in one call per candidate; candidates
-* are dispatched with bounded concurrency.
-*/
-const decideLinks = (candidates, options) => gen(function* () {
-	const records = yield* forEach$1(candidates, (candidate) => decide(LinkDecision, { input: candidate }).pipe(map$5(({ answers }) => {
-		const realReason = answers.realReason.probability;
-		const anchorPresent = answers.anchorPresent.probability;
-		return {
-			sourceUrl: candidate.sourceUrl,
-			destinationUrl: candidate.destinationUrl,
-			sourceText: candidate.sourceText,
-			existingAnchor: candidate.existingAnchor ?? null,
-			realReason,
-			anchorPresent,
-			verdict: classifyVerdict(realReason, anchorPresent, options.threshold)
-		};
-	})), { concurrency: options.concurrency ?? 4 });
-	return buildLinksDecideReport({
-		model: options.model,
-		threshold: options.threshold,
-		records
-	});
-});
-/** Decode the candidate array the CLI reads from a file or stdin. Throws on invalid input. */
-const decodeLinkCandidates = (input) => decodeUnknownSync(ArraySchema(LinkCandidate))(input);
-//#endregion
 //#region src/cli/commands/links.ts
 const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
 const positive = (name, value) => Number.isSafeInteger(value) && value > 0 ? succeed$2(value) : fail$3(new SeoCliError({ message: `--${name} must be a positive integer` }));
-const urlArg = String$1("url").pipe(withDescription("Absolute http(s) URL of the site homepage to crawl"));
+const urlArg = String$1("url").pipe(withDescription("Absolute http(s) URL of the site homepage to crawl (omit with --rendered)"), optional);
 const limitFlag = Int("limit").pipe(withDescription$2("Maximum pages to fetch, including the homepage"), withDefault(100));
 const allowPrivate = Boolean$1("allow-private").pipe(withDescription$2("Allow localhost and private addresses (local development only)"), withDefault(false));
 const requestTimeoutMs = Int("request-timeout-ms").pipe(withDescription$2("HTTP request timeout in milliseconds"), withDefault(15e3));
 const maxBodyBytes = Int("max-body-bytes").pipe(withDescription$2("Maximum captured response bytes per page"), withDefault(2e6));
 /**
-* The declared graph is optional input. A missing `seo.config.ts` means the
-* rendered-only report; a config that exists but fails to load is a warning, not
-* a failure, because verifying served HTML works on any deployed site. Origins
-* are compared before diffing, so a graph from another project is never silently
-* attributed to this crawl.
+* Load the app's declared graph when a `seo.config.ts` exists and derive the two
+* things `verify` needs from it: the declared `related` edges for the diff, and —
+* under `--assert-coverage` — the rendered coverage assertion. Both are computed
+* inside one scoped graph acquisition so the Vite loader is acquired once.
+*
+* Without `--assert-coverage` the declared graph is optional enrichment: a
+* missing or broken config, an invalid origin, or an origin mismatch each become a
+* warning, because verifying served HTML works on any deployed site. Under
+* `--assert-coverage` every one of those is a hard failure — an assertion must
+* know which pages the rules target and that this crawl is the same site, and a
+* truncated crawl is refused before the graph is even loaded.
 */
-const loadDeclaredGraph = gen(function* () {
-	const config = yield* loadSeoConfigOptional;
-	if (config === void 0) return { kind: "absent" };
+const analyzeDeclared = (crawlOrigin, renderedEdges, assertCoverage, crawlState) => gen(function* () {
+	if (assertCoverage) {
+		if (crawlState.truncated) return yield* new SeoCliError({ message: "Refusing to assert rendered coverage on a truncated crawl; re-run with a higher --limit." });
+		if (crawlState.failures > 0) return yield* new SeoCliError({ message: `Refusing to assert rendered coverage: ${crawlState.failures} page(s) failed to fetch, so their anchors are missing.` });
+		if (crawlState.bodyTruncated) return yield* new SeoCliError({ message: "Refusing to assert rendered coverage when a crawled body was truncated; raise --max-body-bytes." });
+	}
+	const warnings = [];
+	const config = yield* loadSeoConfigOptional.pipe(catchTag("SeoCliError", (error) => assertCoverage ? fail$3(error) : sync(() => {
+		warnings.push(`Ignoring declared graph: ${error.message}`);
+	})));
+	if (config === void 0) {
+		if (assertCoverage) return yield* new SeoCliError({ message: "Coverage assertion needs a seo.config.ts declaring `coverage` rules." });
+		return {
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
+		};
+	}
 	let configOrigin;
 	try {
 		configOrigin = new URL(config.origin).origin;
 	} catch {
+		const message = `Ignoring declared graph: seo.config.ts origin "${config.origin}" is not a valid URL.`;
+		if (assertCoverage) return yield* new SeoCliError({ message });
+		warnings.push(message);
 		return {
-			kind: "warning",
-			message: `Ignoring declared graph: seo.config.ts origin "${config.origin}" is not a valid URL.`
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
 		};
 	}
-	const graph = yield* scoped(acquireGraph(config));
-	return {
-		kind: "loaded",
-		graph: {
-			origin: configOrigin,
-			edges: graph.edges.filter((edge) => edge.type === "related").map((edge) => ({
+	const rules = config.coverage ?? [];
+	if (assertCoverage && rules.length === 0) return yield* new SeoCliError({ message: "seo.config.ts declares no `coverage` rules; nothing to assert." });
+	if (configOrigin !== crawlOrigin) {
+		const mismatch = `declared graph origin ${configOrigin} differs from crawled origin ${crawlOrigin}`;
+		if (assertCoverage) return yield* new SeoCliError({ message: `Cannot assert coverage: ${mismatch}.` });
+		warnings.push(`${mismatch.charAt(0).toUpperCase()}${mismatch.slice(1)}; skipping the declared-vs-rendered diff.`);
+		return {
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
+		};
+	}
+	return yield* scoped(gen(function* () {
+		const graph = yield* acquireGraph(config);
+		return {
+			declaredEdges: graph.edges.filter((edge) => edge.type === "related").map((edge) => ({
 				from: edge.from,
 				to: edge.to
-			}))
-		}
-	};
-}).pipe(catchTag("SeoCliError", (error) => succeed$2({
-	kind: "warning",
-	message: `Ignoring declared graph: ${error.message}`
-})));
+			})),
+			coverage: assertCoverage ? {
+				rules: rules.length,
+				violations: checkRenderedCoverage(graph, renderedEdges, rules)
+			} : void 0,
+			warnings
+		};
+	}));
+});
+/** Read and decode a saved rendered-edge artifact; the file is user input. */
+const readRenderedArtifact = (file) => try_({
+	try: () => decodeRenderedEdgeArtifact(JSON.parse(readFileSync(file, "utf8"))),
+	catch: (cause) => new SeoCliError({ message: `Could not read rendered artifact from ${file}: ${messageOf(cause)}` })
+});
+/** Write a rendered-edge artifact, creating its parent directory when needed. */
+const writeRenderedArtifact = (file, artifact) => try_({
+	try: () => {
+		mkdirSync(dirname(resolve(file)), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+	},
+	catch: (cause) => new SeoCliError({ message: `Could not write rendered artifact to ${file}: ${messageOf(cause)}` })
+});
 const linksVerifyCommand = make$9("verify", {
 	url: urlArg,
 	json: jsonFlag,
 	limit: limitFlag,
 	allowPrivate,
 	requestTimeoutMs,
-	maxBodyBytes
+	maxBodyBytes,
+	emitRendered: String$2("emit-rendered").pipe(withDescription$2("Write the crawled rendered-edge artifact to this path (crawl mode)"), optional$1),
+	rendered: String$2("rendered").pipe(withDescription$2("Replay a saved rendered-edge artifact instead of crawling"), optional$1),
+	assertCoverage: Boolean$1("assert-coverage").pipe(withDescription$2("Assert seo.config.ts coverage rules against the rendered anchors; exit 1 on unmet (refuses truncated crawls)"), withDefault(false))
 }).pipe(withDescription$1("Crawl served HTML and report homepage depth, rendered orphans, and the declared-vs-rendered gap"), withExamples([
 	{
 		command: "pagegraph links verify https://example.com",
 		description: "Crawl the homepage and report the rendered link graph"
 	},
 	{
-		command: "pagegraph links verify https://example.com --limit 25",
-		description: "Bound the crawl to 25 pages"
+		command: "pagegraph links verify https://example.com --limit 25 --json | jq",
+		description: "Bound the crawl to 25 pages and emit versioned JSON"
+	},
+	{
+		command: "pagegraph links verify https://example.com --emit-rendered rendered.json",
+		description: "Crawl once and save the rendered-edge artifact"
+	},
+	{
+		command: "pagegraph links verify --rendered rendered.json --assert-coverage",
+		description: "Assert seo.config.ts coverage offline against a saved crawl (exit 1 on unmet)"
 	},
 	{
-		command: "pagegraph links verify https://example.com --json | jq",
-		description: "One versioned JSON report on stdout"
+		command: "pagegraph links verify https://example.com --assert-coverage",
+		description: "Crawl and assert coverage against the served anchors in one pass"
 	},
 	{
 		command: "pagegraph links verify http://localhost:3000 --allow-private",
 		description: "Verify a local app"
 	}
 ]), withHandler(fn("SeoCli.linksVerify")(function* (options) {
-	const checkedLimit = yield* positive("limit", options.limit);
-	const checkedTimeout = yield* positive("request-timeout-ms", options.requestTimeoutMs);
-	const checkedMaxBody = yield* positive("max-body-bytes", options.maxBodyBytes);
-	const crawl = yield* tryPromise({
-		try: () => crawlRenderedPages(options.url, {
-			limit: checkedLimit,
-			timeoutMs: checkedTimeout,
-			maxBodyBytes: checkedMaxBody,
-			allowPrivate: options.allowPrivate
-		}),
-		catch: (cause) => new SeoCliError({ message: `Could not crawl ${options.url}: ${messageOf(cause)}` })
-	});
-	if (crawl.pages.length === 0) {
-		const reason = crawl.failures[0]?.error ?? "no pages fetched";
-		return yield* new SeoCliError({ message: `No page could be crawled at ${options.url}: ${reason}` });
-	}
-	const graph = buildRenderedGraph(crawl.origin, crawl.pages, crawl.root);
+	const emitPath = getOrUndefined$1(options.emitRendered);
+	const artifactPath = getOrUndefined$1(options.rendered);
+	const url = getOrUndefined$1(options.url);
+	if (emitPath !== void 0 && artifactPath !== void 0) return yield* new SeoCliError({ message: "--emit-rendered writes a fresh crawl; --rendered replays one. Use one or the other." });
+	if (url === void 0 && artifactPath === void 0) return yield* new SeoCliError({ message: "Provide a homepage URL to crawl, or --rendered <path> to replay a saved crawl." });
 	const warnings = [];
-	if (crawl.truncatedBodies.length > 0) warnings.push(`${crawl.truncatedBodies.length} page body/bodies exceeded --max-body-bytes; anchors past the cutoff are missing.`);
-	const declared = yield* loadDeclaredGraph;
-	let declaredEdges;
-	if (declared.kind === "warning") warnings.push(declared.message);
-	if (declared.kind === "loaded") if (declared.graph.origin === crawl.origin) declaredEdges = declared.graph.edges;
-	else warnings.push(`Declared graph origin ${declared.graph.origin} differs from crawled origin ${crawl.origin}; skipping the declared-vs-rendered diff.`);
-	const diff = declaredEdges === void 0 ? void 0 : diffLinkGraph(declaredEdges, graph);
-	const report = {
-		kind: "links-verify",
-		schemaVersion: 1,
-		origin: crawl.origin,
-		seed: crawl.seed,
-		crawl: {
+	let origin;
+	let seed;
+	let graph;
+	let renderedEdges;
+	let crawlReport;
+	if (artifactPath !== void 0) {
+		const artifact = yield* readRenderedArtifact(artifactPath);
+		if (url !== void 0) {
+			let requestedOrigin;
+			try {
+				requestedOrigin = new URL(url).origin;
+			} catch {
+				return yield* new SeoCliError({ message: `Not a valid URL: ${url}` });
+			}
+			if (requestedOrigin !== new URL(artifact.origin).origin) return yield* new SeoCliError({ message: `--rendered artifact origin ${artifact.origin} does not match ${url}.` });
+		}
+		origin = artifact.origin;
+		seed = artifact.seed;
+		graph = renderedGraphFromEdges(artifact.edges, artifact.crawl.root, artifact.nodes);
+		renderedEdges = artifact.edges;
+		crawlReport = {
+			pages: artifact.crawl.pages,
+			limit: artifact.crawl.limit,
+			truncated: artifact.crawl.truncated,
+			failures: artifact.crawl.failures,
+			bodyTruncated: artifact.crawl.bodyTruncated,
+			truncatedPages: artifact.crawl.truncatedPages
+		};
+	} else {
+		const checkedLimit = yield* positive("limit", options.limit);
+		const checkedTimeout = yield* positive("request-timeout-ms", options.requestTimeoutMs);
+		const checkedMaxBody = yield* positive("max-body-bytes", options.maxBodyBytes);
+		const crawl = yield* tryPromise({
+			try: () => crawlRenderedPages(url, {
+				limit: checkedLimit,
+				timeoutMs: checkedTimeout,
+				maxBodyBytes: checkedMaxBody,
+				allowPrivate: options.allowPrivate
+			}),
+			catch: (cause) => new SeoCliError({ message: `Could not crawl ${url}: ${messageOf(cause)}` })
+		});
+		if (crawl.pages.length === 0) return yield* new SeoCliError({ message: `No page could be crawled at ${url}: ${crawl.failures[0]?.error ?? "no pages fetched"}` });
+		graph = buildRenderedGraph(crawl.origin, crawl.pages, crawl.root);
+		renderedEdges = graph.internalEdges;
+		origin = crawl.origin;
+		seed = crawl.seed;
+		crawlReport = {
 			pages: crawl.pages.length,
 			limit: crawl.limit,
 			truncated: crawl.truncated,
 			failures: crawl.failures,
 			bodyTruncated: crawl.truncatedBodies.length > 0,
 			truncatedPages: crawl.truncatedBodies
-		},
+		};
+		if (emitPath !== void 0) {
+			const artifact = {
+				kind: "links-rendered",
+				schemaVersion: 1,
+				origin: crawl.origin,
+				seed: crawl.seed,
+				crawl: {
+					pages: crawl.pages.length,
+					root: crawl.root,
+					limit: crawl.limit,
+					truncated: crawl.truncated,
+					bodyTruncated: crawl.truncatedBodies.length > 0,
+					truncatedPages: crawl.truncatedBodies,
+					failures: crawl.failures
+				},
+				nodes: graph.nodes,
+				edges: graph.internalEdges
+			};
+			yield* writeRenderedArtifact(emitPath, artifact);
+			yield* logInfo(`Wrote rendered edges to ${emitPath}`);
+		}
+	}
+	if (crawlReport.truncatedPages.length > 0) warnings.push(`${crawlReport.truncatedPages.length} page body/bodies exceeded --max-body-bytes; anchors past the cutoff are missing.`);
+	const analysis = yield* analyzeDeclared(origin, renderedEdges, options.assertCoverage, {
+		truncated: crawlReport.truncated,
+		bodyTruncated: crawlReport.bodyTruncated,
+		failures: crawlReport.failures.length
+	});
+	warnings.push(...analysis.warnings);
+	const diff = analysis.declaredEdges === void 0 ? void 0 : diffLinkGraph(analysis.declaredEdges, graph);
+	const coverage = analysis.coverage === void 0 ? void 0 : {
+		rules: analysis.coverage.rules,
+		ok: analysis.coverage.violations.length === 0,
+		violations: analysis.coverage.violations
+	};
+	const report = {
+		kind: "links-verify",
+		schemaVersion: 1,
+		origin,
+		seed,
+		crawl: crawlReport,
 		rendered: {
-			pages: crawl.pages.length,
+			pages: crawlReport.pages,
 			internalEdges: graph.internalEdges.length,
 			contextualEdges: graph.contextualEdges.length,
 			maxDepth: graph.maxDepth,
@@ -41646,15 +43010,18 @@ const linksVerifyCommand = make$9("verify", {
 			declaredNotRendered: diff.declaredNotRendered,
 			renderedNotDeclared: diff.renderedNotDeclared
 		},
+		...coverage === void 0 ? {} : { coverage },
 		warnings
 	};
 	if (options.json) yield* printJson(report);
 	else yield* printText(renderLinksReport(report));
+	if (coverage !== void 0 && !coverage.ok) return yield* new SeoCliError({ message: `${coverage.violations.length} rendered coverage violation(s) — the served anchors do not satisfy seo.config.ts.` });
 })));
 const decideFile = String$1("file").pipe(withDescription("JSON file with an array of link candidates (default: stdin)"), optional);
 const thresholdFlag = Finite("threshold").pipe(withDescription$2("Probability above which an answer is confident; below is review (0.5 < t < 1)"), withDefault(DEFAULT_LINK_THRESHOLD));
 const modelFlag = String$2("model").pipe(withDescription$2("TypeSafe System One model identifier"), withDefault("jev-latest"));
 const concurrencyFlag = Int("concurrency").pipe(withDescription$2("Maximum concurrent decision calls"), withDefault(4));
+const budgetFlag = Int("budget").pipe(withDescription$2("Keep only the top-K candidates per source by relevance"), withDefault(4));
 const checkThreshold = (value) => Number.isFinite(value) && value > .5 && value < 1 ? succeed$2(value) : fail$3(new SeoCliError({ message: "--threshold must be greater than 0.5 and less than 1 (a review band needs 1 - t < t)" }));
 /** Read the candidate JSON from a file argument or stdin; a TTY with no file is an error. */
 const readCandidatesText = (file) => try_({
@@ -41678,8 +43045,9 @@ const linksDecideCommand = make$9("decide", {
 	json: jsonFlag,
 	threshold: thresholdFlag,
 	model: modelFlag,
-	concurrency: concurrencyFlag
-}).pipe(withDescription$1("Answer real-reason and anchor-present decisions for candidate links; below-threshold candidates go to review"), withExamples([
+	concurrency: concurrencyFlag,
+	budget: budgetFlag
+}).pipe(withDescription$1("Answer real-reason, anchor-present, direction, and relevance for candidate links; below-threshold candidates go to review"), withExamples([
 	{
 		command: "pagegraph links decide candidates.json",
 		description: "Decide a candidate set and print the reviewable plan"
@@ -41695,13 +43063,15 @@ const linksDecideCommand = make$9("decide", {
 ]), withHandler(fn("SeoCli.linksDecide")(function* (options) {
 	const threshold = yield* checkThreshold(options.threshold);
 	const concurrency = yield* positive("concurrency", options.concurrency);
+	const budget = yield* positive("budget", options.budget);
 	const text = yield* readCandidatesText(getOrUndefined$1(options.file));
 	const candidates = yield* parseCandidates(text);
 	if (process.env.TYPESAFE_API_KEY === void 0 || process.env.TYPESAFE_API_KEY === "") return yield* new SeoCliError({ message: "TYPESAFE_API_KEY is not set; `pagegraph links decide` answers through TypeSafe System One." });
 	const report = yield* decideLinks(candidates, {
 		model: options.model,
 		threshold,
-		concurrency
+		concurrency,
+		budget
 	}).pipe(provide(typeSafeDecisionModel(options.model)), mapError(decisionErrorMessage));
 	if (options.json) yield* printJson(report);
 	else yield* printText(renderLinksDecideReport(report));
@@ -41864,6 +43234,7 @@ const cli = make$9("pagegraph").pipe(withDescription$1("Inspect and audit a TanS
 	}
 ]), withSubcommands([
 	auditCommand,
+	decideCommandGroup,
 	diffCommand,
 	graphCommand,
 	inspectCommand,