pagegraph 0.11.0 → 0.13.0

package/README.md

@@ -1,21 +1,22 @@
 # pagegraph
 
-Route-declared SEO for TanStack Router. Each route declares its SEO policy once, in
-`staticData.seo` — the sitemap, `robots.txt`, breadcrumbs, JSON-LD, cross-links, and
-the CI check all derive from that one declaration. There is no second place to update,
-so nothing drifts. A public page that ships without a declaration **fails the build**.
+Route-declared SEO for TanStack Start and TanStack Router. Each route declares its SEO
+policy and head once, in `staticData.seo` — the `<head>`, sitemap, `robots.txt`,
+breadcrumbs, JSON-LD, cross-links, and the CI check all derive from that one
+declaration. There is no second place to update, so nothing drifts. A public page that
+ships without a declaration **fails the build**.
 
 ```mermaid
 flowchart LR
   subgraph declare["declare once"]
-    route["staticData.seo<br/>+ head()"]
+    route["staticData.seo (+ head)<br/>head: seo.head"]
   end
-  route --> seograph["SeoGraph<br/>(nodes + edges)"]
+  route --> seograph["SeoGraph<br/>(built by the Vite plugin)"]
   seograph --> sitemap["sitemap.xml"]
   seograph --> robots["robots.txt"]
   seograph --> check["pagegraph check · CI gate"]
   route --> head["&lt;head&gt; meta · canonical<br/>Breadcrumbs · JSON-LD"]
-  gate["seoRouteConfig (vite)"] -. "fails undeclared pages" .-> route
+  gate["pagegraph() (vite)"] -. "fails undeclared pages" .-> route
 ```
 
 ## Install
@@ -25,17 +26,201 @@ bun add pagegraph
 bun add -D lighthouse   # only for `pagegraph audit` performance evidence
 ```
 
-| Entry                        | Exports                                                                                        | Peers                                       |
-| ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `pagegraph`        | `buildSeoGraph`, `renderSitemap`, `renderRobots`, `contentSignal`, `checkGraph`, `checkRenderedCoverage`, `decodeRenderedEdgeArtifact`, `inspectHtml` | —                                           |
-| `pagegraph/react`  | `createSeo` → `seoHead`, `Breadcrumbs`, JSON-LD generators                                     | `react`, `@tanstack/react-router`           |
-| `pagegraph/vite`   | `seoRouteConfig` coverage gate                                                                 | `vite`                                      |
-| `pagegraph/config` | `defineSeoConfig`, `viteGraphLoader`, `selectPageHeadNodes`, `pageHeads`, `loadPageHeads`                                                           | `vite`                                      |
-| `pagegraph/audit`  | Audit services, scanner protocol, rules, and report schemas                                    | `effect`                                    |
-| `pagegraph` bin                   | CLI over the same graph                                                                        | bundled — runs on Bun                        |
+## Authored pages
 
-The core and React import graphs have **zero runtime dependencies** — everything they use is a
-peer, and only the entries you import need those peers loaded.
+Keep authored text beside its React layout. `DocumentProvider` records only its page body when
+supplied a collector; ordinary rendering preserves the layout. `Title` assigns a heading to the
+nearest section or item, `Fact` resolves shared values, and `Visual` describes content for the
+markdown document without rendering its children during capture.
+
+```tsx
+import { renderToStaticMarkup } from "react-dom/server";
+import { defineFacts, fact, documentMarkdown } from "pagegraph";
+import {
+  DocumentProvider, T, Title, Section, Fact, createCollector, finishDocument,
+} from "pagegraph/react";
+
+const facts = defineFacts({ attempts: fact.number(8) });
+declare module "pagegraph" {
+  interface Register { facts: typeof facts }
+}
+
+const collector = createCollector({ path: "/email", site: "https://example.com", facts });
+const page = (
+  <DocumentProvider collector={collector}>
+    <Section kind="prose" id="intro">
+      <h1><Title>Email delivery</Title></h1>
+      <p><T>Retry up to <Fact id="attempts" /> times.</T></p>
+    </Section>
+  </DocumentProvider>
+);
+// Your SSR renderer supplies completed HTML, whose markers determine document order.
+const html = renderToStaticMarkup(page);
+const document = finishDocument(collector, {
+  title: "Email delivery", description: "Reliable delivery with retries.",
+}, html);
+const markdown = documentMarkdown(document, "https://example.com");
+```
+
+Use `defineSectionKind` for custom formatting; its markdown writer provides `text`, `heading`,
+and `table`:
+
+```ts
+import { defineSectionKind } from "pagegraph";
+const comparison = defineSectionKind({
+  kind: "comparison",
+  markdown: (section, md) => md.heading(2, section.title)
+    + md.table(section.items.map((item) => item.cells)),
+}); // pass kind={comparison} to Section
+```
+
+`Section.Item.Link` records a card's destination, while `CaptureAnchor` is the
+public anchor boundary for router `createLink` integrations. `ForAgents` and `ForHumans` mark
+audience-specific text; markdown excludes human-only content. `messageText` extracts text or
+inline markdown for head metadata. The root entry also provides `hashDocument`,
+`createMarkdownLock`, and pure `llmsMarkdown`/`llmsSection` string builders.
+
+## Rendered markdown with TanStack Start
+
+Declare rendered pages on the route that owns `DocumentProvider`. Collection instances inherit
+these fields from their parameter route; the parameter template itself is never captured.
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { DocumentProvider, Section, T, Title } from "pagegraph/react";
+import { Link } from "pagegraph/tanstack-start/react";
+
+export const Route = createFileRoute("/pricing")({
+  staticData: {
+    seo: { kind: "page", head: { title: "Pricing", description: "Plans for your team." } },
+    markdown: "rendered",
+    llms: "Product",
+  },
+  head: () => ({ meta: [{ title: "Pricing" }, { name: "description", content: "Plans for your team." }] }),
+  component: () => (
+    <DocumentProvider>
+      <Section kind="prose" id="plans">
+        <h1><Title>Plans for your team</Title></h1>
+        <Link to="/"><T>Back home</T></Link>
+      </Section>
+    </DocumentProvider>
+  ),
+});
+```
+
+`markdown: "source"` identifies pages whose Markdown is supplied by the application; pagegraph
+captures only `"rendered"` pages. `llms` sets an optional llms.txt group. Use the capture-aware
+`Link` for authored links: it uses TanStack's ordinary Link outside a capture and records resolved
+anchor destinations during capture. The plugin adds `source=` locations to authored JSX imported
+from `pagegraph/react`. In development, `DocumentProvider` rejects a current route lacking
+`staticData.markdown: "rendered"`.
+
+Configure the plugin and pass its fixed capture page to Start:
+
+```ts
+import { pagegraph } from "pagegraph/tanstack-start";
+
+const graph = pagegraph({
+  origin: "https://preview.example.com", // this deployment's SEO origin
+  collections: "src/collections.ts",
+  markdown: {
+    origin: "https://example.com", // canonical document and twin links
+    serverEntry: "dist/server/index.js", // default; relative to the Vite root
+  },
+  facts: "src/facts.ts", // exports `facts`; evaluated in the pagegraph environment
+});
+
+// In your Vite plugins:
+// tanstackStart({
+//   prerender: { enabled: true, autoStaticPathsDiscovery: false, crawlLinks: false, failOnError: true },
+//   pages: [...graph.prerenderPages],
+// }), graph
+```
+
+For Cloudflare, wire the non-deployed prerender Worker to the compiled Start server. Add this to
+`cloudflare()` alongside the production Worker's configuration:
+
+```ts
+experimental: {
+  prerenderWorker: {
+    config: {
+      name: "app-markdown-prerender",
+      main: "pagegraph/tanstack-start/prerender-worker",
+      compatibility_date: "2026-09-20",
+      compatibility_flags: ["nodejs_compat"],
+      vars: { TSS_PRERENDERING: "true" },
+      assets: { binding: "ASSETS", run_worker_first: true },
+    },
+  },
+},
+```
+
+Call the capture adapter before your normal Start handler, forwarding the same request options:
+
+```ts
+import handler from "@tanstack/react-start/server-entry";
+import { markdownRequest } from "pagegraph/tanstack-start/markdown";
+
+export default {
+  async fetch(request: Request) {
+    return await markdownRequest(request) ?? handler.fetch(request);
+  },
+};
+```
+
+Only dev and the prerender Worker capture documents. `GET` and `HEAD` on
+`/__pagegraph/markdown.json` capture all rendered pages; `/pricing.md` and
+`/pricing.document.json` capture one page in dev. Ordinary requests return `null`. In production,
+private capture paths return 404 and Markdown twins fall through to your static asset server.
+`markdownPagePaths()` exposes the concrete rendered page paths.
+
+After prerender, the plugin writes `dist/client/pricing.md` (`/` becomes `index.md`),
+`.pagegraph/documents/pricing.json`, and `.pagegraph/heads.json`, and removes the emitted private
+capture response. Stale valid documents at their derived paths are pruned; unrelated files are
+preserved. Ignore the private generated documents and heads in Git. Claims replay is reserved for
+a separate integration.
+
+Serve graph-derived llms.txt without rendering pages:
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+import { llmsTxt } from "pagegraph/tanstack-start/server";
+
+export const Route = createFileRoute("/llms.txt")({
+  server: { handlers: { GET: llmsTxt({ sections: ["## Docs\n\nRead our documentation."] }) } },
+});
+```
+
+`llmsSection()` returns the generated section for custom composition. It includes rendered twins
+and explicitly grouped pages, using graph titles and descriptions and `markdown.origin`.
+
+## What runs where
+
+Every entry belongs to one place. Runtime entries use portable graph and document code with
+the framework peers listed below; the capture adapter runs on a Start server. Build entries
+load your app through Vite, parse routes natively, or drive Node I/O.
+
+| Entry              | Runs in                       | Exports                                                                                                   | Peers                             |
+| ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `pagegraph`        | runtime (Worker, SSR, browser) | `buildSeoGraph`, `contentCollection`, `renderSitemap`, `renderRobots`, `pageHeads`, `graphToJson`/`graphFromJson`, checks, `inspectHtml`, document types, facts, markdown and locks | —                                 |
+| `pagegraph/react`  | runtime                       | `createSeo` → `seo.head`, `seoHead`, `Breadcrumbs`, JSON-LD generators, authored page primitives                                    | `react`, `@tanstack/react-router` |
+| `pagegraph/tanstack-start/server` | runtime (Start server routes) | `robotsTxt`, `sitemapXml`, `llmsTxt`, `llmsSection`, `seoGraph`, `seoSite`                                           | the `pagegraph()` plugin          |
+| `pagegraph/tanstack-start/markdown` | runtime (Start server) | `markdownRequest`, `markdownPagePaths` | `react`, `react-dom`, `@tanstack/react-start`, `@tanstack/react-router` |
+| `pagegraph/tanstack-start/react` | runtime | capture-aware `Link` | `react`, `@tanstack/react-router` |
+| `pagegraph/tanstack-start/prerender-worker` | non-deployed prerender Worker | compiled Start server | the `pagegraph()` plugin |
+| `pagegraph/tanstack-start` | build (`vite.config.ts`, `pagegraph.config.ts`) | `pagegraph()` Vite plugin, `tanstackStartGraph`, `evaluateAppGraph`                        | `vite`, `@tanstack/router-generator`, `effect` |
+| `pagegraph/vite`   | build (`vite.config.ts`)      | `seoRouteConfig` coverage gate                                                                            | `vite`, `@tanstack/router-generator` |
+| `pagegraph/config` | build (`pagegraph.config.ts`, CLI)  | `defineSeoConfig`, `viteGraphLoader`, `loadPageHeads`                                                     | `vite`                            |
+| `pagegraph/claims` | build / CLI (Node or Bun) | `claimsInput`, `claimsFamily`, document resolution, committed claims checks | `effect` |
+| `pagegraph/audit`  | build / CLI (Node or Bun)     | Audit services, scanner protocol, rules, and report schemas                                               | `effect`                          |
+| `pagegraph/oxlint` | build (oxlint)               | `pagegraph` plugin: `no-bare-text`, `t-children`                                                        | —                                 |
+| `pagegraph` bin    | CLI (Bun)                     | CLI over the same graph                                                                                   | bundled                           |
+
+Build entries resolve to a stub under the `workerd`, `worker`, and `browser` export conditions.
+A Worker or browser bundle that reaches one fails at import with an error naming the entry,
+instead of crashing on a native binding when a request first runs the code. The runtime entries
+have **zero runtime dependencies** beyond their listed peers; a test pins each entry's import
+graph.
 
 The CLI **bundles PageGraph's Effect and TypeSafe provider runtime**, so it does not depend on the
 app's Effect version; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). Agentic workflows load the
@@ -46,8 +231,9 @@ Effect and Drizzle versions. Executor plugins must use OpenCode's Effect version
 Bun and network access to npm are required for the first install. The pinned OpenCode client's
 HTTP error handling retains the method, path, status, and response body for diagnostics;
 undeclared error bodies are capped at 16 KiB.
-Discovery-only research gets one continuation to complete provider evidence; if it still cannot,
-`research-failure.json` preserves the transcript and tool results in the requested output directory. `vite` stays a peer — graph commands
+Discovery-only research gets one continuation to complete provider evidence. Every workflow failure
+after run creation writes `failure.json` in the run directory, with the stage, session ID when available,
+transcript, and cause chain. `vite` stays a peer — graph commands
 load your app through Vite at runtime — and `lighthouse` is only needed by `pagegraph audit`.
 Importing `pagegraph/audit` programmatically needs `effect@^4.0.0`. The Effect and TypeSafe
 peers remain optional for other library entry points and the bundled CLI.
@@ -63,7 +249,7 @@ pagegraph skills get core
 
 The skill is maintained at [skill-data/core/SKILL.md](skill-data/core/SKILL.md) and compiled into the CLI, so the instructions match the installed Pagegraph version. `skills get core` prints Markdown to stdout; `--json` returns a structured payload.
 
-## Quick start
+## Quick start (TanStack Start)
 
 **1. Bind your site identity once.** Route files never see an origin or a brand name.
 
@@ -71,7 +257,7 @@ The skill is maintained at [skill-data/core/SKILL.md](skill-data/core/SKILL.md)
 // lib/seo.ts
 import { createSeo } from "pagegraph/react";
 
-export const { seoHead } = createSeo({
+const site = createSeo({
   origin: "https://example.com",
   site: {
     name: "Example",
@@ -85,19 +271,17 @@ export const { seoHead } = createSeo({
     description: "What the company does.",
     sameAs: ["https://github.com/example"],
     contactPoint: { contactType: "support", email: "hi@example.com" },
-    address: {
-      streetAddress: "123 Example Street",
-      addressLocality: "Example City",
-      addressRegion: "CA",
-      postalCode: "94105",
-      addressCountry: "US",
-    },
   },
   website: { searchPath: "/docs?q={search_term_string}" },
 });
+
+export const seo = site; // seo.head for static routes
+export const { seoHead } = site;
 ```
 
-**2. Declare on the route.** Policy in `staticData.seo`, per-page content in `head()`.
+**2. Declare each page once.** `staticData.seo` holds the crawl policy and the head
+together; `seo.head` renders it. The graph and the checks read the same
+`staticData.seo.head` — the page and the graph cannot disagree.
 
 ```tsx
 export const Route = createFileRoute("/pricing")({
@@ -109,124 +293,111 @@ export const Route = createFileRoute("/pricing")({
       related: ["/features", "/docs"],
       link: { title: "Pricing", description: "Simple volume pricing." },
       modifiedAt: "2026-09-29", // sitemap <lastmod> and the freshness report
+      head: {
+        title: "Pricing — Example",
+        description: "Simple volume pricing.",
+        faqs: pricingFaqs,
+      },
     },
   },
-  head: (ctx) =>
-    seoHead(ctx, {
-      title: "Pricing — Example",
-      description: "Simple volume pricing.",
-    }),
+  head: seo.head,
+  component: PricingPage,
 });
 ```
 
-`seoHead` returns the `meta` + canonical `links` TanStack renders into `<head>` —
+`seo.head` returns the `meta` + canonical `links` TanStack renders into `<head>` —
 title, description, og/twitter cards, robots, and the JSON-LD each page warrants
-(BreadcrumbList always; Article, FAQPage, Service, ItemList when the instance
-declares them).
+(BreadcrumbList always; Article, FAQPage, Service, ItemList when the head declares
+them). A route that renders from `loaderData` calls `seoHead(ctx, instance)` in its
+own `head()` and declares a `titleTemplate` (`"%s | Example Blog"`): `seoHead` applies it,
+and the graph applies it to the route's collection pages.
 
-### Extensible JSON-LD
-
-The built-in generators are conveniences, not a closed schema registry. Define any
-`schema-dts` entity, link it to the plugin's stable site identities, and compose one
-site graph:
+**3. Register the plugin.** It builds the graph once per build (and on change in dev)
+inside your app's Vite pipeline — path aliases, `define`s, and content plugins such as
+Fumadocs apply, with no stubs — and ships it to the server runtime as data.
 
 ```ts
-import {
-  createSeo,
-  defineJsonLd,
-  extendJsonLd,
-  jsonLdRef,
-} from "pagegraph/react";
+// vite.config.ts
+import { pagegraph } from "pagegraph/tanstack-start";
 
-export const seo = createSeo({
-  // site, organization, and website as above
-  jsonLd: {
-    site: (ids) => [
-      defineJsonLd({
-        "@type": "SoftwareApplication",
-        "@id": "https://example.com/#product",
-        name: "Example",
-        applicationCategory: "DeveloperApplication",
-        operatingSystem: "Web",
-        provider: jsonLdRef(ids.organization),
-      }),
-    ],
-    transform: (entry) => {
-      if (entry.kind === "organization") {
-        return extendJsonLd(entry.document, {
-          slogan: "Ship with confidence.",
-        });
-      }
-      return entry.document;
-    },
+pagegraph({
+  origin: "https://example.com",
+  indexable: process.env.DEPLOY_ENV === "production", // previews disallow everything
+  robots: { contentSignal: "search=yes, ai-input=yes, ai-train=yes" },
+  collections: "src/lib/seo/collections.ts",
+  routeConfig: {
+    outputPath: fileURLToPath(new URL("./src/lib/route-config.ts", import.meta.url)),
+    publicGroups: ["(marketing)", "(docs)"],
+    enforceCoverageIn: ["(marketing)", "(docs)"],
+    alwaysDisallow: ["/dashboard", "/api"],
   },
 });
-
-const siteGraph = seo.generateSiteGraphSchema();
 ```
 
-`generateSiteGraphSchema()` includes Organization, WebSite, and configured site
-entities in one `@graph`. Organization and WebSite use stable `#organization` and
-`#website` IDs; articles and services provided by the site reference the same
-Organization. Existing individual generators remain available and are not transformed.
-
-Add page-specific entities through `seoHead`:
-
 ```ts
-head: (ctx) =>
-  seo.seoHead(ctx, {
-    title: "Example for developers",
-    description: "A focused description of the product.",
-    jsonLd: [
-      defineJsonLd({
-        "@type": "SoftwareApplication",
-        name: "Example",
-        url: "https://example.com/product",
-      }),
-    ],
-  });
+// src/lib/seo/collections.ts — evaluated in the app's Vite pipeline
+import { contentCollection } from "pagegraph";
+import { blogSource } from "../blog-source"; // e.g. a Fumadocs loader()
+
+export const collections = () => [
+  contentCollection({
+    route: "/blog/$slug",
+    source: "blog",
+    pages: blogSource.getPages(),
+    entry: (page) => ({
+      title: page.data.title,
+      description: page.data.description,
+      publishedAt: page.data.date,
+      related: page.data.related,
+    }),
+  }),
+];
 ```
 
-The transform sees discriminated generated and custom entries plus `origin`,
-`canonical`, and `entityIds`. Return the document to keep it, no value (or `false`)
-to suppress it, or an array to expand it. Output preserves caller order and never
-silently deduplicates entities.
+The plugin evaluates every route file that declares `staticData` — never the generated
+route tree — in a Node environment named `pagegraph`. A route that imports a module
+only the server runtime provides (`cloudflare:workers`) fails with its file name; add an
+app-only route to `exclude` (route-file globs).
 
-**3. Serve the projections.** Build the graph from your route tree, render strings.
+**4. Serve robots.txt and sitemap.xml.** One line each; the output depends on the
+deployment's origin and indexability, so they stay routes.
 
 ```ts
-// lib/seo/graph.ts — also the module the CLI loads
-import { buildSeoGraph } from "pagegraph";
+// src/routes/robots[.]txt.ts — sitemap[.]xml.ts is symmetric with sitemapXml
+import { robotsTxt } from "pagegraph/tanstack-start/server";
 
-export const loadSeoGraph = () =>
-  buildSeoGraph({ routeTree, collections: [blogCollection] });
+export const Route = createFileRoute("/robots.txt")({ server: { handlers: { GET: robotsTxt } } });
 ```
 
+**5. Gate CI.** The CLI reads the same graph through `pagegraph.config.ts`:
+
 ```ts
-// routes/sitemap[.]xml.ts — robots[.]txt.ts is symmetric
-import { renderRobots, renderSitemap } from "pagegraph";
-
-renderSitemap(loadSeoGraph(), { origin, indexable: true });
-renderRobots(loadSeoGraph(), {
-  origin,
-  indexable: true,
-  disallow: routeConfig.robotsExclusions,
-  contentSignal: "search=yes, ai-input=yes, ai-train=yes",
+// pagegraph.config.ts
+import { defineSeoConfig } from "pagegraph/config";
+import { tanstackStartGraph } from "pagegraph/tanstack-start";
+
+export default defineSeoConfig({
+  loadGraph: tanstackStartGraph({ root: import.meta.dirname }),
 });
 ```
 
+```bash
+pagegraph check
+```
+
+### Without TanStack Start
+
+`buildSeoGraph({ routeTree, collections })` builds the same graph from any TanStack
+Router tree; render it with `renderSitemap(graph, { origin, indexable })` and
+`renderRobots(graph, { origin, indexable, disallow, contentSignal })`, and point
+`pagegraph.config.ts` at it with `viteGraphLoader` (see [CLI](#cli)).
+
 `renderRobots` does not invent a Content-Signal. Pass `contentSignal` for
 the value (the plugin prefixes `Content-Signal: `), `directives` for extra
 group lines, and `transform` if you need to wrap or replace the whole file.
 Preview hosts (`indexable: false`) drop `contentSignal` and `directives`;
 `transform` still runs.
 
-**4. Gate CI.** The same graph, the same rules, exit 1 on structural violations.
-
-```bash
-pagegraph check
-```
-
 ## Agentic workflows
 
 PageGraph can combine the deterministic route graph with a project-owned embedded OpenCode agent,
@@ -241,7 +412,7 @@ The generated `.pagegraph/opencode` directory contains one `seo` agent and custo
 the plugin own model and Executor authentication. PageGraph does not copy credentials or assume
 fixed provider-tool addresses.
 
-Enable workflows in `seo.config.ts`:
+Enable workflows in `pagegraph.config.ts`:
 
 ```ts
 export default defineSeoConfig({
@@ -294,6 +465,11 @@ After research is validated, the run directory contains `research.json`: an inco
 with the collected evidence, decision inputs, and OpenCode transcript. A downstream failure reports
 its path so the evidence remains available for diagnosis. Only a completed workflow writes
 `run.json` and `summary.md`; a research checkpoint is not a final recommendation.
+Model JSON drops null properties and array elements before validation. Schema validation collects all
+issues for one read-only repair turn. Every error after run creation writes `failure.json` in that
+run directory with the workflow, stage, available OpenCode session ID, transcript, and full cause
+chain. The error reports the artifact path and a next step; a failed artifact write preserves the
+original error with a note.
 
 | Command | Result |
 | --- | --- |
@@ -382,9 +558,10 @@ route's date is never inherited by its instances. Undated pages emit no
 
 ## Coverage gate (Vite)
 
-`seoRouteConfig` parses the route tree with `@tanstack/router-generator` (the same
-parser as the router) and fails `vite build` when a page in an enforced group has
-neither `staticData` nor `head`:
+`pagegraph({ routeConfig })` — or `seoRouteConfig` from `pagegraph/vite` in a Router-only
+app — parses the route tree with `@tanstack/router-generator` (the same parser as the
+router) and fails `vite build` when a page in an enforced group has neither `staticData`
+nor `head`:
 
 ```ts
 // vite.config.ts
@@ -399,53 +576,128 @@ seoRouteConfig({
 ```
 
 It also derives a small config module from the route tree: `robotsExclusions`
-(feed to `renderRobots`) and `reservedSegments` (top-level segments an app must
-not hand out as tenant/org slugs).
+(the plugin adds them to robots.txt; a Router-only app feeds them to `renderRobots`) and
+`reservedSegments` (top-level segments an app must not hand out as tenant/org slugs).
+
+## Claims gate
+
+Declare probability rules against `claimsInput` from the build-only `pagegraph/claims` entry.
+Each rule asks whether the section violates your policy:
+
+```ts
+import { Decision } from "effect/ai";
+import { claimsInput } from "pagegraph/claims";
+import { pagegraph } from "pagegraph/tanstack-start";
+
+const rules = Decision.make({
+  input: claimsInput,
+  decisions: {
+    unsupportedPromise: Decision.probability({
+      instructions: "Does this section promise a capability unsupported by its facts or evidence?",
+    }),
+  },
+});
+
+const graph = pagegraph({
+  origin: "https://example.com",
+  markdown: { origin: "https://example.com" },
+  facts: "src/facts.ts",
+  claims: { rules, model: "typesafe/jev", cutoff: 0.8 },
+});
+```
+
+Pass `graph.prerenderPages` to Start as shown in the rendered Markdown setup. The build persists
+captured documents and graph heads, then replays committed answers without a model or credentials.
+Missing answers and violations fail the build and name the page, section, and rule.
+
+Run `pagegraph claims check` after changing prose, facts, context, or rules, then review and commit
+`.pagegraph/decisions/claims/`. The cache key includes the rule definition fingerprint, model, and
+input hash. Cached answers are reused; `--refresh` asks again and replaces them. The command reports
+cached and asked counts and exits nonzero on violations. Set `TYPESAFE_API_KEY` when answers need
+asking. `pagegraph check` also replays configured claims without model calls.
+
+```sh
+pagegraph claims check
+pagegraph claims check --refresh
+pagegraph claims check --dev http://localhost:3000
+```
+
+`claims.context` supplies policy text to every input. Inputs include the section's authored
+Markdown, messages, all code-owned facts, and other sections marked as evidence. Page metadata is
+judged as a `head` section, including graph pages outside rendered capture. `excludeHeads` accepts
+path globs to omit metadata while keeping captured sections in the gate. The default cutoff is
+`0.8` only when omitted; any probability at or above the configured cutoff is a violation, and
+values below it pass. Changing the cutoff reuses answers and recalculates verdicts.
+
+## Markdown CLI
+
+Inspect captured documents, search page metadata and sections, and maintain a reviewable lock:
+
+```sh
+pagegraph markdown show /pricing
+pagegraph markdown find email
+pagegraph markdown lock
+pagegraph markdown lock --check
+```
+
+`show` prints the page's Markdown twin. `find` reports matching pages and sections.
+`lock` writes `.pagegraph/markdown.lock.json` from document and message hashes, including
+head-only pages; `--check` exits nonzero if the lock is missing or differs. These commands use
+`.pagegraph/documents/` and `.pagegraph/heads.json` from the build. Use `--dev <origin>` to inspect
+the development bundle instead. `--json` emits structured output using the CLI's usual conventions.
+Markdown and claims settings come from `pagegraph()` in Vite, including the canonical Markdown
+origin and facts module. Built-mode commands read Vite with `command: "build"` and
+`mode: "production"`; `--dev` reads `command: "serve"` and `mode: "development"`.
+Put CLI policies and the graph loader in `pagegraph.config.ts`.
 
 ## CLI
 
-The graph commands acquire your graph through `seo.config.ts` at the app root —
-the `viteGraphLoader` evaluates your graph module inside a headless Vite server,
-so path aliases, content plugins, and virtual modules all resolve:
+The graph commands acquire your graph through `pagegraph.config.ts` at the app root.
+Rename an existing `seo.config.ts`, `.js`, or `.mjs` to its `pagegraph.config.*` equivalent.
+The file holds CLI policies and `loadGraph`; site identity and robots policy come from the
+loader result, and Markdown and claims settings come from the Vite plugin. A
+TanStack Start app uses `tanstackStartGraph` (above), which also supplies the robots
+policy and site identity from `pagegraph()`, using build settings in production mode by default.
+Pass `command: "serve", mode: "development"` to inspect a development configuration instead.
+Otherwise `viteGraphLoader` evaluates your graph
+module inside a headless Vite server, so path aliases, content plugins, and virtual modules all resolve:
 
 ```ts
-// seo.config.ts
+// pagegraph.config.ts
 import { defineSeoConfig, viteGraphLoader } from "pagegraph/config";
+import { routeConfig } from "./src/lib/route-config";
 
 export default defineSeoConfig({
-  origin: "https://example.com",
-  disallow: routeConfig.robotsExclusions,
-  contentSignal: "search=yes, ai-input=yes, ai-train=yes",
   // Fail `check` unless each named money page has enough contextual links.
   coverage: [{ path: "/pricing", minInbound: 2 }, { path: "/features/*", minInbound: 1 }],
   loadGraph: viteGraphLoader({
     root: import.meta.dirname,
     entry: "/lib/seo/graph.ts",
     exportName: "loadSeoGraph",
+    site: {
+      origin: "https://example.com",
+      indexable: true,
+      robots: { disallow: routeConfig.robotsExclusions, contentSignal: "search=yes, ai-input=yes, ai-train=yes" },
+    },
   }),
 });
 ```
 
-`viteGraphLoader<Input>(options)` returns a loader whose JSON input is passed to
-its entry export. Existing zero-argument loaders remain valid. The host resolves
-framework-specific route `head()` values into node instances; pagegraph selects
-and validates the resulting plain metadata:
+Build-time consumers of page titles and descriptions read the same graph:
 
 ```ts
-import { loadPageHeads, viteGraphLoader } from "pagegraph/config";
+import { loadPageHeads } from "pagegraph/config"; // build-only
+import { tanstackStartGraph } from "pagegraph/tanstack-start";
 
-const loader = viteGraphLoader<{ exclude: string[] }>({
-  root: import.meta.dirname,
-  entry: "/lib/seo/graph.ts",
-  exportName: "loadHeadGraph",
+const heads = await loadPageHeads(tanstackStartGraph({ root: import.meta.dirname }), {
+  exclude: ["/docs", "/docs/**"],
 });
-const exclude = ["/docs", "/docs/**", "/captured-page"];
-const heads = await loadPageHeads(() => loader({ exclude }), { exclude });
 ```
 
-`selectPageHeadNodes(graph, options)` selects nodes before host metadata resolution.
-`pageHeads(graph, options)` returns `{ path, title, description }[]`, requiring
-nonblank titles and descriptions and naming the page on failure. `loadPageHeads`
+`selectPageHeadNodes(graph, options)` selects the page nodes `pageHeads` reads.
+`pageHeads(graph, options)` returns `{ path, title, description }[]` from each node's
+`head` (a declared `staticData.seo.head`, or a collection instance through its route's title
+template), requiring nonblank titles and descriptions and naming the page on failure. `loadPageHeads`
 always disposes the acquired graph, including when validation fails. Page nodes
 carry a sitemap declaration or an instance; layouts are excluded. By default,
 selection excludes noindex pages, redirects and parameter templates, while retaining
@@ -461,7 +713,7 @@ pagegraph graph                 # the graph as a tree · --format mermaid | json
 pagegraph inspect /pricing      # one node: policy, sitemap status, in/out edges
 pagegraph inspect <url> --live  # fetch a deployed page, validate its rendered <head>
 pagegraph links verify <url>    # crawl served HTML: depth, orphans, declared-vs-rendered
-pagegraph links verify <url> --assert-coverage  # also assert seo.config.ts coverage on served anchors
+pagegraph links verify <url> --assert-coverage  # also assert pagegraph.config.ts coverage on served anchors
 pagegraph links verify <url> --emit-rendered <file>  # save the rendered edge set
 pagegraph links candidates      # propose contextual links from the declared graph
 pagegraph research keywords --query "email api"  # combine graph, Executor, and Jev evidence
@@ -477,7 +729,7 @@ Stdout is data, stderr is status — `pagegraph check --json | jq` just works.
 `pagegraph links verify` crawls a site's served HTML — through the same DNS-pinned,
 private-IP-blocked HTTP path as `pagegraph audit` — and reports what a crawler
 actually receives: the real homepage depth, the pages with no incoming internal
-edge (rendered orphans), and, when the app has a `seo.config.ts`, the
+edge (rendered orphans), and, when the app has a `pagegraph.config.ts`, the
 declared-vs-rendered link diff. It is bounded with `--limit` and needs no
 framework or config. Discovery reads same-origin `robots.txt` and bounded
 sitemaps before following page anchors, so a sitemap-only page can appear as an
@@ -532,7 +784,7 @@ It is also a drop-in input for `pagegraph links candidates --rendered`.
 
 ### Assert coverage on the rendered graph
 
-`pagegraph check` evaluates the `seo.config.ts` `coverage` rules against the
+`pagegraph check` evaluates the `pagegraph.config.ts` `coverage` rules against the
 **declared** graph; `pagegraph links verify --assert-coverage` evaluates the same
 rules against the anchors a crawler **actually receives**. Only same-origin
 body-region anchors count — nav, header, and footer links are chrome — which is
@@ -549,7 +801,7 @@ non-zero) rather than reporting a false pass when the crawl outran `--limit`, a
 page failed to fetch (its anchors are missing), a body hit `--max-body-bytes`, the
 robots or sitemap discovery is incomplete, the
 config declares no `coverage`, or the artifact's origin differs from
-`seo.config.ts`. Under `--assert-coverage` the report gains a `coverage` block
+`pagegraph.config.ts`. Under `--assert-coverage` the report gains a `coverage` block
 (`{ rules, ok, violations }`); the default `--json` summary is unchanged.
 
 ### Propose contextual links
@@ -615,7 +867,7 @@ both `links candidates --site` and `improve links --suggestions`.
 
 ### Contextual-link coverage
 
-Declare a contextual-link coverage policy in `seo.config.ts` (a `coverage` array
+Declare a contextual-link coverage policy in `pagegraph.config.ts` (a `coverage` array
 of `{ path, minInbound }`), or pass repeatable `--require-inbound "<path-glob>=<n>"`
 flags to override it for one run. `pagegraph check` then fails (exit 1) unless
 every sitemap-eligible page matching the glob has at least `minInbound` incoming
@@ -709,7 +961,7 @@ undated rather than stale; give content its `modifiedAt` (or a route its
 
 ### Audit any website
 
-`pagegraph audit` is framework-independent and does not need `seo.config.ts`. It
+`pagegraph audit` is framework-independent and does not need `pagegraph.config.ts`. It
 validates target URLs before making requests, follows redirects through the same
 validation boundary, inspects the rendered document and discovery files, and
 can collect Lighthouse evidence through a validating proxy.
@@ -772,8 +1024,11 @@ import {
   hasStructuralViolations,
   inspectHtml,
 } from "pagegraph";
+import { evaluateAppGraph } from "pagegraph/tanstack-start";
 
-expect(hasStructuralViolations(checkGraph(loadSeoGraph()))).toBe(false);
+// the graph the plugin ships, evaluated through your Vite config
+const { graph } = await evaluateAppGraph({ root: appRoot, mode: "production" });
+expect(hasStructuralViolations(checkGraph(graph))).toBe(false);
 
 // render a page however you like, then assert the head it actually ships
 const report = inspectHtml(url, 200, html);