@capacms/sdk 1.0.0-next.4 → 1.0.0-next.7

package/README.md

@@ -1,21 +1,34 @@
 # @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` | 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 +36,30 @@ 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` and `versions`. The first client built with
+one prints a warning once per process, naming the `cap_` key to mint. Draft
+previews keep their rule and take a `cap_` key only: `preview()`,
+`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 +89,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 +100,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 +111,51 @@ 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
@@ -90,11 +171,13 @@ const flat = await capa.entries.list<Article, typeof select>("articles", {
 });
 
 flat.data[0].fields.author;             // { id: "…", model: "authors" }
-flat.included.authors[authorId].fields; // { name: "Ada Vale" }, typed as Author
+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. A select written as a plain string types it as
+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.
 
@@ -104,12 +187,15 @@ same request without `shape` returns:
 ```ts
 import { inflate } from "@capacms/sdk/next";
 
-const tree = inflate(flat); // { data, page, meta, cacheTags }, no included
+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
@@ -151,7 +237,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:
 
@@ -185,19 +275,780 @@ 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).
+
+## 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 };
@@ -213,7 +1064,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
 
@@ -320,7 +1195,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]");
@@ -398,7 +1273,8 @@ editor sees the path without a link to open it.
 
 ### Quick start (Next.js)
 
-Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`) and `CAPA_DRAFT_KEY` (`cap_test_`), then:
+Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`) and `CAPA_DRAFT_KEY` (`cap_test_`).
+Draft previews take `cap_` keys only (see Keys). Then:
 
 ```ts
 // middleware.ts
@@ -413,15 +1289,16 @@ import { createPreviewRoute } from "@capacms/sdk/nextjs";
 export const GET = createPreviewRoute({ draftMode, redirect });
 
 // 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
 ```
 
-In Capa, set the project's preview URL to your site. Add the overlay from step 2
-below and editors can click your page. The sections below explain each piece.
+In Capa, set the project's preview URL to your site, and editors can click
+your page. The sections below explain each piece.
 
 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. It needs three things on your side. A
-complete, runnable example is `examples/sdk-demo` in this repository.
+and the draft re-renders in place. It needs three things on your side.
 
 ### 1. Turn on edit mode and tag what an editor can click
 
@@ -461,6 +1338,43 @@ 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
+// getServerSideProps, a +page.server.ts load, useAsyncData on the server...
+return { props: { entry, edit: draft } };
+
+// in the component
+<h1 {...capaAttrs(entry, "title", edit)}>{entry.fields.title}</h1>
+```
+
+Or re-mark the entries where they arrive with `markEditEntries(data)` when the
+page is in edit mode. Tested on the Pages Router, SvelteKit and Nuxt.
+
+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:
+
+```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>
+```
+
+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.
+
 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`:
@@ -478,22 +1392,19 @@ export async function middleware(request: NextRequest) {
 }
 ```
 
-### 2. Start the overlay in draft mode
+### 2. Start the overlay in edit mode
 
 ```tsx
-// app/capa-overlay.tsx
-"use client";
-import { useEffect } from "react";
-import { useRouter } from "next/navigation";
-import { startOverlay } from "@capacms/sdk/overlay";
-
-export function CapaOverlay({ adminOrigins }: { adminOrigins: string[] }) {
-  const router = useRouter();
-  useEffect(() => startOverlay({ adminOrigins, onRefresh: () => router.refresh() }), [adminOrigins, router]);
-  return null;
-}
+// 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 a visitor never downloads it.
 `startOverlay` returns a disposer and is safe to call twice. Outside a frame it
@@ -552,32 +1463,35 @@ every navigation, `select { entryId, field }` on a click, and `hover`.
 `acceptMessage(event, allowedOrigins, parent)` is the site's filter, exported
 for your own tests.
 
-Since 1.0.0-next.2 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. It is additive and still `v: 1`: an older
-overlay never sends it and the editor simply does not follow.
+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.
 
 ## Not yet
 
-`--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`
+`--select-from-depth`, `capa convert-url`, GraphQL mutations, and `/api/`
 writes are not in this release.
 
 ## The legacy `/v2/api` client
 
-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.
+`@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_BASE_URL!,
-  apiKey: process.env.CAPA_API_KEY!,
+  baseUrl: process.env.CAPA_API_URL!,
+  apiKey: process.env.CAPA_KEY!,                      // a pk_ key, not a cap_ key
   tenantId: process.env.CAPA_TENANT_ID!,
 });
 
@@ -585,80 +1499,31 @@ const page = await capa.listContent<BlogPost>("blog_post", { limit: 10 });
 const one  = await capa.findOne<BlogPost>("blog_post", { handle: "hello" });
 ```
 
-## Codegen
-
-```
-CAPA_BASE_URL=... CAPA_API_KEY=... CAPA_TENANT_ID=... capa-codegen --out src/capa-types.ts
-```
-
-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.** 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.
-
-Re-running when nothing changed costs **one conditional request returning 0
-bytes** — see below.
-
-## Three server-side rough edges, handled here
-
-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.
-
-**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.
+### An entry's id: read `Page.ids`
 
-**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.
-
-**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`.
-
-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.**
-
-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.
-
-So **read `Page.ids`, not `row.id`**:
+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
@@ -666,67 +1531,89 @@ 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
+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`.
 
-**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.
+### Codegen
 
-**`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.
-
-**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.
+
+Re-running when nothing changed costs one conditional request that returns
+no body: codegen stamps the schema's checksum in the file and fetches the
+types only when the schema moved. 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({
@@ -737,10 +1624,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
@@ -788,18 +1674,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";
@@ -838,12 +1723,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
 });
@@ -858,19 +1743,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:
 
@@ -893,9 +1779,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
@@ -903,10 +1789,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.