pagegraph 0.11.0 → 0.12.0

package/dist/cli.js

@@ -35946,7 +35946,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.11.0";
+var version = "0.12.0";
 //#endregion
 //#region src/core/links.ts
 const TOKEN = /<(\/?)(nav|footer|header)\b[^>]*>|<a\b([^>]*)>([\s\S]*?)<\/a>/gi;
@@ -38254,7 +38254,7 @@ const isWorkflowConfig = (value) => {
 * an undefined `origin` would otherwise surface as "undefined/pricing" in a
 * rendered sitemap rather than as an error here.
 */
-const isSeoCliConfig = (value) => isObject$1(value) && isFunction(value["loadGraph"]) && isString(value["origin"]) && isStringArray(value["disallow"]) && (value["contentSignal"] === void 0 || isString(value["contentSignal"])) && (value["directives"] === void 0 || isStringArray(value["directives"])) && (value["transform"] === void 0 || isFunction(value["transform"])) && (value["coverage"] === void 0 || isCoverageRules(value["coverage"])) && (value["content"] === void 0 || isContentPolicy(value["content"])) && (value["freshness"] === void 0 || isFreshnessPolicy(value["freshness"])) && (value["workflows"] === void 0 || isWorkflowConfig(value["workflows"]));
+const isSeoCliConfig = (value) => isObject$1(value) && isFunction(value["loadGraph"]) && isString(value["origin"]) && (value["disallow"] === void 0 || isStringArray(value["disallow"])) && (value["contentSignal"] === void 0 || isString(value["contentSignal"])) && (value["directives"] === void 0 || isStringArray(value["directives"])) && (value["transform"] === void 0 || isFunction(value["transform"])) && (value["coverage"] === void 0 || isCoverageRules(value["coverage"])) && (value["content"] === void 0 || isContentPolicy(value["content"])) && (value["freshness"] === void 0 || isFreshnessPolicy(value["freshness"])) && (value["workflows"] === void 0 || isWorkflowConfig(value["workflows"]));
 /** Import and validate one config path. */
 const loadConfigFile = (configPath) => gen(function* () {
 	yield* logDebug(`Loading SEO config from ${configPath}`);
@@ -38262,7 +38262,7 @@ const loadConfigFile = (configPath) => gen(function* () {
 		try: () => import(pathToFileURL(configPath).href),
 		catch: (cause) => new SeoCliError({ message: `Could not load ${configPath}: ${messageOf$2(cause)}` })
 	});
-	if (!isSeoCliConfig(module.default)) return yield* new SeoCliError({ message: `${configPath} must default-export defineSeoConfig({ origin, disallow, loadGraph }).` });
+	if (!isSeoCliConfig(module.default)) return yield* new SeoCliError({ message: `${configPath} must default-export defineSeoConfig({ origin, loadGraph }).` });
 	return module.default;
 });
 /**
@@ -38272,7 +38272,7 @@ const loadConfigFile = (configPath) => gen(function* () {
 const loadSeoConfig = gen(function* () {
 	const cwd = process.cwd();
 	const configPath = findConfigFile(cwd);
-	if (configPath === void 0) return yield* new SeoCliError({ message: `No ${CONFIG_FILENAMES[0]} in ${cwd} or any parent directory. Create one that exports \`defineSeoConfig({ origin, disallow, loadGraph })\` from "pagegraph/config".` });
+	if (configPath === void 0) return yield* new SeoCliError({ message: `No ${CONFIG_FILENAMES[0]} in ${cwd} or any parent directory. Create one that exports \`defineSeoConfig({ origin, loadGraph })\` from "pagegraph/config".` });
 	return yield* loadConfigFile(configPath);
 });
 /** Load the config together with the project root that owns it. */
@@ -38302,15 +38302,17 @@ const loadSeoConfigOptional = gen(function* () {
 * {@link viteGraphLoader}, an in-process Vite server) is released when the
 * surrounding `Effect.scoped` exits, on success or failure.
 */
-const acquireGraph = (config) => gen(function* () {
+const acquireLoadedGraph = (config) => gen(function* () {
 	yield* logDebug("Loading the SEO graph…");
 	const loaded = yield* acquireRelease(tryPromise({
 		try: () => config.loadGraph(),
 		catch: (cause) => new SeoCliError({ message: messageOf$2(cause) })
 	}), (acquired) => promise(() => acquired.dispose()).pipe(catchDefect((defect) => logWarning(`Could not dispose the SEO graph loader: ${messageOf$2(defect)}`))));
 	yield* logDebug(`Loaded SEO graph: ${loaded.graph.nodes.size} nodes, ${loaded.graph.edges.length} edges.`);
-	return loaded.graph;
+	return loaded;
 });
+/** {@link acquireLoadedGraph}, for commands that need only the graph. */
+const acquireGraph = (config) => map$5(acquireLoadedGraph(config), (loaded) => loaded.graph);
 //#endregion
 //#region src/cli/render.ts
 /** Count of edges pointing *at* each node — 0 means nothing links to it. */
@@ -40581,11 +40583,22 @@ const loadWorkflowOpenCode = async () => {
 };
 //#endregion
 //#region src/workflows/opencode.ts
-var MissingExecutorEvidenceError = class extends Error {
+var WorkflowHostError = class extends Error {
+	sessionId;
+	transcript;
+	constructor(message, sessionId, transcript, cause) {
+		super(message, { cause });
+		this.sessionId = sessionId;
+		this.transcript = transcript;
+		this.name = "WorkflowHostError";
+	}
+};
+var MissingExecutorEvidenceError = class extends WorkflowHostError {
 	result;
 	constructor(result) {
-		super(`The SEO agent returned without the required Executor evidence (searches: ${result.executor.searches.length}, calls: ${result.executor.calls.length}).`);
+		super(`The SEO agent returned without the required Executor evidence (searches: ${result.executor.searches.length}, calls: ${result.executor.calls.length}).`, result.sessionId, result.transcript, void 0);
 		this.result = result;
+		this.name = "MissingExecutorEvidenceError";
 	}
 };
 const requireExecutorEvidence = async (result, recover) => {
@@ -40653,15 +40666,18 @@ const parseWorkflowState = (transcript) => {
 			return isSome(text) && text.value.text.includes("{") ? [text.value.text] : [];
 		});
 	});
+	let parseCause;
 	for (const text of candidates.reverse()) {
 		const start = text.indexOf("{");
 		const end = text.lastIndexOf("}");
 		if (start === -1 || end <= start) continue;
 		try {
 			return JSON.parse(text.slice(start, end + 1));
-		} catch {}
+		} catch (cause) {
+			parseCause = cause;
+		}
 	}
-	throw new Error("The SEO agent did not return a valid workflow JSON object.");
+	throw new Error("The SEO agent did not return a valid workflow JSON object.", { cause: parseCause });
 };
 const parseWorkflowStateWithRepair = async (transcript, repair) => {
 	try {
@@ -40669,12 +40685,16 @@ const parseWorkflowStateWithRepair = async (transcript, repair) => {
 			state: parseWorkflowState(transcript),
 			transcript
 		};
-	} catch {
-		const repaired = await repair();
-		return {
-			state: parseWorkflowState(repaired),
-			transcript: repaired
-		};
+	} catch (firstError) {
+		try {
+			const repaired = await repair();
+			return {
+				state: parseWorkflowState(repaired),
+				transcript: repaired
+			};
+		} catch (repairError) {
+			throw new AggregateError([firstError, repairError], "The SEO agent did not return valid workflow JSON after one repair.", { cause: repairError });
+		}
 	}
 };
 const STATE_REPAIR_PROMPT = [
@@ -40925,70 +40945,93 @@ const acquireWorkflowHost = async (options) => {
 		const location = { directory: options.root };
 		if (!await waitForActiveExecutorPlugin({ list: async () => (await openCodeOperation("GET /api/plugin (plugin.list)", () => host.plugin.list({ location }))).data })) throw new Error(`No active Executor plugin was discovered in ${configDirectory}; agentic SEO workflows require Executor.`);
 		const cursors = /* @__PURE__ */ new Map();
+		const transcripts = /* @__PURE__ */ new Map();
 		const complete = async (sessionId, prompt, workflowOptions) => {
-			assertWorkflowSkillsAvailable(configDirectory, workflowOptions.skills);
-			if (workflowOptions.permissions !== void 0) await host.sessions.update({
-				sessionID: sessionId,
-				permissions: [...workflowOptions.permissions]
-			});
-			const configuredTimeoutMs = options.timeoutMs ?? options.config.timeoutMs ?? 18e4;
-			const deadline = Date.now() + configuredTimeoutMs;
-			const remaining = () => Math.max(0, deadline - Date.now());
-			const activity = {
-				modelSteps: 0,
-				completedTools: 0,
-				toolNames: /* @__PURE__ */ new Map()
-			};
-			let cursor = await runWorkflowTurn(host, sessionId, prompt, {
-				timeoutMs: remaining(),
-				configuredTimeoutMs,
-				stage: "prompt admission",
-				after: cursors.get(sessionId),
-				skills: workflowOptions.skills,
-				activity
-			});
-			cursors.set(sessionId, cursor);
-			let transcript = await host.sessions.export({
-				sessionID: sessionId,
-				sanitize: false
-			});
-			const parsed = await parseWorkflowStateWithRepair(transcript, async () => {
-				const priorPermissions = [...workflowOptions.permissions ?? []];
-				await host.sessions.update({
+			let transcript = transcripts.get(sessionId) ?? { messages: [] };
+			try {
+				assertWorkflowSkillsAvailable(configDirectory, workflowOptions.skills);
+				if (workflowOptions.permissions !== void 0) await host.sessions.update({
 					sessionID: sessionId,
-					permissions: [{
-						action: "*",
-						resource: "*",
-						effect: "deny"
-					}]
+					permissions: [...workflowOptions.permissions]
 				});
-				try {
-					cursor = await runWorkflowTurn(host, sessionId, STATE_REPAIR_PROMPT, {
-						timeoutMs: remaining(),
-						configuredTimeoutMs,
-						stage: "workflow state repair",
-						after: cursor,
-						activity
+				const configuredTimeoutMs = options.timeoutMs ?? options.config.timeoutMs ?? 18e4;
+				const deadline = Date.now() + configuredTimeoutMs;
+				const remaining = () => Math.max(0, deadline - Date.now());
+				const activity = {
+					modelSteps: 0,
+					completedTools: 0,
+					toolNames: /* @__PURE__ */ new Map()
+				};
+				let cursor = await runWorkflowTurn(host, sessionId, prompt, {
+					timeoutMs: remaining(),
+					configuredTimeoutMs,
+					stage: "prompt admission",
+					after: cursors.get(sessionId),
+					skills: workflowOptions.skills,
+					activity
+				});
+				cursors.set(sessionId, cursor);
+				transcript = await host.sessions.export({
+					sessionID: sessionId,
+					sanitize: false
+				});
+				transcripts.set(sessionId, transcript);
+				const parsed = await parseWorkflowStateWithRepair(transcript, async () => {
+					const priorPermissions = [...workflowOptions.permissions ?? []];
+					await host.sessions.update({
+						sessionID: sessionId,
+						permissions: [{
+							action: "*",
+							resource: "*",
+							effect: "deny"
+						}]
 					});
-					cursors.set(sessionId, cursor);
+					let repairFailed = false;
+					try {
+						cursor = await runWorkflowTurn(host, sessionId, STATE_REPAIR_PROMPT, {
+							timeoutMs: remaining(),
+							configuredTimeoutMs,
+							stage: "workflow state repair",
+							after: cursor,
+							activity
+						});
+						cursors.set(sessionId, cursor);
+						transcript = await host.sessions.export({
+							sessionID: sessionId,
+							sanitize: false
+						});
+						transcripts.set(sessionId, transcript);
+						return transcript;
+					} catch (cause) {
+						repairFailed = true;
+						throw cause;
+					} finally {
+						try {
+							await host.sessions.update({
+								sessionID: sessionId,
+								permissions: priorPermissions
+							});
+						} catch (cause) {
+							if (!repairFailed) throw cause;
+						}
+					}
+				});
+				return {
+					state: parsed.state,
+					sessionId,
+					transcript: parsed.transcript,
+					executor: collectExecutorEvidence(parsed.transcript)
+				};
+			} catch (cause) {
+				try {
 					transcript = await host.sessions.export({
 						sessionID: sessionId,
 						sanitize: false
-					});
-					return transcript;
-				} finally {
-					await host.sessions.update({
-						sessionID: sessionId,
-						permissions: priorPermissions
-					});
-				}
-			});
-			return {
-				state: parsed.state,
-				sessionId,
-				transcript: parsed.transcript,
-				executor: collectExecutorEvidence(parsed.transcript)
-			};
+					}, { signal: AbortSignal.timeout(5e3) });
+				} catch {}
+				transcripts.set(sessionId, transcript);
+				throw new WorkflowHostError(openCodeErrorMessage(cause), sessionId, transcript, cause);
+			}
 		};
 		return {
 			model,
@@ -41010,7 +41053,9 @@ const acquireWorkflowHost = async (options) => {
 			close: () => host.close()
 		};
 	} catch (cause) {
-		await host.close();
+		try {
+			await host.close();
+		} catch {}
 		throw cause;
 	}
 };
@@ -44817,13 +44862,33 @@ const writeResearchCheckpoint = (root, runsDirectory, checkpoint) => {
 	writeFileSync(path, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
 	return path;
 };
-const writeResearchFailure = (root, runsDirectory, id, details) => {
+const writeWorkflowFailure = (root, runsDirectory, id, details) => {
 	const directory = resolve(root, runsDirectory, id);
 	mkdirSync(directory, { recursive: true });
-	const path = resolve(directory, "research-failure.json");
+	const path = resolve(directory, "failure.json");
 	writeFileSync(path, `${JSON.stringify(details, null, 2)}\n`, "utf8");
 	return path;
 };
+const serializeCause = (value, top = true, seen = /* @__PURE__ */ new Set()) => {
+	if (seen.has(value)) return {
+		name: "CircularCause",
+		message: "Circular error cause"
+	};
+	if (value !== null && typeof value === "object") {
+		seen.add(value);
+		return {
+			message: value instanceof Error ? value.message : "message" in value ? String(value.message) : JSON.stringify(value),
+			name: value instanceof Error ? value.name : "name" in value ? String(value.name) : "Error",
+			...top && value instanceof Error ? { stack: value.stack } : {},
+			..."cause" in value ? { cause: serializeCause(value.cause, false, seen) } : {},
+			...value instanceof AggregateError ? { errors: value.errors.map((error) => serializeCause(error, false, new Set(seen))) } : {}
+		};
+	}
+	return {
+		name: "Error",
+		message: String(value)
+	};
+};
 //#endregion
 //#region node_modules/effect/dist/ai/Decision.js
 /**
@@ -45151,8 +45216,8 @@ const runDecisions = (options) => gen(function* () {
 //#endregion
 //#region src/workflows/specs/types.ts
 const defineWorkflow = (definition) => {
-	const decodeState = decodeUnknownSync(definition.stateSchema);
-	const decodeInput = decodeUnknownSync(definition.family.input);
+	const decodeState = decodeUnknownSync(definition.stateSchema, { errors: "all" });
+	const decodeInput = decodeUnknownSync(definition.family.input, { errors: "all" });
 	const inputsFrom = (state) => definition.decisionInputs(decodeState(state));
 	const decodedInputs = (inputs) => inputs.map((input) => decodeInput(input));
 	const decodeDecisionMetadata = decodeUnknownSync(Struct({
@@ -46243,6 +46308,11 @@ const defaultDecide = async (inputs, spec) => {
 		});
 	}).pipe(provide(layer$14)));
 };
+const dropNulls = (value) => {
+	if (Array.isArray(value)) return value.filter((item) => item !== null).map(dropNulls);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== null).map(([key, item]) => [key, dropNulls(item)]));
+	return value;
+};
 const capState = (state, limit) => {
 	if (state === null || typeof state !== "object" || Array.isArray(state)) return state;
 	const record = state;
@@ -46291,236 +46361,270 @@ const runWorkflow = async (input, dependencies = {}) => {
 	const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
 	const started = now();
 	const id = createRunId(started, spec.id);
-	const gitAtStart = inspectGit(input.root);
-	const mutation = createWorkflowMutationPolicy({
-		root: input.root,
-		dirtyAtStart: gitAtStart.dirty,
-		dryRun: spec.mutatesFiles ? input.options.dryRun : true,
-		allowDirty: input.options.allowDirty
-	});
-	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,
-		model: input.model ?? workflows.opencode.models?.[spec.id]
-	});
+	const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
+	let stage = "acquire";
+	let sessionId;
+	let transcript = null;
+	const retainResult = (result) => {
+		sessionId = result.sessionId;
+		transcript = result.transcript;
+	};
 	try {
-		const researchPermissions = repositoryMutationPermissionRules(input.root);
-		const actionPermissions = spec.mutatesFiles && !input.options.dryRun ? mutation.sessionPermissions : researchPermissions;
-		let researched;
+		const gitAtStart = inspectGit(input.root);
+		const mutation = createWorkflowMutationPolicy({
+			root: input.root,
+			dirtyAtStart: gitAtStart.dirty,
+			dryRun: spec.mutatesFiles ? input.options.dryRun : true,
+			allowDirty: input.options.allowDirty
+		});
+		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,
+			model: input.model ?? workflows.opencode.models?.[spec.id]
+		});
+		let turnFailed = false;
 		try {
-			researched = await host.research(researchPrompt(spec, suppliedEvidence, input.options), {
+			const researchPermissions = repositoryMutationPermissionRules(input.root);
+			const actionPermissions = spec.mutatesFiles && !input.options.dryRun ? mutation.sessionPermissions : researchPermissions;
+			stage = "research";
+			let researched = await host.research(researchPrompt(spec, suppliedEvidence, input.options), {
 				skills: spec.skills,
 				permissions: researchPermissions
 			});
-		} catch (cause) {
-			if (cause instanceof MissingExecutorEvidenceError) {
-				const path = writeResearchFailure(input.root, input.out ?? workflows.runsDirectory ?? ".pagegraph/runs", id, {
-					message: cause.message,
-					...cause.result
-				});
-				throw new Error(`${cause.message}\nResearch failure: ${path}`, { cause });
-			}
-			throw cause;
-		}
-		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) => {
-			const decoded = spec.decodeState(capState(value, input.options.limit));
-			for (const item of spec.decisionInputs(decoded)) {
-				const error = spec.validateDecisionInput(item);
-				if (error !== void 0) throw new Error(error);
-			}
-			return decoded;
-		};
-		let state;
-		try {
-			state = decodeResearchState(researched.state);
-		} catch (firstError) {
-			const original = researched;
-			let repaired;
+			retainResult(researched);
+			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) => {
+				const decoded = spec.decodeState(capState(dropNulls(value), input.options.limit));
+				const issues = [];
+				for (const [index, item] of spec.decisionInputs(decoded).entries()) try {
+					const error = spec.validateDecisionInput(item);
+					if (error !== void 0) issues.push(`decisionInputs[${index}]: ${error}`);
+				} catch (cause) {
+					issues.push(`decisionInputs[${index}]: ${cause instanceof Error ? cause.message : String(cause)}`);
+				}
+				if (issues.length > 0) throw new Error(issues.join("\n"));
+				return decoded;
+			};
+			let state;
 			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 runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
-		const checkpoint = {
-			kind: "pagegraph-workflow-research-checkpoint",
-			schemaVersion: 1,
-			id,
-			workflow: spec.id,
-			startedAt: started.toISOString(),
-			checkpointedAt: now().toISOString(),
-			project: {
-				root: input.root,
-				head: gitAtStart.head,
-				dirtyAtStart: gitAtStart.dirty,
-				filesAtStart: gitAtStart.files
-			},
-			options: input.options,
-			evidence: {
-				...suppliedEvidence,
-				executor: researched.executor
-			},
-			state,
-			decisionInputs,
-			opencode: {
-				agent: "seo",
-				sessionId: researched.sessionId,
-				model: host.model,
-				transcript: researched.transcript
-			}
-		};
-		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.`);
+				state = decodeResearchState(researched.state);
+			} catch (firstError) {
+				stage = "repair";
+				try {
+					const 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
+					});
+					retainResult(repaired);
+					assertResearchReadOnly();
+					state = decodeResearchState(repaired.state);
+					researched = repaired;
+				} catch (repairError) {
+					throw new Error(`${spec.id} research state failed schema validation after one read-only repair.`, { cause: new AggregateError([firstError, repairError], "Research decode and repair failed", { cause: repairError }) });
 				}
 			}
-			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 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");
 				}
-			};
-			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",
+			}
+			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: {
 					...suppliedEvidence,
-					executor: acted.executor
+					executor: researched.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,
+				state,
+				decisionInputs,
 				opencode: {
 					agent: "seo",
-					sessionId: acted.sessionId,
-					transcript: acted.transcript
+					sessionId: researched.sessionId,
+					model: host.model,
+					transcript: researched.transcript
 				}
 			};
-			return {
-				run,
-				directory: writeRunBundle(input.root, runsDirectory, run)
-			};
+			const checkpointPath = writeResearchCheckpoint(input.root, runsDirectory, checkpoint);
+			const gitAtCheckpoint = inspectGit(input.root);
+			stage = "decide";
+			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);
+				if (mayAct) stage = "action";
+				const acted = mayAct ? await host.continue(researched.sessionId, actionPrompt(spec, actionState, actionDecisions, mutation), {
+					skills: spec.skills,
+					permissions: actionPermissions
+				}) : researched;
+				retainResult(acted);
+				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 });
+			}
 		} catch (cause) {
-			const message = cause instanceof Error ? cause.message : String(cause);
-			throw new Error(`${message}\nResearch checkpoint: ${checkpointPath}`, { cause });
+			turnFailed = true;
+			throw cause;
+		} finally {
+			try {
+				await host.close();
+			} catch (cause) {
+				if (!turnFailed) throw cause;
+			}
 		}
-	} finally {
-		await host.close();
+	} catch (cause) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = cause;
+		while (current instanceof Error && !seen.has(current)) {
+			seen.add(current);
+			if (current instanceof WorkflowHostError) {
+				sessionId = current.sessionId;
+				transcript = current.transcript;
+				break;
+			}
+			current = current.cause;
+		}
+		const message = cause instanceof Error ? cause.message : String(cause);
+		let path;
+		try {
+			path = writeWorkflowFailure(input.root, runsDirectory, id, {
+				kind: "pagegraph-workflow-failure",
+				schemaVersion: 1,
+				id,
+				workflow: spec.id,
+				stage,
+				sessionId,
+				transcript,
+				cause: serializeCause(cause)
+			});
+		} catch (writeError) {
+			if (cause instanceof Error) {
+				cause.message += `\nCould not write failure artifact: ${writeError instanceof Error ? writeError.message : String(writeError)}`;
+				throw cause;
+			}
+			throw new Error(`${message}\nCould not write failure artifact: ${String(writeError)}`, { cause });
+		}
+		throw new Error(`${message}\nFailure artifact: ${path}\nNext: ${stage === "acquire" ? "inspect that file; check the OpenCode preset and Executor plugin configuration" : stage === "decide" ? "inspect that file and research.json; check the decision provider configuration and retry" : "inspect the transcript in that file; rerun with --model <id> or raise workflows.opencode.timeoutMs"}`, { cause });
 	}
 };
 //#endregion
@@ -47557,13 +47661,15 @@ const robotsCommand = make$9("robots", {
 	description: "Disallow-all with no Sitemap line — the preview posture"
 }]), withHandler(fnUntraced(function* ({ origin, indexable }) {
 	const config = yield* loadSeoConfig;
-	const graph = yield* scoped(acquireGraph(config));
-	yield* printText(renderRobots(graph, {
+	const loaded = yield* scoped(acquireLoadedGraph(config));
+	if ((config.disallow !== void 0 || config.contentSignal !== void 0 || config.directives !== void 0) && loaded.robots !== void 0) return yield* new SeoCliError({ message: "The graph loader supplies the robots policy; remove disallow, contentSignal, and directives from seo.config.ts." });
+	const policy = loaded.robots ?? config;
+	yield* printText(renderRobots(loaded.graph, {
 		origin: originOf(origin, config.origin),
 		indexable,
-		disallow: config.disallow,
-		contentSignal: config.contentSignal,
-		directives: config.directives,
+		disallow: policy.disallow ?? [],
+		contentSignal: policy.contentSignal,
+		directives: policy.directives,
 		transform: config.transform
 	}));
 })));
@@ -47606,7 +47712,7 @@ const staleCommand = make$9("stale", {
 })));
 //#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, headings, and JSON-LD are verified only by inspecting HTML (`check --site`).\n- A FAQPage question or answer, or an Offer price, that is not in the server-rendered text fails `check --site`. Accordions must render closed panels into the HTML (for example `hidden=\"until-found\"`), not mount them on open.\n- Dates (`publishedAt`, `modifiedAt`, a route's `modifiedAt`) must be ISO 8601 (`2026-09-29`, or a date-time with an offset); they become the sitemap's `<lastmod>`, and `check` rejects any other form.\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| Headings, JSON-LD, robots meta, canonicals, page copy | `pagegraph check --site <url>` against a running server | Every declared page's rendered HTML matches its declaration and its structured data |\n| `modifiedAt` dates, `freshness` policy | `pagegraph stale` | The refresh queue and which pages are undated |\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` without `--site` says nothing about served HTML. Verify head and content changes with `check --site`, `inspect --live`, or a rendered-HTML 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 skills = { core: "---\nname: core\ndescription: Use when adding Pagegraph to a TanStack Start app or changing its SEO wiring — the pagegraph() Vite plugin, staticData.seo declarations and seo.head, title templates, typed related links, content collections, the 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\nconst site = 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\nexport const seo = site; // seo.head for static routes\nexport const { seoHead } = site;\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 each static page once.** `staticData.seo` holds the crawl policy and the head together; `seo.head` renders it.\n\n```tsx\n// src/routes/(marketing)/pricing.tsx\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport { seo } 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      head: { title: \"Pricing — Example\", description: \"Simple volume pricing.\", faqs: pricingFaqs },\n    },\n  },\n  head: seo.head,\n  component: PricingPage,\n});\n```\n\n- Policy fields: `kind`, `crumb`, `sitemap` (or `false`), `robots`, `related`, `link`, `redirectTo`, `modifiedAt`, `titleTemplate`.\n- `head` is the full `title` and `description`, plus optional `faqs`, `article`, `service`, `itemList`, `jsonLd`, `ogTitle`, `canonicalPath`, and `breadcrumbs`. The title, description, and FAQs land in `staticData.seo.head`, which the graph, `pageHeads`, and `check` read — the page and the graph cannot disagree.\n- Write `staticData` as an object literal and `head: seo.head`: the coverage gate reads both keys statically, and a helper call or an arrow typed with `AnyRouteMatch` in route options would make TanStack infer `any` search and loader types for the route tree.\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. Dynamic routes keep `head()` and declare a title template.** A param route renders from `loaderData`, so it calls `seoHead`; its `titleTemplate` (`%s` is the page title) is applied by `seoHead` and by the graph to the route's collection instances, so the suffix lives in one place.\n\n```tsx\nexport const Route = createFileRoute(\"/(marketing)/blog/$slug\")({\n  staticData: {\n    seo: { kind: \"article\", titleTemplate: \"%s | Example Blog\", sitemap: { priority: 0.7, changeFrequency: \"weekly\" } },\n  },\n  head: (ctx) => (ctx.loaderData ? seoHead(ctx, { title: ctx.loaderData.title, description: ctx.loaderData.description }) : {}),\n});\n```\n\n**4. List content pages as collections.** A param route such as `/blog/$slug` never enters the sitemap itself; its pages come from a collections module. `contentCollection` accepts any pages with a `url` (Fumadocs `loader().getPages()` directly) and turns each entry's `related` into edges. Instances inherit the param route's `kind`, `sitemap`, and `titleTemplate`.\n\n```ts\n// src/lib/seo/collections.ts\nimport { contentCollection } from \"pagegraph\";\nimport { blogSource } from \"../blog-source\";\n\nexport const collections = () => [\n  contentCollection({\n    route: \"/blog/$slug\",\n    source: \"blog\",\n    pages: blogSource.getPages(),\n    entry: (page) => ({\n      title: page.data.title,\n      description: page.data.description,\n      publishedAt: page.data.date,\n      related: page.data.related,\n    }),\n  }),\n];\n```\n\n**5. Register the plugin once.** It builds the graph inside the app's Vite pipeline (aliases, `define`s, and content plugins apply; no stubs) and ships it to the server runtime.\n\n```ts\n// vite.config.ts\nimport { fileURLToPath } from \"node:url\";\nimport { tanstackStart } from \"@tanstack/react-start/plugin/vite\";\nimport { pagegraph } from \"pagegraph/tanstack-start\";\nimport { defineConfig } from \"vite\";\n\nexport default defineConfig({\n  plugins: [\n    tanstackStart(),\n    pagegraph({\n      origin: \"https://example.com\",\n      indexable: process.env.DEPLOY_ENV === \"production\",\n      robots: { contentSignal: \"search=yes, ai-input=yes, ai-train=yes\" },\n      collections: \"src/lib/seo/collections.ts\",\n      routeConfig: {\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```\n\n- The graph evaluates every route file that declares `staticData` in a Node environment named `pagegraph`, never `routeTree.gen.ts`. A route that imports a server-runtime-only module (`cloudflare:workers`) fails with its file name; if it is an app surface rather than a public page, add it to `exclude` (route-file globs relative to `src/routes`).\n- `routeConfig` is the coverage gate: dev and `vite build` fail when a page leaf in an enforced group has neither `staticData` nor `head`. Its `robotsExclusions` join `robots.disallow`.\n- `indexable: false` (previews, local) serves a disallow-all robots.txt with no Sitemap line.\n\n**6. Serve robots.txt and sitemap.xml.** They are routes, because their output depends on the deployment.\n\n```ts\n// src/routes/robots[.]txt.ts — sitemap[.]xml.ts is the same with sitemapXml\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport { robotsTxt } from \"pagegraph/tanstack-start/server\";\n\nexport const Route = createFileRoute(\"/robots.txt\")({ server: { handlers: { GET: robotsTxt } } });\n```\n\n`pagegraph/tanstack-start/server` also exports `seoGraph()` and `seoSite()` for other server code. Never import `pagegraph/tanstack-start`, `pagegraph/config`, `pagegraph/vite`, or `pagegraph/audit` from code a Worker or browser bundle reaches: under those runtimes they resolve to a stub that throws at import.\n\n**7. Point the CLI at the same graph** with `seo.config.ts` at the app root:\n\n```ts\n// seo.config.ts\nimport { defineSeoConfig } from \"pagegraph/config\";\nimport { tanstackStartGraph } from \"pagegraph/tanstack-start\";\n\nexport default defineSeoConfig({\n  origin: \"https://example.com\",\n  loadGraph: tanstackStartGraph({ root: import.meta.dirname }),\n});\n```\n\n`tanstackStartGraph` evaluates the app's Vite config the way the dev server does (command `serve`) in `production` mode, and returns the plugin's graph and robots policy. Optional fields: `coverage` (`[{ path, minInbound }]`, contextual-link minimums enforced by `check`), `content`, `freshness`, and `workflows`. Build-time head consumers use `loadPageHeads(tanstackStartGraph({ root }), { exclude })` from `pagegraph/config`.\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- `routeConfig.outputPath` must be in an existing directory outside `src/routes`, so the route watcher does not loop.\n- The graph knows declared heads (`staticData.seo.head`) and collection instances, not what a dynamic `head()` computes at request time. A route's rendered headings and JSON-LD are verified only by inspecting HTML (`check --site`).\n- A FAQPage question or answer, or an Offer price, that is not in the server-rendered text fails `check --site`. Accordions must render closed panels into the HTML (for example `hidden=\"until-found\"`), not mount them on open.\n- Dates (`publishedAt`, `modifiedAt`, a route's `modifiedAt`) must be ISO 8601 (`2026-09-29`, or a date-time with an offset); they become the sitemap's `<lastmod>`, and `check` rejects any other form.\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, the plugin, `seo.config.ts` | `pagegraph check` | No structural violations (exit 1 otherwise); editorial findings are reported but do not fail |\n| Headings, JSON-LD, robots meta, canonicals, page copy | `pagegraph check --site <url>` against a running server | Every declared page's rendered HTML matches its declaration and its structured data |\n| `modifiedAt` dates, `freshness` policy | `pagegraph stale` | The refresh queue and which pages are undated |\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| Declared heads, `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` without `--site` says nothing about served HTML. Verify head and content changes with `check --site`, `inspect --live`, or a rendered-HTML 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",