pagegraph 0.8.3 → 0.9.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import * as NFS from "node:fs";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import * as NodeChildProcess from "node:child_process";
 import { execFileSync, spawn } from "node:child_process";
 import { PassThrough } from "node:stream";
@@ -9,7 +9,7 @@ import { createHash, randomUUID } from "node:crypto";
 import * as OS from "node:os";
 import { tmpdir } from "node:os";
 import * as Path from "node:path";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import * as NodeUrl from "node:url";
 import { pathToFileURL } from "node:url";
 import * as readline from "node:readline";
@@ -35710,7 +35710,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.8.3";
+var version = "0.9.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;");
@@ -36166,12 +36166,13 @@ const findConfigFile = (from) => {
 const isStringArray = (value) => Array.isArray(value) && value.every(isString);
 const isCoverageRules = (value) => Array.isArray(value) && value.every((rule) => isObject$1(rule) && isString(rule["path"]) && Number.isSafeInteger(rule["minInbound"]) && rule["minInbound"] > 0);
 const isStringRecord = (value) => isObject$1(value) && Object.values(value).every(isString);
+const isWorkflowTimeout = (value) => Number.isSafeInteger(value) && value > 0 && value <= 2147483647;
 const isStringArrayRecord = (value) => isObject$1(value) && Object.values(value).every(isStringArray);
 const isWorkflowConfig = (value) => {
 	if (!isObject$1(value) || !isObject$1(value["opencode"])) return false;
 	const opencode = value["opencode"];
 	const context = value["context"];
-	return isString(opencode["configDirectory"]) && isString(opencode["defaultModel"]) && (opencode["models"] === void 0 || isStringRecord(opencode["models"])) && (context === void 0 || isObject$1(context) && (context["files"] === void 0 || isStringArray(context["files"])) && (context["byWorkflow"] === void 0 || isStringArrayRecord(context["byWorkflow"]))) && (value["runsDirectory"] === void 0 || isString(value["runsDirectory"]));
+	return isString(opencode["configDirectory"]) && isString(opencode["defaultModel"]) && (opencode["models"] === void 0 || isStringRecord(opencode["models"])) && (opencode["timeoutMs"] === void 0 || isWorkflowTimeout(opencode["timeoutMs"])) && (context === void 0 || isObject$1(context) && (context["files"] === void 0 || isStringArray(context["files"])) && (context["byWorkflow"] === void 0 || isStringArrayRecord(context["byWorkflow"]))) && (value["runsDirectory"] === void 0 || isString(value["runsDirectory"]));
 };
 /**
 * `seo.config.ts` is the consumer's file and may be plain JS, so its types are
@@ -37524,6 +37525,15 @@ const decodeRenderedEdgeArtifact = (input) => {
 	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");
+	const skipped = provenance["skipped"];
+	if (skipped !== void 0 && (!Array.isArray(skipped) || !skipped.every((url) => typeof url === "string"))) throw new Error("rendered-edge artifact `crawl.skipped` must be an array of URLs");
+	const nonHtml = provenance["nonHtml"];
+	if (nonHtml !== void 0 && (!Array.isArray(nonHtml) || !nonHtml.every((item) => item !== null && typeof item === "object" && typeof item.url === "string" && typeof item.finalUrl === "string" && typeof item.contentType === "string"))) throw new Error("rendered-edge artifact `crawl.nonHtml` must be an array of { url, finalUrl, contentType }");
+	if (Array.isArray(nonHtml)) for (const item of nonHtml) {
+		requiredAbsoluteUrl(item.url, "crawl.nonHtml.url");
+		requiredAbsoluteUrl(item.finalUrl, "crawl.nonHtml.finalUrl");
+	}
+	for (const field of ["sitemapTruncated", "sitemapUsed"]) if (provenance[field] !== void 0 && typeof provenance[field] !== "boolean") throw new Error(`rendered-edge artifact \`crawl.${field}\` must be a boolean`);
 	return {
 		kind: ARTIFACT_KIND,
 		schemaVersion: 1,
@@ -37536,7 +37546,12 @@ const decodeRenderedEdgeArtifact = (input) => {
 			truncated: provenance["truncated"],
 			bodyTruncated: bodyTruncated === true,
 			truncatedPages: truncatedPages ?? [],
-			failures: decodeArtifactFailures(provenance["failures"])
+			failures: decodeArtifactFailures(provenance["failures"]),
+			...nonHtml === void 0 ? {} : { nonHtml },
+			...provenance["discoveryFailures"] === void 0 ? {} : { discoveryFailures: decodeArtifactFailures(provenance["discoveryFailures"]) },
+			...skipped === void 0 ? {} : { skipped },
+			...provenance["sitemapTruncated"] === void 0 ? {} : { sitemapTruncated: provenance["sitemapTruncated"] },
+			...provenance["sitemapUsed"] === void 0 ? {} : { sitemapUsed: provenance["sitemapUsed"] }
 		},
 		nodes: decodeArtifactNodes(value["nodes"]),
 		edges: decodeArtifactEdges(value["edges"])
@@ -37751,7 +37766,7 @@ const canonicalUrl = (html) => {
 };
 const countMatches = (value, pattern) => [...value.matchAll(pattern)].length;
 const extractDocumentSignals = (body, contentType, requestedUrl) => {
-	const isHtml = contentType.includes("text/html");
+	const isHtml = contentType.includes("text/html") || contentType.includes("application/xhtml+xml");
 	const isMarkdown = contentType.includes("text/markdown");
 	const looksJson = contentType.includes("json") || requestedUrl.pathname.endsWith(".json");
 	const titleMatch = isHtml ? /<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(body) : null;
@@ -37846,6 +37861,8 @@ const probeHttp = async (request, options) => {
 		let currentUrl = request.url;
 		let response = null;
 		for (let redirectCount = 0; redirectCount <= 10; redirectCount += 1) {
+			if (options.sameOrigin !== void 0 && currentUrl.origin !== options.sameOrigin) throw new Error(`Redirected off-origin to ${currentUrl.href}`);
+			if (options.allowUrl !== void 0 && !options.allowUrl(currentUrl)) throw new Error(`Redirected to robots-disallowed URL ${currentUrl.href}`);
 			response = await requestPinned(currentUrl, request, options);
 			headersAt = performance.now();
 			const location = response.headers.location;
@@ -37863,7 +37880,7 @@ const probeHttp = async (request, options) => {
 		} : await readBoundedBody(response, options.maxBodyBytes);
 		const contentType = typeof response.headers["content-type"] === "string" ? response.headers["content-type"] : "";
 		const body = new TextDecoder().decode(bounded.bytes);
-		const anchors = options.captureAnchors === true && contentType.includes("text/html") ? extractAnchors(body, currentUrl.href) : void 0;
+		const anchors = options.captureAnchors === true && (contentType === "" || /text\/html|application\/xhtml\+xml/i.test(contentType)) ? extractAnchors(body, currentUrl.href) : void 0;
 		return {
 			kind: request.kind,
 			method: request.method,
@@ -37880,6 +37897,7 @@ const probeHttp = async (request, options) => {
 			capturedBodySha256: bounded.bytes.byteLength === 0 ? null : createHash("sha256").update(bounded.bytes).digest("hex"),
 			bodyTruncated: bounded.truncated,
 			bodyExcerpt: bodyExcerpt(body, contentType),
+			...options.captureBody === true ? { body } : {},
 			document: body.length === 0 ? null : extractDocumentSignals(body, contentType, currentUrl),
 			anchors,
 			error: null
@@ -37901,6 +37919,7 @@ const probeHttp = async (request, options) => {
 			capturedBodySha256: null,
 			bodyTruncated: false,
 			bodyExcerpt: null,
+			...options.captureBody === true ? { body: void 0 } : {},
 			document: null,
 			error: errorMessage$2(error)
 		};
@@ -42011,6 +42030,845 @@ const layer = /*#__PURE__*/ layerMergedContext(/*#__PURE__*/ succeed$2(/* @__PUR
 	return send(void 0);
 })));
 //#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;
+/** The graph keys pages by path, so dedupe crawled URLs the same way. */
+const pageKey = (url) => normalizePath(url);
+const XML_LOC = /<loc\b[^>]*>([\s\S]*?)<\/loc>/gi;
+const xmlText = (value) => value.trim().replace(/&(amp|lt|gt|quot|apos|#x[0-9a-f]+|#[0-9]+);/gi, (entity, code) => {
+	const named = {
+		amp: "&",
+		lt: "<",
+		gt: ">",
+		quot: "\"",
+		apos: "'"
+	};
+	if (named[code.toLowerCase()] !== void 0) return named[code.toLowerCase()];
+	const numeric = code.startsWith("#x") || code.startsWith("#X") ? Number.parseInt(code.slice(2), 16) : Number.parseInt(code.slice(1), 10);
+	if (!Number.isInteger(numeric) || numeric === 0 || numeric < 32 && numeric !== 9 && numeric !== 10 && numeric !== 13 || numeric >= 55296 && numeric <= 57343 || numeric > 1114111) throw new Error(`Invalid XML character reference: ${entity}`);
+	return String.fromCodePoint(numeric);
+});
+const robotsRules = (body) => {
+	const groups = [];
+	const sitemaps = [];
+	let group;
+	let hasDirective = false;
+	for (const raw of body.split(/\r?\n/)) {
+		const line = raw.replace(/\s+#.*$/, "").trim();
+		const match = /^([^:]+):\s*(.*)$/.exec(line);
+		if (!match) continue;
+		const name = match[1].trim().toLowerCase();
+		const value = match[2].trim();
+		if (name === "sitemap") {
+			sitemaps.push(value);
+			continue;
+		}
+		if (name === "user-agent") {
+			if (group === void 0 || hasDirective) {
+				group = {
+					agents: [],
+					rules: []
+				};
+				groups.push(group);
+				hasDirective = false;
+			}
+			group.agents.push(value.toLowerCase());
+			continue;
+		}
+		if (name === "allow" || name === "disallow") {
+			hasDirective = true;
+			if (group !== void 0 && value.startsWith("/")) group.rules.push({
+				path: value,
+				allow: name === "allow"
+			});
+		}
+	}
+	const score = (agent) => agent === "*" ? 0 : "pagegraph/0.4".startsWith(agent) ? agent.length : -1;
+	const best = Math.max(-1, ...groups.flatMap((entry) => entry.agents.map(score)));
+	return {
+		rules: groups.filter((entry) => best >= 0 && entry.agents.some((agent) => score(agent) === best)).flatMap((entry) => entry.rules),
+		sitemaps
+	};
+};
+const allowedByRobots = (path, rules) => {
+	let chosen;
+	let bestLength = -1;
+	for (const rule of rules) {
+		const anchored = rule.path.endsWith("$");
+		const parts = (anchored ? rule.path.slice(0, -1) : rule.path).split("*");
+		if (!path.startsWith(parts[0])) continue;
+		let offset = parts[0].length;
+		let matches = true;
+		for (let at = 1; at < parts.length; at++) {
+			const part = parts[at];
+			const found = path.indexOf(part, offset);
+			if (found < 0) {
+				matches = false;
+				break;
+			}
+			offset = found + part.length;
+		}
+		if (!matches || anchored && (parts.length === 1 ? path !== parts[0] : !path.endsWith(parts.at(-1)))) continue;
+		const length = rule.path.replace(/[\*$]/g, "").length;
+		if (length > bestLength || length === bestLength && rule.allow) {
+			chosen = rule;
+			bestLength = length;
+		}
+	}
+	return chosen?.allow ?? true;
+};
+/** Run `run` over `items` with at most `limit` in flight, preserving order. */
+const mapLimit = async (items, limit, run) => {
+	const results = Array.from({ length: items.length });
+	let index = 0;
+	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		for (;;) {
+			const current = index++;
+			if (current >= items.length) return;
+			results[current] = await run(items[current]);
+		}
+	});
+	await Promise.all(workers);
+	return results.map((result, at) => {
+		if (result === void 0) throw new Error(`Crawl worker ${at} produced no result`);
+		return result;
+	});
+};
+/**
+* Crawl `seed`'s origin breadth-first and return one {@link RenderedPage} per
+* successfully fetched HTML page. The seed must be an absolute `http(s)` URL;
+* private and reserved destinations are rejected unless `allowPrivate` is set.
+*/
+const crawlRenderedPages = async (seed, options) => {
+	let seedUrl;
+	try {
+		seedUrl = new URL(seed);
+	} catch {
+		throw new Error(`Not a valid URL: ${seed}`);
+	}
+	if (seedUrl.protocol !== "https:" && seedUrl.protocol !== "http:") throw new Error(`Unsupported URL protocol: ${seedUrl.protocol}`);
+	if (!Number.isSafeInteger(options.limit) || options.limit < 1) throw new Error(`Crawl limit must be a positive integer: ${options.limit}`);
+	const origin = seedUrl.origin;
+	const probeOptions = {
+		allowPrivate: options.allowPrivate,
+		timeoutMs: options.timeoutMs,
+		maxBodyBytes: options.maxBodyBytes,
+		captureAnchors: true,
+		sameOrigin: origin
+	};
+	const concurrency = Math.max(1, options.concurrency ?? 4);
+	const visited = /* @__PURE__ */ new Set([pageKey(seedUrl)]);
+	/** Final paths already rendered, so a redirect cannot add the same page twice. */
+	const rendered = /* @__PURE__ */ new Set();
+	const canonicalByPath = /* @__PURE__ */ new Map();
+	const pages = [];
+	const failures = [];
+	const nonHtml = [];
+	const truncatedBodies = [];
+	const discoveryFailures = [];
+	const skipped = [];
+	let sitemapTruncated = false;
+	let sitemapUsed = false;
+	let attempts = 0;
+	let truncated = false;
+	let root = pageKey(seedUrl);
+	let frontier = [{
+		url: seedUrl,
+		depth: 0
+	}];
+	const discoveryProbe = async (url, kind, allowUrl) => probeHttp({
+		kind,
+		method: "GET",
+		accept: "text/plain, application/xml, text/xml",
+		url
+	}, {
+		...probeOptions,
+		captureAnchors: false,
+		captureBody: true,
+		allowUrl
+	});
+	const robots = await discoveryProbe(new URL("/robots.txt", origin), "robots");
+	if (!robots.ok && robots.status !== 404) discoveryFailures.push({
+		url: new URL("/robots.txt", origin).href,
+		error: robots.error ?? `HTTP ${robots.status}`
+	});
+	if (robots.bodyTruncated) discoveryFailures.push({
+		url: robots.requestedUrl,
+		error: "robots.txt body truncated"
+	});
+	const policy = robots.ok && !robots.bodyTruncated ? robotsRules(robots.body ?? "") : {
+		rules: [],
+		sitemaps: []
+	};
+	const permitted = (url) => {
+		if (allowedByRobots(`${url.pathname}${url.search}`, policy.rules)) return true;
+		skipped.push(url.href);
+		return false;
+	};
+	const sitemapUrls = [];
+	const sitemapQueue = (policy.sitemaps.length > 0 ? policy.sitemaps : [new URL("/sitemap.xml", origin).href]).flatMap((entry) => {
+		try {
+			return [new URL(entry, origin)];
+		} catch {
+			return [];
+		}
+	});
+	const seenSitemaps = /* @__PURE__ */ new Set();
+	const seenSitemapPages = /* @__PURE__ */ new Set();
+	while (sitemapQueue.length > 0) {
+		const url = sitemapQueue.shift();
+		if (url.origin !== origin) {
+			discoveryFailures.push({
+				url: url.href,
+				error: "Advertised sitemap is off-origin and was not fetched"
+			});
+			continue;
+		}
+		if (seenSitemaps.has(url.href) || !permitted(url)) continue;
+		if (seenSitemaps.size >= Math.max(1, Math.min(options.limit, 16))) {
+			sitemapTruncated = true;
+			break;
+		}
+		seenSitemaps.add(url.href);
+		const probe = await discoveryProbe(url, "sitemap", permitted);
+		if (!probe.ok) {
+			if (probe.status !== 404 || policy.sitemaps.length > 0) discoveryFailures.push({
+				url: url.href,
+				error: probe.error ?? `HTTP ${probe.status}`
+			});
+			continue;
+		}
+		const body = probe.body ?? "";
+		if (probe.bodyTruncated || !/<(?:urlset|sitemapindex)\b/i.test(body)) {
+			discoveryFailures.push({
+				url: url.href,
+				error: probe.bodyTruncated ? "sitemap body truncated" : "malformed sitemap"
+			});
+			continue;
+		}
+		const index = /<sitemapindex\b/i.test(body);
+		const entries = [...body.matchAll(index ? /<sitemap\b[^>]*>([\s\S]*?)<\/sitemap>/gi : /<url\b[^>]*>([\s\S]*?)<\/url>/gi)];
+		for (const entry of entries) {
+			XML_LOC.lastIndex = 0;
+			const loc = XML_LOC.exec(entry[1] ?? "")?.[1];
+			if (loc === void 0) continue;
+			let target;
+			try {
+				if (/&(?!(?:amp|lt|gt|quot|apos|#x[0-9a-f]+|#[0-9]+);)[^;\s]+;/i.test(loc)) throw new Error("unsupported XML entity");
+				const decoded = xmlText(loc);
+				target = new URL(decoded, url);
+			} catch {
+				discoveryFailures.push({
+					url: url.href,
+					error: `Invalid sitemap <loc>: ${loc.slice(0, 120)}`
+				});
+				continue;
+			}
+			if (index) {
+				sitemapQueue.push(target);
+				continue;
+			}
+			if (target.origin !== origin || !permitted(target)) continue;
+			if (NON_PAGE.test(target.pathname)) continue;
+			const key = pageKey(target);
+			if (seenSitemapPages.has(key)) continue;
+			if (seenSitemapPages.size >= options.limit * 4) {
+				sitemapTruncated = true;
+				break;
+			}
+			seenSitemapPages.add(key);
+			sitemapUrls.push(target);
+		}
+		if (sitemapTruncated) break;
+	}
+	sitemapUsed = sitemapUrls.length > 0;
+	const sitemapListed = new Set(sitemapUrls.map(pageKey));
+	if (!permitted(seedUrl)) frontier = [];
+	const probePage = async (item) => {
+		const request = {
+			kind: "page-html",
+			method: "GET",
+			accept: "text/html, */*;q=0.1",
+			url: item.url
+		};
+		const probe = await probeHttp(request, {
+			...probeOptions,
+			allowUrl: permitted
+		});
+		if (!probe.ok || probe.finalUrl === null) return {
+			item,
+			page: null,
+			failure: {
+				url: item.url.href,
+				error: probe.error ?? `HTTP ${probe.status ?? "no response"}`
+			},
+			links: [],
+			bodyTruncated: false,
+			canonical: null
+		};
+		if (probe.responseHeaders["content-type"] !== void 0 && !/text\/html|application\/xhtml\+xml/i.test(probe.responseHeaders["content-type"])) {
+			const expectedHtml = item.depth === 0 || sitemapListed.has(pageKey(item.url)) || sitemapListed.has(pageKey(new URL(probe.finalUrl)));
+			return {
+				item,
+				page: null,
+				failure: expectedHtml ? {
+					url: item.url.href,
+					error: "Response is not HTML"
+				} : null,
+				...expectedHtml ? {} : { nonHtml: {
+					url: item.url.href,
+					finalUrl: probe.finalUrl,
+					contentType: probe.responseHeaders["content-type"]
+				} },
+				links: [],
+				bodyTruncated: false,
+				canonical: null
+			};
+		}
+		if (new URL(probe.finalUrl).origin !== origin) return {
+			item,
+			page: null,
+			failure: {
+				url: item.url.href,
+				error: `Redirected off-origin to ${probe.finalUrl}`
+			},
+			links: [],
+			bodyTruncated: false,
+			canonical: null
+		};
+		const anchors = probe.anchors ?? [];
+		const links = anchors.flatMap((anchor) => {
+			if (!anchor.internal) return [];
+			let target;
+			try {
+				target = new URL(anchor.href);
+			} catch {
+				return [];
+			}
+			if (target.origin !== origin) return [];
+			if (NON_PAGE.test(target.pathname)) return [];
+			return [target];
+		});
+		return {
+			item,
+			page: {
+				url: probe.finalUrl,
+				anchors
+			},
+			failure: null,
+			links,
+			bodyTruncated: probe.bodyTruncated,
+			canonical: probe.document?.canonicalUrl ?? null
+		};
+	};
+	while (frontier.length > 0) {
+		const remaining = options.limit - attempts;
+		if (remaining <= 0) {
+			truncated = true;
+			break;
+		}
+		const batch = frontier.length > remaining ? frontier.slice(0, remaining) : frontier;
+		if (frontier.length > batch.length) truncated = true;
+		frontier = [];
+		attempts += batch.length;
+		const probed = await mapLimit(batch, concurrency, probePage);
+		const discovered = [];
+		for (const result of probed) {
+			if (result.failure !== null) failures.push(result.failure);
+			if (result.nonHtml !== void 0) nonHtml.push(result.nonHtml);
+			if (result.page === null) continue;
+			const page = result.page;
+			const finalKey = pageKey(new URL(page.url));
+			if (result.canonical !== null) try {
+				const canonical = new URL(result.canonical, page.url);
+				if (canonical.origin === origin && pageKey(canonical) !== finalKey) canonicalByPath.set(finalKey, pageKey(canonical));
+			} catch {}
+			if (result.item.depth === 0) root = finalKey;
+			if (rendered.has(finalKey)) continue;
+			rendered.add(finalKey);
+			visited.add(finalKey);
+			pages.push(page);
+			if (result.bodyTruncated) truncatedBodies.push(page.url);
+			for (const link of result.links) {
+				if (!permitted(link)) continue;
+				const key = pageKey(link);
+				if (visited.has(key)) continue;
+				visited.add(key);
+				discovered.push({
+					url: link,
+					depth: result.item.depth + 1
+				});
+			}
+		}
+		if (attempts === 1) for (const url of sitemapUrls) {
+			const key = pageKey(url);
+			if (visited.has(key) || !permitted(url)) continue;
+			visited.add(key);
+			discovered.push({
+				url,
+				depth: 1
+			});
+		}
+		frontier = discovered;
+	}
+	const renderedByPath = new Map(pages.map((page) => [pageKey(new URL(page.url)), page]));
+	const retainedPages = pages.filter((page) => {
+		const canonical = canonicalByPath.get(pageKey(new URL(page.url)));
+		const canonicalPage = canonical === void 0 ? void 0 : renderedByPath.get(canonical);
+		return canonicalPage === void 0 || JSON.stringify(page.anchors) !== JSON.stringify(canonicalPage.anchors);
+	});
+	const canonicalRoot = canonicalByPath.get(root);
+	if (canonicalRoot !== void 0 && !retainedPages.some((page) => pageKey(new URL(page.url)) === root)) root = canonicalRoot;
+	return {
+		origin,
+		seed: seedUrl.href,
+		root,
+		pages: retainedPages,
+		failures,
+		nonHtml,
+		truncatedBodies,
+		truncated,
+		discoveryFailures,
+		skipped: [...new Set(skipped)],
+		sitemapTruncated,
+		sitemapUsed,
+		limit: options.limit
+	};
+};
+//#endregion
+//#region src/core/link-candidates.ts
+/**
+* Canonical path key: query and hash stripped, trailing slashes removed, "/"
+* preserved. This is the same path key the graph and the rendered-link core
+* use, so a served anchor like `/blog/a?ref=nav` still matches the graph pair
+* `/blog/a`.
+*/
+const normalize = (path) => {
+	const trimmed = (path.split(/[?#]/, 1)[0] ?? "").replace(/\/+$/, "");
+	return trimmed === "" ? "/" : trimmed;
+};
+const directedEdgeKey = (from, to) => `${normalize(from)}\u0000${normalize(to)}`;
+/** First path segment, or undefined for the root page. */
+const topSegment = (path) => {
+	const segment = path.split("/").filter(Boolean)[0];
+	return segment === void 0 || segment === "" ? void 0 : segment;
+};
+/** A page with no nested segment (`/`, `/pricing`, `/blog`) is root-level. */
+const isRootLevel = (path) => path.split("/").filter(Boolean).length <= 1;
+/**
+* The cluster a pair shares, or undefined when they share none. Section-first:
+* a shared top-level section wins. The kind fallback is local to root-level
+* pages, so it never pairs two nested pages from different sections.
+*/
+const candidateClusterOf = (a, b) => {
+	const aSegment = topSegment(a.path);
+	const bSegment = topSegment(b.path);
+	if (aSegment !== void 0 && aSegment === bSegment) return {
+		key: aSegment,
+		reason: `same top-level section "/${aSegment}"`
+	};
+	if (isRootLevel(a.path) && isRootLevel(b.path) && a.kind === b.kind) return {
+		key: `kind:${a.kind}`,
+		reason: `same kind "${a.kind}"`
+	};
+};
+/** A `--cluster` filter matches a section by name, or a kind via its bare label. */
+const matchesClusterFilter = (cluster, filter) => {
+	const normalized = filter.replace(/^\/+/, "").toLowerCase();
+	const key = cluster.toLowerCase();
+	return key === normalized || key === `kind:${normalized}`;
+};
+/**
+* Enumerate reviewable contextual-link candidates from the declared graph.
+*
+* Excluded: self-pairs, pages that are not sitemap-eligible, pairs already
+* declared as a `related` edge, and — when {@link LinkCandidateOptions.renderedEdges}
+* is supplied — pairs already rendered as an anchor. Queries, hashes, and
+* trailing slashes are normalized so both sides compare by the graph's path key.
+*/
+const generateLinkCandidates = (graph, options = {}) => {
+	const limit = options.limit ?? 50;
+	const filters = options.clusters ?? [];
+	const rendered = new Set((options.renderedEdges ?? []).filter((edge) => edge.region === void 0 || edge.region === "body").map((edge) => directedEdgeKey(edge.from, edge.to)));
+	const declared = new Set(graph.edges.filter((edge) => edge.type === "related").map((edge) => directedEdgeKey(edge.from, edge.to)));
+	const eligible = [...graph.nodes.values()].filter(isSitemapEligible);
+	const all = [];
+	for (let i = 0; i < eligible.length; i++) for (let j = i + 1; j < eligible.length; j++) {
+		const a = eligible[i];
+		const b = eligible[j];
+		const cluster = candidateClusterOf(a, b);
+		if (cluster === void 0) continue;
+		if (filters.length > 0 && !filters.some((filter) => matchesClusterFilter(cluster.key, filter))) continue;
+		for (const [source, destination] of [[a.path, b.path], [b.path, a.path]]) {
+			const key = directedEdgeKey(source, destination);
+			if (declared.has(key) || rendered.has(key)) continue;
+			all.push({
+				source,
+				destination,
+				cluster: cluster.key,
+				reason: cluster.reason
+			});
+		}
+	}
+	const compare = (x, y) => x.cluster < y.cluster ? -1 : x.cluster > y.cluster ? 1 : x.source < y.source ? -1 : x.source > y.source ? 1 : x.destination < y.destination ? -1 : x.destination > y.destination ? 1 : 0;
+	all.sort(compare);
+	const counts = /* @__PURE__ */ new Map();
+	for (const pair of all) counts.set(pair.cluster, (counts.get(pair.cluster) ?? 0) + 1);
+	const candidates = all.slice(0, limit);
+	return {
+		candidates,
+		total: all.length,
+		truncated: all.length > candidates.length,
+		clusters: [...counts.entries()].map(([key, count]) => ({
+			key,
+			candidates: count
+		}))
+	};
+};
+/**
+* Decode a rendered-edge dump supplied to the CLI: either a bare array of
+* `{ from, to }` edges, or an object carrying `edges` (or `internalEdges`).
+* Throws on any other shape — this is user input, not a provider payload.
+*/
+const decodeRenderedEdges = (input) => {
+	const array = Array.isArray(input) ? input : input !== null && typeof input === "object" && Array.isArray(input.edges) ? input.edges : input !== null && typeof input === "object" && Array.isArray(input.internalEdges) ? input.internalEdges : void 0;
+	if (array === void 0) throw new Error("expected an array of { from, to } edges, or an object with an `edges` array");
+	return array.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each rendered 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 rendered edge must have string `from` and `to`");
+		if (region !== void 0 && ![
+			"nav",
+			"header",
+			"footer",
+			"body"
+		].includes(region)) throw new Error("rendered edge region must be nav, header, footer, or body");
+		return region === void 0 ? {
+			from,
+			to
+		} : {
+			from,
+			to,
+			region
+		};
+	});
+};
+//#endregion
+//#region src/core/link-suggestions.ts
+/** Select pages around low-inbound directions without materializing the full pair universe. */
+const selectSuggestionPages = (graph, options) => {
+	const eligible = [...graph.nodes.values()].filter(isSitemapEligible).sort((a, b) => a.path.localeCompare(b.path));
+	const byPath = new Map(eligible.map((node) => [node.path, node]));
+	for (const path of [...options.targets, ...options.sources]) if (!byPath.has(path)) throw new Error(`Requested page is not a sitemap-eligible graph path: ${path}`);
+	const selected = /* @__PURE__ */ new Set([...options.targets, ...options.sources]);
+	if (selected.size > options.pageLimit || options.targets.size > 0 && options.sources.size === 0 && options.targets.size >= options.pageLimit) throw new Error("--page-limit must leave room for a candidate source beyond requested targets");
+	const normalized = (path) => path.split(/[?#]/, 1)[0].replace(/\/+$/, "") || "/";
+	const key = (source, destination) => `${normalized(source)}\u0000${normalized(destination)}`;
+	const excluded = /* @__PURE__ */ new Set([...graph.edges.filter((edge) => edge.type === "related").map((edge) => key(edge.from, edge.to)), ...options.renderedEdges.filter((edge) => edge.region === void 0 || edge.region === "body").map((edge) => key(edge.from, edge.to))]);
+	const inbound = /* @__PURE__ */ new Map();
+	for (const edge of graph.edges) if (edge.type === "related") inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1);
+	const sections = /* @__PURE__ */ new Map();
+	const rootKinds = /* @__PURE__ */ new Map();
+	for (const node of eligible) {
+		const segments = node.path.split("/").filter(Boolean);
+		const section = segments[0];
+		if (section) {
+			if (!sections.has(section)) sections.set(section, []);
+			sections.get(section).push(node);
+		}
+		if (segments.length <= 1) {
+			if (!rootKinds.has(node.kind)) rootKinds.set(node.kind, []);
+			rootKinds.get(node.kind).push(node);
+		}
+	}
+	const requestedSources = eligible.filter((node) => options.sources.has(node.path));
+	const requestedSections = /* @__PURE__ */ new Map();
+	const requestedRootKinds = /* @__PURE__ */ new Map();
+	const relevant = /* @__PURE__ */ new Map();
+	for (const source of requestedSources) {
+		const segments = source.path.split("/").filter(Boolean);
+		const section = segments[0];
+		if (section) {
+			if (!requestedSections.has(section)) requestedSections.set(section, []);
+			requestedSections.get(section).push(source);
+			for (const node of sections.get(section) ?? []) relevant.set(node.path, node);
+		}
+		if (segments.length <= 1) {
+			if (!requestedRootKinds.has(source.kind)) requestedRootKinds.set(source.kind, []);
+			requestedRootKinds.get(source.kind).push(source);
+			for (const node of rootKinds.get(source.kind) ?? []) relevant.set(node.path, node);
+		}
+	}
+	const relevantDestinations = options.sources.size === 0 ? eligible : [...relevant.values()];
+	const destinations = (options.targets.size === 0 ? relevantDestinations : relevantDestinations.filter((node) => options.targets.has(node.path))).sort((a, b) => (inbound.get(a.path) ?? 0) - (inbound.get(b.path) ?? 0) || a.path.localeCompare(b.path));
+	const directionBudget = Math.max(100, options.pageLimit * 100);
+	let examined = 0;
+	for (const destination of destinations) {
+		if (selected.size >= options.pageLimit || examined >= directionBudget) break;
+		const segments = destination.path.split("/").filter(Boolean);
+		const section = segments[0];
+		const sources = [...new Map([...section ? (options.sources.size > 0 ? requestedSections : sections).get(section) ?? [] : [], ...segments.length <= 1 ? (options.sources.size > 0 ? requestedRootKinds : rootKinds).get(destination.kind) ?? [] : []].map((node) => [node.path, node])).values()];
+		for (const source of sources) {
+			if (source.path === destination.path) continue;
+			if (++examined > directionBudget) break;
+			const cluster = candidateClusterOf(source, destination);
+			if (!cluster || options.clusters.length > 0 && !options.clusters.some((filter) => matchesClusterFilter(cluster.key, filter)) || excluded.has(key(source.path, destination.path))) continue;
+			const needed = Number(!selected.has(source.path)) + Number(!selected.has(destination.path));
+			if (selected.size + needed > options.pageLimit) continue;
+			selected.add(source.path);
+			selected.add(destination.path);
+			if (selected.size >= options.pageLimit) break;
+		}
+	}
+	return eligible.filter((node) => selected.has(node.path));
+};
+const decode = (text) => text.replace(/&nbsp;|&#160;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, "\"").replace(/&#39;|&apos;/gi, "'").replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)));
+/** Restrict placements to visible main/article copy, ignoring site chrome and scripts. */
+const extractPageSentences = (html) => {
+	const visibleHtml = html.replace(/<(script|style|noscript|svg|nav|header|footer|template)\b[^>]*>[\s\S]*?<\/\1>/gi, " ");
+	const containerHtml = visibleHtml.replace(/<(pre|code|table|dl)\b[^>]*>[\s\S]*?<\/\1>/gi, " ");
+	const container = /<main\b/i.test(containerHtml) ? "main" : "article";
+	if (!new RegExp(`<${container}\\b`, "i").test(containerHtml)) return [];
+	const suppressedTags = /* @__PURE__ */ new Set([
+		"script",
+		"style",
+		"noscript",
+		"svg",
+		"nav",
+		"header",
+		"footer",
+		"template",
+		"a",
+		"pre",
+		"code",
+		"table",
+		"dl",
+		"kbd",
+		"samp"
+	]);
+	const blockTags = /* @__PURE__ */ new Set([
+		"p",
+		"li",
+		"blockquote",
+		"section",
+		"div",
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"h6"
+	]);
+	const voidTags = /* @__PURE__ */ new Set([
+		"area",
+		"base",
+		"br",
+		"col",
+		"embed",
+		"hr",
+		"img",
+		"input",
+		"link",
+		"meta",
+		"param",
+		"source",
+		"track",
+		"wbr"
+	]);
+	const stack = [];
+	const blocks = [];
+	let current = "";
+	let inside = 0;
+	const flush = () => {
+		if (current.trim()) blocks.push(current);
+		current = "";
+	};
+	for (const token of visibleHtml.match(/<[^>]*>|[^<]+/g) ?? []) {
+		if (!token.startsWith("<")) {
+			if (inside > 0 && !stack.some((entry) => entry.suppressed)) current += token;
+			continue;
+		}
+		const tag = /^<\s*(\/?)\s*([a-z][\w:-]*)\b([^>]*)>/i.exec(token);
+		if (!tag) continue;
+		const name = tag[2].toLowerCase();
+		if (tag[1] === "/") {
+			if (name === container && inside > 0) inside--;
+			const at = stack.findLastIndex((entry) => entry.name === name);
+			if (blockTags.has(name) || suppressedTags.has(name) || name === container || at >= 0 && stack[at].suppressed) flush();
+			if (at >= 0) stack.splice(at);
+			continue;
+		}
+		const attrs = tag[3] ?? "";
+		const suppressed = /(?:^|\s)hidden(?:\s|=|$)/i.test(attrs) || /\baria-hidden\s*=\s*(?:"true"|'true'|true)(?:\s|$)/i.test(attrs) || /\bstyle\s*=\s*(?:"[^"]*(?:display\s*:\s*none|visibility\s*:\s*hidden)[^"]*"|'[^']*(?:display\s*:\s*none|visibility\s*:\s*hidden)[^']*')/i.test(attrs) || suppressedTags.has(name) || /\brole\s*=\s*(?:"(?:table|grid)"|'(?:table|grid)'|(?:table|grid))(?:\s|$)/i.test(attrs);
+		if (name === container) {
+			flush();
+			inside++;
+		}
+		if (suppressed || blockTags.has(name)) flush();
+		if (!voidTags.has(name) && !/\/\s*>$/.test(token)) stack.push({
+			name,
+			suppressed
+		});
+	}
+	flush();
+	return blocks.flatMap((block) => decode(block).replace(/\s+/g, " ").split(/(?<=[.!?])\s+/)).map((part) => part.trim()).filter((part) => part.length >= 30 && part.length <= 500 && !/;\s*(?:or|and)?$/i.test(part));
+};
+const stop = new Set("a an as at about after again also and are but by can for from had has have in into is it more most of on or our over that the their them there these this those through to was we were with your you what when where which while will would".split(" "));
+const words = (value) => (value.toLowerCase().match(/[a-z][a-z0-9]{2,}/g) ?? []).filter((word) => !stop.has(word));
+const clauseBreaks = /* @__PURE__ */ new Set([
+	"unless",
+	"because",
+	"although",
+	"whereas",
+	"whether",
+	"until",
+	"however",
+	"therefore",
+	"otherwise"
+]);
+const topicConnectors = /* @__PURE__ */ new Set([
+	"a",
+	"an",
+	"and",
+	"the"
+]);
+const normalizeHyphens = (value) => value.replace(/[\u2010-\u2015\u2212\uFE58\uFE63\uFF0D]/g, "-");
+const anchorPhrases = (sentence) => {
+	const tokens = [...sentence.matchAll(/[A-Za-z][A-Za-z0-9\u2010-\u2015\u2212\uFE58\uFE63\uFF0D-]*/g)].map((match) => ({
+		text: match[0],
+		start: match.index,
+		end: match.index + match[0].length
+	}));
+	const phrases = [];
+	for (let start = 0; start < tokens.length; start++) {
+		if (stop.has(tokens[start].text.toLowerCase()) || clauseBreaks.has(tokens[start].text.toLowerCase())) continue;
+		if (new Set(words(tokens[start].text)).size >= 2) phrases.push(tokens[start].text);
+		for (let end = start + 1; end < Math.min(tokens.length, start + 5); end++) {
+			if (!/^\s+$/.test(sentence.slice(tokens[end - 1].end, tokens[end].start))) break;
+			if (clauseBreaks.has(tokens[end].text.toLowerCase())) break;
+			if (stop.has(tokens[end].text.toLowerCase())) continue;
+			const phrase = sentence.slice(tokens[start].start, tokens[end].end);
+			if (new Set(words(phrase)).size >= 2) phrases.push(phrase);
+		}
+	}
+	return phrases;
+};
+const indexTargetPage = (page) => {
+	const passages = page.sentences.map((sentence) => ({
+		sentence,
+		normalized: normalizeHyphens(sentence.toLowerCase()).replace(/\s+/g, " ").trim(),
+		terms: new Set(words(sentence))
+	}));
+	const byTerm = /* @__PURE__ */ new Map();
+	passages.forEach((passage, index) => {
+		for (const term of passage.terms) {
+			if (!byTerm.has(term)) byTerm.set(term, []);
+			byTerm.get(term).push(index);
+		}
+	});
+	return {
+		passages,
+		byTerm,
+		terms: new Set(passages.flatMap((passage) => [...passage.terms]))
+	};
+};
+/** Deterministic, content-grounded ranking; no placement is emitted without shared terms. */
+const rankLinkSuggestions = (pairs, pages, inbound, limit) => {
+	const byPath = new Map(pages.map((page) => [page.path, page]));
+	const frequency = /* @__PURE__ */ new Map();
+	for (const page of pages) for (const term of new Set(page.sentences.flatMap(words))) frequency.set(term, (frequency.get(term) ?? 0) + 1);
+	const targetIndexes = /* @__PURE__ */ new Map();
+	const scored = [];
+	for (const pair of pairs) {
+		const source = byPath.get(pair.source);
+		const target = byPath.get(pair.destination);
+		if (!source || !target || pair.destination === "/") continue;
+		const destinationSegments = pair.destination.split("/").filter(Boolean);
+		const destinationSlug = destinationSegments.at(-1) ?? "";
+		const destinationTerms = words(destinationSlug.replace(/[-_]/g, " "));
+		if (destinationSegments.length === 1 && destinationTerms.length === 0) continue;
+		let targetIndex = targetIndexes.get(pair.destination);
+		if (!targetIndex) {
+			targetIndex = indexTargetPage(target);
+			targetIndexes.set(pair.destination, targetIndex);
+		}
+		const namedSection = destinationSegments.length >= 2 && ["compare", "legal"].includes(destinationSegments[0]);
+		const namedDestination = destinationTerms.filter((term) => destinationSegments.length === 1 || namedSection || term.length > 3 && targetIndex.terms.has(term));
+		let best;
+		for (const sentence of source.sentences) {
+			if ([...new Set(words(sentence))].filter((term) => targetIndex.terms.has(term)).length < 2) continue;
+			const normalizedSource = normalizeHyphens(sentence.toLowerCase()).replace(/\s+/g, " ").trim();
+			for (const anchor of anchorPhrases(sentence)) {
+				const anchorTerms = [...new Set(words(anchor))];
+				const passageIndex = (anchorTerms.map((term) => targetIndex.byTerm.get(term) ?? []).sort((a, b) => a.length - b.length)[0] ?? []).find((index) => anchorTerms.every((term) => targetIndex.passages[index].terms.has(term)));
+				if (passageIndex === void 0) continue;
+				const passage = targetIndex.passages[passageIndex];
+				if (namedDestination.length > 0 && !anchorTerms.some((term) => namedDestination.includes(term))) {
+					if (destinationSegments.length === 1 || namedSection) continue;
+					const targetWords = (passage.sentence.toLowerCase().match(/[a-z][a-z0-9]*/g) ?? []).filter((term) => !topicConnectors.has(term));
+					if (!targetWords.some((term, index) => {
+						if (!namedDestination.includes(term)) return false;
+						return [[index - 2, index - 1], [index + 1, index + 2]].some(([first, second]) => anchorTerms.includes(targetWords[first] ?? "") && anchorTerms.includes(targetWords[second] ?? ""));
+					})) continue;
+				}
+				if (!(normalizeHyphens(anchor).match(/[A-Za-z0-9]+(?:-[A-Za-z0-9]+)+/g) ?? []).every((compound) => passage.normalized.includes(compound.toLowerCase()))) continue;
+				if (normalizedSource === passage.normalized) continue;
+				const topical = anchorTerms.length;
+				const rarity = Math.round(anchorTerms.reduce((sum, term) => sum + 1 / (frequency.get(term) ?? 1), 0) * 100) / 100;
+				const inboundNeed = Math.round(100 / (1 + (inbound.get(pair.destination) ?? 0))) / 100;
+				const graph = pair.cluster.startsWith("kind:") ? .5 : 1;
+				const scores = {
+					topical,
+					rarity,
+					inboundNeed,
+					graph
+				};
+				const score = Math.round((topical + rarity + inboundNeed + graph) * 100) / 100;
+				const item = {
+					...pair,
+					sentence,
+					anchor,
+					targetSentence: passage.sentence,
+					score,
+					scores,
+					reason: `${pair.reason}; ${anchorTerms.join(", ")} connect the served passages`
+				};
+				if (!best || item.score > best.score || item.score === best.score && (item.anchor.length < best.anchor.length || item.anchor.length === best.anchor.length && (item.sentence < best.sentence || item.sentence === best.sentence && item.anchor < best.anchor))) best = item;
+			}
+		}
+		if (best) scored.push(best);
+	}
+	scored.sort((a, b) => b.score - a.score || a.source.localeCompare(b.source) || a.destination.localeCompare(b.destination));
+	return {
+		candidates: scored.slice(0, limit),
+		total: scored.length
+	};
+};
+const pathValid = (value) => typeof value === "string" && /^\/(?!\/)[^?#]*$/.test(value);
+const decodeLinksSuggestionReport = (value, origin) => {
+	if (!value || typeof value !== "object") throw new Error("Suggestion report must be an object");
+	const report = value;
+	if (report.kind !== "links-candidates" || report.schemaVersion !== 2 || report.origin !== origin || !Array.isArray(report.candidates)) throw new Error(`Expected schema-version-2 suggestions for ${origin}`);
+	if (!Number.isSafeInteger(report.limit) || report.limit < 1 || !Number.isSafeInteger(report.pageLimit) || report.pageLimit < 1 || report.maxBodyBytes !== void 0 && (!Number.isSafeInteger(report.maxBodyBytes) || report.maxBodyBytes < 1 || report.maxBodyBytes > 1e7) || !Number.isSafeInteger(report.total) || report.total < report.candidates.length || typeof report.truncated !== "boolean" || !Array.isArray(report.skipped)) throw new Error("Invalid suggestion report counts");
+	const seen = /* @__PURE__ */ new Set();
+	for (const candidate of report.candidates) {
+		if (!pathValid(candidate.source) || !pathValid(candidate.destination) || candidate.source === candidate.destination || typeof candidate.cluster !== "string" || typeof candidate.sentence !== "string" || !candidate.sentence.trim() || typeof candidate.anchor !== "string" || !candidate.anchor.trim() || !candidate.sentence.includes(candidate.anchor) || typeof candidate.targetSentence !== "string" || !candidate.targetSentence.trim() || typeof candidate.reason !== "string" || typeof candidate.score !== "number" || !Number.isFinite(candidate.score) || !candidate.scores || [
+			candidate.scores.topical,
+			candidate.scores.rarity,
+			candidate.scores.inboundNeed,
+			candidate.scores.graph
+		].some((part) => typeof part !== "number" || !Number.isFinite(part))) throw new Error("Malformed or ungrounded suggestion candidate");
+		const key = `${candidate.source}\u0000${candidate.destination}\u0000${candidate.anchor}`;
+		if (seen.has(key)) throw new Error("Duplicate suggestion candidate");
+		seen.add(key);
+	}
+	return {
+		...report,
+		maxBodyBytes: report.maxBodyBytes ?? 1e7
+	};
+};
+//#endregion
 //#region src/workflows/prompts/summary.md
 var summary_default = "# PageGraph {{workflow}}\n\n- Run: `{{runId}}`\n- Model: `{{model}}`\n- Pages: {{pages}}\n- Decisions: {{decisions}} ({{review}} review)\n- Executor searches: {{executorSearches}}\n- Executor calls: {{executorCalls}}\n- Changed files: {{changedFiles}}\n\n{{summary}}\n";
 //#endregion
@@ -42084,6 +42942,20 @@ const writeRunBundle = (root, runsDirectory, run) => {
 	writeFileSync(resolve(directory, "summary.md"), summary(run), "utf8");
 	return directory;
 };
+const writeResearchCheckpoint = (root, runsDirectory, checkpoint) => {
+	const directory = resolve(root, runsDirectory, checkpoint.id);
+	mkdirSync(directory, { recursive: true });
+	const path = resolve(directory, "research.json");
+	writeFileSync(path, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+	return path;
+};
+const writeResearchFailure = (root, runsDirectory, id, details) => {
+	const directory = resolve(root, runsDirectory, id);
+	mkdirSync(directory, { recursive: true });
+	const path = resolve(directory, "research-failure.json");
+	writeFileSync(path, `${JSON.stringify(details, null, 2)}\n`, "utf8");
+	return path;
+};
 //#endregion
 //#region node_modules/effect/dist/unstable/ai/Decision.js
 /**
@@ -43281,6 +44153,30 @@ const selectGraph = (graph, options) => {
 		collisions: graph.collisions
 	};
 };
+const selectNeighborhood = (graph, targetPaths) => {
+	const inbound = [];
+	const outbound = [];
+	for (const edge of graph.edges) {
+		if (targetPaths.has(edge.to) && !targetPaths.has(edge.from)) {
+			const node = graph.nodes.get(edge.from);
+			if (node !== void 0) inbound.push({
+				edge,
+				node: serializeNode(node)
+			});
+		}
+		if (targetPaths.has(edge.from) && !targetPaths.has(edge.to)) {
+			const node = graph.nodes.get(edge.to);
+			if (node !== void 0) outbound.push({
+				edge,
+				node: serializeNode(node)
+			});
+		}
+	}
+	return {
+		inbound,
+		outbound
+	};
+};
 const collectContextFiles = (root, workflow, context) => {
 	const paths = [...context?.files ?? [], ...context?.byWorkflow?.[workflow] ?? []];
 	return [...new Set(paths)].map((path) => ({
@@ -43288,14 +44184,18 @@ const collectContextFiles = (root, workflow, context) => {
 		content: readFileSync(resolve(root, path), "utf8")
 	}));
 };
-const collectWorkflowEvidence = (graph, options, root, workflow, context) => ({
-	graph: serializeGraph(selectGraph(graph, options)),
-	sources: collectContextFiles(root, workflow, context)
-});
+const collectWorkflowEvidence = (graph, options, root, workflow, context) => {
+	const selected = selectGraph(graph, options);
+	return {
+		graph: serializeGraph(selected),
+		neighborhood: selectNeighborhood(graph, new Set(selected.nodes.keys())),
+		sources: collectContextFiles(root, workflow, context)
+	};
+};
 //#endregion
 //#region src/workflows/git.ts
-const run$1 = (root, args) => execFileSync("git", args, {
-	cwd: root,
+const run$1 = (cwd, args) => execFileSync("git", args, {
+	cwd,
 	encoding: "utf8",
 	stdio: [
 		"ignore",
@@ -43304,38 +44204,36 @@ const run$1 = (root, args) => execFileSync("git", args, {
 	]
 }).trim();
 const nul = (value) => value.split("\0").filter((item) => item.length > 0);
-const fingerprint = (root, path) => {
+const fingerprint = (root, gitRoot, path) => {
 	const absolute = resolve(root, path);
-	const content = existsSync(absolute) ? readFileSync(absolute) : Buffer.from("<deleted>");
-	const status = run$1(root, [
+	const gitPath = relative(gitRoot, absolute);
+	const status = run$1(gitRoot, [
 		"status",
 		"--short",
 		"--",
-		path
+		gitPath
 	]);
+	let content;
+	if (!existsSync(absolute)) content = Buffer.from("<deleted>");
+	else if (statSync(absolute).isDirectory()) {
+		const stage = run$1(gitRoot, [
+			"ls-files",
+			"--stage",
+			"--",
+			gitPath
+		]);
+		if (stage.split(/\s+/, 1)[0] !== "160000") throw new Error(`Cannot fingerprint directory reported as a Git file: ${path}`);
+		const submoduleRoot = realpathSync(run$1(absolute, ["rev-parse", "--show-toplevel"]));
+		if (submoduleRoot !== realpathSync(absolute)) throw new Error(`Git submodule is unavailable: ${path}`);
+		content = Buffer.from(`gitlink:${stage}\0${JSON.stringify(inspectGit(submoduleRoot))}`);
+	} else content = readFileSync(absolute);
 	return createHash("sha256").update(status).update("\0").update(content).digest("hex");
 };
 const inspectGit = (root) => {
+	const absoluteRoot = realpathSync(root);
+	let gitTopLevel;
 	try {
-		const tracked = nul(run$1(root, [
-			"diff",
-			"--name-only",
-			"-z",
-			"HEAD"
-		]));
-		const untracked = nul(run$1(root, [
-			"ls-files",
-			"--others",
-			"--exclude-standard",
-			"-z"
-		]));
-		const files = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].sort();
-		return {
-			head: run$1(root, ["rev-parse", "HEAD"]),
-			dirty: files.length > 0,
-			files,
-			fingerprints: Object.fromEntries(files.map((path) => [path, fingerprint(root, path)]))
-		};
+		gitTopLevel = run$1(absoluteRoot, ["rev-parse", "--show-toplevel"]);
 	} catch {
 		return {
 			dirty: false,
@@ -43343,6 +44241,27 @@ const inspectGit = (root) => {
 			fingerprints: {}
 		};
 	}
+	const gitRoot = realpathSync(gitTopLevel);
+	const tracked = nul(run$1(gitRoot, [
+		"diff",
+		"--name-only",
+		"-z",
+		"HEAD"
+	]));
+	const untracked = nul(run$1(gitRoot, [
+		"ls-files",
+		"--others",
+		"--exclude-standard",
+		"--full-name",
+		"-z"
+	]));
+	const files = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].map((path) => relative(absoluteRoot, resolve(gitRoot, path))).sort();
+	return {
+		head: run$1(gitRoot, ["rev-parse", "HEAD"]),
+		dirty: files.length > 0,
+		files,
+		fingerprints: Object.fromEntries(files.map((path) => [path, fingerprint(absoluteRoot, gitRoot, path)]))
+	};
 };
 const changedFiles = (before, after) => [.../* @__PURE__ */ new Set([...before.files, ...after.files])].filter((path) => before.fingerprints[path] !== after.fingerprints[path]).sort();
 //#endregion
@@ -43478,9 +44397,20 @@ const decodeToolPart = decodeUnknownOption(Struct({
 	state: Struct({
 		status: String$6,
 		input: optionalKey(Unknown),
-		content: optionalKey(Unknown)
+		content: optionalKey(Unknown),
+		error: optionalKey(Unknown),
+		metadata: optionalKey(Unknown)
 	})
 }));
+const decodeCodeModeMetadata = decodeUnknownOption(Struct({ toolCalls: ArraySchema(Struct({
+	tool: String$6,
+	status: Literals$2([
+		"running",
+		"completed",
+		"error"
+	]),
+	input: optionalKey(Unknown)
+})) }));
 const toolParts = (transcript) => decodeTranscript(transcript).messages.flatMap((message) => {
 	const assistant = decodeAssistantMessage(message);
 	if (isNone(assistant)) return [];
@@ -43489,15 +44419,6 @@ const toolParts = (transcript) => decodeTranscript(transcript).messages.flatMap(
 		return isSome(decoded) ? [decoded.value] : [];
 	});
 });
-const toolText = (value) => {
-	if (typeof value === "string") return value;
-	if (Array.isArray(value)) return value.map(toolText).join("\n");
-	if (value === null || typeof value !== "object") return "";
-	const record = value;
-	if (record["type"] === "text" && typeof record["text"] === "string") return record["text"];
-	return Object.values(record).map(toolText).join("\n");
-};
-const pathsIn = (value) => [...toolText(value).matchAll(/tools\.([A-Za-z0-9_.-]+)/g)].map((match) => match[1] ?? "").filter(Boolean);
 const toolPathPattern = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+$/;
 const pathsInSearchOutput = (value) => {
 	const found = /* @__PURE__ */ new Set();
@@ -43526,27 +44447,50 @@ const pathsInSearchOutput = (value) => {
 const evidenceRecord = (part) => ({
 	tool: part.name,
 	input: part.state.input ?? null,
-	output: part.state.content ?? null
+	output: part.state.content ?? part.state.error ?? null
 });
 const collectExecutorEvidence = (transcript) => {
 	const discovered = /* @__PURE__ */ new Set();
 	const searches = [];
 	const calls = [];
 	for (const part of toolParts(transcript)) {
-		const inputPaths = pathsIn(part.state.input);
-		const inputText = toolText(part.state.input);
-		if (part.name === "executor_search" || part.name === "executor.search" || inputPaths.some((path) => path === "executor.search")) {
+		const metadata = decodeCodeModeMetadata(part.state.metadata);
+		if (isSome(metadata)) {
+			const invocations = metadata.value.toolCalls;
+			for (const invocation of invocations) {
+				if (invocation.status !== "completed") continue;
+				const record = codeModeEvidenceRecord(invocation, part.state.content);
+				if (invocation.tool === "executor.search") {
+					for (const path of pathsInSearchOutput(part.state.content)) if (path !== "executor.search") discovered.add(path);
+					searches.push(record);
+					continue;
+				}
+				if ([...discovered].some((path) => matchesToolPath(invocation.tool, path))) calls.push(record);
+			}
+			continue;
+		}
+		if (part.state.status === "completed" && (part.name === "executor_search" || part.name === "executor.search")) {
 			for (const path of pathsInSearchOutput(part.state.content)) if (path !== "executor.search") discovered.add(path);
 			searches.push(evidenceRecord(part));
 			continue;
 		}
-		if ([...discovered].some((path) => part.name === path || part.name === path.replaceAll(".", "_") || inputPaths.includes(path) || inputText.includes(path))) calls.push(evidenceRecord(part));
+		if (part.state.status === "completed" && [...discovered].some((path) => matchesToolPath(part.name, path))) calls.push(evidenceRecord(part));
 	}
 	return {
 		searches,
 		calls
 	};
 };
+const codeModeEvidenceRecord = (invocation, codeModeOutput) => ({
+	tool: invocation.tool,
+	input: invocation.input ?? null,
+	output: {
+		status: invocation.status,
+		scope: "shared CodeMode execution result",
+		content: codeModeOutput ?? null
+	}
+});
+const matchesToolPath = (tool, path) => tool === path || tool === path.replaceAll(".", "_");
 const interactionEventError = (event, sessionId) => {
 	if (event === null || typeof event !== "object") return void 0;
 	const record = event;
@@ -43559,15 +44503,61 @@ const interactionEventError = (event, sessionId) => {
 		if (form !== null && typeof form === "object" && form["sessionID"] === sessionId) return /* @__PURE__ */ new Error("OpenCode requested a form; embedded PageGraph workflows are noninteractive.");
 	}
 };
+const recordWorkflowActivity = (activity, event) => {
+	if (event.type === "log.synced") return;
+	activity.lastActivity = {
+		type: event.type,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		seq: event.durable.seq
+	};
+	if (event.type === "session.step.started") {
+		activity.modelSteps += 1;
+		activity.lastModel = `${event.data.model.providerID}/${event.data.model.id}`;
+		return;
+	}
+	if (event.type === "session.tool.input.started") {
+		activity.toolNames.set(event.data.id, event.data.name);
+		activity.lastTool = {
+			id: event.data.id,
+			name: event.data.name,
+			status: "input"
+		};
+		return;
+	}
+	if (event.type === "session.tool.called") {
+		activity.lastTool = {
+			id: event.data.id,
+			name: activity.toolNames.get(event.data.id) ?? event.data.id,
+			status: "called"
+		};
+		return;
+	}
+	if (event.type === "session.tool.success" || event.type === "session.tool.failed") {
+		activity.completedTools += 1;
+		activity.lastTool = {
+			id: event.data.id,
+			name: activity.toolNames.get(event.data.id) ?? event.data.id,
+			status: event.type === "session.tool.success" ? "succeeded" : "failed"
+		};
+	}
+};
+const describeWorkflowActivity = (activity, stage) => {
+	const lastActivity = activity.lastActivity ? `${activity.lastActivity.type} at ${activity.lastActivity.at}${activity.lastActivity.seq === void 0 ? "" : ` (seq ${activity.lastActivity.seq})`}` : `none observed during ${stage}`;
+	const lastTool = activity.lastTool ? `; last tool ${activity.lastTool.name} (${activity.lastTool.id}, ${activity.lastTool.status})` : "";
+	const model = activity.lastModel ? `; last model ${activity.lastModel}` : "";
+	return `Model steps: ${activity.modelSteps}; completed tools: ${activity.completedTools}; last activity: ${lastActivity}${model}${lastTool}.`;
+};
 const waitForIdle = async (host, sessionId, options) => {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+	const controller = options.signal === void 0 ? new AbortController() : void 0;
+	const signal = options.signal ?? controller.signal;
+	const timer = controller === void 0 ? void 0 : setTimeout(() => controller.abort(), options.timeoutMs);
 	try {
 		for await (const event of host.sessions.log({
 			sessionID: sessionId,
 			follow: true,
 			after: options.after
-		}, { signal: controller.signal })) {
+		}, { signal })) {
+			if (options.activity !== void 0) recordWorkflowActivity(options.activity, event);
 			const interactionError = interactionEventError(event, sessionId);
 			if (interactionError !== void 0) throw interactionError;
 			if (event.type === "session.execution.succeeded" && event.data.sessionID === sessionId) return event.durable.seq;
@@ -43575,13 +44565,44 @@ const waitForIdle = async (host, sessionId, options) => {
 			if (event.type === "session.execution.interrupted" && event.data.sessionID === sessionId) throw new Error(`OpenCode session was interrupted: ${event.data.reason}.`);
 		}
 	} catch (cause) {
-		if (controller.signal.aborted) throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs ?? options.timeoutMs}ms.`, { cause });
+		if (controller?.signal.aborted) throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs ?? options.timeoutMs}ms.`, { cause });
 		throw cause;
 	} finally {
-		clearTimeout(timer);
+		if (timer !== void 0) clearTimeout(timer);
 	}
 	throw new Error("OpenCode session log ended before the SEO agent completed.");
 };
+const runWorkflowTurn = async (host, sessionId, prompt, options) => {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+	let stage = options.stage;
+	try {
+		await host.sessions.prompt({
+			sessionID: sessionId,
+			text: prompt,
+			...options.skills === void 0 ? {} : { skills: options.skills.map((id) => ({ id })) }
+		}, { signal: controller.signal });
+		if (stage === "prompt admission") stage = "model execution";
+		return await waitForIdle(host, sessionId, {
+			timeoutMs: options.timeoutMs,
+			configuredTimeoutMs: options.configuredTimeoutMs,
+			after: options.after,
+			signal: controller.signal,
+			activity: options.activity
+		});
+	} catch (cause) {
+		if (!controller.signal.aborted) throw cause;
+		let interruption = "unknown";
+		try {
+			interruption = (await host.sessions.interrupt({ sessionID: sessionId }, { signal: AbortSignal.timeout(5e3) })).interrupted ? "active execution interrupted" : "no active execution to interrupt";
+		} catch (interruptCause) {
+			interruption = `interrupt request failed: ${interruptCause instanceof Error ? interruptCause.message : String(interruptCause)}`;
+		}
+		throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs}ms during ${stage}; ${describeWorkflowActivity(options.activity, stage)} Timeout handling: ${interruption}.`, { cause });
+	} finally {
+		clearTimeout(timer);
+	}
+};
 const acquireWorkflowHost = async (options) => {
 	const model = parseModel(options.model ?? options.config.defaultModel);
 	const configDirectory = resolve(options.root, options.config.configDirectory);
@@ -43603,18 +44624,21 @@ const acquireWorkflowHost = async (options) => {
 				sessionID: sessionId,
 				permissions: [...workflowOptions.permissions]
 			});
-			const configuredTimeoutMs = options.timeoutMs ?? 18e4;
+			const configuredTimeoutMs = options.timeoutMs ?? options.config.timeoutMs ?? 18e4;
 			const deadline = Date.now() + configuredTimeoutMs;
 			const remaining = () => Math.max(0, deadline - Date.now());
-			await host.sessions.prompt({
-				sessionID: sessionId,
-				text: prompt,
-				skills: workflowOptions.skills.map((id) => ({ id }))
-			});
-			let cursor = await waitForIdle(host, sessionId, {
+			const activity = {
+				modelSteps: 0,
+				completedTools: 0,
+				toolNames: /* @__PURE__ */ new Map()
+			};
+			let cursor = await runWorkflowTurn(host, sessionId, prompt, {
 				timeoutMs: remaining(),
 				configuredTimeoutMs,
-				after: cursors.get(sessionId)
+				stage: "prompt admission",
+				after: cursors.get(sessionId),
+				skills: workflowOptions.skills,
+				activity
 			});
 			cursors.set(sessionId, cursor);
 			let transcript = await host.sessions.export({
@@ -43632,14 +44656,12 @@ const acquireWorkflowHost = async (options) => {
 					}]
 				});
 				try {
-					await host.sessions.prompt({
-						sessionID: sessionId,
-						text: STATE_REPAIR_PROMPT
-					});
-					cursor = await waitForIdle(host, sessionId, {
+					cursor = await runWorkflowTurn(host, sessionId, STATE_REPAIR_PROMPT, {
 						timeoutMs: remaining(),
 						configuredTimeoutMs,
-						after: cursor
+						stage: "workflow state repair",
+						after: cursor,
+						activity
 					});
 					cursors.set(sessionId, cursor);
 					transcript = await host.sessions.export({
@@ -43691,9 +44713,43 @@ const acquireWorkflowHost = async (options) => {
 var action_default = "Continue PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nObserved state:\n{{state}}\n\nJev decisions:\n{{decisions}}\n\nApply only records in the resolved set whose verdict calls for a change. Never apply review records;\nleave them in the artifact for a human. If nothing is safely resolved, return no-change.\n\nRepository mutation mode: {{mutationMode}}. {{mutationInstruction}}\n\nReturn only one JSON object with this shape:\n{\"summary\":\"...\",\"files\":[\"relative/path\"],\"outcome\":\"applied|dry-run|no-change\"}\n";
 //#endregion
 //#region src/workflows/prompts/research.md
-var research_default = "You are running PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nUse these skills: {{skills}}. Treat the supplied project evidence as the deterministic baseline.\nSearch Executor's live catalog in one Code Mode turn, then call at least one exact returned tool\npath in a later turn. Compose whichever current integrations best support this workflow. Do not\nassume fixed provider or tool names. Preserve source references in the structured state.\n\nReturn only one JSON object matching this JSON Schema:\n{{stateSchema}}\n\nMarket: {{market}}\nLanguage: {{language}}\nDevice: {{device}}\nRefresh requested: {{refresh}}\nDo not ask questions, request permissions, or create interactive forms. Fail clearly if required\ninput is missing.\nSeed queries: {{queries}}\nCompetitor seeds: {{competitors}}\nAuthority-domain seeds: {{domains}}\nDeterministic evidence:\n{{evidence}}\n";
+var research_default = "You are running PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nUse these skills: {{skills}}. Treat the supplied project evidence as the deterministic baseline.\nThe graph contains the selected target pages. Its neighborhood preserves incoming and outgoing\nrelationships to pages outside that selection; those neighbors are context, not additional targets.\nWhen suggestion evidence is supplied, preserve each candidate's exact source sentence as `context`,\nverbatim anchor, source and destination paths. Do not invent additional link placements.\nReturn at most {{limit}} items or opportunities. Keep exploration scoped to these targets and stop\nwhen the collected evidence supports the requested decision; do not expand into a site-wide audit.\n\nSearch Executor's live catalog with a short intent phrase, then use Code Mode's local `search` for\nthe exact returned path to inspect its current argument signature before calling it in a later turn.\nCatalog discovery returns tool names and descriptions, not complete input schemas. Never guess\narguments from a description. If discovery returns no matches, simplify the query. Compose whichever\ncurrent integrations best support this workflow; tool names and providers are discovered dynamically.\nCall at least one relevant discovered tool and preserve source references and provider errors in the\nstructured state. Do not treat an errored call or empty dataset as proof of indexing or traffic.\nDistinguish project market settings from the country, language, device, and date filters actually\napplied to provider data; report only the segments supported by the call and its response.\n\nReturn only one JSON object matching this JSON Schema:\n{{stateSchema}}\n\nMarket: {{market}}\nLanguage: {{language}}\nDevice: {{device}}\nRefresh requested: {{refresh}}\nDo not ask questions, request permissions, or create interactive forms. Fail clearly if required\ninput is missing.\nSeed queries: {{queries}}\nCompetitor seeds: {{competitors}}\nAuthority-domain seeds: {{domains}}\nDeterministic evidence:\n{{evidence}}\n";
 //#endregion
 //#region src/workflows/run.ts
+const readCurrentSuggestionSentences = async (origin, path, allowPrivate, maxBodyBytes) => {
+	const options = {
+		sameOrigin: origin,
+		allowPrivate,
+		timeoutMs: 15e3,
+		maxBodyBytes
+	};
+	const robots = await probeHttp({
+		kind: "robots",
+		method: "GET",
+		accept: "text/plain",
+		url: new URL("/robots.txt", origin)
+	}, {
+		...options,
+		captureBody: true
+	});
+	if (!robots.ok && robots.status !== 404 || robots.bodyTruncated) throw new Error("Could not verify current robots policy for suggestion freshness");
+	const rules = robots.ok ? robotsRules(robots.body ?? "").rules : [];
+	const url = new URL(path, origin);
+	if (!allowedByRobots(`${url.pathname}${url.search}`, rules)) throw new Error(`Suggestion page is robots-disallowed: ${path}`);
+	const probe = await probeHttp({
+		kind: "page-html",
+		method: "GET",
+		accept: "text/html",
+		url
+	}, {
+		...options,
+		captureBody: true,
+		allowUrl: (next) => allowedByRobots(`${next.pathname}${next.search}`, rules)
+	});
+	const contentType = probe.responseHeaders["content-type"];
+	if (!probe.ok || probe.bodyTruncated || !probe.body || !probe.finalUrl || contentType !== void 0 && !/text\/html|application\/xhtml\+xml/i.test(contentType) || new URL(probe.finalUrl).pathname.replace(/\/+$/, "") !== path.replace(/\/+$/, "")) throw new Error(`Could not verify current served copy for suggestion page ${path}: ${probe.error ?? "unreadable or redirected page"}`);
+	return extractPageSentences(probe.body);
+};
 const defaultDecide = async (inputs, spec) => {
 	const layer$14 = model("jev-latest").pipe(provide$2(layerConfig()), provide$2(layer));
 	return runPromise(gen(function* () {
@@ -43720,6 +44776,7 @@ const capState = (state, limit) => {
 };
 const researchPrompt = (spec, evidence, options) => TextTemplate.from(research_default).values({
 	workflow: spec.id,
+	limit: options.limit,
 	instructions: spec.researchInstructions,
 	skills: spec.skills.join(", "),
 	stateSchema: JSON.stringify(spec.stateJsonSchema),
@@ -43761,6 +44818,20 @@ const runWorkflow = async (input, dependencies = {}) => {
 	});
 	if (spec.mutatesFiles) mutation.assertStartAllowed();
 	const evidence = collectWorkflowEvidence(input.graph, input.options, input.root, spec.id, workflows.context);
+	const suggestionReport = input.options.suggestions === void 0 ? void 0 : (() => {
+		if (spec.id !== "improve.links") throw new Error("--suggestions is only valid for improve links");
+		const report = decodeLinksSuggestionReport(JSON.parse(readFileSync(resolve(input.root, input.options.suggestions), "utf8")), new URL(input.config.origin).origin);
+		const selectedSources = selectGraph(input.graph, input.options).nodes;
+		for (const candidate of report.candidates) {
+			if (!input.graph.nodes.has(candidate.source) || !input.graph.nodes.has(candidate.destination)) throw new Error(`Suggestion references a path absent from seo.config.ts: ${candidate.source} → ${candidate.destination}`);
+			if (!selectedSources.has(candidate.source)) throw new Error(`Suggestion source is outside workflow page/kind/limit targets: ${candidate.source}`);
+		}
+		return report;
+	})();
+	const suppliedEvidence = suggestionReport === void 0 ? evidence : {
+		...evidence,
+		suggestions: suggestionReport
+	};
 	const host = await (dependencies.acquireHost ?? acquireWorkflowHost)({
 		root: input.root,
 		config: workflows.opencode,
@@ -43769,67 +44840,184 @@ const runWorkflow = async (input, dependencies = {}) => {
 	try {
 		const researchPermissions = repositoryMutationPermissionRules(input.root);
 		const actionPermissions = spec.mutatesFiles && !input.options.dryRun ? mutation.sessionPermissions : researchPermissions;
-		const researched = await host.research(researchPrompt(spec, evidence, input.options), {
+		let researched = await host.research(researchPrompt(spec, suppliedEvidence, input.options), {
 			skills: spec.skills,
 			permissions: researchPermissions
 		});
-		const gitAfterResearch = inspectGit(input.root);
-		const researchFiles = changedFiles(gitAtStart, gitAfterResearch);
-		if (researchFiles.length > 0) throw new Error(`${spec.id} changed repository files during its read-only research turn: ${researchFiles.join(", ")}`);
-		const state = spec.decodeState(capState(researched.state, input.options.limit));
+		const assertResearchReadOnly = () => {
+			const researchFiles = changedFiles(gitAtStart, inspectGit(input.root));
+			if (researchFiles.length > 0) throw new Error(`${spec.id} changed repository files during its read-only research turn: ${researchFiles.join(", ")}`);
+		};
+		assertResearchReadOnly();
+		const decodeResearchState = (value) => spec.decodeState(capState(value, input.options.limit));
+		let state;
+		try {
+			state = decodeResearchState(researched.state);
+		} catch (firstError) {
+			const original = researched;
+			let repaired;
+			try {
+				repaired = await host.continue(researched.sessionId, [
+					`The previous ${spec.id} research JSON did not match the required state schema: ${firstError instanceof Error ? firstError.message : String(firstError)}.`,
+					`Return only one corrected JSON object matching this schema: ${JSON.stringify(spec.stateJsonSchema)}.`,
+					"Use only evidence already collected. Do not call tools, edit files, or add commentary."
+				].join(" "), {
+					skills: spec.skills,
+					permissions: researchPermissions
+				});
+				assertResearchReadOnly();
+				state = decodeResearchState(repaired.state);
+				researched = repaired;
+			} catch (repairError) {
+				const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
+				const path = writeResearchFailure(input.root, runsDirectory, id, {
+					kind: "pagegraph-workflow-research-failure",
+					workflow: spec.id,
+					original,
+					repaired,
+					firstError: String(firstError),
+					repairError: String(repairError)
+				});
+				throw new Error(`${spec.id} research state failed schema validation after one read-only repair. Research failure artifact: ${path}`, { cause: repairError });
+			}
+		}
 		const decisionInputs = spec.decisionInputs(state);
+		if (suggestionReport !== void 0) {
+			const valid = new Set(suggestionReport.candidates.map((item) => `${item.source}\u0000${item.destination}\u0000${item.anchor}\u0000${item.sentence}`));
+			for (const item of decisionInputs) {
+				const link = item;
+				if (!valid.has(`${link.from}\u0000${link.to}\u0000${link.anchor}\u0000${link.context}`)) throw new Error("Research proposed a link absent from the supplied suggestions");
+			}
+		}
 		for (const item of decisionInputs) {
 			const error = spec.validateDecisionInput(item);
 			if (error !== void 0) throw new Error(error);
 		}
-		const decisionReport = await (dependencies.decide ?? defaultDecide)(decisionInputs, spec);
-		const acted = spec.mutatesFiles ? await host.continue(researched.sessionId, actionPrompt(spec, state, decisionReport, mutation), {
-			skills: spec.skills,
-			permissions: actionPermissions
-		}) : researched;
-		const gitAfter = inspectGit(input.root);
-		const files = changedFiles(gitAtStart, gitAfter);
-		if ((!spec.mutatesFiles || input.options.dryRun) && files.length > 0) throw new Error(`${spec.id} changed repository files while running in read-only mode: ${files.join(", ")}`);
-		const run = {
-			kind: "pagegraph-workflow-run",
+		const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
+		const checkpoint = {
+			kind: "pagegraph-workflow-research-checkpoint",
 			schemaVersion: 1,
 			id,
 			workflow: spec.id,
 			startedAt: started.toISOString(),
-			finishedAt: now().toISOString(),
+			checkpointedAt: now().toISOString(),
 			project: {
 				root: input.root,
 				head: gitAtStart.head,
-				dirtyAtStart: gitAtStart.dirty
+				dirtyAtStart: gitAtStart.dirty,
+				filesAtStart: gitAtStart.files
 			},
 			options: input.options,
-			model: host.model,
-			targets: {
-				pages: evidence.graph.nodes.map((node) => node.path),
-				queries: input.options.queries,
-				kinds: input.options.kinds
-			},
 			evidence: {
-				...evidence,
-				executor: acted.executor
+				...suppliedEvidence,
+				executor: researched.executor
 			},
-			decisions: [decisionArtifact(spec, decisionInputs, decisionReport)],
-			changes: {
-				files,
-				providerCalls: acted.executor.calls.map((call) => call.tool)
-			},
-			result: spec.mutatesFiles ? acted.state : state,
+			state,
+			decisionInputs,
 			opencode: {
 				agent: "seo",
-				sessionId: acted.sessionId,
-				transcript: acted.transcript
+				sessionId: researched.sessionId,
+				model: host.model,
+				transcript: researched.transcript
 			}
 		};
-		const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
-		return {
-			run,
-			directory: writeRunBundle(input.root, runsDirectory, run)
-		};
+		const checkpointPath = writeResearchCheckpoint(input.root, runsDirectory, checkpoint);
+		const gitAtCheckpoint = inspectGit(input.root);
+		try {
+			const decisionReport = await (dependencies.decide ?? defaultDecide)(decisionInputs, spec);
+			const accepted = spec.id === "improve.links" ? decisionReport.resolved.filter((record) => record.verdict === "add" || record.verdict === "update") : void 0;
+			const acceptedIndexes = /* @__PURE__ */ new Set();
+			if (accepted !== void 0) for (const record of accepted) {
+				const match = /^workflow-links:(\d+)$/.exec(record.decisionId);
+				const index = match === null ? -1 : Number(match[1]);
+				const item = decisionInputs[index];
+				if (!item || record.inputRef !== `${item.from} → ${item.to}`) throw new Error(`Decision does not match a researched link: ${record.decisionId}`);
+				acceptedIndexes.add(index);
+			}
+			const actionItems = accepted === void 0 ? void 0 : state.items.filter((_, index) => acceptedIndexes.has(index));
+			if (actionItems !== void 0 && actionItems.length > 0 && suggestionReport !== void 0) {
+				const readSentences = dependencies.readSuggestionSentences ?? readCurrentSuggestionSentences;
+				const current = /* @__PURE__ */ new Map();
+				for (const item of actionItems) {
+					const candidate = suggestionReport.candidates.find((entry) => entry.source === item.from && entry.destination === item.to && entry.anchor === item.anchor && entry.sentence === item.context);
+					if (!candidate) throw new Error("Accepted link is absent from the supplied suggestions");
+					for (const path of [candidate.source, candidate.destination]) if (!current.has(path)) current.set(path, await readSentences(suggestionReport.origin, path, input.options.allowPrivate === true, suggestionReport.maxBodyBytes));
+					if (!current.get(candidate.source).includes(candidate.sentence) || !current.get(candidate.destination).includes(candidate.targetSentence)) throw new Error(`Suggestion is stale; served copy changed for ${candidate.source} → ${candidate.destination}. Regenerate links candidates --site.`);
+				}
+			}
+			const actionState = actionItems === void 0 ? state : {
+				...state,
+				items: actionItems
+			};
+			const actionDecisions = accepted === void 0 ? decisionReport : {
+				...decisionReport,
+				resolved: accepted,
+				review: [],
+				counts: {
+					inputs: accepted.length,
+					resolved: accepted.length,
+					review: 0
+				},
+				verdicts: {
+					add: accepted.filter((record) => record.verdict === "add").length,
+					update: accepted.filter((record) => record.verdict === "update").length
+				}
+			};
+			const mayAct = spec.mutatesFiles && (actionItems === void 0 || actionItems.length > 0);
+			const acted = mayAct ? await host.continue(researched.sessionId, actionPrompt(spec, actionState, actionDecisions, mutation), {
+				skills: spec.skills,
+				permissions: actionPermissions
+			}) : researched;
+			const gitAfter = inspectGit(input.root);
+			const files = changedFiles(gitAtCheckpoint, gitAfter);
+			if ((!spec.mutatesFiles || input.options.dryRun) && files.length > 0) throw new Error(`${spec.id} changed repository files while running in read-only mode: ${files.join(", ")}`);
+			const run = {
+				kind: "pagegraph-workflow-run",
+				schemaVersion: 1,
+				id,
+				workflow: spec.id,
+				startedAt: started.toISOString(),
+				finishedAt: now().toISOString(),
+				project: {
+					root: input.root,
+					head: gitAtStart.head,
+					dirtyAtStart: gitAtStart.dirty
+				},
+				options: input.options,
+				model: host.model,
+				targets: {
+					pages: evidence.graph.nodes.map((node) => node.path),
+					queries: input.options.queries,
+					kinds: input.options.kinds
+				},
+				evidence: {
+					...suppliedEvidence,
+					executor: acted.executor
+				},
+				decisions: [decisionArtifact(spec, decisionInputs, decisionReport)],
+				changes: {
+					files,
+					providerCalls: acted.executor.calls.map((call) => call.tool)
+				},
+				result: mayAct ? acted.state : accepted !== void 0 ? {
+					summary: "No link suggestions accepted.",
+					outcome: "no-change",
+					files: []
+				} : state,
+				opencode: {
+					agent: "seo",
+					sessionId: acted.sessionId,
+					transcript: acted.transcript
+				}
+			};
+			return {
+				run,
+				directory: writeRunBundle(input.root, runsDirectory, run)
+			};
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new Error(`${message}\nResearch checkpoint: ${checkpointPath}`, { cause });
+		}
 	} finally {
 		await host.close();
 	}
@@ -43851,6 +45039,7 @@ const configFlag = String$2("opencode-config").pipe(withDescription$2("OpenCode
 const outFlag = String$2("out").pipe(withDescription$2("Run-artifact directory override"), optional$1);
 const dryRunFlag$1 = Boolean$1("dry-run").pipe(withDescription$2("Suppress file writes; discovered Executor tools remain available"), withDefault(false));
 const allowDirtyFlag$1 = Boolean$1("allow-dirty").pipe(withDescription$2("Permit file changes when the working tree is already dirty"), withDefault(false));
+const suggestionsFlag = String$2("suggestions").pipe(withDescription$2("Schema-version-2 links candidate JSON to evaluate"), optional$1);
 const baseFlags = {
 	page: pageFlag,
 	kind: kindFlag,
@@ -43894,7 +45083,9 @@ const optionsFrom = (flags, extra = {}) => {
 		domains: strings(flags.domain),
 		refresh: flags.refresh === true,
 		dryRun: extra.dryRun === true,
-		allowDirty: extra.allowDirty === true
+		allowDirty: extra.allowDirty === true,
+		allowPrivate: flags.allowPrivate === true,
+		suggestions: optionalString(flags.suggestions)
 	};
 };
 const resultSummary = (result) => {
@@ -44298,70 +45489,70 @@ var seo_default = "---\ndescription: Execute PageGraph SEO workflows from reposi
 var opencode_default = "{\n  \"default_agent\": \"seo\",\n  \"plugins\": [\n    // Add your Executor plugin package or local path here.\n    // \"opencode-plugin-executor\"\n  ]\n}\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/ai-search/SKILL.md
-var SKILL_default$10 = "---\nname: ai-search\ndescription: Evaluate answer extractability, entity clarity, support, and citation readiness.\n---\n\n# AI Search Analysis\n\nStart from the page's visible content, structured data, route context, and cited sources. Read\n[Executor Starters](references/executor.md) before collecting current AI-search observations.\n\nEvaluate whether an answer engine can identify the subject, extract a concise answer, understand\nentity relationships, and trace material claims to first-party or trustworthy support. Distinguish\nobserved citations from inferred readiness. Do not claim a visibility lift from formatting alone.\n\nReturn the structured state requested by the workflow. This workflow produces evidence and a\ndiagnosis; it does not edit pages or submit them to an answer engine.\n";
+var SKILL_default$11 = "---\nname: ai-search\ndescription: Evaluate answer extractability, entity clarity, support, and citation readiness.\n---\n\n# AI Search Analysis\n\nStart from the page's visible content, structured data, route context, and cited sources. Read\n[Executor Starters](references/executor.md) before collecting current AI-search observations.\n\nEvaluate whether an answer engine can identify the subject, extract a concise answer, understand\nentity relationships, and trace material claims to first-party or trustworthy support. Distinguish\nobserved citations from inferred readiness. Do not claim a visibility lift from formatting alone.\n\nReturn the structured state requested by the workflow. This workflow produces evidence and a\ndiagnosis; it does not edit pages or submit them to an answer engine.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/ai-search/references/executor.md
 var executor_default$10 = "# Executor Starters for AI Search Analysis\n\nThese snippets are starting points, not an inventory. Search for current citation, brand-mention,\nanswer-engine, and owned-performance capabilities available through Executor.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"AI search citations answer visibility brand mentions\", limit: 8 }),\n  tools.executor.search({ query: \"Google Search Console generative AI performance page\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst visibility = (await search({ query: \"tools.<exact-ai-visibility-path>\", limit: 1 })).items[0];\nreturn visibility.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  domain,\n  queries,\n  market,\n  language,\n});\n~~~\n\nRecord engine or surface, query, market, collection date, cited URL, response excerpt, sampling\nmethod, task status, errors, and cost. Missing citations in a small sample do not prove absence.\nDo not mutate provider projects or publish content.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/authority-research/SKILL.md
-var SKILL_default$9 = "---\nname: authority-research\ndescription: Qualify legitimate citation, directory, editorial, partner, and community opportunities.\n---\n\n# Authority Research\n\nUse PageGraph's pages to identify the asset that could reasonably earn each citation. Read\n[Executor Starters](references/executor.md) before collecting backlink or live-page evidence.\n\nUse backlink gaps only to nominate sources. Verify the current page and qualify topical relevance,\nlegitimacy, editorial fit, audience overlap, and eligibility. Reject paid-link schemes, bulk\ndirectories, expired pages, scraped lists, and opportunities with no suitable destination asset.\n\nReturn the structured state requested by the workflow. Contact discovery, outreach, submission,\nand provider project updates are separate operations and remain outside this research workflow.\n";
+var SKILL_default$10 = "---\nname: authority-research\ndescription: Qualify legitimate citation, directory, editorial, partner, and community opportunities.\n---\n\n# Authority Research\n\nUse PageGraph's pages to identify the asset that could reasonably earn each citation. Read\n[Executor Starters](references/executor.md) before collecting backlink or live-page evidence.\n\nUse backlink gaps only to nominate sources. Verify the current page and qualify topical relevance,\nlegitimacy, editorial fit, audience overlap, and eligibility. Reject paid-link schemes, bulk\ndirectories, expired pages, scraped lists, and opportunities with no suitable destination asset.\n\nReturn the structured state requested by the workflow. Contact discovery, outreach, submission,\nand provider project updates are separate operations and remain outside this research workflow.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/authority-research/references/executor.md
 var executor_default$9 = "# Executor Starters for Authority Research\n\nThese snippets are starting points, not an inventory. Discover backlink and live-page capabilities\nbefore composing exact calls.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"OpenSEO DataForSEO backlink domain intersection\", limit: 8 }),\n  tools.executor.search({ query: \"web search fetch directory editorial partner eligibility\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst gap = (await search({ query: \"tools.<exact-backlink-gap-path>\", limit: 1 })).items[0];\nreturn gap.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  targets: [ownedDomain, ...competitors],\n  excludeInternal: true,\n  limit: 100,\n});\n~~~\n\nRecord source URL, target domain, dates, limits, authority metrics, task status, errors, and cost.\nProvider metrics nominate prospects; current pages determine legitimacy. Do not discover personal\ncontact data, send outreach, submit listings, or mutate OpenSEO project state.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/competitive-landscape/SKILL.md
-var SKILL_default$8 = "---\nname: competitive-landscape\ndescription: Identify current search competitors and evidence-backed openings across representative queries.\n---\n\n# Competitive Landscape\n\nUse PageGraph's public-page corpus and product context to decide which domains compete for the same\nneed. Read [Executor Starters](references/executor.md) before collecting live market evidence.\n\nSample representative queries, find domains that recur, and compare their page types, intent,\ncoverage, differentiation, and authority signals. Separate direct product competitors, publishers,\ndirectories, communities, and incidental results. Study only the leaders whose evidence could\nchange a decision.\n\nReturn the structured state requested by the workflow. Do not copy competitor claims, treat every\nranking keyword as desirable, or update a provider's saved competitor list.\n";
+var SKILL_default$9 = "---\nname: competitive-landscape\ndescription: Identify current search competitors and evidence-backed openings across representative queries.\n---\n\n# Competitive Landscape\n\nUse PageGraph's public-page corpus and product context to decide which domains compete for the same\nneed. Read [Executor Starters](references/executor.md) before collecting live market evidence.\n\nSample representative queries, find domains that recur, and compare their page types, intent,\ncoverage, differentiation, and authority signals. Separate direct product competitors, publishers,\ndirectories, communities, and incidental results. Study only the leaders whose evidence could\nchange a decision.\n\nReturn the structured state requested by the workflow. Do not copy competitor claims, treat every\nranking keyword as desirable, or update a provider's saved competitor list.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/competitive-landscape/references/executor.md
 var executor_default$8 = "# Executor Starters for a Competitive Landscape\n\nThese snippets are starting points, not an inventory. Discover current tools and call only exact\nreturned paths after resolving their signatures.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"OpenSEO SERP competitors recurring domains\", limit: 8 }),\n  tools.executor.search({ query: \"domain overview ranked keywords backlink authority\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst serp = (await search({ query: \"tools.<exact-serp-path>\", limit: 1 })).items[0];\nreturn serp.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  queries,\n  market,\n  language,\n  device,\n});\n~~~\n\nPrefer relevant cached OpenSEO context or research when an existing project matches the domain\nunambiguously. Use external traffic and keyword values as estimates. Record query, market, device,\ndate, result depth, task status, errors, and cost. Do not update project context or competitors.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/content-analysis/SKILL.md
-var SKILL_default$7 = "---\nname: content-analysis\ndescription: Evaluate a page's substance, intent coverage, answer quality, and differentiation.\n---\n\n# Content Analysis\n\nStart from the supplied source, rendered page, route relationships, and project truth. Read\n[Executor Starters](references/executor.md) when live owned-site or competitive evidence is needed.\n\nJudge whether the page answers its intended need, supports material claims, avoids sibling-page\ncannibalization, and offers useful depth for its format. Use word counts and competitor excerpts as\ndescriptive signals, never as universal targets. Keep product accuracy ahead of search demand.\n\nReturn the structured state requested by the workflow. This workflow diagnoses content; it does not\nedit source files.\n";
+var SKILL_default$8 = "---\nname: content-analysis\ndescription: Evaluate a page's substance, intent coverage, answer quality, and differentiation.\n---\n\n# Content Analysis\n\nStart from the supplied source, rendered page, route relationships, and project truth. Read\n[Executor Starters](references/executor.md) when live owned-site or competitive evidence is needed.\n\nJudge whether the page answers its intended need, supports material claims, avoids sibling-page\ncannibalization, and offers useful depth for its format. Use word counts and competitor excerpts as\ndescriptive signals, never as universal targets. Keep product accuracy ahead of search demand.\n\nReturn the structured state requested by the workflow. This workflow diagnoses content; it does not\nedit source files.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/content-analysis/references/executor.md
 var executor_default$7 = "# Executor Starters for Content Analysis\n\nThese snippets are starting points, not an inventory. Discover owned query/page performance and\ncurrent result-page evidence when they can change the diagnosis.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console query page performance\", limit: 8 }),\n  tools.executor.search({ query: \"OpenSEO current SERP competitor content\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst owned = (await search({ query: \"tools.<exact-owned-performance-path>\", limit: 1 })).items[0];\nreturn owned.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"PAGE\", \"QUERY\"],\n});\n~~~\n\nKeep Search Console or Bing performance separate from provider estimates and live-page\nobservations. Record reporting dates, filters, market, limits, task status, errors, and cost. Do not\nchange content or provider state.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/content-improvement/SKILL.md
-var SKILL_default$6 = "---\nname: content-improvement\ndescription: Research and apply bounded content changes supported by PageGraph and live evidence.\n---\n\n# Content Improvement\n\nResearch the target page exactly as described by [Executor Starters](references/executor.md). During\nthe research turn, diagnose intent, substance, differentiation, support, and sibling-page ownership\nwithout editing files.\n\nDuring the host-authorized action turn, apply only recommendations accepted by the decision report.\nPreserve the repository's public positioning and voice, edit the owning source rather than generated\noutput, and keep the change local to the selected page and intent. Do not invent metrics, customers,\ncapabilities, or citations.\n\nLeave the resulting repository diff uncommitted for review. Provider state remains read-only.\n";
+var SKILL_default$7 = "---\nname: content-improvement\ndescription: Research and apply bounded content changes supported by PageGraph and live evidence.\n---\n\n# Content Improvement\n\nResearch the target page exactly as described by [Executor Starters](references/executor.md). During\nthe research turn, diagnose intent, substance, differentiation, support, and sibling-page ownership\nwithout editing files.\n\nDuring the host-authorized action turn, apply only recommendations accepted by the decision report.\nPreserve the repository's public positioning and voice, edit the owning source rather than generated\noutput, and keep the change local to the selected page and intent. Do not invent metrics, customers,\ncapabilities, or citations.\n\nLeave the resulting repository diff uncommitted for review. Provider state remains read-only.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/content-improvement/references/executor.md
 var executor_default$6 = "# Executor Starters for Content Improvement\n\nThese snippets are starting points, not an inventory. Discover owned performance and current SERP\nevidence during the read-only research turn.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console page query performance\", limit: 8 }),\n  tools.executor.search({ query: \"OpenSEO current SERP intent competitor pages\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst serp = (await search({ query: \"tools.<exact-serp-path>\", limit: 1 })).items[0];\nreturn serp.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  query,\n  market,\n  language,\n  device,\n});\n~~~\n\nRecord market, language, device, dates, limits, task status, errors, and cost. Search evidence may\nsupport a source edit only after the host evaluates it; never edit during research or write to an\nOpenSEO project.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/internal-linking/SKILL.md
-var SKILL_default$5 = "---\nname: internal-linking\ndescription: Research and apply useful contextual links supported by route and page evidence.\n---\n\n# Internal Linking\n\nUse PageGraph's nodes and edges to find relevant source-target pairs, then inspect both pages before\nproposing a link. Read [Executor Starters](references/executor.md) only when owned search evidence\ncan clarify page ownership or discoverability.\n\nPrefer links that help a reader continue a task, strengthen a clear hierarchy, or connect an\norphaned but relevant page. Reject forced anchors, repeated links, unsupported wording, and links\nwhose target does not satisfy the promised intent.\n\nDuring the host-authorized action turn, apply only accepted links at the owning source or route\ndeclaration. Preserve generated graph contracts, use natural anchor text, leave the diff uncommitted,\nand keep provider state read-only.\n";
+var SKILL_default$6 = "---\nname: internal-linking\ndescription: Research and apply useful contextual links supported by route and page evidence.\n---\n\n# Internal Linking\n\nUse PageGraph's nodes and edges to find relevant source-target pairs, then inspect both pages before\nproposing a link. Read [Executor Starters](references/executor.md) only when owned search evidence\ncan clarify page ownership or discoverability.\n\nPrefer links that help a reader continue a task, strengthen a clear hierarchy, or connect an\norphaned but relevant page. Reject forced anchors, repeated links, unsupported wording, and links\nwhose target does not satisfy the promised intent.\n\nDuring the host-authorized action turn, apply only accepted links at the owning source or route\ndeclaration. Preserve generated graph contracts, use natural anchor text, leave the diff uncommitted,\nand keep provider state read-only.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/internal-linking/references/executor.md
 var executor_default$5 = "# Executor Starters for Internal Linking\n\nThese snippets are starting points, not an inventory. PageGraph's graph is primary; discover owned\nquery/page or crawl evidence only when it resolves ownership or discoverability.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console query page internal ownership\", limit: 8 }),\n  tools.executor.search({ query: \"Bing Webmaster crawl links URL information\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst owned = (await search({ query: \"tools.<exact-owned-pages-path>\", limit: 1 })).items[0];\nreturn owned.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"PAGE\", \"QUERY\"],\n});\n~~~\n\nRecord dates, page and query filters, crawl state, task status, errors, and cost. Search performance\ncan support a graph recommendation but does not override the source content. Do not submit URLs,\nrequest indexing, or mutate provider projects.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/keyword-research/SKILL.md
-var SKILL_default$4 = "---\nname: keyword-research\ndescription: Discover current search demand, validate intent, and map opportunities to public pages.\n---\n\n# Keyword Research\n\nUse PageGraph's route and page evidence as the ownership baseline. Read\n[Executor Starters](references/executor.md) before collecting live evidence.\n\nStart from the supplied seeds and consumer product context. Expand only into queries that match the\nactual product, audience, and market. Use owned-site performance to establish current visibility,\nprovider metrics to estimate demand and competition, and current SERPs to validate intent. A volume\nestimate alone does not establish product fit or justify a new page.\n\nMap each supported query to the strongest existing page. Propose a new page only when no current\npage can satisfy the distinct intent without becoming unfocused. Preserve evidence and caveats for\nevery opportunity.\n\nReturn the structured state requested by the workflow. Do not save keywords, update provider\nprojects, submit URLs, or edit repository files during research.\n";
+var SKILL_default$5 = "---\nname: keyword-research\ndescription: Discover current search demand, validate intent, and map opportunities to public pages.\n---\n\n# Keyword Research\n\nUse PageGraph's route and page evidence as the ownership baseline. Read\n[Executor Starters](references/executor.md) before collecting live evidence.\n\nStart from the supplied seeds and consumer product context. Expand only into queries that match the\nactual product, audience, and market. Use owned-site performance to establish current visibility,\nprovider metrics to estimate demand and competition, and current SERPs to validate intent. A volume\nestimate alone does not establish product fit or justify a new page.\n\nMap each supported query to the strongest existing page. Propose a new page only when no current\npage can satisfy the distinct intent without becoming unfocused. Preserve evidence and caveats for\nevery opportunity.\n\nReturn the structured state requested by the workflow. Do not save keywords, update provider\nprojects, submit URLs, or edit repository files during research.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/keyword-research/references/executor.md
 var executor_default$4 = "# Executor Starters for Keyword Research\n\nThese snippets are starting points, not an inventory. Search Executor in one Code Mode turn, retain\nthe exact returned paths, and call those paths in a later turn after resolving their current\nsignatures.\n\nDiscover Google Search Console or Bing query/page performance, OpenSEO cached project context and\nkeyword research, provider keyword metrics, and live SERP results. Prefer a relevant cached OpenSEO\nresult when it already covers the requested market, language, device, and freshness. When a matching\nOpenSEO project can be resolved unambiguously, its project context and research log are supporting\nevidence; the consumer repository remains authoritative for product truth.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console performance query page\", limit: 8 }),\n  tools.executor.search({ query: \"OpenSEO project context cached keyword research\", limit: 8 }),\n  tools.executor.search({ query: \"keyword volume difficulty current SERP results\", limit: 8 }),\n]);\n~~~\n\nIn a later turn, replace placeholders with exact discovered paths:\n\n~~~ts\nconst call = (path, input) => path.split(\".\").reduce((node, segment) => node[segment], tools)(input);\nconst owned = (await search({ query: \"tools.<exact-owned-performance-path>\", limit: 1 })).items[0];\nconst demand = (await search({ query: \"tools.<exact-demand-path>\", limit: 1 })).items[0];\nreturn Promise.all([\n  call(owned.path, { siteUrl, startDate, endDate, dimensions: [\"PAGE\", \"QUERY\"] }),\n  call(demand.path, { keywords, market, language, device }),\n]);\n~~~\n\nTreat Search Console and Bing as owned-site evidence, OpenSEO and DataForSEO as provider evidence,\nand current result pages as observed evidence. Record market, language, device, reporting dates,\nlimits, task status, errors, and cost metadata when returned. Do not create or update an OpenSEO\nproject, save keywords, or perform another provider write.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/metadata-improvement/SKILL.md
-var SKILL_default$3 = "---\nname: metadata-improvement\ndescription: Research and apply truthful title and description improvements at the owning source.\n---\n\n# Metadata Improvement\n\nUse the route's intent, rendered head, sibling ownership, and live evidence described in\n[Executor Starters](references/executor.md). During research, compare candidate titles and\ndescriptions for accuracy, distinctness, intent alignment, and usefulness rather than fixed length\nor keyword-density targets.\n\nDuring the host-authorized action turn, apply only the accepted candidate at the owning route or\ncontent source. Preserve truthful product claims, existing metadata composition, canonical output,\nand repository conventions. Do not edit generated artifacts.\n\nLeave the resulting repository diff uncommitted. Provider state remains read-only.\n";
+var SKILL_default$4 = "---\nname: metadata-improvement\ndescription: Research and apply truthful title and description improvements at the owning source.\n---\n\n# Metadata Improvement\n\nUse the route's intent, rendered head, sibling ownership, and live evidence described in\n[Executor Starters](references/executor.md). During research, compare candidate titles and\ndescriptions for accuracy, distinctness, intent alignment, and usefulness rather than fixed length\nor keyword-density targets.\n\nDuring the host-authorized action turn, apply only the accepted candidate at the owning route or\ncontent source. Preserve truthful product claims, existing metadata composition, canonical output,\nand repository conventions. Do not edit generated artifacts.\n\nLeave the resulting repository diff uncommitted. Provider state remains read-only.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/metadata-improvement/references/executor.md
 var executor_default$3 = "# Executor Starters for Metadata Improvement\n\nThese snippets are starting points, not an inventory. Discover owned query/page evidence and a\ncurrent SERP before selecting a candidate.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console query page CTR position\", limit: 8 }),\n  tools.executor.search({ query: \"current SERP titles snippets intent\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst owned = (await search({ query: \"tools.<exact-owned-performance-path>\", limit: 1 })).items[0];\nreturn owned.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"PAGE\", \"QUERY\"],\n});\n~~~\n\nRecord dates, query and page filters, market, device, task status, errors, and cost. CTR and position\ndescribe observed performance; they do not prove a particular title caused it. Do not mutate\nprovider metadata or request recrawls.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/schema/SKILL.md
-var SKILL_default$2 = "---\nname: schema\ndescription: Research and apply JSON-LD types justified by visible page content.\n---\n\n# Schema\n\nUse the rendered page, existing JSON-LD, route kind, and owning source as the primary evidence. Read\n[Executor Starters](references/executor.md) when owned search appearance or current eligibility\nevidence is material.\n\nPropose only types and properties that describe visible content. Schema does not repair missing\ncontent, guarantee a rich result, or justify unsupported ratings, prices, authorship, FAQs, or\norganization claims.\n\nDuring the host-authorized action turn, apply only accepted changes through the repository's\nexisting JSON-LD composition primitives. Do not edit rendered or generated output. Leave the diff\nuncommitted and provider state unchanged.\n";
+var SKILL_default$3 = "---\nname: schema\ndescription: Research and apply JSON-LD types justified by visible page content.\n---\n\n# Schema\n\nUse the rendered page, existing JSON-LD, route kind, and owning source as the primary evidence. Read\n[Executor Starters](references/executor.md) when owned search appearance or current eligibility\nevidence is material.\n\nPropose only types and properties that describe visible content. Schema does not repair missing\ncontent, guarantee a rich result, or justify unsupported ratings, prices, authorship, FAQs, or\norganization claims.\n\nDuring the host-authorized action turn, apply only accepted changes through the repository's\nexisting JSON-LD composition primitives. Do not edit rendered or generated output. Leave the diff\nuncommitted and provider state unchanged.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/schema/references/executor.md
 var executor_default$2 = "# Executor Starters for Schema\n\nThese snippets are starting points, not an inventory. Discover owned search-appearance, URL\ninspection, rich-result, or documentation tools when they can change the eligibility assessment.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console search appearance page\", limit: 8 }),\n  tools.executor.search({ query: \"URL inspection rich results structured data eligibility\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst appearance = (await search({ query: \"tools.<exact-search-appearance-path>\", limit: 1 })).items[0];\nreturn appearance.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"SEARCH_APPEARANCE\", \"PAGE\"],\n});\n~~~\n\nTreat visible page content and current primary requirements as eligibility authority. Record dates,\npage filters, result types, task status, errors, and cost. Do not request indexing, submit schemas,\nor update provider projects.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/serp-analysis/SKILL.md
-var SKILL_default$1 = "---\nname: serp-analysis\ndescription: Compare a target page with current results, intent, formats, features, and title patterns.\n---\n\n# SERP Analysis\n\nTreat each supplied query, market, language, device, and target page as one analysis unit. Read\n[Executor Starters](references/executor.md) before fetching current result evidence.\n\nIdentify dominant intent, page format, result features, recurring domains, title framing, and the\nevidence a useful page must satisfy. Compare the target against those patterns without turning\ncompetitor wording into product truth. Mark mixed or unstable intent rather than forcing a single\nconclusion.\n\nReturn the structured state requested by the workflow. A current SERP is observed evidence for its\nmarket and time, not a universal ranking rule.\n";
+var SKILL_default$2 = "---\nname: serp-analysis\ndescription: Compare a target page with current results, intent, formats, features, and title patterns.\n---\n\n# SERP Analysis\n\nTreat each supplied query, market, language, device, and target page as one analysis unit. Read\n[Executor Starters](references/executor.md) before fetching current result evidence.\n\nIdentify dominant intent, page format, result features, recurring domains, title framing, and the\nevidence a useful page must satisfy. Compare the target against those patterns without turning\ncompetitor wording into product truth. Mark mixed or unstable intent rather than forcing a single\nconclusion.\n\nReturn the structured state requested by the workflow. A current SERP is observed evidence for its\nmarket and time, not a universal ranking rule.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/serp-analysis/references/executor.md
 var executor_default$1 = "# Executor Starters for SERP Analysis\n\nThese snippets are starting points, not an inventory. Discover a current organic SERP capability\nand resolve its exact signature before use.\n\n~~~ts\nreturn tools.executor.search({\n  query: \"OpenSEO DataForSEO current organic SERP features intent\",\n  limit: 8,\n});\n~~~\n\nIn a later turn:\n\n~~~ts\nconst serp = (await search({ query: \"tools.<exact-serp-path>\", limit: 1 })).items[0];\nreturn serp.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  query,\n  market,\n  language,\n  device,\n  depth: 20,\n});\n~~~\n\nReuse a matching cached OpenSEO SERP when it satisfies the requested freshness. Record query,\nmarket, language, device, collection time, depth, features, task status, errors, and cost. Fetch\nindividual result pages only when their content is material to the decision.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/site-architecture/SKILL.md
-var SKILL_default = "---\nname: site-architecture\ndescription: Plan clear route ownership, hierarchy, collections, and contextual navigation.\n---\n\n# Site Architecture\n\nUse PageGraph's deterministic route nodes and edges as the primary model. Read\n[Executor Starters](references/executor.md) when owned search or crawl evidence can resolve an\nownership or discoverability question.\n\nAssign one clear intent owner, identify useful collections and parent-child relationships, and\nprefer consolidation when multiple pages compete for the same need. Propose new routes only when a\ndistinct supported intent lacks an adequate owner. Treat URL changes as consequential and preserve\nredirect and canonical requirements in the recommendation.\n\nReturn the structured state requested by the workflow. This planning workflow does not move routes,\nedit navigation, or submit sitemaps.\n";
+var SKILL_default$1 = "---\nname: site-architecture\ndescription: Plan clear route ownership, hierarchy, collections, and contextual navigation.\n---\n\n# Site Architecture\n\nUse PageGraph's deterministic route nodes and edges as the primary model. Read\n[Executor Starters](references/executor.md) when owned search or crawl evidence can resolve an\nownership or discoverability question.\n\nAssign one clear intent owner, identify useful collections and parent-child relationships, and\nprefer consolidation when multiple pages compete for the same need. Propose new routes only when a\ndistinct supported intent lacks an adequate owner. Treat URL changes as consequential and preserve\nredirect and canonical requirements in the recommendation.\n\nReturn the structured state requested by the workflow. This planning workflow does not move routes,\nedit navigation, or submit sitemaps.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/site-architecture/references/executor.md
-var executor_default = "# Executor Starters for Site Architecture\n\nThese snippets are starting points, not an inventory. Discover owned page/query, crawl, sitemap,\nand URL evidence only when the deterministic graph does not answer the question.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console page query canonical indexing\", limit: 8 }),\n  tools.executor.search({ query: \"Bing Webmaster crawl sitemap URL information\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst pages = (await search({ query: \"tools.<exact-owned-pages-path>\", limit: 1 })).items[0];\nreturn pages.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"PAGE\", \"QUERY\"],\n});\n~~~\n\nKeep submitted, crawled, indexed, ranking, and clicked evidence distinct. Record reporting dates,\nfilters, canonical state, task status, errors, and cost. Do not request indexing, submit sitemaps,\nor update provider projects.\n";
+var executor_default = "# Executor Starters for Site Architecture\n\nThese snippets are starting points, not an inventory. Discover owned page/query, crawl, sitemap,\nand URL evidence only when the deterministic graph does not answer the question.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Search Console page performance\", limit: 8 }),\n  tools.executor.search({ query: \"Bing Webmaster crawl\", limit: 8 }),\n]);\n~~~\n\nInspect a selected tool's signature before executing it. This is Code Mode's local schema lookup;\nit does not call the provider:\n\n~~~ts\nreturn await search({ query: \"tools.<exact-path-returned-by-executor>\", limit: 1 });\n~~~\n\nIn a later turn, call that exact path with the required fields from its returned signature. Property,\nproject, URL, date, and dimension arguments differ between integrations. Do not copy guessed fields\nfrom a recipe. Prefer page/query performance for demand and ownership questions; use URL inspection\nwhen the question actually concerns crawl, canonical, or indexing state.\n\nKeep submitted, crawled, indexed, ranking, and clicked evidence distinct. Record reporting dates,\nfilters, canonical state, task status, errors, and cost. Do not request indexing, submit sitemaps,\nor update provider projects.\n";
 //#endregion
 //#region src/cli/preset/opencode/preset.ts
 const skill = (name, definition, executor) => ({
@@ -44372,17 +45563,17 @@ const opencodePreset = {
 	".pagegraph/opencode/opencode.jsonc": opencode_default,
 	".pagegraph/opencode/AGENTS.md": AGENTS_default,
 	".pagegraph/opencode/agents/seo.md": seo_default,
-	...skill("keyword-research", SKILL_default$4, executor_default$4),
-	...skill("competitive-landscape", SKILL_default$8, executor_default$8),
-	...skill("authority-research", SKILL_default$9, executor_default$9),
-	...skill("serp-analysis", SKILL_default$1, executor_default$1),
-	...skill("content-analysis", SKILL_default$7, executor_default$7),
-	...skill("ai-search", SKILL_default$10, executor_default$10),
-	...skill("site-architecture", SKILL_default, executor_default),
-	...skill("content-improvement", SKILL_default$6, executor_default$6),
-	...skill("metadata-improvement", SKILL_default$3, executor_default$3),
-	...skill("schema", SKILL_default$2, executor_default$2),
-	...skill("internal-linking", SKILL_default$5, executor_default$5)
+	...skill("keyword-research", SKILL_default$5, executor_default$4),
+	...skill("competitive-landscape", SKILL_default$9, executor_default$8),
+	...skill("authority-research", SKILL_default$10, executor_default$9),
+	...skill("serp-analysis", SKILL_default$2, executor_default$1),
+	...skill("content-analysis", SKILL_default$8, executor_default$7),
+	...skill("ai-search", SKILL_default$11, executor_default$10),
+	...skill("site-architecture", SKILL_default$1, executor_default),
+	...skill("content-improvement", SKILL_default$7, executor_default$6),
+	...skill("metadata-improvement", SKILL_default$4, executor_default$3),
+	...skill("schema", SKILL_default$3, executor_default$2),
+	...skill("internal-linking", SKILL_default$6, executor_default$5)
 };
 //#endregion
 //#region src/cli/commands/init.ts
@@ -44448,277 +45639,6 @@ const initCommand = make$9("init", {
 	else yield* printText(`${dryRun ? "Would create" : "Created"} ${created.length} file(s). Kept ${existing.length} existing file(s).`);
 })));
 //#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;
-/** The graph keys pages by path, so dedupe crawled URLs the same way. */
-const pageKey = (url) => normalizePath(url);
-/** Run `run` over `items` with at most `limit` in flight, preserving order. */
-const mapLimit = async (items, limit, run) => {
-	const results = Array.from({ length: items.length });
-	let index = 0;
-	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-		for (;;) {
-			const current = index++;
-			if (current >= items.length) return;
-			results[current] = await run(items[current]);
-		}
-	});
-	await Promise.all(workers);
-	return results.map((result, at) => {
-		if (result === void 0) throw new Error(`Crawl worker ${at} produced no result`);
-		return result;
-	});
-};
-/**
-* Crawl `seed`'s origin breadth-first and return one {@link RenderedPage} per
-* successfully fetched HTML page. The seed must be an absolute `http(s)` URL;
-* private and reserved destinations are rejected unless `allowPrivate` is set.
-*/
-const crawlRenderedPages = async (seed, options) => {
-	let seedUrl;
-	try {
-		seedUrl = new URL(seed);
-	} catch {
-		throw new Error(`Not a valid URL: ${seed}`);
-	}
-	if (seedUrl.protocol !== "https:" && seedUrl.protocol !== "http:") throw new Error(`Unsupported URL protocol: ${seedUrl.protocol}`);
-	if (!Number.isSafeInteger(options.limit) || options.limit < 1) throw new Error(`Crawl limit must be a positive integer: ${options.limit}`);
-	const origin = seedUrl.origin;
-	const probeOptions = {
-		allowPrivate: options.allowPrivate,
-		timeoutMs: options.timeoutMs,
-		maxBodyBytes: options.maxBodyBytes,
-		captureAnchors: true
-	};
-	const concurrency = Math.max(1, options.concurrency ?? 4);
-	const visited = /* @__PURE__ */ new Set([pageKey(seedUrl)]);
-	/** Final paths already rendered, so a redirect cannot add the same page twice. */
-	const rendered = /* @__PURE__ */ new Set();
-	const pages = [];
-	const failures = [];
-	const truncatedBodies = [];
-	let attempts = 0;
-	let truncated = false;
-	let root = pageKey(seedUrl);
-	let frontier = [{
-		url: seedUrl,
-		depth: 0
-	}];
-	const probePage = async (item) => {
-		const request = {
-			kind: "page-html",
-			method: "GET",
-			accept: "text/html, */*;q=0.1",
-			url: item.url
-		};
-		const probe = await probeHttp(request, probeOptions);
-		if (!probe.ok || probe.finalUrl === null) return {
-			item,
-			page: null,
-			failure: {
-				url: item.url.href,
-				error: probe.error ?? `HTTP ${probe.status ?? "no response"}`
-			},
-			links: [],
-			bodyTruncated: false
-		};
-		if (new URL(probe.finalUrl).origin !== origin) return {
-			item,
-			page: null,
-			failure: {
-				url: item.url.href,
-				error: `Redirected off-origin to ${probe.finalUrl}`
-			},
-			links: [],
-			bodyTruncated: false
-		};
-		const anchors = probe.anchors ?? [];
-		const links = anchors.flatMap((anchor) => {
-			if (!anchor.internal) return [];
-			let target;
-			try {
-				target = new URL(anchor.href);
-			} catch {
-				return [];
-			}
-			if (target.origin !== origin) return [];
-			if (NON_PAGE.test(target.pathname)) return [];
-			return [target];
-		});
-		return {
-			item,
-			page: {
-				url: probe.finalUrl,
-				anchors
-			},
-			failure: null,
-			links,
-			bodyTruncated: probe.bodyTruncated
-		};
-	};
-	while (frontier.length > 0) {
-		const remaining = options.limit - attempts;
-		if (remaining <= 0) {
-			truncated = true;
-			break;
-		}
-		const batch = frontier.length > remaining ? frontier.slice(0, remaining) : frontier;
-		if (frontier.length > batch.length) truncated = true;
-		frontier = [];
-		attempts += batch.length;
-		const probed = await mapLimit(batch, concurrency, probePage);
-		const discovered = [];
-		for (const result of probed) {
-			if (result.failure !== null) failures.push(result.failure);
-			if (result.page === null) continue;
-			const finalKey = pageKey(new URL(result.page.url));
-			if (result.item.depth === 0) root = finalKey;
-			if (rendered.has(finalKey)) continue;
-			rendered.add(finalKey);
-			visited.add(finalKey);
-			pages.push(result.page);
-			if (result.bodyTruncated) truncatedBodies.push(result.page.url);
-			for (const link of result.links) {
-				const key = pageKey(link);
-				if (visited.has(key)) continue;
-				visited.add(key);
-				discovered.push({
-					url: link,
-					depth: result.item.depth + 1
-				});
-			}
-		}
-		frontier = discovered;
-	}
-	return {
-		origin,
-		seed: seedUrl.href,
-		root,
-		pages,
-		failures,
-		truncatedBodies,
-		truncated,
-		limit: options.limit
-	};
-};
-//#endregion
-//#region src/core/link-candidates.ts
-/**
-* Canonical path key: query and hash stripped, trailing slashes removed, "/"
-* preserved. This is the same path key the graph and the rendered-link core
-* use, so a served anchor like `/blog/a?ref=nav` still matches the graph pair
-* `/blog/a`.
-*/
-const normalize = (path) => {
-	const trimmed = (path.split(/[?#]/, 1)[0] ?? "").replace(/\/+$/, "");
-	return trimmed === "" ? "/" : trimmed;
-};
-/** Directionless pair key, so an edge in either direction means "connected". */
-const undirectedEdgeKey = (from, to) => {
-	const [a, b] = [normalize(from), normalize(to)].sort();
-	return `${a}\u0000${b}`;
-};
-/** First path segment, or undefined for the root page. */
-const topSegment = (path) => {
-	const segment = path.split("/").filter(Boolean)[0];
-	return segment === void 0 || segment === "" ? void 0 : segment;
-};
-/** A page with no nested segment (`/`, `/pricing`, `/blog`) is root-level. */
-const isRootLevel = (path) => path.split("/").filter(Boolean).length <= 1;
-/**
-* The cluster a pair shares, or undefined when they share none. Section-first:
-* a shared top-level section wins. The kind fallback is local to root-level
-* pages, so it never pairs two nested pages from different sections.
-*/
-const clusterOf = (a, b) => {
-	const aSegment = topSegment(a.path);
-	const bSegment = topSegment(b.path);
-	if (aSegment !== void 0 && aSegment === bSegment) return {
-		key: aSegment,
-		reason: `same top-level section "/${aSegment}"`
-	};
-	if (isRootLevel(a.path) && isRootLevel(b.path) && a.kind === b.kind) return {
-		key: `kind:${a.kind}`,
-		reason: `same kind "${a.kind}"`
-	};
-};
-/** A `--cluster` filter matches a section by name, or a kind via its bare label. */
-const matchesClusterFilter = (cluster, filter) => {
-	const normalized = filter.replace(/^\/+/, "").toLowerCase();
-	const key = cluster.toLowerCase();
-	return key === normalized || key === `kind:${normalized}`;
-};
-/**
-* Enumerate reviewable contextual-link candidates from the declared graph.
-*
-* Excluded: self-pairs, pages that are not sitemap-eligible, pairs already
-* declared as a `related` edge, and — when {@link LinkCandidateOptions.renderedEdges}
-* is supplied — pairs already rendered as an anchor. Queries, hashes, and
-* trailing slashes are normalized so both sides compare by the graph's path key.
-*/
-const generateLinkCandidates = (graph, options = {}) => {
-	const limit = options.limit ?? 50;
-	const filters = options.clusters ?? [];
-	const rendered = new Set((options.renderedEdges ?? []).map((edge) => undirectedEdgeKey(edge.from, edge.to)));
-	const declared = new Set(graph.edges.filter((edge) => edge.type === "related").map((edge) => undirectedEdgeKey(edge.from, edge.to)));
-	const eligible = [...graph.nodes.values()].filter(isSitemapEligible);
-	const all = [];
-	for (let i = 0; i < eligible.length; i++) for (let j = i + 1; j < eligible.length; j++) {
-		const a = eligible[i];
-		const b = eligible[j];
-		const cluster = clusterOf(a, b);
-		if (cluster === void 0) continue;
-		if (filters.length > 0 && !filters.some((filter) => matchesClusterFilter(cluster.key, filter))) continue;
-		const key = undirectedEdgeKey(a.path, b.path);
-		if (declared.has(key) || rendered.has(key)) continue;
-		all.push({
-			source: a.path,
-			destination: b.path,
-			cluster: cluster.key,
-			reason: cluster.reason
-		});
-		all.push({
-			source: b.path,
-			destination: a.path,
-			cluster: cluster.key,
-			reason: cluster.reason
-		});
-	}
-	const compare = (x, y) => x.cluster < y.cluster ? -1 : x.cluster > y.cluster ? 1 : x.source < y.source ? -1 : x.source > y.source ? 1 : x.destination < y.destination ? -1 : x.destination > y.destination ? 1 : 0;
-	all.sort(compare);
-	const counts = /* @__PURE__ */ new Map();
-	for (const pair of all) counts.set(pair.cluster, (counts.get(pair.cluster) ?? 0) + 1);
-	const candidates = all.slice(0, limit);
-	return {
-		candidates,
-		total: all.length,
-		truncated: all.length > candidates.length,
-		clusters: [...counts.entries()].map(([key, count]) => ({
-			key,
-			candidates: count
-		}))
-	};
-};
-/**
-* Decode a rendered-edge dump supplied to the CLI: either a bare array of
-* `{ from, to }` edges, or an object carrying `edges` (or `internalEdges`).
-* Throws on any other shape — this is user input, not a provider payload.
-*/
-const decodeRenderedEdges = (input) => {
-	const array = Array.isArray(input) ? input : input !== null && typeof input === "object" && Array.isArray(input.edges) ? input.edges : input !== null && typeof input === "object" && Array.isArray(input.internalEdges) ? input.internalEdges : void 0;
-	if (array === void 0) throw new Error("expected an array of { from, to } edges, or an object with an `edges` array");
-	return array.map((item) => {
-		if (item === null || typeof item !== "object") throw new Error("each rendered edge must be an object with string `from` and `to`");
-		const { from, to } = item;
-		if (typeof from !== "string" || typeof to !== "string") throw new Error("each rendered edge must have string `from` and `to`");
-		return {
-			from,
-			to
-		};
-	});
-};
-//#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` }));
@@ -44744,6 +45664,7 @@ const analyzeDeclared = (crawlOrigin, renderedEdges, assertCoverage, crawlState)
 	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.discoveryFailures > 0 || crawlState.sitemapTruncated) return yield* new SeoCliError({ message: "Refusing to assert rendered coverage: sitemap or robots discovery was incomplete." });
 		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 = [];
@@ -44785,6 +45706,11 @@ const analyzeDeclared = (crawlOrigin, renderedEdges, assertCoverage, crawlState)
 	}
 	return yield* scoped(gen(function* () {
 		const graph = yield* acquireGraph(config);
+		if (assertCoverage && crawlState.nonHtml.length > 0) {
+			const declaredPaths = new Set([...graph.nodes.values()].filter(isSitemapEligible).map((node) => normalizePath(new URL(node.path, crawlOrigin))));
+			const missed = crawlState.nonHtml.find((item) => declaredPaths.has(normalizePath(new URL(item.url))) || declaredPaths.has(normalizePath(new URL(item.finalUrl))));
+			if (missed !== void 0) return yield* new SeoCliError({ message: `Refusing to assert rendered coverage: declared page ${missed.url} served non-HTML content.` });
+		}
 		return {
 			declaredEdges: graph.edges.filter((edge) => edge.type === "related").map((edge) => ({
 				from: edge.from,
@@ -44878,8 +45804,13 @@ const linksVerifyCommand = make$9("verify", {
 			limit: artifact.crawl.limit,
 			truncated: artifact.crawl.truncated,
 			failures: artifact.crawl.failures,
+			...artifact.crawl.nonHtml === void 0 ? {} : { nonHtml: artifact.crawl.nonHtml },
 			bodyTruncated: artifact.crawl.bodyTruncated,
-			truncatedPages: artifact.crawl.truncatedPages
+			truncatedPages: artifact.crawl.truncatedPages,
+			...artifact.crawl.discoveryFailures === void 0 ? {} : { discoveryFailures: artifact.crawl.discoveryFailures },
+			...artifact.crawl.skipped === void 0 ? {} : { skipped: artifact.crawl.skipped },
+			...artifact.crawl.sitemapTruncated === void 0 ? {} : { sitemapTruncated: artifact.crawl.sitemapTruncated },
+			...artifact.crawl.sitemapUsed === void 0 ? {} : { sitemapUsed: artifact.crawl.sitemapUsed }
 		};
 	} else {
 		const checkedLimit = yield* positive("limit", options.limit);
@@ -44904,8 +45835,13 @@ const linksVerifyCommand = make$9("verify", {
 			limit: crawl.limit,
 			truncated: crawl.truncated,
 			failures: crawl.failures,
+			nonHtml: crawl.nonHtml,
 			bodyTruncated: crawl.truncatedBodies.length > 0,
-			truncatedPages: crawl.truncatedBodies
+			truncatedPages: crawl.truncatedBodies,
+			discoveryFailures: crawl.discoveryFailures,
+			skipped: crawl.skipped,
+			sitemapTruncated: crawl.sitemapTruncated,
+			sitemapUsed: crawl.sitemapUsed
 		};
 		if (emitPath !== void 0) {
 			const artifact = {
@@ -44920,7 +45856,12 @@ const linksVerifyCommand = make$9("verify", {
 					truncated: crawl.truncated,
 					bodyTruncated: crawl.truncatedBodies.length > 0,
 					truncatedPages: crawl.truncatedBodies,
-					failures: crawl.failures
+					failures: crawl.failures,
+					nonHtml: crawl.nonHtml,
+					discoveryFailures: crawl.discoveryFailures,
+					skipped: crawl.skipped,
+					sitemapTruncated: crawl.sitemapTruncated,
+					sitemapUsed: crawl.sitemapUsed
 				},
 				nodes: graph.nodes,
 				edges: graph.internalEdges
@@ -44930,10 +45871,15 @@ const linksVerifyCommand = make$9("verify", {
 		}
 	}
 	if (crawlReport.truncatedPages.length > 0) warnings.push(`${crawlReport.truncatedPages.length} page body/bodies exceeded --max-body-bytes; anchors past the cutoff are missing.`);
+	if ((crawlReport.discoveryFailures?.length ?? 0) > 0 || crawlReport.sitemapTruncated === true) warnings.push("Sitemap or robots discovery was incomplete; rendered coverage cannot be asserted.");
+	if ((crawlReport.nonHtml?.length ?? 0) > 0) warnings.push(`${crawlReport.nonHtml.length} link-only URL(s) served non-HTML and were skipped.`);
 	const analysis = yield* analyzeDeclared(origin, renderedEdges, options.assertCoverage, {
 		truncated: crawlReport.truncated,
 		bodyTruncated: crawlReport.bodyTruncated,
-		failures: crawlReport.failures.length
+		failures: crawlReport.failures.length,
+		discoveryFailures: crawlReport.discoveryFailures?.length ?? 0,
+		sitemapTruncated: crawlReport.sitemapTruncated ?? false,
+		nonHtml: crawlReport.nonHtml ?? []
 	});
 	warnings.push(...analysis.warnings);
 	const diff = analysis.declaredEdges === void 0 ? void 0 : diffLinkGraph(analysis.declaredEdges, graph);
@@ -44971,6 +45917,10 @@ const linksVerifyCommand = make$9("verify", {
 const candidatesLimitFlag = Int("limit").pipe(withDescription$2("Maximum candidates to output after ordering"), withDefault(50));
 const clusterFlag = String$2("cluster").pipe(withDescription$2("Restrict to a cluster: a top-level section or a kind (repeatable)"), between(0, 64));
 const renderedFlag = String$2("rendered").pipe(withDescription$2("JSON file of already-rendered edges to exclude (array or { edges })"), optional$1);
+const siteFlag = String$2("site").pipe(withDescription$2("Opt in to same-origin served-content suggestions"), optional$1);
+const pageLimitFlag = Int("page-limit").pipe(withDescription$2("Maximum declared pages to probe for content (default 25)"), withDefault(25));
+const targetFlag = String$2("target").pipe(withDescription$2("Prioritize an exact target page path (repeatable)"), between(0, 64));
+const sourceFlag = String$2("source").pipe(withDescription$2("Prioritize an exact source page path (repeatable)"), between(0, 64));
 /** Read already-rendered edges from an optional JSON file; absent input is no exclusions. */
 const readRenderedEdges = (file) => file === void 0 ? succeed$2([]) : try_({
 	try: () => decodeRenderedEdges(JSON.parse(readFileSync(file, "utf8"))),
@@ -44980,7 +45930,14 @@ const linksCandidatesCommand = make$9("candidates", {
 	json: jsonFlag,
 	limit: candidatesLimitFlag,
 	cluster: clusterFlag,
-	rendered: renderedFlag
+	rendered: renderedFlag,
+	site: siteFlag,
+	pageLimit: pageLimitFlag,
+	target: targetFlag,
+	source: sourceFlag,
+	allowPrivate,
+	requestTimeoutMs,
+	maxBodyBytes
 }).pipe(withDescription$1("Propose reviewable contextual links from the declared graph, clustered and not already connected"), withExamples([
 	{
 		command: "pagegraph links candidates",
@@ -44993,12 +45950,149 @@ const linksCandidatesCommand = make$9("candidates", {
 	{
 		command: "pagegraph links candidates --rendered rendered.json --json | jq",
 		description: "Exclude anchors already served, and emit versioned JSON"
+	},
+	{
+		command: "pagegraph links candidates --site https://example.com --json",
+		description: "Rank verifiable sentence-and-anchor suggestions from served pages"
+	},
+	{
+		command: "pagegraph links candidates --site https://example.com --cluster blog --page-limit 25 --json",
+		description: "Focus a bounded probe on an editorial section when the site-wide sample is sparse"
+	},
+	{
+		command: "pagegraph links candidates --site https://example.com --target /blog/weak --json",
+		description: "Probe a weak target and its candidate source pages first"
 	}
 ]), withHandler(fn("SeoCli.linksCandidates")(function* (options) {
 	const limit = yield* positive("limit", options.limit);
+	const pageLimit = yield* positive("page-limit", options.pageLimit);
+	if (isSome(options.site) && (!Number.isSafeInteger(options.maxBodyBytes) || options.maxBodyBytes < 1 || options.maxBodyBytes > 1e7)) return yield* new SeoCliError({ message: "--max-body-bytes must be between 1 and 10000000 in site mode" });
 	const config = yield* loadSeoConfig;
 	const graph = yield* scoped(acquireGraph(config));
 	const renderedEdges = yield* readRenderedEdges(getOrUndefined$1(options.rendered));
+	const site = getOrUndefined$1(options.site);
+	if (site !== void 0) {
+		const report = yield* tryPromise({
+			try: async () => {
+				const target = new URL(site);
+				const configured = new URL(config.origin);
+				if (!["http:", "https:"].includes(target.protocol) || target.origin !== configured.origin) throw new Error(`--site origin must match seo.config.ts (${configured.origin})`);
+				const requestedTargets = new Set(options.target);
+				const requestedSources = new Set(options.source);
+				const nodes = [...graph.nodes.values()].filter(isSitemapEligible);
+				const selected = selectSuggestionPages(graph, {
+					pageLimit,
+					targets: requestedTargets,
+					sources: requestedSources,
+					clusters: options.cluster,
+					renderedEdges
+				});
+				const selectedPaths = new Set(selected.map((node) => node.path));
+				const skipped = nodes.filter((node) => !selectedPaths.has(node.path)).map((node) => ({
+					path: node.path,
+					reason: "page limit or target filter"
+				}));
+				const robots = await probeHttp({
+					kind: "robots",
+					method: "GET",
+					accept: "text/plain",
+					url: new URL("/robots.txt", configured)
+				}, {
+					sameOrigin: configured.origin,
+					allowPrivate: options.allowPrivate,
+					timeoutMs: options.requestTimeoutMs,
+					maxBodyBytes: options.maxBodyBytes,
+					captureBody: true
+				});
+				if (!robots.ok && robots.status !== 404 || robots.bodyTruncated) throw new Error("Could not establish complete robots policy for the site");
+				const rules = robots.ok ? robotsRules(robots.body ?? "").rules : [];
+				const pages = [];
+				const observed = [];
+				for (const node of selected) {
+					if (!allowedByRobots(node.path, rules)) {
+						skipped.push({
+							path: node.path,
+							reason: "robots disallow"
+						});
+						continue;
+					}
+					const url = new URL(node.path, configured);
+					const probe = await probeHttp({
+						kind: "page-html",
+						method: "GET",
+						accept: "text/html",
+						url
+					}, {
+						sameOrigin: configured.origin,
+						allowPrivate: options.allowPrivate,
+						timeoutMs: options.requestTimeoutMs,
+						maxBodyBytes: options.maxBodyBytes,
+						captureAnchors: true,
+						captureBody: true,
+						allowUrl: (next) => allowedByRobots(`${next.pathname}${next.search}`, rules)
+					});
+					const contentType = probe.responseHeaders["content-type"];
+					if (!probe.ok || probe.bodyTruncated || contentType !== void 0 && !/text\/html|application\/xhtml\+xml/i.test(contentType) || !probe.body || !probe.finalUrl || new URL(probe.finalUrl).pathname.replace(/\/+$/, "") !== node.path.replace(/\/+$/, "")) {
+						skipped.push({
+							path: node.path,
+							reason: probe.error ?? (probe.bodyTruncated ? "body truncated" : "unreadable or redirected page")
+						});
+						continue;
+					}
+					const sentences = extractPageSentences(probe.body);
+					if (sentences.length === 0) {
+						skipped.push({
+							path: node.path,
+							reason: "no readable main content"
+						});
+						continue;
+					}
+					pages.push({
+						path: node.path,
+						sentences
+					});
+					for (const anchor of probe.anchors ?? []) {
+						if (!anchor.internal) continue;
+						observed.push({
+							from: node.path,
+							to: new URL(anchor.href).pathname.replace(/\/+$/, "") || "/",
+							region: anchor.region
+						});
+					}
+				}
+				const readablePaths = new Set(pages.map((page) => page.path));
+				const scopedGraph = {
+					...graph,
+					nodes: new Map([...graph.nodes].filter(([path]) => readablePaths.has(path))),
+					edges: graph.edges.filter((edge) => readablePaths.has(edge.from) && readablePaths.has(edge.to))
+				};
+				const pairs = generateLinkCandidates(scopedGraph, {
+					clusters: options.cluster,
+					limit: Number.MAX_SAFE_INTEGER,
+					renderedEdges: [...renderedEdges, ...observed]
+				}).candidates.filter((pair) => (requestedTargets.size === 0 || requestedTargets.has(pair.destination)) && (requestedSources.size === 0 || requestedSources.has(pair.source)));
+				const inbound = /* @__PURE__ */ new Map();
+				for (const edge of [...graph.edges.filter((edge) => edge.type === "related"), ...observed.filter((edge) => edge.region === "body")]) inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1);
+				const ranked = rankLinkSuggestions(pairs, pages, inbound, limit);
+				return {
+					kind: "links-candidates",
+					schemaVersion: 2,
+					origin: configured.origin,
+					limit,
+					pageLimit,
+					maxBodyBytes: options.maxBodyBytes,
+					total: ranked.total,
+					truncated: ranked.total > ranked.candidates.length || skipped.some((item) => item.reason === "page limit or target filter"),
+					skipped,
+					candidates: ranked.candidates
+				};
+			},
+			catch: (cause) => new SeoCliError({ message: `Could not produce site suggestions: ${messageOf(cause)}` })
+		});
+		if (options.json) yield* printJson(report);
+		else yield* printText(`${report.total} content-backed suggestion(s) · ${report.skipped.length} page(s) skipped\n\n${report.candidates.map((item) => `${item.source} → ${item.destination} (score ${item.score})\n  ${item.sentence}\n  Anchor: ${item.anchor}\n  Target: ${item.targetSentence}\n  ${item.reason}`).join("\n\n")}`);
+		return;
+	}
 	const result = generateLinkCandidates(graph, {
 		limit,
 		clusters: options.cluster,
@@ -45029,6 +46123,7 @@ const writeFlags = {
 	dryRun: dryRunFlag$1,
 	allowDirty: allowDirtyFlag$1
 };
+const allowPrivateFlag = Boolean$1("allow-private").pipe(withDescription$2("Allow localhost/private site probes for suggestion freshness (local development only)"), withDefault(false));
 /** File-writing content, metadata, schema, and link workflows. */
 const improveCommandGroup = make$9("improve").pipe(withDescription$1("Apply page-backed SEO improvements through the configured OpenCode agent"), withSubcommands([
 	workflowCommand({
@@ -45075,6 +46170,8 @@ const improveCommandGroup = make$9("improve").pipe(withDescription$1("Apply page
 		description: "Add contextual internal links and update PageGraph declarations when appropriate",
 		flags: {
 			...baseFlags,
+			suggestions: suggestionsFlag,
+			allowPrivate: allowPrivateFlag,
 			dryRun: writeFlags.dryRun,
 			allowDirty: writeFlags.allowDirty
 		},
@@ -45134,6 +46231,51 @@ const sitemapCommand = make$9("sitemap", {
 	}));
 })));
 //#endregion
+//#region src/cli/commands/skills.ts
+const skills = { core: "---\nname: core\ndescription: Use when adding Pagegraph to a TanStack Start app or changing its SEO wiring — staticData.seo declarations, seoHead in route head(), typed related links, content collections, the seoRouteConfig coverage gate, seo.config.ts, sitemap and robots routes — or when a `pagegraph check`, coverage, or rendered-head failure needs diagnosing.\n---\n\n# Pagegraph and TanStack Start\n\nEach route declares its SEO policy once in `staticData.seo`; Pagegraph derives the sitemap, robots, breadcrumbs, JSON-LD, related links, and `pagegraph check` from those declarations. TanStack Start still owns routing and the document shell. This skill ships inside the Pagegraph CLI that printed it, so it matches that version. Run the app's installed binary (`bunx pagegraph` from the app root) so the guidance and the types agree.\n\nBefore editing, read the app's `package.json`, `src/routes/`, `src/routeTree.gen.ts`, any existing `seo.config.ts`, and `vite.config.ts`. Adapt the paths below to the app's layout.\n\n## Wire it up\n\n**1. Bind site identity and typed paths once.** Route files never repeat the origin or brand.\n\n```ts\n// src/lib/seo.ts\nimport { createSeo } from \"pagegraph/react\";\nimport type { FileRouteTypes } from \"../routeTree.gen\";\n\ndeclare module \"pagegraph\" {\n  interface Register {\n    paths: FileRouteTypes[\"fullPaths\"];\n    kinds: \"page\" | \"article\" | \"hub\";\n  }\n}\n\nexport const { seoHead } = createSeo({\n  origin: \"https://example.com\",\n  site: {\n    name: \"Example\",\n    logo: \"/logo.png\",\n    publisherLogo: \"/publisher.png\",\n    defaultImage: \"/og.png\",\n    defaultAuthor: { name: \"Example Team\" },\n  },\n  organization: {\n    description: \"What the company does.\",\n    sameAs: [],\n    contactPoint: { contactType: \"support\", email: \"support@example.com\" },\n  },\n  website: { searchPath: \"/search?q={search_term_string}\" },\n});\n```\n\nThe `Register` augmentation is what types `staticData.seo` on TanStack routes and checks `related` and `redirectTo` against real paths, so a renamed route becomes a compile error. `kinds` is the app's own taxonomy; nothing branches on it.\n\n**2. Declare policy on the route, content in `head()`.**\n\n```tsx\n// src/routes/(marketing)/pricing.tsx\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport { seoHead } from \"../../lib/seo\";\n\nexport const Route = createFileRoute(\"/(marketing)/pricing\")({\n  staticData: {\n    seo: {\n      kind: \"page\",\n      crumb: \"Pricing\",\n      sitemap: { priority: 0.9, changeFrequency: \"monthly\" },\n      related: [\"/features\"],\n      link: { title: \"Pricing\", description: \"Simple volume pricing.\" },\n    },\n  },\n  head: (ctx) =>\n    seoHead(ctx, {\n      title: \"Pricing — Example\",\n      description: \"Simple volume pricing.\",\n    }),\n  component: PricingPage,\n});\n```\n\n- `staticData.seo` is static crawl policy and graph edges: `kind`, `crumb`, `sitemap` (or `false`), `robots`, `related`, `link`, `redirectTo`.\n- `seoHead(ctx, instance)` takes the full `title` (no suffix is added) and `description`, and optionally `article`, `faqs`, `service`, `itemList`, `jsonLd`, `canonicalPath`, and `breadcrumbs`. It returns `meta` and a canonical `links` entry for TanStack to render; the document shell must keep `<HeadContent />` and `<Scripts />`.\n- `link` is how other pages render a card for this route. Add it to every route that appears in someone's `related`.\n- Declare `related` only for links the page actually renders in its body.\n- `crumb` accepts `(match) => string` for dynamic segments, such as a title from `loaderData`.\n\n**3. Export one graph loader.** The CLI, sitemap, and robots all read it.\n\n```ts\n// src/lib/seo/graph.ts\nimport { buildSeoGraph } from \"pagegraph\";\nimport { routeTree } from \"../../routeTree.gen\";\nimport { posts } from \"../content/posts\"; // the app's own content source\n\nexport const loadSeoGraph = async () =>\n  buildSeoGraph({\n    routeTree,\n    collections: [\n      {\n        route: \"/blog/$slug\",\n        source: \"blog\",\n        instances: posts.map((post) => ({\n          path: `/blog/${post.slug}`,\n          title: post.title,\n          description: post.description,\n          publishedAt: post.date,\n        })),\n      },\n    ],\n  });\n```\n\nA param route such as `/blog/$slug` never enters the sitemap itself; list its pages as a collection. Instances inherit the param route's `kind` and `sitemap`, so declare those on `/blog/$slug`. Omit `collections` when every public page is a static route.\n\n**4. Point the CLI at the loader** with `seo.config.ts` at the app root:\n\n```ts\n// seo.config.ts\nimport { defineSeoConfig, viteGraphLoader } from \"pagegraph/config\";\n\nexport default defineSeoConfig({\n  origin: \"https://example.com\",\n  disallow: [\"/dashboard\", \"/api\"],\n  loadGraph: viteGraphLoader({\n    root: import.meta.dirname,\n    entry: \"/src/lib/seo/graph.ts\",\n    exportName: \"loadSeoGraph\",\n  }),\n});\n```\n\n`entry` is root-relative and evaluated in a headless Vite server, so aliases and content plugins resolve as they do in the app. Optional fields: `contentSignal`, `coverage` (`[{ path, minInbound }]`, contextual-link minimums enforced by `check`), `directives`, and `transform`.\n\n**5. Serve the projections.** In Start server routes, return `renderSitemap(graph, { origin, indexable })` and `renderRobots(graph, { origin, indexable, disallow, contentSignal })` from `pagegraph`. On preview deployments, pass `indexable: false` so robots.txt disallows everything; the sitemap body does not change.\n\n**6. Optionally gate coverage at build time.**\n\n```ts\n// vite.config.ts\nimport { fileURLToPath } from \"node:url\";\nimport { tanstackStart } from \"@tanstack/react-start/plugin/vite\";\nimport { defineConfig } from \"vite\";\nimport { seoRouteConfig } from \"pagegraph/vite\";\n\nexport default defineConfig({\n  plugins: [\n    tanstackStart(),\n    // Runs its own route parse; it does not replace the Start plugin.\n    seoRouteConfig({\n      outputPath: fileURLToPath(new URL(\"./src/lib/route-config.ts\", import.meta.url)),\n      publicGroups: [\"(marketing)\"],\n      enforceCoverageIn: [\"(marketing)\"],\n      alwaysDisallow: [\"/dashboard\", \"/api\"],\n    }),\n  ],\n});\n```\n\nThis plugin fails dev startup and `vite build` when a page leaf in an enforced group has neither `staticData` nor `head`. It writes `robotsExclusions` and `reservedSegments` to `outputPath`. Feed `robotsExclusions` into `seo.config.ts` `disallow` and `renderRobots` instead of repeating the list.\n\n## Rules that bite\n\n- `robots` values must be lowercase (`\"noindex, follow\"`). The sitemap projection matches `noindex` literally, so `check` rejects mixed case.\n- A route with `robots` containing `noindex` or with `redirectTo` must not declare a positive `sitemap`. Use `sitemap: false` or omit it.\n- A `related` target route without `link` fails `check`. Collection instances are exempt because their card uses the instance `title` and `description`.\n- Coverage enforcement sees only route files inside the named group folders. `route.tsx` layouts, `.ts` server routes, and ungrouped routes are not checked. List ungrouped public routes in `extraPublicRoutes`.\n- `seoRouteConfig` throws if the directory of `outputPath` does not exist. Point it outside `src/routes` so the route watcher does not loop.\n- The graph knows route declarations and collection instances, not `head()` output. Editorial title and description checks cover instances only. A route's rendered title is verified only by inspecting HTML.\n- Keep indexable pages server-rendered or prerendered. An `ssr: false` route's head is not in the served HTML.\n\n## Verify\n\n| Changed | Run | Proves |\n| --- | --- | --- |\n| Declarations, collections, `seo.config.ts` | `pagegraph check` | No structural violations (exit 1 otherwise); editorial findings are reported but do not fail |\n| Graph shape | `pagegraph graph`, `pagegraph inspect /path` | Nodes, edges, and a page's sitemap status |\n| Sitemap or robots wiring | `pagegraph sitemap`, `pagegraph robots` | The projections from the declared graph |\n| `head()`, `seoHead` input, document shell | `pagegraph inspect <full-url> --live` against a running server | The served `<head>` and JSON-LD |\n| Rendered links vs `related` | `pagegraph links verify <url>` (add `--assert-coverage` for `coverage` rules) | What a crawler receives, not what was declared |\n| Coverage gate | `vite build` | Every enforced page leaf declares SEO |\n\nA passing `check` says nothing about served HTML. Verify head changes with `inspect --live` or a rendered-head test. Add `--json` when a script consumes the output. Stdout carries the data and stderr carries status. Check the exit code as well as the output.\n" };
+const nameArgument = String$1("name").pipe(withDescription("Bundled skill name from `pagegraph skills list`"));
+const listCommand = make$9("list", { json: jsonFlag }).pipe(withDescription$1("List skills embedded in this Pagegraph CLI"), withExamples([{
+	command: "pagegraph skills list",
+	description: "List embedded skills"
+}, {
+	command: "pagegraph skills list --json",
+	description: "List skill names as JSON"
+}]), withHandler(fnUntraced(function* ({ json }) {
+	const names = Object.keys(skills);
+	if (json) return yield* printJson({
+		schemaVersion: 1,
+		skills: names
+	});
+	return yield* printText(names.join("\n"));
+})));
+const getCommand = make$9("get", {
+	name: nameArgument,
+	json: jsonFlag
+}).pipe(withDescription$1("Print a skill embedded in this Pagegraph CLI"), withExamples([{
+	command: "pagegraph skills get core",
+	description: "Read Pagegraph integration guidance"
+}, {
+	command: "pagegraph skills get core --json",
+	description: "Read the skill as JSON"
+}]), withHandler(fnUntraced(function* ({ name, json }) {
+	if (!Object.hasOwn(skills, name)) return yield* new SeoCliError({ message: `Unknown skill "${name}". Run \`pagegraph skills list\` to see available names.` });
+	const content = skills[name];
+	if (json) return yield* printJson({
+		schemaVersion: 1,
+		name,
+		content
+	});
+	return yield* printText(content.trimEnd());
+})));
+/** Serve Pagegraph's version-matched agent guidance from the installed CLI. */
+const skillsCommand = make$9("skills").pipe(withDescription$1("List and read skills embedded in Pagegraph"), withExamples([{
+	command: "pagegraph skills list",
+	description: "Discover embedded skills"
+}, {
+	command: "pagegraph skills get core",
+	description: "Read the integration skill"
+}]), withSubcommands([listCommand, getCommand]));
+//#endregion
 //#region src/cli/cli.ts
 /**
 * Root `pagegraph` command. Every subcommand reads the same SEO graph that render
@@ -45154,6 +46296,10 @@ const cli = make$9("pagegraph").pipe(withDescription$1("Inspect, audit, research
 		command: "pagegraph graph",
 		description: "Print the SEO graph as a tree"
 	},
+	{
+		command: "pagegraph skills get core",
+		description: "Read bundled agent guidance"
+	},
 	{
 		command: "pagegraph sitemap",
 		description: "Render sitemap.xml"
@@ -45175,6 +46321,7 @@ const cli = make$9("pagegraph").pipe(withDescription$1("Inspect, audit, research
 	researchCommandGroup,
 	checkCommand,
 	sitemapCommand,
+	skillsCommand,
 	robotsCommand
 ]));
 //#endregion