@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/README.md

@@ -1,21 +1,36 @@
 # @capacms/sdk
 
-## The `/api/` client (`@capacms/sdk/next`)
-
-Install the SDK from the `next` dist tag:
+The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from
+your models, Next.js caching and live preview, and codegen. The API reference
+is at https://docs.capacms.com/api.
 
 ```sh
 pnpm add @capacms/sdk@next
 ```
 
+It runs on Node 18 or later. Its types need TypeScript 5.0 or later, with
+`strict` on or off.
+
+| Import | What it is |
+|---|---|
+| `@capacms/sdk/next` | The client for `/api/`: entries, GraphQL, pages and preview. It takes a `cap_` key, or the legacy key a site already holds for reads. Start here. |
+| `@capacms/sdk/nextjs` | Next.js helpers: `graphql()` in a server component, cache tags, draft and edit mode, webhook revalidation. |
+| `@capacms/sdk/nextjs/overlay` | The live preview overlay, as a Next.js client component. |
+| `@capacms/sdk/overlay` | The same overlay without Next. |
+| `@capacms/sdk/image` | Image URLs on Capa's CDN for any framework: `imageUrl`, `srcSet`, `sizes` and `isCapaImageUrl`. |
+| `@capacms/sdk/nextjs/image-loader` | A `next/image` loader that lets Capa's CDN resize, for `images.loaderFile`. |
+| `@capacms/sdk` | The legacy `/v2/api` client, which takes a legacy key and a tenant id and refuses a `cap_` key, and the webhook signature check. |
+
+## The `/api/` client (`@capacms/sdk/next`)
+
 Create one client per key and pin the platform version in code:
 
 ```ts
 import { createClient, CapaError } from "@capacms/sdk/next";
 
 const capa = createClient({
-  baseUrl: process.env.CAPA_BASE_URL!,
-  apiKey: process.env.CAPA_API_KEY!,       // cap_live_... or cap_test_...
+  baseUrl: process.env.CAPA_API_URL!,
+  apiKey: process.env.CAPA_KEY!,           // cap_live_..., cap_test_..., or the legacy key your site has
   version: "2026-10-01",
   contract: 1,
 });
@@ -23,7 +38,32 @@ const capa = createClient({
 
 The `/api/` client sends `x-api-key`, `Capa-Version`, optional
 `Capa-Contract`, and `Accept: application/json`. It never sends
-`X-Tenant-Key`; the tenant comes from the `cap_` key.
+`X-Tenant-Key`; the tenant comes from the key.
+
+### Keys
+
+A `cap_` key is the key for `/api/`: scoped, and stored hashed. `cap_live_`
+reads published content, `cap_test_` drafts too. Mint one in the Capa admin
+under Developers > Keys.
+
+The legacy key your site already holds works too, for every read: a `pk_`
+or `sk_` key, or an older key with no prefix, since every key but `cap_` is
+a legacy key to the API. That covers `entries`, `graphql`,
+`graphqlSchema`, `pages`, `me`, `versions` and `preview`: a site checks an
+editor's preview link with the key it already holds, and Capa refuses a link
+made for another project. The first client built with one prints a warning
+once per process, naming the `cap_` key to mint. Draft reads through the SDK
+keep their rule and take a `cap_` key only: `draftClient`'s `draft` config,
+and `CAPA_DRAFT_KEY` for `getCapaClient` and `graphql()`, throw a `TypeError`
+for a legacy key before any request. An `apiKey` that is not a string is
+refused where the client is built.
+
+`CAPA_API_URL` and `CAPA_KEY` are the names every Capa tool reads: the
+`/nextjs` helpers, `capa-codegen` and Capa's MCP server, so one `.env` serves
+them all. `capa persist` registers with the development key in
+`CAPA_DRAFT_KEY`, since only a development key stores a document (see
+Persisted queries). `CAPA_BASE_URL` and `CAPA_API_KEY` still work as
+aliases; when both are set, the first pair wins.
 
 ### Entries
 
@@ -53,8 +93,8 @@ const one = await capa.entries.get("articles", "entry-id", {
 });
 ```
 
-`select` may be the grammar string from `docs/api/entries.md` or the object
-form above. Lists return `{ data, page, meta, cacheTags }`; singles return
+`select` may be the grammar string the API reference describes
+(https://docs.capacms.com/api/entries) or the object form above. Lists return `{ data, page, meta, cacheTags }`; singles return
 `{ data, meta, cacheTags }`. `cacheTags` is parsed from the `Surrogate-Key`
 header. `get()` returns `null` for `404 entry_not_found` and throws every other
 error.
@@ -64,7 +104,7 @@ Filters use the `/api/` operators:
 ```ts
 await capa.entries.list("articles", {
   filter: {
-    id: { in: ["a", "b"] },
+    id: { in: ["00000000-0000-4000-8000-000000000021", "00000000-0000-4000-8000-000000000022"] },
     views: { gte: 10 },
     tags: { hasAny: ["news", "launch"] },
   },
@@ -75,6 +115,102 @@ await capa.entries.list("articles", {
 Unknown filter operators throw a local `TypeError` before any request is sent.
 Per-call `{ signal }` is forwarded to `fetch`.
 
+#### Typed reads
+
+`capa-codegen` writes an interface per model (see Codegen). Pass it, and the
+select's own type, and `fields` is typed as the API returns it:
+
+```ts
+import type { Articles, ArticlesSelect } from "./capa-types"; // written by capa-codegen
+
+const select = [
+  "title",
+  { author: ["name"] },
+  { coauthors: { select: ["name"], limit: 3 } },
+] as const satisfies ArticlesSelect;
+
+const typed = await capa.entries.list<Articles, typeof select>("articles", { select });
+
+for (const article of typed.data) {
+  const { title, author, coauthors } = article.fields;
+  if (author && "fields" in author) console.log(title, author.fields.name);
+  for (const coauthor of coauthors.items) {
+    if ("fields" in coauthor) console.log(coauthor.fields.name);
+  }
+  article.fields.body; // compile error: the select does not name it
+}
+```
+
+- A relation the select expands is the related entry, with its own `fields`,
+  or `{ id, model, missing: true }` when that entry was deleted, is
+  unpublished for a production key, or is in a model the key cannot read.
+  `"fields" in author` tells them apart.
+- A relation the select names without expanding it (`"author"`, or every
+  relation under `*`) is a reference, `{ id, model }`.
+- A relation list is `{ items, pageInfo }`, expanded or not.
+- Media is `{ id, url, alt, type, width, height }`.
+- A field the select names is always there, and `null` when it was never
+  filled, as the API writes it. `title?: string` in the model reads as
+  `string | null`.
+- A field the select does not name is not there, so reading it does not
+  compile.
+
+Without `typeof select`, or with a select written as a string, every field is
+typed, and each relation as whichever of the three it may be. `get` and
+`iterate` take the same two types, and `EntryFields<Articles, typeof select>`
+names the type of `fields`.
+
+### Flat responses: each related entry once
+
+By default an expanded relation is nested where you selected it, so twenty
+articles by one author carry that author twenty times. Pass `shape: "flat"` and
+every relation comes back as a `{ id, model }` reference, with each expanded
+entry once in `included`, keyed by model namespace and then id:
+
+```ts
+const select = ["title", { author: ["name"] }] as const satisfies Select<Article>;
+const flat = await capa.entries.list<Article, typeof select>("articles", {
+  select,
+  shape: "flat",
+});
+
+flat.data[0].fields.author;             // { id: "…", model: "authors" }
+flat.included.authors[authorId].fields; // { name: "Ada Vale" }, typed from Author
+```
+
+`included` is typed by the select: the union of the entry types it expands, at
+any depth, each field of which may be absent, since an entry holds what every
+path that reached it selected. A relation in `data` or in `included` is a
+reference. A select written as a plain string types `included` as
+`Record<string, unknown>`. `get` takes `shape: "flat"` the same way.
+`iterate` reads the tree shape only.
+
+`inflate` turns a flat result back into the tree result, deep-equal to what the
+same request without `shape` returns:
+
+```ts
+import { inflate } from "@capacms/sdk/next";
+
+const tree = inflate(flat); // { data, page, meta, cacheTags }, typed as the tree read
+```
+
+- It walks the select the request sent. A result from this client carries it
+  (`flat.select`); for a body you fetched yourself, pass it:
+  `inflate(body, "title,author(name)")`.
+- `$tags`, `$createdAt` and the other `$` names in the select are the system
+  keys, as the API reads them, so `select=$tags,tags` on a model with its own
+  `tags` field comes back with both.
+- It returns copies. The same author under twenty articles is twenty equal,
+  independent objects, as when a tree body is parsed. The input is not changed.
+- Cycles end where the select ends: `a` related to `b` related to `a` is
+  inflated to the depth you wrote and no further.
+- An entry reached by two paths holds the union of what they selected, and one
+  value per field. If two paths expand the same array relation with different
+  `limit` or `sort`, the first one wins, and `inflate` cannot tell them apart.
+  Every other request round-trips exactly.
+- In edit mode, included entries are marked, and so is every copy `inflate`
+  makes of them.
+
 ### Errors
 
 ```ts
@@ -105,7 +241,11 @@ const capa = createClient({ baseUrl, apiKey, version: "2026-10-01", fetch: fetch
 ```
 
 `withCache` merges `{ next: { tags, revalidate } }` into every fetch call.
-`tagsFor` builds Capa surrogate keys: `m:`, `e:`, `k:`, and `t:`.
+`tagsFor` builds Capa surrogate keys: `m:`, `e:`, `k:`, and `t:`, by id, and
+`tagsFor({ namespace: "articles" })` builds `capa:model:articles`, the tag
+for a GraphQL read (see GraphQL), and `capa:media`. `revalidateFromWebhook`
+revalidates all of them for the entry and model a webhook names, and for a
+media event, the file's `f:` key and `capa:media`.
 
 Webhook revalidation pairs with the existing signature verifier:
 
@@ -139,19 +279,982 @@ SDK never imports `next/*`:
 ```ts
 import { draftMode } from "next/headers";
 import { draftClient } from "@capacms/sdk/nextjs";
+import type { CapaQuery } from "./capa-graphql"; // written by capa-codegen --graphql
 
-const capa = await draftClient({
+const capa = await draftClient<CapaQuery>({
   production,
   draft,
   isDraft: async () => (await draftMode()).isEnabled,
 });
 ```
 
+`CapaQuery` types the GraphQL builder on the client it returns, as it does
+for `createClient<CapaQuery>`; `getCapaClient<CapaQuery>` and
+`getPublishedClient<CapaQuery>` take it the same way. Without it each helper
+returns an untyped client. `getCapaClient` sends its GraphQL reads as it
+sends its REST reads, which Next does not keep, unless a call gives `tags` or
+`revalidate`; then it keeps them in Next's data cache as `graphql()` does
+(see The typed builder).
+
+## Images
+
+Capa serves every upload from its CDN at
+`https://cdn.capacms.com/files/<key>`, and resizes it from the query string.
+`@capacms/sdk/image` builds those URLs for any framework:
+
+```ts
+import { imageUrl, srcSet, sizes } from "@capacms/sdk/image";
+
+const hero = { id: "f1", url: "https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg", alt: "Terrace", type: "image", width: 2400, height: 1600 };
+
+imageUrl(hero, { width: 1200, format: "webp" });
+// https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=1200
+
+srcSet(hero, [640, 960, 1280, 1920], { format: "webp" });
+// ...?format=webp&width=640 640w, ...?format=webp&width=960 960w, ...
+
+sizes({ 768: "50vw", 1280: "33vw" });
+// (min-width: 1280px) 33vw, (min-width: 768px) 50vw, 100vw
+```
+
+`imageUrl(image, options)` and `srcSet(image, widths, options)` take a media
+value as `/api/` returns it (`{ id, url, alt, type, width, height }`), the
+legacy client's `CapaImage`, a CDN URL, or a file key such as
+`sunns_1790971326210_d54fed020806.jpg`.
+
+| Option | Values | Default, left out of the URL |
+|---|---|---|
+| `width`, `height` | CSS pixels, whole numbers | the image's own size |
+| `fit` | `inside`, `cover` (crop), `contain` (pad), when both `width` and `height` are given | `inside` |
+| `quality` | 1 to 100 | 80; 60 with `format: "avif"`. Kept in the URL with `avif` and `auto` |
+| `dpr` | 1 to 3; the image is `width × dpr` pixels wide | 1 |
+| `blur` | 1 to 256: a blurred placeholder that many pixels square | none |
+| `format` | `webp`, `avif`, `jpeg`, `png`, `auto` | the image's own format |
+
+What the helpers do for you:
+
+- **Every URL is already in the order and spelling Capa's CDN serves.** Capa
+  answers any other spelling of the same query with a 301, which costs the
+  first view of each image a round trip. Defaults are left out, as the CDN
+  leaves them out.
+- **Nothing is enlarged.** When the image's own `width` (and, for a box,
+  `height`) is known, a request for more pixels than it has is brought down
+  to its size, keeping the requested shape. A media value from `/api/` has
+  both. `srcSet` lists one candidate at the image's own width in place of the
+  wider ones.
+- **`format=auto` is sent only when you pass it.** Note that the CDN
+  currently returns JPEG for `format=auto` whatever the browser accepts. Use
+  `format: "webp"` until that is fixed.
+- **Anything that is not a Capa image comes back unchanged:** another host's
+  URL, a path on your own site, or a media value whose `type` is not
+  `image`. `isCapaImageUrl(src)` says which is which.
+- **An older upload's `https://api.capacms.com/files/...` URL is built on
+  `cdn.capacms.com`.** It is the same file: the CDN fetches from that host,
+  which has no cache in front of it. On the CDN a resized copy is made once
+  and cached at the edge.
+- **No image gives `undefined`.** `imageUrl` returns `undefined` for `null`,
+  or for a media value whose `url` is null or empty (the legacy API sends an
+  unset image as `{ url: "" }`), so for a media value its type is
+  `string | undefined`; for a string it is `string`. `srcSet` returns
+  `undefined` whenever it has nothing to resize. Either can go straight into
+  a `src` or `srcSet` prop.
+- An option the CDN would refuse with a 400 (a width that is not a whole
+  number, `quality: 120`, more than 4096 pixels on an edge) throws a
+  `TypeError` naming the option.
+
+For a crop at a fixed shape, `srcSet` takes `aspectRatio` (width over height)
+in place of `height`:
+
+```ts
+import { srcSet } from "@capacms/sdk/image";
+import type { EntryMedia } from "@capacms/sdk/next";
+
+declare const cover: EntryMedia | null;
+
+const candidates = srcSet(cover, [640, 1280, 1920], { aspectRatio: 16 / 9, fit: "cover", format: "webp" });
+```
+
+### Plain HTML
+
+Build the attributes wherever the page is rendered, a server template or a
+build script:
+
+```ts
+import { imageUrl, srcSet, sizes } from "@capacms/sdk/image";
+import type { EntryMedia } from "@capacms/sdk/next";
+
+const attr = (value: unknown) => String(value ?? "").replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+function picture(image: EntryMedia): string {
+  return `<img
+  src="${attr(imageUrl(image, { width: 1280, format: "webp" }))}"
+  srcset="${attr(srcSet(image, [480, 800, 1280, 1920], { format: "webp" }))}"
+  sizes="${sizes({ 1024: "50vw" })}"
+  width="${attr(image.width)}" height="${attr(image.height)}"
+  alt="${attr(image.alt)}" loading="lazy">`;
+}
+```
+
+In the browser the result is an ordinary responsive image:
+
+```html
+<img
+  src="https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=1280"
+  srcset="https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=480 480w, https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=800 800w, https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=1280 1280w, https://cdn.capacms.com/files/sunns_1790971326210_d54fed020806.jpg?format=webp&width=1920 1920w"
+  sizes="(min-width: 1024px) 50vw, 100vw"
+  width="2400" height="1600" alt="Terrace" loading="lazy">
+```
+
+`@capacms/sdk/image` is an ES module for bundlers and CommonJS for
+`require`, and carries no other part of the SDK, so it adds little to a
+browser bundle.
+
+### React
+
+```tsx
+import { imageUrl, srcSet, sizes } from "@capacms/sdk/image";
+import type { EntryMedia } from "@capacms/sdk/next";
+
+export function Hero({ image }: { image: EntryMedia | null }) {
+  if (!image?.url) return null;
+  return (
+    <img
+      src={imageUrl(image, { width: 1280, format: "webp" })}
+      srcSet={srcSet(image, [640, 960, 1280, 1920], { format: "webp" })}
+      sizes={sizes({ 1024: "50vw" })}
+      width={image.width ?? undefined}
+      height={image.height ?? undefined}
+      alt={image.alt ?? ""}
+    />
+  );
+}
+```
+
+A blurred placeholder is one more URL: `imageUrl(image, { blur: 20, format: "webp" })`
+is a few hundred bytes to show while the full image loads.
+
+### Next.js: let Capa resize for next/image
+
+`next/image` sends every image through Next's optimizer unless a loader says
+otherwise, and on Vercel that optimizer is billed by use. A custom loader hands the
+resizing to Capa's CDN instead. Add a loader file:
+
+```ts
+// capa-image-loader.ts (or .js)
+"use client";
+import { createCapaImageLoader } from "@capacms/sdk/nextjs/image-loader";
+
+export default createCapaImageLoader({ format: "webp" });
+```
+
+and name it in `next.config`:
+
+```js
+// next.config.mjs
+export default {
+  images: {
+    loader: "custom",
+    loaderFile: "./capa-image-loader.ts",
+  },
+};
+```
+
+Then use `<Image>` as usual, with the media value's `url`. Mark any other
+image `unoptimized`, since the loader leaves it as it is and Next warns in
+development that the loader ignores its width:
+
+```tsx
+import Image from "next/image";
+import { isCapaImageUrl } from "@capacms/sdk/image";
+import type { EntryMedia } from "@capacms/sdk/next";
+
+export function Cover({ image }: { image: EntryMedia }) {
+  const src = image.url ?? "/placeholder.jpg";
+  return <Image src={src} unoptimized={!isCapaImageUrl(src)} alt={image.alt ?? ""} width={image.width ?? 1200} height={image.height ?? 800} sizes="(min-width: 1024px) 50vw, 100vw" />;
+}
+```
+
+Next lists a URL per width it wants, and the loader turns each into a Capa
+URL in canonical order: `?format=webp&width=640`, `?format=webp&width=750`,
+and so on. An `<Image>`'s `quality` prop becomes `quality`; without one,
+Capa's default of 80 applies. `createCapaImageLoader` takes `format` and a
+default `quality`; `capaImageLoader`, the default export of
+`@capacms/sdk/nextjs/image-loader`, sets neither, so each image keeps its own
+format. Both are also exported from `@capacms/sdk/nextjs` for server code.
+
+The loader resizes only a full Capa URL, on `cdn.capacms.com` or
+`api.capacms.com` (built on the CDN host, as above). Any other `src` goes
+back unchanged: a file in `public/`, another host, or a bare name such as
+`logo.png`, which is your site's file and not a Capa key.
+
+The loader never throws, because a throw fails the render of the whole page.
+A `src` or prop the CDN would refuse, such as a src carrying `dpr=2` at a
+width of 3840 (past the 4096-pixel edge) or `quality={0}`, gets the `src`
+back unchanged. A width past 4096 pixels asks for 4096. The loader only sees
+the `src` string, so it cannot know the image's own width: keep
+`deviceSizes` to the widths your layout uses.
+
+The loader file needs its own entry, `@capacms/sdk/nextjs/image-loader`,
+because Next runs the loader in the browser on every page with an image, and
+that entry holds the image rules and nothing else.
+
+## GraphQL
+
+`/api/graphql` reads the same content as `/api/entries`, with the same key,
+version, limits and error codes. The schema is built for your key: it has
+exactly the models the key can read. The API reference is at
+https://docs.capacms.com/api/graphql.
+
+### In a Next.js server component
+
+```tsx
+// app/blog/page.tsx
+import { draftMode, headers } from "next/headers";
+import { capaAttrs } from "@capacms/sdk/next";
+import { graphql, tagsFor } from "@capacms/sdk/nextjs";
+import { BlogIndexModels } from "./capa-graphql"; // written by capa-codegen --graphql
+
+const BLOG_INDEX = `#graphql
+  query BlogIndex($first: Int) {
+    articles(first: $first, sort: [publishedAt_DESC]) {
+      nodes { id model title author { name } }
+    }
+  }
+`;
+
+export default async function Blog() {
+  const { data } = await graphql(BLOG_INDEX, { first: 5 }, {
+    draftMode,
+    headers,
+    tags: tagsFor({ namespace: BlogIndexModels }), // articles, and authors for author { name }
+    revalidate: 60,
+  });
+  return (
+    <ul>
+      {data?.articles?.nodes.map((a) => <li key={a.id} {...capaAttrs(a, "title")}>{a.title}</li>)}
+    </ul>
+  );
+}
+```
+
+`data` and the variables are typed from the document itself, with no cast,
+once `capa-codegen --graphql` has read it (see Typed documents). Until then
+the call does not compile, and the error says to run it, so a document edited
+since the last run is never silently untyped.
+
+Given `tags` or `revalidate`, `graphql()` keeps a published read in Next's
+data cache, through Next's own `unstable_cache`, under the tags you give.
+Given neither, it keeps nothing: the read is sent as a REST read is, and the
+page shows a publish on its next render. `BlogIndexModels` lists the models
+the query reads, which codegen writes beside its types: `articles`, and
+`authors` for `author { name }`. It changes when the query does, so a model
+the query starts reading is never left out. `tagsFor({ namespace })` makes
+one tag per model (`capa:model:articles`), and `capa:media`. The webhook
+route above calls `revalidateFromWebhook`, which revalidates a model's tag
+whenever an entry of the model is published, unpublished or deleted, so the
+page shows the change on the next request. Editing a file in the media
+library, its alt text say, changes no entry, so it revalidates `capa:media`
+instead, and every read tagged by its models shows the new text. How long a
+read is kept:
+
+- With neither `tags` nor `revalidate`, not at all: every render reads the
+  API, as `entries.list` does, so a site with no webhook route still shows a
+  publish on the next request.
+- With `tags` and no `revalidate`, until one of its tags is revalidated.
+  With the webhook route, that is until the next publish of a model it reads.
+- With `revalidate: 60`, also at most 60 seconds, so a missed webhook costs
+  a minute of stale content at most.
+- With `revalidate: 0`, not at all.
+
+A read with a `revalidate` and no `tags` is tagged `capa:graphql`
+(`GRAPHQL_TAG`), which `revalidateFromWebhook` revalidates on every content
+change, so it is never stale after a publish; tag it with its models to
+refresh the page only when one of them changes.
+
+A read that answered with `errors` is never kept: a root field that timed
+out is shown once and read again on the next request. Next's fetch cache is
+not used for a GraphQL read, since it keeps every 200 and a GraphQL error is
+a 200, and in Next 15 it keeps nothing without a `revalidate`. A draft and an
+edit-mode page are read uncached. Outside a Next request, in a script or a
+test, the read is simply sent. `unstable_cache` is an option only to supply
+another implementation.
+
+`draftMode` and `headers` work out draft and edit mode as `getCapaClient`
+does. Under draft mode the read uses `CAPA_DRAFT_KEY`, a `cap_` key, and
+bypasses the cache.
+In edit mode (draft mode, or the editor's Published view) each entry that
+selected `id` and `model` is marked, so `capaAttrs(node, field)` makes it
+clickable in the Capa editor (see Live preview); a visitor's page carries no
+tags. Leave both out for a page with no preview.
+
+`graphql()` reads `CAPA_API_URL`, `CAPA_KEY` and `CAPA_API_VERSION` like the
+other helpers, and a setting you pass in `config` (`baseUrl`, `apiKey`,
+`version`, `fetch`) is used instead of its variable, so a full `config`
+needs no env at all. A published read is a GET, which the CDN and the API
+also cache for the published key; a document too long for a URL goes as a
+POST, which only Next's data cache keeps (see How reads are sent and cached).
+The result's `cacheTags`
+holds the API's `Surrogate-Key` for a GET (`m:<modelId>`, `e:<entryId>`), for
+purging a CDN of your own. `draft: true` or `false` decides draft mode
+yourself. Pass `persisted: true` once your documents are stored with
+`capa persist` (see Persisted queries).
+
+### In a Node script
+
+```ts
+import { createClient, isCapaError } from "@capacms/sdk/next";
+
+const capa = createClient({
+  baseUrl: process.env.CAPA_API_URL!,
+  apiKey: process.env.CAPA_KEY!,
+  version: "2026-10-01",
+});
+
+const POPULAR = `#graphql
+  query Popular { articles(first: 5, filter: { views: { gte: 10 } }) { nodes { id title } } }
+`;
+
+const { data, errors, extensions } = await capa.graphql(POPULAR);
+
+for (const error of errors) console.warn(error.code, error.message, error.hint, error.path);
+console.log(data?.articles?.nodes, extensions.cost?.actualQueryCost);
+```
+
+For a string codegen has not read, such as one built at run time, pass the
+data type yourself: `capa.graphql<{ version: string }>("{ version }")`.
+
+`capa.graphql(document, variables?, options?)` resolves once the API has run
+the document, even when `errors` is not empty: the root fields that worked
+still carry data, a root field that failed is `null` (which is why every list
+root is nullable in the schema and in generated types), and each error is a
+`CapaGraphQLError`.
+
+A `CapaGraphQLError` is a plain object: the spec's `message`, `locations`,
+`path` and `extensions`, with `code`, `hint`, `docs`, `param` and `type`
+lifted out of `extensions`. So `Response.json(result)` in a route handler, and
+a server component passing `errors` to a client component, keep every field.
+`isCapaGraphQLError(value)` checks one by its shape, so it holds after JSON.
+
+A request the API refuses as a whole throws `CapaError`, whose
+`graphqlErrors` holds every error the API sent: a document that does not
+parse or validate, a variable of the wrong type, a query over a budget, a
+filter the planner refuses. Its body has `errors` and no `data`. GraphQL over
+HTTP sends that refusal as a 200 on `application/json`, which this client
+asks for, and as a 4xx on `application/graphql-response+json`; either way the
+`CapaError` is the same, with `status` 400. Other refusals keep their own
+status: the key (401), the plan (402), the origin (403), the contract (404),
+a mutation (405) and the rate (429).
+
+The API runs 4 reads at once per project, GraphQL documents and
+`/api/entries` reads counted together, and at most 3 of them for one client
+of a key, so one busy visitor never holds every slot. Up to 64 more per
+client and 256 per key wait for a slot. Past that it answers 429 with
+`Retry-After`. The client waits that long, plus up to 250 ms, and sends the
+request again, up to 3 times, so a page that reads many things at once from
+one key slows down instead of failing. `retries: 0` throws the first 429
+instead, and `retries: n` allows n repeats. A 429 that is thrown carries
+`retryAfter`, in seconds. A `Retry-After` over 30 seconds is thrown at once
+rather than waited out, and `signal` ends a wait early. `entries.list` and
+`entries.get` share these limits and throw their 429 with `retryAfter`
+rather than repeat it. When an API machine is full of other projects' reads,
+it answers 503 `service_unavailable` with `Retry-After`, which is thrown.
+
+Where GraphQL is switched off (`CAPA_API_GRAPHQL=off`), the `CapaError`
+says "This Capa deployment does not serve GraphQL." and its `hint` says to
+read with `entries.list` or `entries.get` meanwhile. Options:
+`operationName`, `method`, `persisted: true`, `retries`, and `signal`.
+
+`extensions.cost` is the query's cost as Shopify's APIs report it, in
+entries. `requestedQueryCost` is the most the document can read: every list at
+its full `first` (25 at a root and 100 nested when you give none), capped at
+5,000, plus 500 for each scan. `actualQueryCost` is what it did read, plus 500
+for each scan that ran. The 5,000 limit is checked before the document runs,
+on a tighter figure: a nested list with no `first` counts 10 for each entry
+above it, not 100, so `{ articles(first: 1) { nodes { coauthors { nodes { name } } } } }`
+passes as 11 entries and requests 101. That figure is `budget.counted`, and
+the limit is `budget.limit`, on every response: it is the number to watch,
+since a document is refused exactly when `counted` passes `limit`, and a
+refusal states it. There is no per-key budget, so there is no
+`throttleStatus`.
+
+A document that uses a deprecated field, argument or enum value gets one
+`{ coordinate, reason }` for each in `extensions.deprecations`, such as
+`{ "coordinate": "Articles._folder", "reason": "Read folder instead." }`.
+`capa-codegen --graphql` warns about the same uses before you ship.
+
+A scan reads entries the answer does not hold. Each of these is one:
+
+- a `totalCount`;
+- a filter or sort through a relation;
+- a root field that filters or sorts by its model's own fields, once however
+  many such conditions it has, so
+  `articles(first: 10, filter: { featured: { eq: true } })` requests 510;
+- each `contains`, `startsWith`, `endsWith` or `ne` condition past the first;
+- a relation list sorted with `sort`.
+
+Filters on `id`, `createdAt`, `updatedAt`, `publishedAt` and `_tags`, and a
+relation's `eq`, are served by an index and cost nothing. The API reference
+has every rule: https://docs.capacms.com/api/graphql#cost.
+
+A development key's reads, such as the draft client's, also carry
+`extensions.capa`. Its `cost` breaks the cost down against every limit
+(depth, root fields, connections, nodes, fields) and counts the `scans`. Its
+`rest` names the REST request each root field was answered with. A production
+key's reads leave `extensions.capa` out, which keeps a cached page's answer
+small.
+
+#### How reads are sent and cached
+
+A read is a GET whenever its URL fits the API's limit of 8,192 bytes (path
+and query string), and a POST when it does not; a long document is never
+refused for its length. `method: "POST"` always sends a POST, and
+`method: "GET"` sends a GET that fits and a POST that does not.
+
+| Request | Cached by the API and the CDN |
+|---|---|
+| GET with a production key, no errors | yes: `public, max-age=60`, purged by the entries it read (`cacheTags`) |
+| GET with a development key | no (`no-store`): drafts move |
+| any response with `errors` | no (`no-store`) |
+| GET selecting `me`, `__schema` or `__type` | no (`no-store`) |
+| POST | never |
+
+So a document too long for a GET is not cached. Keep it cacheable with
+persisted queries: `persisted: true` sends only the hash by GET (see
+Persisted queries). `graphqlSchema()` reads the introspection by POST, since
+it is never cached. The admin host serves GraphQL by POST only and answers a
+GET as a path it does not serve; a read that did not ask for GET is then
+repeated as a POST, and that host is read by POST for five minutes. A
+`method: "GET"` read there throws "This Capa host does not serve GraphQL by
+GET." In Next.js, `graphql()` from `/nextjs` adds Next's data cache on top
+when a read gives `tags` or `revalidate`, for a published read with no
+errors, a POST included: kept under its `tags` until one is revalidated, or
+for `revalidate` seconds when you give it, and never for a draft.
+
+### The typed builder
+
+Write the query as an object and get the result typed from exactly what you
+selected, without writing GraphQL text:
+
+```ts
+import { createClient } from "@capacms/sdk/next";
+import type { CapaQuery } from "./capa-graphql"; // written by capa-codegen --graphql
+
+const capa = createClient<CapaQuery>({ baseUrl, apiKey, version: "2026-10-01" });
+
+const { data } = await capa.graphql.query({
+  articles: {
+    args: { first: 5, sort: ["publishedAt_DESC"], filter: { featured: { eq: true } } },
+    nodes: { title: true, author: { name: true } },
+  },
+});
+
+data?.articles?.nodes[0].author?.name; // string | null
+data?.articles?.nodes[0].body;         // compile error: not selected
+```
+
+`true` selects a scalar, an object selects fields of a relation or a
+connection, and `args` sits beside the fields of anything that takes
+arguments. A misspelled field, argument, filter field or operator fails to
+compile, even beside a correct one, and so does an argument of the wrong type,
+a sort value that is not in the enum, or a required argument left out
+(`article` without `args: { id }`). The compiler's error names the key and
+where it was written: `titel: true` under `articles.nodes` fails with
+`Type 'true' is not assignable to type 'true & SelectionError<"titel is not a
+field of articles.nodes">'`. A `Date` in `args` is sent as its ISO text.
+Without `CapaQuery` the builder still runs, untyped.
+`selectionToDocument(selection)` returns the text it sends.
+
+`query()` takes the options `capa.graphql` takes, except `persisted`. Its
+document is printed when it runs, so `capa persist` never stored it, and it
+is already a GET that the API and the CDN cache. To persist a read, write it
+as a `#graphql` literal (see Persisted queries).
+
+In a Next.js server component, read through `getCapaClient`. A read that
+names tags is kept in Next's data cache under them:
+
+```tsx
+// app/blog/page.tsx
+import { draftMode, headers } from "next/headers";
+import { getCapaClient, tagsFor } from "@capacms/sdk/nextjs";
+import type { CapaQuery } from "./capa-graphql";
+
+export default async function Blog() {
+  const capa = await getCapaClient<CapaQuery>({ draftMode, headers });
+  const { data } = await capa.graphql.query(
+    { articles: { args: { first: 5, sort: ["publishedAt_DESC"] }, nodes: { id: true, title: true } } },
+    { tags: tagsFor({ namespace: "articles" }), revalidate: 60 },
+  );
+  return <ul>{data?.articles?.nodes.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
+}
+```
+
+`tags` and `revalidate` work as they do for `graphql()` (see In a Next.js
+server component). A read is kept until a publish of a model its tags name,
+a read with errors is never kept, and a draft or an edit-mode page is read
+uncached. A read with neither is not kept, as the client's REST reads are
+not. `capa.graphql(document)` on the same client takes them too.
+
+Read one field twice in one request with an alias: any other key, with
+`__aliasFor` naming the field it reads. A home page's featured and latest
+articles are one request:
+
+```ts
+const { data: home } = await capa.graphql.query({
+  articles: { args: { first: 3, filter: { featured: { eq: true } } }, nodes: { id: true, title: true } },
+  latest: { __aliasFor: "articles", args: { first: 5, sort: ["publishedAt_DESC"] }, nodes: { id: true, title: true } },
+});
+
+home?.latest?.nodes[0].title; // string | null, typed as articles is
+```
+
+The alias is checked as the field it names, arguments and fields included,
+and sent as `latest: articles(...)`. A scalar is aliased with `__aliasFor`
+alone: `{ headline: { __aliasFor: "title" } }`.
+
+#### Typing a component's props
+
+`NodeOf` names one entry of a builder read, so a component that renders it
+takes exactly what the selection reads, and the two cannot drift:
+
+```tsx
+import type { NodeOf } from "@capacms/sdk/next";
+import type { CapaQuery } from "./capa-graphql";
+
+const teasers = {
+  articles: { args: { first: 5 }, nodes: { id: true, title: true, author: { name: true } } },
+} as const;
+
+// { id: string; title: string | null; author: { name: string | null } | null }
+type Teaser = NodeOf<CapaQuery, typeof teasers, "articles">;
+
+function Card({ article }: { article: Teaser }) {
+  return <li>{article.title} by {article.author?.name}</li>;
+}
+
+const { data } = await capa.graphql.query(teasers);
+const cards = data?.articles?.nodes.map((article) => <Card key={article.id} article={article} />);
+```
+
+It is a node of a list root, the entry of a single root (`article`), or the
+node of an alias (`NodeOf<CapaQuery, typeof home, "latest">`).
+`QueryResult<CapaQuery, typeof teasers>` is the type of `data` as a whole.
+
+#### The same data in REST's shape
+
+The builder returns GraphQL's shape, because that is what its types describe:
+`articles.nodes[0].author.name`. Code written against `/api/entries` reads
+entries instead: `data[0].fields.author.fields.name`. `toTree` converts one to
+the other:
+
+```ts
+import { toTree } from "@capacms/sdk/next";
+import { capaTreeLayout } from "./capa-graphql"; // written by capa-codegen --graphql
+
+const selection = {
+  articles: {
+    args: { first: 5, sort: ["publishedAt_DESC"] },
+    nodes: { id: true, status: true, title: true, author: { id: true, status: true, name: true } },
+  },
+} as const;
+const { data } = await capa.graphql.query(selection);
+const { articles } = toTree(data, selection, capaTreeLayout);
+articles?.map((entry) => entry.fields.title); // each a string | null, as entries.list types it
+// deep-equal to (await capa.entries.list("articles", { select: "title,author(name)", sort: ["-publishedAt"], limit: 5 })).data
+```
+
+`capaTreeLayout` is what `toTree` reads of your schema (each model's root
+fields, and which fields are renamed, relations, ids or media), written by
+codegen beside the types, so the conversion reads nothing from the API.
+Without codegen, pass the key's schema instead. That is one introspection
+request, so read it once and reuse it:
+
+```ts
+import { toTree } from "@capacms/sdk/next";
+
+const schema = await capa.graphqlSchema(); // one request: read it once, reuse it
+const selection = { articles: { args: { first: 5 }, nodes: { id: true, status: true, title: true } } } as const;
+const { data } = await capa.graphql.query(selection);
+const { articles } = toTree(data, selection, schema); // the same tree as with capaTreeLayout
+```
+
+A selection kept in a variable is declared `as const`, so each `true` and
+each `sort` value keeps its exact type and the result is typed exactly.
+
+Each model root field becomes its REST `data`, typed from the selection: a
+list root as an array of entries, a single root as one entry or `null`, and
+`null` for a root that failed (its error is in `errors`). System fields sit beside `fields`
+(`_version` as `version`), every other field sits under `fields` by its
+namespace (`hero_image` as `hero-image`), every entry carries its `model`
+from the schema, whether you selected it or not, a relation list becomes
+`{ items, pageInfo }` (`{ items }` when you did not select its `pageInfo`), a
+relation into a model the key cannot read is
+`{ id, model }` as REST writes it unexpanded (a list of them is
+`{ items, pageInfo }`), and a media value keeps REST's public shape and key
+order, `{ id, url, alt, type, width, height }`, as far as you selected it (a
+list of media is an array of those).
+
+The result is deep-equal to the REST response for the same read when the
+selection names the rest of what REST always returns: `id` and `status` on
+every entry, `pageInfo { hasNextPage endCursor }` on each relation list, and
+all six media fields. Its type is then assignable to the entry
+`entries.list<Articles, typeof select>` returns for the same read, so a
+function written for the REST read takes it unchanged. With a typed client,
+a selection without `id` and `status` does not compile. Three things differ by design, because GraphQL
+does not carry what REST says there:
+
+- A missing single relation (deleted, or a draft the key cannot see) is `null`
+  in GraphQL and `{ id, model, missing: true }` in REST.
+- A missing item of a relation list is left out in GraphQL, so `items` is
+  shorter. REST keeps its slot as `{ id, model, missing: true }`.
+- A value that does not fit its field's type is `null` in GraphQL and the raw
+  value in REST.
+
+Page a list with the GraphQL result's own `pageInfo`; `version`, `me`
+and `entry` are not model roots, and `toTree` refuses them. A root alias
+(`latest: { __aliasFor: "articles", ... }`) becomes the REST data of the field
+it names, under its own key. An alias below a root has no REST equivalent,
+since REST reads each field once, so `toTree` refuses it too.
+
+### Typed documents
+
+```json
+{
+  "scripts": {
+    "dev": "capa-codegen --graphql --watch --out src/capa-graphql.ts & next dev",
+    "prebuild": "capa-codegen --graphql --out src/capa-graphql.ts"
+  }
+}
+```
+
+`capa-codegen` reads `CAPA_API_URL` and `CAPA_KEY` from your shell, else from
+`.env.local` and `.env` as `next dev` reads them, so a Next.js site needs no
+extra setup. `--watch` keeps running and writes the module again whenever a
+document changes, and when the key's schema does (it reads the schema again
+every minute). A document with a problem is printed with its file and line,
+and the last good module stays in place.
+
+Write a document where you use it, marked in one of three ways, and codegen
+types it by its text:
+
+```ts
+import { createClient, gql } from "@capacms/sdk/next";
+
+const LATEST = `#graphql
+  query Latest($first: Int) { articles(first: $first) { nodes { id title } } }
+`;
+const ONE = /* capa */ `query One($id: ID!) { article(id: $id) { title views } }`;
+const VERSION = gql(`query Version { version }`);
+
+const { data } = await capa.graphql(LATEST, { first: 10 });
+data?.articles?.nodes[0].title;             // string | null
+await capa.graphql(LATEST, { first: "10" }); // compile error
+await capa.graphql(ONE);                     // compile error: id is required
+```
+
+The generated file adds each literal's text to `CapaDocuments` with
+`declare module "@capacms/sdk/next"`, and `client.graphql` and `graphql()`
+from `/nextjs` look the text up, so nothing is imported from it. Keep the
+generated file inside your tsconfig's `include`. A literal is sent exactly as
+written, so it holds one operation and every fragment it spreads, written
+inside it or spread in with `${}` (see Fragments); codegen says so, with the
+file and line, when it does not. A literal of fragments only is a fragment
+source for others.
+
+Codegen also reads every `.graphql` file and every gql`...` tagged template
+under `src` (or `--documents dir1,dir2`). A tagged template is a plain string
+to TypeScript, so for those, and for `.graphql` files, import the
+`<Name>Document` codegen writes for every named operation:
+
+```ts
+// src/queries/articles.graphql
+// query ArticlesPage($first: Int) { articles(first: $first) { nodes { id title } } }
+
+import { ArticlesPageDocument } from "./capa-graphql";
+
+const { data } = await capa.graphql(ArticlesPageDocument, { first: 10 });
+data?.articles?.nodes[0].title;                            // string | null
+await capa.graphql(ArticlesPageDocument, { first: "10" }); // compile error
+```
+
+#### Fragments
+
+```ts
+import type { ArticleTeaserFragment } from "./capa-graphql";
+
+const ARTICLE_TEASER = `#graphql
+  fragment ArticleTeaser on Articles { id title }
+`;
+
+const TEASERS = `#graphql
+  query Teasers($first: Int) { articles(first: $first) { nodes { ...ArticleTeaser } } }
+  ${ARTICLE_TEASER}
+` as const;
+
+function teaser(props: ArticleTeaserFragment) {
+  return props.title;
+}
+
+const { data } = await capa.graphql(TEASERS, { first: 3 });
+data?.articles?.nodes.map(teaser);
+```
+
+Write a fragment in a `#graphql` literal of its own and spread it into a
+query with `${NAME}`, as Hydrogen does. Codegen reads the query with the
+fragment's text in place, which is exactly the text the program sends, so the
+query is typed and persisted like any other literal. End the query's template
+with `as const`: TypeScript keeps the text of a template with `${}` only
+then, and codegen says so when it is missing. A `${}` that names anything
+else is text only known at run time, which codegen skips and names.
+
+Codegen writes a `<Name>Fragment` type for every fragment, from a literal or
+a `.graphql` file, for a component that takes the fragment's data as props:
+the nodes of any query that spreads the fragment fit it.
+
+The generated file also holds the schema's types, `CapaQuery` for the typed
+builder, `capaTreeLayout` for `toTree`, and `<Name>Models` beside each
+operation: the models it reads, for its cache tags (see In a Next.js server
+component). That is each model whose entries it selects, and each model a
+filter or sort reaches through a relation. A filter or sort passed as a
+variable counts every model its type can reach, and `entry(id:)` counts every
+model, since either can read any of them.
+
+Codegen names, with its file and line, every template it does not read that
+looks like a query, and says what to change: one left unmarked, graphql`...`
+(from `/nextjs` that is a request, not a tag), and one with a `${}` that names
+no literal of the project, whose text is only known at run time.
+
+A field the key cannot read is a codegen error with its file and line, so a
+model change fails CI instead of production. A field, argument, filter
+operator or sort value a later `Capa-Version` phases out is `@deprecated` in
+the generated types, so your editor strikes it through, and codegen prints
+each use with its file, line and the reason, while still writing the module.
+`--check` exits 2 when the committed file is stale. `--save-schema
+capa-schema.json` writes the schema it read, and `--schema capa-schema.json`
+reads it back instead of calling the API, for CI without a key. Codegen needs
+`graphql` installed in your project (`pnpm add -D graphql`); nothing else in
+the SDK does.
+
+A literal codegen has not read yet, new or edited since the last run, does
+not compile: the error says `run capa-codegen --graphql`. Text built at run
+time is a plain `string` and stays untyped, and so does a call that names its
+data type, `capa.graphql<{ version: string }>(text)`.
+
+### Persisted queries
+
+Register your documents at build time, with a development key:
+
+```sh
+CAPA_API_URL=https://api.capacms.com CAPA_DRAFT_KEY=cap_test_... capa persist --manifest persisted.json
+```
+
+Then send only their hash, with any key, including the production key your
+site ships:
+
+```ts
+import { ArticlesPageDocument } from "./capa-graphql";
+
+const { data } = await capa.graphql(ArticlesPageDocument, { first: 10 }, { persisted: true });
+```
+
+With `persisted: true` the client sends the document's sha256 as one small
+GET, which the CDN and the API cache for a production key, and the document
+never travels. Variables too long for a GET URL (8,192 bytes) go with the hash
+in a POST instead, which works the same way but is not cached. `capa persist` prints `<sha256>  <operation>  stored, pinned` per
+operation, hashing the same text `capa-codegen --graphql` exports, so run
+both from the same documents. A document written as a literal is stored
+twice, as its `<Name>Document` text and as written (`<Name> (literal)`),
+since a call with the literal sends that text.
+
+`capa persist` registers every document with `Capa-Persist: pin`. The API
+drops unpinned documents first when a project's store is full, so the
+documents developers register while trying queries in the Explorer or a
+draft preview never push your site's documents out. A document the API
+stores without its pin is reported as `stored, not pinned` and the command
+exits 3, since it is exposed to exactly that. `--manifest` writes each
+operation's `sha256`, `stored` and `pinned`.
+
+Name the build too, so a run of preview deploys never pushes production's
+documents out:
+
+```sh
+capa persist --release "$GIT_COMMIT" --env production
+```
+
+That sends `Capa-Persist: pin; release=<commit>; env=production`. A project
+keeps up to 2,000 documents and 16 MiB, and when it is full the API keeps
+the pins of the latest 3 production releases first, then what a production
+key ran in the last 30 days, then other pins, such as a preview build's.
+On Vercel and Netlify the command reads both from the build
+(`VERCEL_GIT_COMMIT_SHA` and `VERCEL_ENV`, or `COMMIT_REF` and `CONTEXT`),
+so there is nothing to pass. Elsewhere, pass the flags or set `CAPA_RELEASE`
+and `CAPA_RELEASE_ENV`. A release is 1 to 64 letters, digits, dots, dashes
+or underscores, such as a commit or a deploy id, and an environment is a
+lowercase name such as `production` or `preview`. The two go together, and
+the command checks them before it sends anything. The manifest records them
+as `release` and `env`.
+
+Two things decide whether a document is stored:
+
+- The key. `capa persist` reads the development key from `CAPA_DRAFT_KEY`,
+  the name `/nextjs` reads for drafts (`CAPA_KEY` when that is unset), and
+  refuses a production key before it sends anything. A production key ships
+  in your site's bundle, so it may run a document but never register one.
+- The host. `capa persist` sends each document to `CAPA_API_URL`, the URL
+  your site already reads. `https://api.capacms.com` passes every POST on to
+  the host that stores documents. On a self-hosted stack whose read host
+  stores nothing, set `CAPA_ADMIN_URL` to the API host your Capa admin uses;
+  it wins over `CAPA_API_URL`. When a host stores nothing, the command says
+  so and names the variable to set.
+
+When a hash is not stored yet, a production client still gets its data, with
+no error: the API answers the GET with `PersistedQueryNotFound`, the client
+sends one POST carrying the document and the hash, and the API runs it and
+answers `extensions.persistedQuery.registered: false`. The client then
+remembers that hash for five minutes and sends POST straight away, so a
+missing registration costs one extra GET per five minutes rather than one per
+call. `registered: false` on a production read is how to spot a document
+`capa persist` did not register. `graphql()` from `/nextjs` is not persisted
+by default for the same reason: until `capa persist` has run, every hash
+misses.
+
+A builder read (`capa.graphql.query`) cannot be persisted, and
+`persisted: true` there throws a `TypeError` before any request. Its
+document is printed when it runs, so `capa persist` never sees it, and a
+production key never stores one. It is already a cacheable GET.
+
+### A REST select as a builder read, and back
+
+`selectToSelection` turns a REST read into a typed builder selection, which
+`client.graphql.query` runs and `toTree` turns into that read's `data`.
+`graphqlToSelect` gives a builder selection's REST request, as it gives a
+tool spec's:
+
+```ts
+import { graphqlToSelect, selectToSelection, toTree } from "@capacms/sdk/next";
+
+const schema = await capa.graphqlSchema();
+const selection = selectToSelection(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 });
+const { data } = await capa.graphql.query(selection);
+const { articles } = toTree(data, selection, schema);
+// deep-equal to (await capa.entries.list("articles", { select: "title,author(name)", sort: ["-views"], limit: 5 })).data
+
+graphqlToSelect(schema, { articles: { args: { first: 5 }, nodes: { title: true, author: { name: true } } } }).url;
+// "/api/entries/articles?select=title,author(name)&limit=5"
+```
+
+The selection names what `toTree` needs to answer what REST answers: `id`,
+`model` and `status` on every entry, `pageInfo` on every relation list, and
+all six media fields. Its fields are known only when it runs, so its data and
+its tree are untyped, with a typed client too. It takes what `selectToGraphQL`
+takes and refuses what it refuses. A relation the select names bare, which
+REST returns unexpanded as `{ id, model }`, is read expanded to its id, the
+REST read `author(id)`, because GraphQL reads a relation to a model the key
+can read as an entry. `graphqlToSelect` reads a selection's one model root
+field, and throws `CapaBuildError` for any other root (`version`, `entry`),
+and for a relation list read from a cursor in a list read, which have no REST
+request here. `last` with no `before`, or with `before: null` as Relay and
+Apollo send it, reads the end of the list: REST's `before=end`.
+
+### The tool spec: build a query for an explorer or an assistant
+
+Tools that build queries (the admin's Explorer, the MCP server) share one
+plain format, the tool spec: `{ model, fields, first, sort, filter }`. The SDK
+reads the key's schema once and writes GraphQL from it in Capa's canonical
+format, and moves between it and a REST read:
+
+```ts
+import { buildGraphQLQuery, graphqlToSelect, selectToGraphQL } from "@capacms/sdk/next";
+
+const schema = await capa.graphqlSchema(); // models, fields, filters, sorts, from one request
+
+const spec = { model: "articles", fields: ["title", { field: "author", fields: ["name"] }], sort: ["views_DESC"], first: 5 };
+const { query, variables } = buildGraphQLQuery(schema, spec);
+graphqlToSelect(schema, spec).url;
+// "/api/entries/articles?select=title,author(name)&sort=-views&limit=5"
+
+selectToGraphQL(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 });
+// the same tool spec, from a REST read
+```
+
+The tool spec is not the typed builder's selection: `client.graphql.query`
+and `toTree` take the selection, which `selectToSelection` writes.
+
+`graphqlToSelect` writes the REST twin exactly as the API writes it in
+`extensions.capa.rest`: the filter as `where` JSON, the root's default page
+size left out, a relation list's `first` written as `limit:` whenever you give
+it (100 included, since REST counts a limit you write in full and one you
+leave out as 10), and a system key a field of the model shadows written with `$`
+(`_tags` beside a field called `tags` is `select=$tags,tags`; `createdAt_DESC`
+beside a field called `createdAt` is `sort=-$createdAt`). That includes a
+field GraphQL leaves out because its name collides with another's, which the
+type's description lists as `Not exposed:` and the schema summary as
+`notExposed`: beside a hidden field called `id`, `id_DESC` is `sort=-$id`.
+`selectToGraphQL` reads `$` names back, and refuses a REST name for a hidden
+field, which GraphQL cannot read. It selects what the REST read returns: a
+media value with all six of its fields (`id url alt type width height`), and
+`*`, or no select, as everything: the system keys `createdAt`, `updatedAt`,
+`publishedAt`, `version`, `folder` and `tags`, every field, and each relation
+list as a connection of ids (`coauthors { nodes { id } }`), the page of
+references REST returns. A reference to an entry the key cannot see is the
+one difference left: REST shows it as `{ id, model, missing: true }`, and
+GraphQL reads it as `null`, or leaves it out of a list. `buildGraphQLQuery`
+with no `fields` keeps its own shorter default, media as `id url alt`. Both helpers send each filter value as the type its
+filter input declares, since GraphQL refuses any other: `"10"` for a number
+field becomes `10`, and `has: "true"` on a list of true/false values becomes
+`true`, which its `BooleanListFilter` takes. A name the schema does not have,
+or a key a relation's spec does not take (`frist` for `first`, at any depth),
+throws `CapaBuildError` with `didYouMean`, before anything is sent. A `where`
+on `$tags` ports to GraphQL's `_tags` filter:
+
+```ts
+import { selectToGraphQL } from "@capacms/sdk/next";
+
+const schema = await capa.graphqlSchema();
+selectToGraphQL(schema, "articles", "title", { where: { $tags: { has: "news" } } });
+// { model: "articles", fields: ["title"], filter: { _tags: { has: "news" } } }
+```
+
+A model GraphQL leaves out, because its type name would collide with
+another's (`twin_a` and `twin-a`), is listed in the summary's `restOnly`.
+Asked for one, the builder throws `CapaBuildError` naming its REST read
+(`twin_a is readable over REST only: GET /api/entries/twin_a.`) and why,
+with no `didYouMean`: `entries.list("twin_a")` reads it.
+
+Two REST reads have no GraphQL twin and throw too: a `where` on `$version`,
+`$folder`, `$model` or `$status` (GraphQL filters `id`, `createdAt`,
+`updatedAt`, `publishedAt` and `_tags`), and a filter hop through a relation
+the key cannot read (REST answers it `unknown_field`).
+
+A tool spec pages as a REST read does: `first` with `after` reads the page after a
+cursor, and `first` with `before` the entries just before one. GraphQL writes
+the second as `last` with `before`, and the API refuses `first` there, so
+`{ first: 25, before }` prints `articles(last: $last, before: $before)`, and
+a tool spec with both `after` and `before` throws, as the API refuses it.
+`before: "end"` reads the last entries of the list, REST's `before=end`:
+`{ first: 5, before: "end" }` prints `articles(last: $last)`, and the list's
+`startCursor` pages back from there. `after: "end"` throws, since `end` is not
+a cursor.
+A read of one entry also pages a relation list from its cursor, as REST's
+`coauthors(name,after:…)` does: `{ field: "coauthors", fields: ["name"],
+after }` in a spec with `mode: "single"`, or `args: { after }` on the list in
+a selection. A list read throws for it, as the API refuses it there
+(`after: applies to a single entry`). `sort` takes one value or a list, at
+the root as on a relation list.
+
+A spec written as REST writes a read throws, and says what to write instead:
+`"author.name"` or `"author(name)"` in `fields` is
+`{ field: "author", fields: ["name"] }`, `"*"` is `fields` left out, and a
+sort `"-publishedAt"` is `"publishedAt_DESC"` (in `didYouMean` too).
+Relations nest up to 4 deep below the root entry, which with the root is the
+API's 5 levels of entries; a fifth throws `CapaBuildError` and names the field
+to select without fields, for its id.
+
 ## Typed select and codegen
 
 `Select<T>` is exported from `@capacms/sdk/next`. `capa-codegen` keeps the legacy
 `/v2/schema/types` shape for schemas without relations. When a schema has
-relations, codegen wraps them in branded helpers:
+relations, codegen wraps them in branded helpers, which describe the model;
+a read's `fields` is typed from them as the API returns it (see Typed reads):
 
 ```ts
 export type CapaRelation<T> = T & { readonly __capaRelation: "one"; readonly __capaRelationTarget: T };
@@ -167,7 +1270,31 @@ export type ArticleSelect = import("@capacms/sdk/next").Select<Article>;
 ```
 
 Those brands let TypeScript tell scalar fields from relation fields, so misspelled
-fields and invalid nested selects fail in consumer typechecks.
+fields and invalid nested selects fail in consumer typechecks. A relation named
+alone (`"author"`) is read as a reference.
+
+Every name is written so the module parses, whatever the namespace holds. A
+field that is not an identifier is quoted (`"am/pm_indicator"?: string;`,
+read as `fields["am/pm_indicator"]`), and a model whose name is not one is
+named as GraphQL names it: `2024_events` is `_2024Events`, with
+`_2024EventsSelect` beside it. Two models whose names give one interface name,
+such as `twin_a` and `twin-a`, are each named from the whole namespace instead:
+`Model_twin_a` and `Model_twin$2da`, each character that is not a letter, digit
+or `_` written as `$` and its hex code. An enum's values are written as stored,
+a quote or a backslash included.
+
+A select names a field by its namespace as saved, whatever it holds:
+`["price.usd", { "at.place": ["zip.code"] }]`. The client writes a name holding
+`,` `(` `)` `:` `.` `"` `*` `[` `]` or a space, or starting with `-`, quoted, as
+REST's grammar reads it: `select="price.usd","at.place"("zip.code")`. A string
+select, `sort` and `where` take REST's own text, so write such a name quoted
+there yourself: `sort: ['-"price.usd"']`.
+
+A select also takes the entry's system keys by their `$` names, which mean the
+system key even on a model with a field of the same plain name
+(`SystemKey`): `["title", "$tags", { coauthors: { select: ["name"], sort: "-$createdAt" } }]`.
+A `$` name that is no system key fails to compile. A field whose namespace
+starts with `$` cannot be named, so `select: "*"` is how to read it.
 
 ## Pages and preview
 
@@ -192,6 +1319,15 @@ const capa = createClient({ baseUrl, apiKey, version: "2026-10-01" });
 const posts = await capa.entries.list("articles", { page: routeOf(import.meta.url) });
 ```
 
+Send `path` beside it, the concrete path being rendered, and Capa can list the
+real URLs an entry appears on, not only the route patterns:
+
+```ts
+await capa.entries.list("articles", { page: "/blog/[slug]", path: `/blog/${slug}` });
+```
+
+`path` goes out as `Capa-Path`, only when `page` is also set.
+
 `routeOf` turns a Next route file into the page string: `/blog/[slug]`. It
 drops route groups `(marketing)`, parallel slots `@modal`, the leaf file name
 and the extension. Write the string out by hand if you prefer; `routeOf` exists
@@ -199,6 +1335,19 @@ so that moving a folder cannot silently split one page's telemetry in two. Set
 `page` on the config instead when a client serves exactly one page; a value on
 the call wins over one on the config.
 
+A layout is not a page. `app/layout.tsx` (and any nested `layout.*` or
+`template.*`) renders around every page below it, and Next does not tell it
+which one, so its reads cannot be charged to the page being rendered. `routeOf`
+returns `"(layout)"` for these files, exported as `LAYOUT_PAGE`, and a read that
+names it sends no `Capa-Page` header at all, even when the client was created
+with a `page`. So a Site singleton or a nav read in your root layout is simply
+not attributed, instead of making `/` look as if it read everything:
+
+```ts
+// In app/layout.tsx: same call as in a page, and no page is recorded.
+const site = await capa.entries.list("site", { page: routeOf(import.meta.url) });
+```
+
 A malformed value throws a `TypeError`. Capa itself ignores a header it cannot
 store, because a mangled page identity must never take a blog down, so the SDK
 is the place a typo surfaces.
@@ -252,7 +1401,7 @@ exactly like a site that is up to date.
 
 `capa.pages.get(page)` carries an `insights` array: suggestions drawn from that
 page's own reads, computed by Capa so that this SDK, the Capa admin and
-`@capa/mcp` all read one answer.
+Capa's MCP server all read one answer.
 
 ```ts
 const detail = await capa.pages.get("/blog/[slug]");
@@ -326,105 +1475,534 @@ const capa = await draftClient({
 Set the preview base URL for your project in Capa (Settings), otherwise the
 editor sees the path without a link to open it.
 
-## Not yet
+## Live preview
 
-`--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`
-writes are not in this release.
+### Quick start (Next.js)
 
-## The legacy `/v2/api` client
+Preview needs `@capacms/sdk` 1.0.0-next.8 or later. The `latest` tag is
+older and has no `capaHeaders`, so install the `next` tag:
+
+```sh
+pnpm add @capacms/sdk@next
+```
 
-A read client for Capa, plus two arrangement writes (`workspaces`,
-`models.setLayout`) and `capa-codegen`, a command that pulls a tenant's
-generated TypeScript so content is typed at the call site.
+Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`, or the legacy key your site
+holds) and `CAPA_DRAFT_KEY` (`cap_test_`). Draft reads through the SDK take a
+`cap_` key only (see Keys). Then:
 
 ```ts
-import { createClient } from "@capacms/sdk";
-import type { BlogPost } from "./capa-types";        // written by capa-codegen
+// middleware.ts
+import { NextResponse } from "next/server";
+import { capaMiddleware } from "@capacms/sdk/nextjs";
+export const middleware = capaMiddleware({ NextResponse });
+
+// app/api/capa/preview/route.ts  (and exit/route.ts with exitPreviewRoute)
+import { cookies, draftMode } from "next/headers";
+import { createPreviewRoute } from "@capacms/sdk/nextjs";
+export const GET = createPreviewRoute({ draftMode, cookies });
+
+// next.config.mjs
+import { capaHeaders } from "@capacms/sdk/nextjs";
+export default { async headers() { return capaHeaders(); } };
+
+// in a page: getCapaClient({ draftMode, headers }), then <h1 {...fieldAttrs(post).title}>
+// in the root layout: const edit = await editMode({ draftMode, headers }) from @capacms/sdk/nextjs,
+// then {edit ? <CapaOverlay adminOrigins={[...]} /> : null} from @capacms/sdk/nextjs/overlay
+```
 
-const capa = createClient({
-  baseUrl: process.env.CAPA_BASE_URL!,
-  apiKey: process.env.CAPA_API_KEY!,
-  tenantId: process.env.CAPA_TENANT_ID!,
-});
+In Capa, set the project's preview URL to your site, and editors can click
+your page. The sections below explain each piece.
 
-const page = await capa.listContent<BlogPost>("blog_post", { limit: 10 });
-const one  = await capa.findOne<BlogPost>("blog_post", { handle: "hello" });
+The Capa editor can show your site beside the form: focus a field and its spot
+on the page is outlined, click the page and the editor jumps to the field, save
+and the draft re-renders in place. Where live preview is on, the text being
+typed shows on the page before the save (see the protocol below). It needs three things on your side.
+
+### 1. Turn on edit mode and tag what an editor can click
+
+Edit mode is on when Next draft mode is on, or when the request carries a
+`capa-edit` token the Capa editor's Published view sends. Work it out once per
+request and build the client with it:
+
+```ts
+// lib/capa.ts
+import { draftMode, headers } from "next/headers";
+import { createClient } from "@capacms/sdk/next";
+import { editMode } from "@capacms/sdk/nextjs";
+
+export async function capa() {
+  const draft = (await draftMode()).isEnabled;
+  return createClient({
+    baseUrl, version: "2026-10-01",
+    apiKey: draft ? process.env.CAPA_DRAFT_KEY! : process.env.CAPA_KEY!,
+    editMode: await editMode({ draftMode, headers }),
+  });
+}
 ```
 
-## Codegen
+Then tag fields with `capaAttrs(entry, field)` from `@capacms/sdk/next`. `field`
+is the field's namespace, its key in `entry.fields`, and it autocompletes when
+the entry is typed. There is no flag to pass: an entry read by an edit-mode
+client carries a hidden mark (related entries too), and `capaAttrs` tags only
+marked entries. A visitor's page therefore ships no `data-capa-` attributes.
 
+```tsx
+import { capaAttrs } from "@capacms/sdk/next";
+
+<h1 {...capaAttrs(article, "title")}>{article.fields.title}</h1>
 ```
-CAPA_BASE_URL=... CAPA_API_KEY=... CAPA_TENANT_ID=... capa-codegen --out src/capa-types.ts
+
+The mark does not survive a spread copy or being passed to a client component,
+so tag in the server component that read the entry. `capaAttrs(entry, field,
+true)` still forces the tags on and `false` forces them off.
+
+**When the entry crosses to the browser as data, pass the flag.** The mark is
+a hidden symbol, so anything that serializes the entry drops it silently: the
+Next Pages Router's `getServerSideProps`, SvelteKit and Remix loaders, Nuxt's
+payload, or your own JSON endpoint. The page then shows the draft with no
+`data-capa-` tags, and the editor has nothing to point at. Nothing errors. Send
+the draft or edit state alongside the entry and hand it to `capaAttrs`:
+
+```tsx
+// pages/articles/[id].tsx on the Pages Router. A +page.server.ts load or
+// useAsyncData on the server hands over the flag the same way.
+import type { Entry } from "@capacms/sdk/next";
+import type { Articles } from "./capa-types";
+
+export async function getServerSideProps({ draftMode = false }) {
+  const entry = (await capa.entries.get<Articles>("articles", "entry-id"))!.data;
+  return { props: { entry, edit: draftMode } };
+}
+
+// in the component
+export default function Page({ entry, edit }: { entry: Entry<Articles>; edit: boolean }) {
+  return <h1 {...capaAttrs(entry, "title", edit)}>{entry.fields.title}</h1>;
+}
 ```
 
-Exit codes: `0` wrote or already current, `1` failed, `2` `--check` found a diff.
-`--check` is the CI mode — it fails when the committed file is stale.
+Or re-mark the entries where they arrive with `markEditEntries(data)` when the
+page is in edit mode.
 
-**Commit the output.** Not generated at install (needs credentials during
-`npm install`, which breaks CI images and Docker builds) and not at build time
-(makes every build network-dependent, and a Capa outage a build outage). A
-committed file is also what makes the feature useful: "a model changed, so the
-build fails" only helps if a human can see *what* changed, and a committed file
-turns that into a reviewable diff instead of a wall of `tsc` errors.
+GraphQL reads are marked the same way, from `getCapaClient`, an edit-mode
+`createClient` or `graphql()` given `{ draftMode, headers }`. A node is an
+entry when it selected `id` and `model`, and `field` is the field as you
+selected it:
 
-Re-running when nothing changed costs **one conditional request returning 0
-bytes** — see below.
+```tsx
+const { data } = await capa.graphql.query({ articles: { nodes: { id: true, model: true, title: true } } });
+<h1 {...capaAttrs(data!.articles!.nodes[0], "title")}>{data!.articles!.nodes[0].title}</h1>
+```
 
-## Three server-side rough edges, handled here
+A field GraphQL renamed (`hero_image` for `hero-image`) is tagged by its
+namespace, which the editor knows it by: in edit mode the client reads the
+names of the key's types and fields once a minute to know which fields those
+are. That read starts beside the page's read, so the page waits for the
+slower of the two, and a document that never says `model` reads no names.
+With a typed client, tagging a node that did not select `model` does not
+compile.
+`toTree` keeps the mark, so its entries tag like REST entries, by namespace.
 
-The API is mid-port to a byte-parity bar, so changing a customer-facing response
-costs a signed exception. None of these is worth one, because each can be
-handled on this side.
+To accept `capa-edit`, verify it in middleware. The token is checked with Capa,
+any forged `x-capa-edit` header is removed, and edit-mode responses are marked
+`private, no-store`:
 
-**1. `/v2/schema/types` has no ETag,** so it cannot be revalidated. `/v2/schema`
-*does* — it returns a `checksum` and honours `If-None-Match` with a 304, and that
-checksum is `sha256({models, relations})`, exactly what the types are generated
-from. So codegen gates on it and fetches types only when the schema moved.
+```ts
+// middleware.ts
+import { NextResponse, type NextRequest } from "next/server";
+import { resolveEditRequest } from "@capacms/sdk/nextjs";
+
+export async function middleware(request: NextRequest) {
+  const edit = await resolveEditRequest(request, publishedClient());
+  const response = NextResponse.next({ request: { headers: edit.headers } });
+  if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+  if (edit.robotsTag) response.headers.set("X-Robots-Tag", edit.robotsTag);
+  return response;
+}
+```
 
-**2. The generator orders models by display name,** while interfaces are *named*
-from the namespace (`blogs_home_section` → `BlogsHomeSection`). Renaming a
-model's display name therefore reorders the whole file without changing a single
-type — a false "your types changed" in the exact mechanism this feature rests
-on. `normalizeTypes` re-sorts by interface name, so the committed file is stable
-under renames.
+### 2. Start the overlay in edit mode
 
-**3. A model field named `id` overwrites the instance id** (#4628). Rows are
-built as `{...instance, ...formatInstanceData(instance)}` (`routes/v2/api.ts`).
-Hoisted fields are spread second, so `id`, `title` and `tags` are overwritten.
-In one ordinary tenant, 20 of 20 models shadow `title` and 7 of 20 shadow `id`.
+```tsx
+// app/layout.tsx
+import { CapaOverlay } from "@capacms/sdk/nextjs/overlay";
+
+{edit ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+```
+
+`@capacms/sdk/nextjs/overlay` is a client component and needs `react` and
+`next`. Without Next, call `startOverlay({ adminOrigins, onRefresh })` from
+`@capacms/sdk/overlay` in your own effect.
+
+Render it from your root layout only in edit mode
+(`await editMode({ draftMode, headers })`), so it never runs for a visitor.
+Imported this way, its code still sits in the layout's chunk, which every
+visitor downloads. To keep it out, load it lazily from a small client
+component, as step 5 of "Add preview to a live site without changing it"
+shows. Both overlay entry points reach a bundler as ES modules, so loading
+the overlay leaves the rest of a visitor's chunks as they were.
+
+`startOverlay` returns a disposer and is safe to call twice. Outside a frame it
+does nothing at all, and inside one it only listens to a parent window at one of
+`adminOrigins`.
+
+**Clicks inside the editor's frame.** A click on a tagged element selects its
+field in the editor. A ⌘-click (Ctrl-click on Windows and Linux) on a tagged
+element that is a link, or sits inside one, follows the link inside the frame
+instead, so an editor can move between pages. The hover label says so over a
+link. A link with no tag on or around it navigates as usual.
+
+**After a save.** `<CapaOverlay />` re-renders the draft in place with
+`router.refresh()` and keeps the scroll position.
+
+- The refresh runs in a React transition. While it is pending, the overlay
+  makes a no-op state update every 300 ms. Under React 19.2 and Next 15.5, a
+  draft refresh can otherwise stay suspended after its whole response has
+  arrived, when the page sits inside a Suspense boundary that is already on
+  screen (a root `loading.tsx` makes one), and show nothing until some other
+  state update.
+- A refresh that has not landed after `refreshTimeoutMs` (10 seconds) reloads
+  the page instead, which comes back to the same scroll position.
+- `refresh="reload"` reloads the page on every save, for a site that prefers
+  it:
+
+```tsx
+<CapaOverlay adminOrigins={["https://app.capacms.com"]} refresh="reload" />
+```
 
-A server-side fix for this shipped briefly as #4628 (`instanceId` appended to
-every public row) and was reverted on 2026-09-20 under the public-surface
-freeze: `/v2/api`, `/v3/api`, the `/v1` public reads and `/files` answer the
-bytes the legacy API answers, and a row key that resolves the shadowing is
-planned for the next API version. **So a row from today's server carries no
-`instanceId`, and `row.id` may be a content value.**
+With `startOverlay`, `onRefresh` may return a promise that settles once the new
+draft is on screen. The overlay waits for it up to `refreshTimeoutMs`, and
+reloads if it rejects or is still pending. Without `onRefresh` every save
+reloads. The scroll position is kept every way.
 
-The client already handles both: `instanceIdOf` prefers `instanceId` when a row
-has one and falls back to `id` when that is a UUID, so nothing here changes when
-the next version starts sending it.
+### 3. Accept the preview link on any page
 
-So **read `Page.ids`, not `row.id`**:
+The editor loads `<preview base URL><path>?capa-preview=<token>`. Honour the
+token on the request itself, not only on a dedicated route: rewrite any request
+carrying it to your draft route, verify it with `preview`, enable draft mode and
+redirect back.
+
+```ts
+// middleware.ts
+export function middleware(request: NextRequest) {
+  // The editor's Published view: render this one request without draft mode.
+  if (request.nextUrl.searchParams.get("capa-view") === "published") {
+    const headers = new Headers(request.headers);
+    const cookies = request.cookies.getAll().filter((c) => c.name !== "__prerender_bypass");
+    headers.set("cookie", cookies.map((c) => `${c.name}=${encodeURIComponent(c.value)}`).join("; "));
+    return NextResponse.next({ request: { headers } });
+  }
+  const token = request.nextUrl.searchParams.get("capa-preview");
+  if (!token) return NextResponse.next();
+  const target = request.nextUrl.clone();
+  target.pathname = "/api/draft";
+  target.search = `?token=${encodeURIComponent(token)}&path=${encodeURIComponent(request.nextUrl.pathname)}`;
+  return NextResponse.rewrite(target);
+}
+```
+
+`/api/draft` is the route handler shown under "Open a draft in your own site"
+above, reading `token` and `path`.
+
+**Cookies in a frame.** The editor frames your site from another site. A
+browser sends a cookie into a cross-site frame only when it is
+`SameSite=None; Secure`, and Safari 26.2 and later only when it is
+`Partitioned` too. Next sets the draft-mode cookie with neither `Partitioned`
+nor `Max-Age`, so it is dropped in Safari's frame and, everywhere else, opens
+every draft on the site until the browser closes. Pass Next's `cookies` to
+`createPreviewRoute` and `exitPreviewRoute` and they re-set it as
+`HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=3600`, and
+delete it the same way. `maxAge` changes the hour. In your own route, call
+`frameDraftCookie(cookies)` after `enable()` and `clearDraftCookie(cookies)`
+after `disable()`. A browser that drops the cookie still gets a fresh token on
+every preview load, which step 3 honours on any page.
+
+Leave `redirect` out of both routes. Each then answers with its own 307,
+marked `X-Robots-Tag: noindex, nofollow`, `Referrer-Policy: no-referrer` (the
+token is in the URL) and `Cache-Control: private, no-store`. Next's
+`redirect()` cannot carry headers, so passing it keeps the old redirect.
+
+**Mark drafts, and let Capa frame them.** `capaHeaders()` returns rules for
+`next.config`'s `headers()` that send `X-Robots-Tag: noindex, nofollow` and
+`Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com` on a
+request carrying the draft cookie or a `capa-preview`, `capa-edit` or
+`capa-view` query, and on nothing else. A visitor's response, cached or not,
+is unchanged. Pass `adminOrigins` to name another admin, such as one running
+locally, and pass the same list to `createPreviewRoute`. A browser applies
+every CSP it is sent, so if your site sends its own `frame-ancestors` or
+`X-Frame-Options`, leave them off draft responses with
+`missing: [{ type: "cookie", key: DRAFT_COOKIE }]` on that rule.
+`capaMiddleware` marks its edit-mode responses noindex too, and
+`resolveEditRequest` returns the value as `robotsTag`.
+
+### Add preview to a live site without changing it
+
+A live Next.js site that reads Capa with its own code keeps that code. Preview
+adds a branch that only draft mode switches on, and draft mode is off for
+every visitor, at build time and during ISR. Reading
+`(await draftMode()).isEnabled` leaves a static page static, so a visitor gets
+the same pages, headers and cache as before.
+
+1. **Read drafts in draft mode.** In the helper that fetches from Capa, before
+   the existing fetch, read the same URL with a draft key and no cache. The
+   data has the same shape, so every page renders unchanged.
+
+   ```ts
+   // lib/capa-draft.ts
+   import "server-only";
+   import { draftMode } from "next/headers";
+
+   export async function isDraft(): Promise<boolean> {
+     // draftMode() throws outside a request (generateStaticParams, some build steps).
+     try { return (await draftMode()).isEnabled; } catch { return false; }
+   }
+
+   // in the fetch helper, before the existing fetch, which stays as it is
+   if (await isDraft()) {
+     return fetch(`https://api.capacms.com/v2/api/${endpoint}${query}`, {
+       headers: { "x-api-key": process.env.CAPA_DRAFT_KEY! },
+       cache: "no-store",
+     }).then(parse); // the helper's existing parse
+   }
+   ```
+
+   The draft key is any key of yours whose environment is not `production`
+   (see Preview is a key, not a flag). Keep it server-only, never in a
+   `NEXT_PUBLIC_` variable, and keep the branch in a `server-only` module: a
+   helper a client component also imports would bundle it.
+
+2. **Add the preview and exit routes** with `createPreviewRoute({ draftMode,
+   cookies })` and `exitPreviewRoute({ draftMode, cookies })`, as in the Quick
+   start. Set `CAPA_API_URL` to `https://api.capacms.com` and `CAPA_KEY` to
+   the production key the site already reads with, server-only: the routes
+   check the editor's token with it.
+
+3. **Add the middleware behind a matcher**, so a visitor's request never runs
+   it. Next reads `config` from the file itself, so write the matcher out:
+
+   ```ts
+   // middleware.ts (proxy.ts on Next 16)
+   import { NextResponse } from "next/server";
+   import { capaMiddleware } from "@capacms/sdk/nextjs";
+
+   export const middleware = capaMiddleware({ NextResponse });
+   export const config = {
+     matcher: [
+       { source: "/:path*", has: [{ type: "query", key: "capa-preview" }] },
+       { source: "/:path*", has: [{ type: "query", key: "capa-edit" }] },
+       { source: "/:path*", has: [{ type: "query", key: "capa-view" }] },
+       { source: "/:path*", has: [{ type: "cookie", key: "__prerender_bypass" }] },
+     ],
+   };
+   ```
+
+4. **Add `capaHeaders()`** to `next.config`'s `headers()`, as in the Quick
+   start: drafts are marked noindex and only the Capa admin can frame them.
+
+5. **Start the overlay and tag fields in draft mode.** Load the overlay
+   lazily from a small client component, so its code is not in a chunk a
+   visitor downloads, and render that component from the root layout in
+   draft mode only:
+
+   ```tsx
+   // components/capa-preview.tsx
+   "use client";
+   import { lazy, Suspense } from "react";
+
+   const CapaOverlay = lazy(() =>
+     import("@capacms/sdk/nextjs/overlay").then((m) => ({ default: m.CapaOverlay })),
+   );
+
+   export default function CapaPreview({ adminOrigins }: { adminOrigins: string[] }) {
+     return (
+       <Suspense fallback={null}>
+         <CapaOverlay adminOrigins={adminOrigins} />
+       </Suspense>
+     );
+   }
+
+   // app/layout.tsx
+   const draft = await isDraft();
+   {draft ? <CapaPreview adminOrigins={["https://app.capacms.com"]} /> : null}
+   ```
+
+   Tag an editable field with `{...capaAttrs({ id: entry.id }, "title", draft)}`.
+   With `draft` false it returns `{}`, so a visitor's HTML gains no
+   attribute. The field is its key in the entry, which is its namespace.
+
+6. **Route handlers that set their own `Cache-Control`** must send
+   `private, no-store` in draft mode. Otherwise a CDN keeps a draft fetched by
+   the editor's browser and serves it to everyone.
+
+Do not call `editMode()`, `getCapaClient()` or `resolveEditRequest()` from a
+static or ISR page or layout. Each reads `headers()`, which makes every route
+that calls it dynamic: the HTML stays the same, but the site loses ISR and
+renders every view. `isDraft()` above is the static-safe check. The editor's
+Published view then shows the static page without the overlay.
+
+In Capa, set the project's preview URL to the site's production origin, and
+give each model with a page a route pattern, or Preview has no link to open.
+
+### A save that shows nothing: a page transition that freezes the route
+
+A site that animates page changes with framer-motion often wraps each page in
+a `FrozenRoute`, which pins Next's `LayoutRouterContext` so the page that is
+leaving keeps its content while it animates out:
+
+```tsx
+"use client";
+
+import { useContext, useRef } from "react";
+import { LayoutRouterContext } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+const FrozenRoute = ({ children }: { children: React.ReactNode }) => {
+  const context = useContext(LayoutRouterContext);
+  const frozen = useRef(context).current;
+
+  return (
+    <LayoutRouterContext.Provider value={frozen}>
+      {children}
+    </LayoutRouterContext.Provider>
+  );
+};
+
+export default FrozenRoute;
+```
+
+The pinned context keeps the page as the frame first drew it. After a save,
+`router.refresh()` fetches the draft and nothing on screen changes, and no
+overlay setting can reach inside the freeze. Skip it in draft mode only. Give
+the page-transition wrapper a `live` prop:
+
+```tsx
+"use client";
+
+import { usePathname } from "next/navigation";
+import { AnimatePresence, motion } from "framer-motion";
+import FrozenRoute from "./frozen-route";
+
+const PageAnimatePresence = ({
+  children,
+  live,
+}: {
+  children: React.ReactNode;
+  /** Capa preview (draft mode only): no freeze, so an editor's save shows in place. */
+  live?: boolean;
+}) => {
+  const pathname = usePathname();
+
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div className="flex flex-col flex-grow" key={pathname}>
+        {live ? children : <FrozenRoute>{children}</FrozenRoute>}
+      </motion.div>
+    </AnimatePresence>
+  );
+};
+
+export default PageAnimatePresence;
+```
+
+and pass it from the root layout as a conditional spread, so a visitor's
+props, and the RSC payload that carries them, are exactly what they were:
+
+```tsx
+// app/layout.tsx
+const draft = await isDraft();
+
+<PageAnimatePresence {...(draft ? { live: true } : {})}>
+  {children}
+</PageAnimatePresence>
+```
+
+Writing `live={draft}` instead would send `live: false` to every visitor.
+To find the freeze, search the site for `LayoutRouterContext`.
+
+### The protocol
+
+Every message is `{ source, v: 1, type, ...fields }`. `source` is
+`capa-admin` on the admin's messages and `capa` on the site's. The admin sends
+`hello`, `highlight { entryId, field }` (`entryId: ""` clears), `outline { on }`
+and `refresh`. The site answers `ready { path, entries }` after every hello and
+every navigation, `select { entryId, field }` on a click, and `hover`.
+`acceptMessage(event, allowedOrigins, parent)` is the site's filter, exported
+for your own tests.
+
+The site also sends `visible { entryId, field }` while the page scrolls (at
+most every 150ms, and only when it changes): the tagged element at the centre
+of the viewport, chosen by `pickCentred`. At the very top of a page, where a
+heading can never reach the centre, it is the topmost visible element instead,
+and at the very bottom the bottommost. The editor's "Follow the page" scrolls
+the form to that field. An overlay older than 1.0.0-next.2 never sends it, and
+the editor then does not follow.
+
+Following a link with ⌘-click sends no message of its own: the page the link
+leads to answers with `ready`, as after any navigation, so an editor of any
+version follows along.
+
+Since 1.0.0-next.10 `ready` also lists `features: ["patch"]`, and the admin
+may send `patch { entryId, fields: [{ field, value, saved }] }` while an
+editor types: the unsaved text of plain text, number and option fields, and
+the saved value the page was rendered from. The overlay puts `value` into a
+tagged element's one text node while that text reads `saved` or what it last
+patched it to, so a field your site formats (a price, a date, Markdown) is
+left alone until the save re-renders it. It writes text, never markup, and
+only for the admin that said hello. Rich text, media and relations wait for
+the save, as before. An admin sends patches only when its project has live
+preview on.
+
+## Not yet
+
+`--select-from-depth`, `capa convert-url`, GraphQL mutations, and `/api/`
+writes are not in this release.
+
+## The legacy `/v2/api` client
+
+`@capacms/sdk` is the client for sites that read `/v2/api` today. It takes a
+legacy key (`pk_`, `sk_` or unprefixed) and the tenant's id, and refuses a
+`cap_` key where it is built, since `/v2` answers one as an invalid key: a
+`cap_` key reads `/api/`, with `createClient` from `@capacms/sdk/next`.
+Besides reads, it schedules publishes, arranges the admin's workspaces and
+entry layouts, and manages webhook endpoints.
+
+```ts
+import { createClient } from "@capacms/sdk";
+import type { BlogPost } from "./capa-types";        // written by capa-codegen
+
+const capa = createClient({
+  baseUrl: process.env.CAPA_API_URL!,
+  apiKey: process.env.CAPA_KEY!,                      // a pk_ key, not a cap_ key
+  tenantId: process.env.CAPA_TENANT_ID!,
+});
+
+const page = await capa.listContent<BlogPost>("blog_post", { limit: 10 });
+const one  = await capa.findOne<BlogPost>("blog_post", { handle: "hello" });
+```
+
+### An entry's id: read `Page.ids`
+
+A `/v2/api` row puts the model's own fields at its top level, so a model
+with a field named `id` replaces the entry's id in the row, and the same goes
+for `title` and `tags`. Many models have one: every Shopify model names a
+field `id`. So read `Page.ids`, not `row.id`:
 
 ```ts
 const page = await capa.listContent("shopify_page");
-page.ids[0]        // the instance UUID when the row has one to give
+page.ids[0]        // the entry's UUID when the row has one to give
 page.data[0].id    // the model's OWN id field whenever one exists
 ```
 
-`Page.ids` is `string | null` per row: `null` means the model shadows `id` and
-the server sent nothing else to read it from, which is the state of every server
-today. `getContentById` throws on a non-UUID rather than spending a request on a
-guaranteed 400.
-
-`search()` is the same story. `/v2/api/search?extended=true` hoists fields the
-same way, so `SearchHit.id` is read through the same `instanceIdOf` and has the
-same `string | null` type.
+`Page.ids` is `string | null` per row, in the order of `data`: `null` means
+the model shadows `id` and the row carries nothing else to read the entry's
+id from. `instanceIdOf(row)` reads one row the same way, and prefers an
+`instanceId` when a row carries one. `getContentById` throws for an id that is
+not a UUID rather than spending a request on a certain 400. `search()` reads
+its hits the same way, so `SearchHit.id` is `string | null` too. `/api/` has
+no such collision: an entry's system keys sit beside its `fields`.
 
-## Preview is a key, not a flag
+### Preview is a key, not a flag
 
-Capa gates unpublished content on the API key's `environment` column, not on
-anything in the request (`routes/v2/api.ts:203`). There is no `?preview=true`, so
+Capa shows unpublished content to a key whose environment is not
+`production`, whatever the request says. There is no `?preview=true`, so
 preview is a second client:
 
 ```ts
@@ -432,67 +2010,91 @@ const capa    = createClient({ ...cfg, apiKey: PUBLISHED_KEY });
 const preview = createClient({ ...cfg, apiKey: PREVIEW_KEY });
 ```
 
-The comparison is exact and case-sensitive against a free-text column, so **any**
-environment that is not literally `production` returns drafts — including a typo
-like `Production`. And a client cannot find out which it holds: `apiKeyEnvironment`
-is consumed internally and returned by no endpoint, so a site handed a `draft`
-key serves unpublished content publicly with no way to detect it.
-
-## Not included
-
-**Caching.** Every framework does it differently and owning it means
-reimplementing all of them badly. Plain `fetch` returning plain data lets Next's
-fetch cache and React Router loaders work natively. What the host cannot know is
-which surrogate keys a response carries, so those are surfaced as
-`Page.cacheTags` for CDN purging.
+The comparison is exact and case-sensitive, so **any** environment that is
+not literally `production` returns drafts, a typo like `Production`
+included. And a `/v2` client cannot find out which it holds: no `/v2`
+endpoint reports a key's environment, so a site handed a `draft` key serves
+unpublished content publicly with no way to detect it. `/api/` reports it:
+`capa.me()` on `@capacms/sdk/next` answers the key's `environment`.
 
-**`getBySlug`.** Capa has no slug convention — the field is `handle` on
-`shopify_page`, `product_handle` on `judge_me_review`, `bloghandle` on
-`shopify_article`, and nothing marks one as *the* slug. `findOne(ns, {handle})`
-is explicit instead. A slug marker belongs on the model, in Capa.
+### Codegen
 
-**Content writes.** `/v2/agent/model-instances` exists and an API key reaches
-it, so an SDK that can silently publish a draft is now technically possible.
-That wants a deliberate surface of its own rather than another method quietly
-added to the client, so it is absent rather than half-built. The one exception
-is `scheduledActions`, below, and the exception is narrow on purpose: a schedule
-is a request that leaves a row you can read, show and cancel. Publishing *now*
-leaves the caller holding the only copy of what happened.
+```sh
+CAPA_API_URL=... CAPA_KEY=pk_... CAPA_TENANT_ID=... capa-codegen --out src/capa-types.ts
+```
 
-This section used to say the SDK could not write at all, because `verifyApiKey`
-guarded five route files carrying 15 GETs and no write verb. That stopped being
-true with the agent surface (`#383`) and `tenant_api_keys.permission` becoming a
-real control (`#4646`). Two things write today, and both touch arrangement
-rather than content:
+Without `--graphql`, `capa-codegen` reads the legacy `/v2` schema, which
+takes a `pk_` key and `CAPA_TENANT_ID`. A `cap_` key, which `/v2` refuses,
+writes the same interfaces from the key's GraphQL schema, with no tenant id,
+and so does `--schema <file>`, a schema `capa-codegen --graphql --save-schema`
+wrote. GraphQL does not say three things, so those types say less: every
+field is optional, an enum is a `string`, and a field GraphQL leaves out is
+`unknown`. There is no `CAPA_SCHEMA_CHECKSUM`, since that is the `/v2`
+schema's checksum. Where the API does not serve GraphQL, use a `pk_` key. It
+reads `.env.local` and `.env` too, as `next dev` does.
+
+Exit codes: `0` wrote or already current, `1` failed, `2` `--check` found a
+diff. `--check` is the CI mode: it fails when the committed file is stale.
+
+**Commit the output.** Generating at install needs credentials during
+`npm install`, which breaks CI images and Docker builds, and generating at
+build time makes every build depend on the network. A committed file also
+turns "a model changed, so the build fails" into a reviewable diff instead of
+a wall of `tsc` errors.
+
+With a `pk_` key, re-running when nothing changed costs one conditional
+request that returns no body: codegen stamps the `/v2` schema's checksum in
+the file and fetches the types only when the schema moved. With `--graphql`,
+a `cap_` key or `--schema` there is no checksum, so every run reads the whole
+schema again: one full introspection request, or the file. Models are written
+in the order of their interface names, so renaming a model's display name
+does not reorder the file.
+
+### What it leaves out
+
+**Caching.** Every framework caches differently, so the client returns plain
+data from plain `fetch`, and Next's fetch cache and React Router loaders work
+with it as they are. What your host cannot know is which surrogate keys a
+response carries, so `Page.cacheTags` holds them for purging a CDN.
+
+**`getBySlug`.** Capa has no slug convention: the field is `handle` on
+`shopify_page`, `product_handle` on `judge_me_review` and `bloghandle` on
+`shopify_article`, and nothing marks one as the slug. `findOne(ns, { handle })`
+says which.
+
+**Content writes.** The client writes no entry content. It schedules
+publishes (`scheduledActions`, below), a request that leaves a row you can
+read, show and cancel, and it writes arrangement, which touches no entry:
 
 ```ts
-await capa.workspaces.apply(id, { tree });        // the admin rail (0h, 0t)
-await capa.models.setLayout(id, layout);          // the entry editor (0m)
+await capa.workspaces.apply(id, { tree });        // the admin's left rail
+await capa.models.setLayout(id, layout);          // the entry editor
 await capa.models.setLayout(id, null);            // back to the linear editor
 ```
 
-Reading has two shapes. `models.getLayout(id)` is the document or null;
-`models.getLayoutInfo(id)` is the same read with the model's `embedByDefault`
-beside it, which is what decides a relation field with no `display` on its
-layout node (section 0m.8, and it applies in linear mode too):
+### Workspaces and entry layouts
+
+Reading a layout has two shapes. `models.getLayout(id)` is the document or
+null; `models.getLayoutInfo(id)` is the same read with the model's
+`embedByDefault` beside it, which decides how a relation field with no
+`display` renders, in linear mode too:
 
 ```ts
 const { layout, embedByDefault } = await capa.models.getLayoutInfo(id);
 ```
 
-A workspace `tree` is a flat `WorkspaceDocNode[]` since 0t: one list of folders
-the customer named, each holding any mix of `{model}`, `{instance}`,
-`{media_folder}` and further folders. The 0h shape, `{ model, content, media }`,
-is still accepted for one release and lands in folders called Models, Content
-and Media.
+A workspace `tree` is a flat `WorkspaceDocNode[]`: one list of folders you
+named, each holding any mix of `{model}`, `{instance}`, `{media_folder}` and
+further folders. The older shape, `{ model, content, media }`, is still
+accepted and lands in folders called Models, Content and Media.
 
 `workspaces.*` needs a key with `write`; `models.setLayout` needs one with
-`agent`, because it writes a MODEL and that is the gate every other model write
-asks for. `models.getLayout` needs only `read`. A refused document comes back as
-`CapaError` carrying the API's own `{ error, path }`, where `path` names the
-node to fix. `apps/api/LAYOUT.md` has the rules and a worked example.
+`agent`, because it writes a model and that is the permission every model
+write asks for. `models.getLayout` needs only `read`. A refused document comes
+back as `CapaError` carrying the API's own `{ error, path }`, where `path`
+names the node to fix.
 
-## Scheduling a publish
+### Scheduling a publish
 
 ```ts
 const { batchId, resolved, actions, replaced } = await capa.scheduledActions.create({
@@ -503,10 +2105,9 @@ const { batchId, resolved, actions, replaced } = await capa.scheduledActions.cre
 });
 ```
 
-**Instance targets only, from a key.** A `{ type: "model" }` target needs the
-`model:publish` permission, and no API key bundle carries it in phase 1, so the
-server answers 403 whatever the key. Scheduling a schema publish is an admin
-session job until a bundle grants it.
+**Entry targets only, from a key.** A `{ type: "model" }` target needs the
+`model:publish` permission, which no API key carries, so the server answers
+403 whatever the key. Scheduling a model publish is done in the Capa admin.
 
 **Send a wall clock and a zone, not an instant.** `wallTime` carrying a `Z` or a
 `+02:00` is refused, here and by the server, because the two together are the
@@ -554,18 +2155,17 @@ right now and `cancel` answers 409 `already_running`. `resultVersionId` on a
 `done` row is the version that went live.
 
 Reading needs a `read` key; every write here needs `instance:publish`, which the
-`write`, `delete` and `agent` bundles carry. A refusal is a `CapaError` with the
-API's own `{ error, code }`. The operator's side of all of this, including what
-to do when an action fails at 3am, is `docs/PUBLISHING.md`.
+`write`, `delete` and `agent` keys carry. A refusal is a `CapaError` with the
+API's own `{ error, code }`.
 
-## Webhooks
+### Webhooks
 
 Two halves that do not need each other. The verifier is clientless, so a
 receiver imports one function and nothing else. The resource manages endpoints,
 and it is the only thing in this SDK that needs a session token rather than an
 API key.
 
-### Verifying a delivery
+#### Verifying a delivery
 
 ```ts
 import { verifyWebhookSignature } from "@capacms/sdk";
@@ -604,12 +2204,12 @@ During the 24 hours after a rotation Capa sends two `v1=` entries, the new
 secret first. Either one verifies, so a receiver can be updated any time inside
 that window without dropping a request.
 
-### Managing endpoints
+#### Managing endpoints
 
 ```ts
 const capa = createClient({
-  baseUrl: process.env.CAPA_BASE_URL!,
-  apiKey: process.env.CAPA_API_KEY!,
+  baseUrl: process.env.CAPA_API_URL!,
+  apiKey: process.env.CAPA_KEY!,
   tenantId: process.env.CAPA_TENANT_ID!,
   accessToken: sessionJwt,                 // from POST /v2/user/login
 });
@@ -624,19 +2224,20 @@ const { secret, ...endpoint } = await capa.webhooks.endpoints.create({
 
 `createClient` still needs `apiKey` and `tenantId` to construct at all, so a
 script that only ever calls `webhooks.*` has to pass something non-empty for
-both. Any placeholder will do, because no webhook call reads either one.
+both. Any legacy-looking placeholder will do, because no webhook call reads
+either one.
 
 **The tenant comes from the session, not from `tenantId`.** These routes read
 the current tenant off the logged-in user's token, so the `tenantId` you passed
 to `createClient` is ignored for every `webhooks.*` call: a client built with one
 `tenantId` operates on whatever tenant that user is currently on.
 
-**`accessToken`, not `apiKey`.** The webhook routes have no API key mount at
-all (publishing spec D8): a key that can add an endpoint can forward every
-content change in the tenant to a URL of its choosing, and a key is a string in
-a config file nobody rotates. So these routes want a logged-in person, and every
-`webhooks.*` method throws `@capacms/sdk: webhooks need accessToken; API keys
-cannot manage endpoints.` before sending anything when the token is absent.
+**`accessToken`, not `apiKey`.** The webhook routes take no API key at all: a
+key that can add an endpoint can forward every content change in the project
+to a URL of its choosing, and a key is a string in a config file nobody
+rotates. So these routes want a logged-in person, and every `webhooks.*`
+method throws `@capacms/sdk: webhooks need accessToken; API keys cannot manage
+endpoints.` before sending anything when the token is absent.
 
 The rest of the resource:
 
@@ -659,9 +2260,9 @@ await capa.webhooks.deliveries.redeliver(deliveryId);    // same event id
 ```
 
 `test` answers `{ eventId }`, and that value is an **opaque request id**: the
-event that actually arrives carries a different `id` (`evt_` plus the outbox row
-id), so there is nothing to correlate on. Read `deliveries(id)` and take the
-newest `webhook.test` row to see what the test did.
+event that actually arrives carries a different `id` (`evt_` plus another
+id), so there is nothing to correlate on. Read `deliveries(id)` and take the newest
+`webhook.test` row to see what the test did.
 
 `resume` without `backfill` is deliberately a two-step: it enables the endpoint
 and tells you how many events it missed, so you can show a person
@@ -669,10 +2270,7 @@ and tells you how many events it missed, so you can show a person
 Call it again with `{ backfill: true, since }` if they say yes.
 
 Reads need `webhook:read`, writes need the `webhook:*` write actions, and
-`revealSecret` needs `secret:reveal`, which no role bundle holds: it is an owner
-or an explicit override, and every call leaves an audit row whether it was
-allowed or denied. A server without `CAPA_SECRET_KEY` set answers `503` with
-code `webhooks_not_configured` to every write while reads keep working.
-
-The operator's side of all of this, including the retry ladder, auto-pause, the
-SSRF rules and how to run a receiver locally, is `docs/WEBHOOKS.md`.
+`revealSecret` needs `secret:reveal`, which no role holds by default: it is an
+owner or an explicit grant, and every call leaves an audit row whether it was
+allowed or denied. A server without webhook secrets configured answers `503`
+with code `webhooks_not_configured` to every write while reads keep working.