pagegraph 0.12.0 → 0.14.0

package/README.md

@@ -26,20 +26,194 @@ bun add pagegraph
 bun add -D lighthouse   # only for `pagegraph audit` performance evidence
 ```
 
+## Authored pages
+
+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 are safe in a Worker, an SSR server, or a
-browser; build entries load your app through Vite, parse routes natively, or drive Node I/O.
+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` | —                                 |
-| `pagegraph/react`  | runtime                       | `createSeo` → `seo.head`, `seoHead`, `Breadcrumbs`, JSON-LD generators                                    | `react`, `@tanstack/react-router` |
-| `pagegraph/tanstack-start/server` | runtime (Start server routes) | `robotsTxt`, `sitemapXml`, `seoGraph`, `seoSite`                                           | the `pagegraph()` plugin          |
-| `pagegraph/tanstack-start` | build (`vite.config.ts`, `seo.config.ts`) | `pagegraph()` Vite plugin, `tanstackStartGraph`, `evaluateAppGraph`                        | `vite`, `@tanstack/router-generator` |
+| `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 (`seo.config.ts`, CLI)  | `defineSeoConfig`, `viteGraphLoader`, `loadPageHeads`                                                     | `vite`                            |
+| `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.
@@ -48,21 +222,14 @@ instead of crashing on a native binding when a request first runs the code. The
 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
-OpenCode SDK only when invoked. The first workflow installs pinned OpenCode 2.0.22 into
-`~/.cache/pagegraph/opencode-2.0.22-2`, outside the app's dependency tree; subsequent workflows
-reuse the verified cache. This keeps consumer dependency overrides away from OpenCode's declared
-Effect and Drizzle versions. Executor plugins must use OpenCode's Effect version (`4.0.0-rc.112`).
-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. 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.
+The CLI **bundles PageGraph's Effect, TypeSafe provider runtime, and Pi agent runtime**, so it does
+not depend on the app's Effect version; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). Every
+workflow runs in-process on Pi 1.0.0. Improve workflows use guarded repository edit tools;
+research and dry-run actions expose only read tools. Every workflow failure after run creation
+writes `failure.json` with its stage, agent messages, 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.
 
 ### Agent skill
 
@@ -195,15 +362,14 @@ import { robotsTxt } from "pagegraph/tanstack-start/server";
 export const Route = createFileRoute("/robots.txt")({ server: { handlers: { GET: robotsTxt } } });
 ```
 
-**5. Gate CI.** The CLI reads the same graph through `seo.config.ts`:
+**5. Gate CI.** The CLI reads the same graph through `pagegraph.config.ts`:
 
 ```ts
-// seo.config.ts
+// pagegraph.config.ts
 import { defineSeoConfig } from "pagegraph/config";
 import { tanstackStartGraph } from "pagegraph/tanstack-start";
 
 export default defineSeoConfig({
-  origin: "https://example.com",
   loadGraph: tanstackStartGraph({ root: import.meta.dirname }),
 });
 ```
@@ -217,7 +383,7 @@ pagegraph check
 `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
-`seo.config.ts` at it with `viteGraphLoader` (see [CLI](#cli)).
+`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
@@ -227,28 +393,37 @@ Preview hosts (`indexable: false`) drop `contentSignal` and `directives`;
 
 ## Agentic workflows
 
-PageGraph can combine the deterministic route graph with a project-owned embedded OpenCode agent,
-live tools exposed by an Executor plugin, and Jev decisions. Scaffold the OpenCode preset once:
+PageGraph combines the deterministic route graph with project-owned agent instructions, live
+Executor tools, and Jev decisions. Every workflow uses Pi in-process. Scaffold the shared preset once:
 
 ```bash
 pagegraph init
 ```
 
-The generated `.pagegraph/opencode` directory contains one `seo` agent and customizable `content`,
-`technical`, and `authority` skills. Add your Executor plugin to its `opencode.jsonc`; OpenCode and
-the plugin own model and Executor authentication. PageGraph does not copy credentials or assume
-fixed provider-tool addresses.
+The generated `.pagegraph/agent` directory contains the `seo` agent instructions, `AGENTS.md`,
+and customizable workflow skills with Executor recipes. Pi composes these files into its system
+prompt and fails if a required file is missing. Pi uses its provider-specific environment variables
+for model authentication, such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
 
-Enable workflows in `seo.config.ts`:
+Research connects to [Executor](https://github.com/RhysSullivan/executor) through
+`@pi-ext/executor`. Set `EXECUTOR_BASE_URL` to the server, plus `EXECUTOR_CLIENT_ID[_FILE]` and
+`EXECUTOR_CLIENT_SECRET[_FILE]` when Cloudflare Access fronts it (both or neither). Every workflow
+declines Executor approval requests, and only provider calls that succeeded count as evidence.
+Use `executor_search` to discover tools and their TypeScript shapes, then `executor_execute` with
+a TypeScript snippet calling `tools.<namespace>.<tool>(input)` and a top-level `return`.
+Repository tools are `read_file`, `list_files`, and `search_text`; structured results go through
+`submit_result`. Improve action turns expose `edit_file` and `write_file` in write mode.
+
+Enable workflows in `pagegraph.config.ts`:
 
 ```ts
 export default defineSeoConfig({
   // origin, disallow, and loadGraph as above
   workflows: {
-    opencode: {
-      configDirectory: ".pagegraph/opencode",
+    agent: {
+      presetDirectory: ".pagegraph/agent",
       defaultModel: "openrouter/example/model",
-      // Optional per-completion budget in milliseconds; default 180000.
+      // Optional per-turn budget in milliseconds; default 180000.
       timeoutMs: 360_000,
       models: {
         "research.keywords": "openrouter/example/research-model",
@@ -279,9 +454,9 @@ Executor's live catalog and inspect the discovered tools' argument schemas, then
 structured observations with Jev. Tool paths are discovered at runtime; the generated skills contain
 editable starter recipes, not a fixed integration list.
 
-`workflows.opencode.timeoutMs` sets the positive integer deadline in milliseconds for each OpenCode
-completion (maximum `2147483647`). It covers prompt admission, model execution, and any workflow JSON
-repair prompt. A later action or continuation turn gets a separate budget. The default is `180000`.
+`workflows.agent.timeoutMs` sets the positive integer deadline in milliseconds for each Pi research or action turn
+(maximum `2147483647`, default `180000`). Research and action share the same agent conversation,
+so action turns retain the research context.
 
 Selecting pages preserves their incoming and outgoing relationships to non-selected pages in
 `evidence.neighborhood`. Those neighbors supply architecture context without becoming workflow
@@ -289,12 +464,13 @@ targets or consuming `--limit`. The agent receives the limit before research, an
 the decoded result before decisions.
 
 After research is validated, the run directory contains `research.json`: an incomplete checkpoint
-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
+with the collected evidence, decision inputs, and agent messages. 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
+Model results drop null properties and array elements before validation. Pi receives decode issues
+and missing Executor evidence through `submit_result`, so it can correct the result in the same
+agent loop; repeated rejected submissions fail the run. Every error after run creation writes
+`failure.json` with the workflow, stage, agent messages, 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.
 
@@ -313,20 +489,24 @@ original error with a note.
 | `improve links` | Contextual internal-link edits from graph and page evidence |
 
 The common selectors are repeatable `--page`, `--query`, and `--kind`, plus `--limit`, `--market`,
-`--language`, `--refresh`, `--model`, `--opencode-config`, and `--out`. Relevant workflows also
-accept `--competitor`, `--domain`, or `--device desktop|mobile`. Workflows are noninteractive and
-fail immediately if the agent asks a question or requests permission.
+`--language`, `--refresh`, `--model`, `--preset-directory`, and `--out`. Relevant workflows also
+accept `--competitor`, `--domain`, or `--device desktop|mobile`. Workflow prompts direct the agent
+to proceed without questions or forms and fail clearly when required input is missing.
 
 The four `improve` workflows write source files by default and require a clean Git tree. Use
-`--dry-run` to keep repository edit and shell tools disabled, or `--allow-dirty` when you explicitly
+`--dry-run` to expose only read tools, or `--allow-dirty` when you explicitly
 want the agent to edit alongside existing changes. PageGraph leaves every diff uncommitted and
-records modified, added, and deleted files after the workflow finishes.
+records modified, added, and deleted files after the workflow finishes. Write tools reject paths
+outside the repository, including symlink escapes, and paths under `.git`, `node_modules`,
+the runs directory, and the preset directory. There is no shell tool. For `improve links`,
+`fetch_page` reads extracted sentences from served pages on suggestion-report origins, respecting
+robots rules and the response size limit.
 
 Each run writes `.pagegraph/runs/<run-id>/run.json` and `summary.md`. The JSON retains the
-deterministic graph, context, complete OpenCode session export, Executor tool evidence, Jev question
-definitions and answers, Git provenance, changed files, and model provenance. Keep this directory
-ignored: provider output can be large or account-specific. Workflows fail when the configured model,
-active Executor plugin, catalog search plus discovered tool call, or `TYPESAFE_API_KEY` for Jev is
+deterministic graph, context, Executor tool evidence, Jev question definitions and answers, Git
+provenance, changed files, and model provenance. Schema-version-2 artifacts record `agent.runtime`
+as the literal `pi`, with messages and usage. Keep this directory ignored: provider output can be large or account-specific. Workflows fail when the configured model,
+Executor toolset, catalog search plus completed tool call, or `TYPESAFE_API_KEY` for Jev is
 unavailable.
 
 ## Typed paths
@@ -406,27 +586,106 @@ It also derives a small config module from the route tree: `robotsExclusions`
 (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. A
+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. Otherwise `viteGraphLoader` evaluates your graph module inside a headless Vite
-server, so path aliases, content plugins, and virtual modules all resolve:
+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" },
+    },
   }),
 });
 ```
@@ -461,7 +720,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 +736,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 +791,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 +808,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 +874,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 +968,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.